The following functions provide a fairly complete interface to
database objects.
As mentioned, some of the functions generate or accept lists of
``object copies''. These are objects that are not included in the
object database for any cell. A list of copies behaves in most
respects like an ordinary object list. The The CopyObjects
function can be used to create a new database object from a copy. The
handle manipulation functions such as HandleCat work, but lists
of copies can not be mixed with lists of database objects, HandleCat will fail quietly if this is attempted. Copies can not be
selected.
-
- (object_handle) ListElecInstances()
This function returns a handle to a complete list of cell instances
found in the electrical part of the current cell. Operation is
identical in electrical and physical modes. In the schematic, cell
instances represent subcircuits, devices, and pins. The ``GetInstance'' functions described below can be used to obtain
information about the instances.
- (object_handle) ListPhysInstances()
This function returns a handle to a complete list of cell instances
found in the physical layout of the current cell. Operation is
identical in electrical and physical modes. The ``GetInstance''
functions described below can be used to obtain information about the
instances.
- (object_handle) SelectHandle()
This function returns a handle to the list of objects currently
selected. The list is copied internally, and so is unchanged if the
objects are subsequently deselected.
A handle to the object list is returned. The ObjectNext
function is used to advance the handle to point to the next object in
the list. The HandleContent function returns the number of
objects remaining in the list.
- (object_handle) SelectHandleTypes(types)
This function returns a handle to a list of objects that are currently
selected, but only the types of objects specified in the argument are
included. The argument is a string which specifies the types of
objects to include. If zero or an empty string is passed, all types
are included, and the function is equivalent to SelectHandle.
Otherwise the characters in the string signify which objects to
include:
| `b' |
boxes |
| `p' |
polygons |
| `w' |
wires |
| `l' |
labels |
| `c' |
subcells |
For example, passing ``pwb'' would include polygons, wires, and
boxes only. The order of the characters is unimportant.
- (object_handle) AreaHandle(l, b, r,
t, types)
This function creates a list of objects that touch the rectangular
area specified by the first four coordinates (which are the left,
bottom, right, and top values of the rectangle). The fifth argument
is a string which specifies the types of objects to include. If zero
or an empty string is passed, all types are included, otherwise the
characters in the string signify which objects to include:
| `b' |
boxes |
| `p' |
polygons |
| `w' |
wires |
| `l' |
labels |
| `c' |
subcells |
For example, passing ``pwb'' would list polygons, wires, and
boxes only. The order of the characters is unimportant.
A handle to the object list is returned. The ObjectNext
function is used to advance the handle to point to the next object in
the list. The HandleContent function returns the number of
objects remaining in the list.
- (object_handle) ObjectHandleDup(object_handle,
types)
This function creates a new handle and list of objects. The new
object list consists of those objects in the list referenced by the
argument whose types are given in the string types argument. If
zero or an empty string is passed, all types are included, otherwise
the characters in the string signify which objects to include:
| `b' |
boxes |
| `p' |
polygons |
| `w' |
wires |
| `l' |
labels |
| `c' |
subcells |
The return value is a handle, or 0 if an error occurred. Note that
the new handle may be empty if there were no matching objects. The
function will fail if the handle argument is not a pointer to an
object list.
- (int) ObjectHandlePurge(object_handle, types)
This function will purge from the list of objects referenced by the
handle argument objects with types listed in the types string.
If zero or an empty string is passed, all types are deleted, otherwise
the characters in the string signify which objects to delete:
| `b' |
boxes |
| `p' |
polygons |
| `w' |
wires |
| `l' |
labels |
| `c' |
subcells |
The return value is the number of objects remaining in the list. The
function will fail if the handle argument does not reference a list of
objects.
- (int) ObjectNext(object_handle)
This function is called with a handle to a list of objects, and causes
the handle to reference the next object in the list. If there are no
more objects, the handle is closed, and this function returns zero.
Otherwise, 1 is returned. This function will fail if the handle
passed is not a handle to an object list.
- (object_handle) MakeObjectCopy(numpts, array)
This function creates an object copy from the numpts coordinate
pairs in the array. The function returns an object list handle
referencing the ``copy'', which can be used in the same manner as
copies of ``real'' objects. The coordinate list must be closed, i.e.,
the last coordinate pair must be the same as the first. If the
coordinates represent a rectangle, a box object is created, otherwise
the object is a polygon. Coordinates are in microns, relative to the
origin of the current cell. The object is associated with the current
layer (but of course it really does not exist on that layer).
- (string) ObjectString(object_handle)
This function returns a CIF-like string describing the object pointed
to by the given object handle. This provides all of the geometric
information for the object. Strings of this format can be reconverted
to object copies with the ObjectCopyFromString function.
On error or for an empty handle, a null string is returned. The
function will fail if the argument is not a handle to an object list.
- (object_handle) ObjectCopyFromString(string, layer)
This function will create an object copy from the CIF-like string, as
generated by the ObjectString function. Boxes, polygons, and
wires are supported, labels and subcells will not return a handle.
The object will be associated with the layer named in the second
argument. The layer will be created if it does not exist. Only
physical layers are accepted.
On success, a handle to an object list containing the new copy is
returned. On error, a scalar zero is returned. The function will
fail if the string is null or a new layer cannot be created.
- (object_handle) FilterObjects(object_list,
template_list, all, touchok, remove)
This function creates a handle to a list of objects that is a subset
of the objects contained in the object_list. The objects in
the new list are those that touch or overlap objects in the template_list, which is also a handle to a list of objects.
If all is nonzero, all of the objects in the template_list will be used for comparison, otherwise only the head
object in the template list will be used.
If touchok is nonzero, objects in the object list that touch but
do not overlap the template object(s) will be added to the new list,
otherwise not.
If remove is nonzero, objects that are added to the new list are
removed from the object_list, otherwise the object_list
is not touched. The function will fail if the handle arguments are of
the wrong type. The return value is a new handle to a list of
objects.
- (object_handle) FilterObjectsA(object_list,
array, array_size, touchok, remove)
This function creates a handle to a list of objects, which consist of
the objects in the object_list that touch or overlap the
polygon defined in the array. The array_size is the
number of x-y coordinates represented in the array. In the array, the
values are x-y coordinate pairs representing the polygon vertices, and
the first pair must match the last pair (i.e., the figure must be
closed). The values are specified in microns. If touchok is
nonzero, objects that touch but do not overlap the polygon will be
added to the list, otherwise not. If remove is nonzero, objects
that are added to the new list are removed from the object_list, otherwise the object_list is not touched.
The function will fail if array_size is less than 4, or the
size of the array is less than twice array_size, or if the
handle argument is not a handle to a list of objects. The return
value is a new handle to a list of objects.
- (int) CheckObjectsConnected(object_handle)
This function returns 1 unless the list contains objects on the layer
of the first object in the list that are mutually disjoint, meaning
that there exist two objects and one can not draw a curve from the
interior of one to the other without crossing empty area. If disjoint
objects are found, 0 is returned.
- (int) CheckForHoles(object_handle, all)
This function returns 1 if the object, or collection of objects, has
``holes'', i.e., uncovered areas completely surrounded by geometry.
The first argument is a handle to a list of objects. If the second
argument is nonzero, the geometry represented by all objects in the
list is checked. If zero, only the first object (which might be a
complex polygon containing holes) is checked. If no holes are found,
0 is returned.
When all is true, only objects on the same layer as the first
object in the list are considered.
- (object_handle) BloatObjects(object_handle, all,
dimen, lname, mode)
This function returns a handle to a list of object copies which are
bloated versions of the objects referenced by the handle argument,
similar to the !bloat command. The passed handle and objects
are not affected. Edges will be pushed outward or pulled inward by
dimen (positive values push outward). The dimen is given
in microns.
The all argument is a boolean that if nonzero indicates that all
objects in the list referenced by the handle may be processed. If
zero, only the first object in the list will be processed.
The lname argument is a layer name. If this argument is zero,
or a null or empty string, all objects on the returned list are
associated with the layer of the first object in the passed list, and
only objects on this layer in the passed list are processed.
Otherwise, the layer will be created if it does not exist, and all new
objects will be associated with this layer, and all objects in the
passed list will be processed.
The mode argument is an integer that specifies the algorithm to
use for bloating. Giving zero specifies the default algorithm. See
the description of the !bloat command (19.13.12) for
documentation of the algorithms available.
The DeleteObjects function can be called to delete the old
objects. The CopyObjects function can be called on the returned
objects to add them to the database. This function returns a handle
to the new list upon success, or 0 if there are no objects. The
function will fail if the first argument is not a handle to a list of
objects or copies, or the lname argument is non-null and not a
valid layer name.
This function uses the JoinMaxXXX variables in processing.
There is no effect on objects in the list whose handle is passed as
the first argument, or on the handle.
- (object_handle) EdgeObjects(object_handle, all,
dimen, lname, mode)
This function creates new polygon copies that cover the edges of the
figures in the passed handle. The dimen is half the effective
path width of the generated wire-like shapes that cover the edges.
If the boolean argument all is nonzero, all of the objects in
the passed list may be processed, otherwise only the object at the
head of the list will be processed.
The lname argument is a layer name. If this argument is zero,
or a null or empty string, all objects on the returned list are
associated with the layer of the first object in the passed list, and
only objects on this layer in the passed list are processed.
Otherwise, the layer will be created if it does not exist, and all new
objects will be associated with this layer, and all objects in the
passed list will be processed.
The mode is an integer which specifies the algorithm to use. The
algorithms are described with the EdgesZ function.
The DeleteObjects function can be called to delete the old
objects. The CopyObjects function can be called on the returned
objects to add them to the database. This function returns a handle
to the new list upon success, or 0 if there are no objects. The
function will fail if the first argument is not a handle to a list of
objects or copies, or the lname argument is non-null and not a
valid layer name.
- (object_handle) ManhattanizeObjects(object_handle,
all, dimen, lname, mode)
This function will convert the objects pointed to by the handle
argument into a list of copies, which is referenced by the returned
handle. The supplied objects and handle are not affected. Each new
object is a Manhattan approximation of the original object. The dimen argument is the minimum height or width in microns of
rectangles created to approximate the non-Manhattan parts.
The all argument is a boolean that if nonzero indicates that all
objects in the list referenced by the handle may be processed. If
zero, only the first object in the list will be processed.
The lname argument is a layer name, or zero. If a layer name is
given, the new objects will be associated with that layer, which will
be created if it does not exist. If 0 or an empty string is passed,
the new objects will be associated with the layer of the original
object.
The mode argument is a boolean value which selects one of two
Manhattanizing algorithms to employ. These algorithms are described
with the !manh command.
The function will fail if the first argument is not a handle to a list
of objects or copies, or the lname argument is non-null and not
a valid layer name, or the dimen argument is smaller than 0.01.
On success, a handle to the list of copies is returned. Each object
in the returned list is a box or Manhattan polygon which approximates
one of the original objects. Of course, if the original objects were
all Manhattan, the shapes will be unchanged, though the coordinates
will be moved to a dimen grid if the gridding mode (mode
nonzero) is given.
The DeleteObjects function can be called to delete the old
objects. The CopyObjects function can be called on the returned
objects to add them to the database.
This function uses the JoinMaxXXX variables in processing.
There is no effect on objects in the list whose handle is passed as
the first argument, or on the handle.
- (int) GroupObjects(object_handle, array)
This function acts on the first object in the list and all other
objects on the same layer found in the list. The objects are copied,
then sorted into groups, so that each group forms a single figure,
i.e., no two members of the same group are disjoint. The groups are
then joined into polygons, and a handle to each group is returned in
the array. The array will be resized if necessary. The returned
value is the number of groups, corresponding to the used entries in
the array. The H function should be used on the array elements
to convert the values to an object handle data type, similar to the
treatment of the array returned from the HandleArray function.
The CloseArray function can be used to close the handles. The
created objects are copies, so are not added to the database.
This function uses the JoinMaxXXX variables in processing.
There is no effect on objects in the list whose handle is passed as
the first argument, or on the handle. The value 0 is returned on
error or if the list is empty.
- (object_handle) JoinObjects(object_handle, lname)
This function will combine the objects in the list passed as the first
argument, if possible, into a new list of object copies, which is
returned. The passed handle and objects are not affected. All
objects in the returned list will be associated with the layer named
in the second argument. This layer will be created if it does not
exist, and the output will consist of the joined outlines of all of
the objects in the passed list, from any layer. If 0, or a null or
empty string is passed, the new objects will be associated with the
layer of the first object in the passed list, and only the outlines of
objects on this layer found in the passed list will contribute to the
result.
The DeleteObjects function can be called to delete the old
objects. The CopyObjects function can be called on the returned
objects to add them to the database. This function returns a handle
to the new list upon success, or 0 if there are no objects. The
function will fail if the first argument is not a handle to a list of
objects or copies, or the lname argument is non-null and not a
vail layer name.
This function uses the JoinMaxXXX variables in processing.
There is no effect on objects in the list whose handle is passed as
the first argument, or on the handle.
- (object_handle) SplitObjects(object_handle, all,
lname, vert)
This function will split the objects in the list passed as the first
argument into horizontal or vertical trapezoids (polygons or boxes)
and return a list of the new objects. The new objects are ``object
copies'' and are not added to the database.
If the boolean argument all is nonzero, all of the objects in
the list referenced by the handle will be processed. Otherwise, only
the first object will be processed.
The new objects are placed on the layer with the name given in lname, which is created if it does not exist, independent of the
originating layer of the objects. If a null string or 0 is passed for
lname, the target layer will be the layer of the first object
found in the object list.
The vert argument is an integer which if nonzero indicates a
vertical decomposition, otherwise a horizontal decomposition is
produced.
The handle and objects passed are untouched. The DeleteObjects
function can be called to delete the old objects. The CopyObjects function can be called on the returned objects to add them
to the database. This function returns a handle to the new list upon
success, or 0 if there are no objects. The function will fail if the
first argument is not a handle to a list of objects or copies, or the
lname argument is non-null and not a valid layer name.
- (int) DeleteObjects(object_handle, all)
Calling this function will delete referenced objects from the current
cell. If the boolean argument all is nonzero, all objects in
the list will be deleted. Otherwise, only the first object in the
list will be deleted. Once deleted, the objects are no longer
referenced by the handle, which may become empty as a result.
This function will fail if the handle passed is not a handle to an
object list. The number of objects deleted is returned.
- (int) SelectObjects(object_handle, all)
This function will select objects referenced by the handle. If the
boolean argument all is nonzero, all objects in the list will be
selected. Otherwise, only the first object in the list will be
selected.
It is not possible to select object copies, 0 is returned if the
passed handle represents copies. Otherwise the return value is the
number of newly selected objects.
This function will fail if the handle passed is not a handle to an
object list.
- (int) DeselectObjects(object_handle, all)
This function will deselect objects referenced by the handle. If the
boolean argument all is nonzero, all objects in the list will be
deselected. Otherwise, only the first object in the list will be
deselected.
It is not possible to select object copies, 0 is returned if the
passed handle represents copies. Otherwise the return value is the
number of newly deselected objects.
This function will fail if the handle passed is not a handle to an
object list.
- (int) MoveObjects(object_handle, all, refx,
refy, x, y)
This function is similar to the Move function, however it
operates on the object(s) referenced by the handle. An object is
moved such that the coordinate refx, refy is translated to
x, y. The current transform will be applied to the move.
If all is nonzero, all objects in the list are moved, otherwise
only the object currently referenced is moved. The function returns
the number of objects moved. This function will fail if the handle
passed is not a handle to an object list.
If the handle references object copies, each copy is translated and
possibly transformed as described above. The handle will subsequently
reference the modified object.
- (int) MoveObjectsToLayer(object_handle, all,
refx, refy, x, y, oldlayer,
newlayer)
This is similar to the MoveObjects function, but allows layer
change. If newlayer is 0, null, or empty, oldlayer is
ignored and the function behaves identically to MoveObjects.
Otherwise the newlayer string must be a layer name. If oldlayer is 0, null, or empty, all moved objects are placed on newlayer. Otherwise, oldlayer must be a layer name, in which
case only objects on oldlayer will be placed on newlayer, other objects will remain on the same layer. Subcell
objects are moved as in MoveObjects, i.e., the layer arguments
are ignored.
- (int) CopyObjects(object_handle, all, refx,
refy, x, y, repcnt)
This function is similar to the Copy function, however it
operates on the object(s) referenced by the handle. An object is
copied such that the coordinate refx, refy is translated
to x, y.
The repcnt is an integer replication count in the range
1-100000, which will be silently taken as one if out of range. If
not one, multiple copies are made, at multiples of the translation
factors given.
The current transform will be applied to the copy. If all is
nonzero, all of the objects in the list are copied, otherwise only the
object currently being referenced is copied. The function returns the
number of objects copied. This function will fail if the handle
passed is not a handle to an object list.
If the handle references object copies, the object copies that are
referenced remains untouched, however the new objects, translated and
possibly transformed as described above, are added to the database.
The repcnt argument is ignored in this case.
- (int) CopyObjectsToLayer(object_handle, all,
refx, refy, x, y, oldlayer,
newlayer, repcnt)
This is similar to the CopyObjects function, but allows layer
change. If newlayer is 0, null, or empty, oldlayer is
ignored and the function behaves identically to CopyObjects.
Otherwise the newlayer string must be a layer name. If oldlayer is 0, null, or empty, all copied objects are placed on newlayer. Otherwise, oldlayer must be a layer name, in which
case only objects on oldlayer will be placed on newlayer, other objects will remain on the same layer. Subcell
objects are copied as in CopyObjects, i.e., the layer arguments
are ignored.
- (object_handle) CopyObjectsH(object_handle, all,
refx, refy, x, y, oldlayer,
newlayer, todb)
This function returns an object handle, containing copies of the
objects in the handle passed as the first argument. If boolean all is set, all passed objects will be copied, otherwise only the
first object in the list will be copied. The next four arguments set
the copy translation, with refx and refy in the passed
object translated to x, y in the copy. The current
transform is also applied to the copy.
The two layer name arguments behave as in CopyObjectToLayer. If
newlayer is 0, null, or empty, oldlayer is ignored and no
object layers will change. Otherwise the newlayer string must
be a layer name. If oldlayer is 0, null, or empty, all copied
objects are placed on newlayer. Otherwise, oldlayer must
be a layer name, in which case only objects on oldlayer will be
placed on newlayer, other objects will remain on the same layer.
Subcell objects are copied as in CopyObjects, i.e., the layer
arguments are ignored.
The final argument is a boolean that when true, the copies are added
to the database, and the returned handle points to the database
objects. If false, the returned handle contains ``object copies''
which do not appear in the database. Note that when copies are added
to the database, unlike other copy functions merging is disabled, and
the replication feature is not available.
- (string) GetObjectType(object_handle)
This function returns a one-character string representing the type of
object referenced by the handle argument. If the handle is invalid, a
null string is returned. The types are:
| `b' |
boxes |
| `p' |
polygons |
| `w' |
wires |
| `l' |
labels |
| `c' |
subcells |
This function will fail if the handle passed is not a handle to an
object list.
- (int) GetObjectID(object_handle)
This function returns a unique id number for the object. The id is
actually the address of the object in the process memory, so it is
valid only for the current Xic process. If the referenced object
is a copy, the id returned is the address of the real object, not the
copy. If no object is referenced by the handle, 0 is returned. The
function fails if the handle is not an object list type.
- (int) GetObjectArea(object_handle)
Return the area in square microns of the object pointed to by the
handle. Zero is returned for a defunct handle or upon error.
- (int) GetObjectPerim(object_handle)
Return the perimeter in microns of the object pointed to by the
handle. Zero is returned for a defunct handle or upon error.
- (int) GetObjectCentroid(object_handle, array)
Return the centroid coordinates in microns of the object pointed to by
the handle. The second argument is an array of size two or larger
that will contain the centroid coordinates upon successful return.
The return value is zero for a defunct handle or upon error, one if
success.
- (int) GetObjectBB(object_handle, array)
This function loads the left, bottom, right, and top coordinates of
the object's bounding box (in microns) into the array passed.
This function will fail if the handle passed is not a handle to an
object list, or if the size of the array is less than 4. The return
value is 1 if successful, 0 otherwise.
- (int) SetObjectBB(object_handle, array)
This function will alter the shape of the object pointed to by the
handle such that it has the bounding box passed. The array
contains the left, bottom, right, and top coordinates, in microns.
This function will fail if the handle passed is not a handle to an
object list, or if the size of the array is less than 4. The return
value is 1 if successful, 0 otherwise. This function has no effect on
subcells, but other types of object will be rescaled to the new
bounding box.
- (int) GetObjectListBB(object_handle, array)
This is similar to GetObjectBB, but computes the bounding box of
all objects in the list of objects referenced by the handle. not just
the list head. The function loads the left, bottom, right, and top
coordinates of the aggregate bounding box (in microns) into the array
passed. This function will fail if the handle passed is not a handle
to an object list, or if the size of the array is less than 4. The
return value is a count of the objects in the list.
- (int) GetObjectXY(object_handle, array)
This function will retrieve the ``XY'' position from the object
pointed to by the handle into the array, which must have size 2 or
larger. This is a coordinate, in microns, the interpretation of which
depends on the object type. For boxes, that value is the lower-left
corner of the box. For wires and polygons, the value is the first
vertex in the coordinate list. For labels, the value is the text
anchor position. For subcells, the value is the instantiation point,
the same as the translation in the instantiation transform.
On success, the return value is 1, with the array values set.
Otherwise, 0 is returned.
- (int) SetObjectXY(object_handle, x, y)
This function will set the ``XY'' coordinate of the object pointed to
by the handle, as if setting the XprpXY pseudo-property number
7215 on the object. This has the effect of moving the object to a new
location. The interpretation of the coordinate, which is supplied in
microns, depends on the type of object. For boxes, the lower-left
corner will assume the new value. For polygons and wires, the object
will be moved so that the first vertex in the coordinate list will
assume the new value. For labels, the text will be anchored at the
new value, and for subcells, the new value will set the translation
part of the instantiation transform.
A value of 1 is returned if the operation succeeds, and the object
will be moved. On failure, 0 is returned.
- (string) GetObjectLayer(object_handle)
This function returns the name of the layer on which the object
referenced by the handle is defined. For subcells, this layer is
named ``$$'', but objects will return a layer from the layer
table. This function will fail if the handle passed is not a handle
to an object list. A stale handle will return a null string.
- (int) SetObjectLayer(object_handle, layername)
This function will move the object to the layer named in the string
layername. This will have no effect on subcells. A value 1 is
returned if successful, 0 otherwise. This function will fail if the
handle passed is not a handle to an object list.
- (int) GetObjectFlags(object_handle)
This function returns internal flag data from the object referenced by
the handle. This function will fail if the handle passed is not a
handle to an object list. A stale handle will return 0.
The following flags are defined:
| Name |
Bit |
Description |
|---|
| MergeDeleted |
0x1 |
Object has been deleted due to merge. |
| MergeCreated |
0x2 |
Object has been created due to merge. |
| NoDRC |
0x4 |
Skip DRC tests on this object. |
| Expand |
0x8 |
Five flags are used to keep track of cell
expansion in main plus four sub-windows, in cell instances only. |
| Mark1 |
0x100 |
General purpose application flag. |
| Mark2 |
0x200 |
General purpose application flag. |
| MarkExtG |
0x400 |
Extraction system, in grouping phonycell. |
| MarkExtE |
0x800 |
Extraction system, in extraction phonycell. |
| InQueue |
0x1000 |
Object is in selection queue. |
| NoMerge |
0x4000 |
Object will not be merged. |
| IsCopy |
0x8000 |
Object is a copy, not in database. |
The bitwise logic functions such as AndBits can be used to check
the state of the flags. Of these, only NoDRC, Mark1, and
Mark2 can be arbitrarily set by the user, using functions
described below.
- (int) SetObjectNoDrcFlag(object_handle, value)
This will set the state of the NoDRC flag of the object
referenced by the handle. The second argument is a boolean
representing the flag state. This can be called on any object, but is
only significant for boxes, polygons, and wires in the database.
Objects with this flag set are ignored during design rule checking.
The return value is 0 or 1 representing the previous state of the
flag, or -1 on error.
- (int) SetObjectMark1Flag(object_handle, value)
This will set the state of the Mark1 flag of the object
referenced by the handle. The second argument is a boolean
representing the flag state. This can be called on any object. The
flag is unused by Xic, but can be set and tested by the user for
any purpose. The flag persists as long as the object is in memory.
The return value is 0 or 1 representing the previous state of the
flag, or -1 on error.
- (int) SetObjectMark2Flag(object_handle, value)
This will set the state of the Mark2 flag of the object
referenced by the handle. The second argument is a boolean
representing the flag state. This can be called on any object. The
flag is unused by Xic, but can be set and tested by the user for
any purpose. The flag persists as long as the object is in memory.
The return value is 0 or 1 representing the previous state of the
flag, or -1 on error.
- (int) GetObjectState(object_handle)
This function returns a status value for the object referenced by the
handle. The status values are:
| 0 |
normal state |
| 1 |
object is selected |
| 2 |
object is deleted |
| 3 |
object is incomplete |
| 4 |
object is internal only |
Only values 0 and 1 are likely to be seen. This function will fail if
the handle passed is not a handle to an object list. A stale handle
will return 0.
- (int) GetObjectGroup(object_handle)
This function returns the conductor group number of the object, which
is a non-negative integer or possibly -1 in certain cases, and is
assigned internally by the extraction system. This is used by the
extraction system to establish connectivity nets of boxes, polygons,
and wires, and for subcell indexing. If extraction is unavailable or
not being used, then an arbitrary integer can be applied for other
uses with the SetObjectGroup function.
This function will fail if the handle passed is not a handle to an
object list. If no group has been assigned, or the handle is stale,
or the object is part of the ``ground'' group, 0 is returned.
Otherwise, any assigned number will be returned.
- (int) SetObjectGroup(object_handle, group_num)
This function will assign the group number to the object. All objects
and instances may receive a group number, which is an arbitrary
integer. The group number is usually assigned and used by the
extraction system, and should not be assigned with this function
if extraction is being used. However, if extraction is unavailable or
not being used, then this function allows an arbitrary integer to be
associated with an object, which might be useful. Beware that this
number is zeroed if the object is modified, or in copies.
The GetObjectGroup function can be used to obtain the group
number of an object or cell instance.
This function will fail if the handle passed is not a handle to an
object list. If the group number is successfully assigned, 1 is
returned, 0 is returned otherwise.
- (int) GetObjectCoords(object_handle, array)
This function will obtain the vertex list for polygons and wires, or
the bounding box vertices of other objects, starting from the lower
left corner and working clockwise. If an array is passed, the vertex
coordinates are copied into the array, and the vertex count is
returned. The array will contain the x, y values of the vertices, in
microns, if successful. The coordinates are copied only if the array
is large enough, or can be resized. If the array is a pointer to a
too small array, or the array is too small but has other variables
pointing to it, resizing is impossible and the copying is skipped. In
this case, the returned value is the negative vertex count. If 0 is
passed instead of the array, the (positive) vertex count is returned.
Zero is returned if there is an error. This function will fail if the
handle passed is not a handle to an object list.
- (int) SetObjectCoords(object_handle, array,
size)
This function will modify a physical object to have the vertex list
passed in the array. The size is the number of vertices (one half the
size of the array used). For all but wires, the first and last
vertices must coincide, thus the minimum number of vertices is four.
The array consists of x, y coordinates of the vertices. If the
operation is successful, 1 is returned, otherwise 0 is returned. The
coordinates in the array are in microns. If the coordinates represent
a rectangle, the new object will be a box, if it was previously a
polygon or box. A box may be converted to a polygon if the
coordinates are not those of a rectangle. For labels, the coordinates
must represent a rectangle, and the label will be stretched to the new
box. The function has no effect on instances. This function will
fail if the handle passed is not a handle to an object list.
- (real) GetObjectMagn(object_handle)
This function returns the magnification part of the transform if the
object referenced by the handle is a subcell, or 1.0 for other
objects. Only physical subcells can have non-unit magnification.
This function will fail if the handle passed is not a handle to an
object list. A stale handle returns 0.
- (int) SetObjectMagn(object_handle, magn)
This will set the magnification of the subcell referenced by the
handle, or scale other physical objects. The real number magn
must be between .001 and 1000 inclusive. If the operation is
successful, 1 is returned, otherwise 0 is returned. This function
will fail if the handle passed is not a handle to an object list.
- (real) GetWireWidth(object_handle)
This function will return the wire width if the object referenced by
the handle is a wire, otherwise 0 is returned. This function will
fail if the handle passed is not a handle to an object list.
- (int) SetWireWidth(object_handle, width)
This function will set the width of the wire referenced by the handle
to the given width (in microns). If the operation is
successful, 1 is returned, otherwise 0 is returned. This function
will fail if the handle passed is not a handle to an object list.
- (int) GetWireStyle(object_handle)
This function returns the end style code of the wire pointed to by the
handle, or -1 if the object is not a wire. The codes are
| 0 |
flush ends |
| 1 |
projecting rounded ends |
| 2 |
projecting square ends |
This function will fail if the handle passed is not a handle to an
object list.
- (int) SetWireStyle(object_handle, code)
This function will change the end style of the wire referenced by the
handle to the given code. The code is an integer which can take
the following values
| 0 |
flush ends |
| 1 |
projecting rounded ends |
| 2 |
projecting square ends |
If the operation succeeds, 1 is returned, otherwise 0. This can apply
to physical wires only. This function will fail if the handle passed
is not a handle to an object list.
- (int) SetWireToPoly(object_handle)
This function converts the wire object referenced by the handle to a
polygon object. If the conversion is done, the handle will reference
the new polygon object. The conversion will be done only if the wire
has nonzero width. If the wire is not a copy, the wire object in the
database will be converted to a polygon. Otherwise, only the copy
will be changed. Upon success, the function returns 1, otherwise 0 is
returned. The function fails if the argument is not a handle to an
object list.
- (int) GetWirePoly(object_handle, array)
This function returns the polygon used for rendering a wire. This
will be different from the wire vertices, if the wire has nonzero
width. The first argument is a handle to an object list which
references a wire object. The second argument is an array which will
hold the polygon coordinates. This argument can be 0, if the polygon
points are not needed. The array will be resized if necessary (and
possible). The return value is the number of vertices required or
used in the polygon. If an error occurs, the return value is 0. If
an array is passed which can't be resized because it is referenced by
a pointer, the return value is a negative value, the negative vertex
count required. The function will fail if the first argument is not a
handle to an object list, or the second argument is not an array or
zero. The coordinates returned in the array are in microns, relative
to the origin of the current cell.
- (string) GetLabelText(object_handle)
This function returns the label text if the object referenced by the
handle is a label. Otherwise, a null string is returned. The actual
text is always returned, and not the symbolic text that is shown
on-screen for script and long text labels. This function will fail if
the handle passed is not a handle to an object list.
- (int) SetLabelText(object_handle, text)
This function will set the label text of a label referenced by the
handle. Setting the text in this manner will cause a long-text label
to revert to a normal label. If the operation succeeds, the return
value is 1, otherwise 0 is returned. This function will fail if the
handle passed is not a handle to an object list.
- (int) GetLabelFlags(object_handle)
This function returns the flags word used to specify a number of label
presentation attributes, as described in C.2.
This function will fail if the handle passed is not a handle to an
object list.
The function was named GetLabelXform in releases prior to 3.3.1,
and is still recognized by that name, though this is deprecated and
undocumented.
- (int) SetLabelFlags(object_handle, flags)
This function will apply the given flags to the label referenced by
the handle. The flags are the label flags used by Xic and
described in C.2. If the operation is successful, 1 is
returned, otherwise 0 is returned. This function will fail if the
handle passed is not a handle to an object list.
The function was named SetLabelXform in releases prior to 3.3.1,
and is still recognized by that name, though this is deprecated and
undocumented.
- (int) GetInstanceArray(object_handle, array)
This function fills in the array, which must have size of four
or larger, with the array parameters for the instance referenced by
the handle. If the operation succeeds, 1 is returned, and the array
components have the following values, relative to the untransformed
coordinates:
| array[0] |
number of cells along x |
| array[1] |
number of cells along y |
| array[2] |
center to center x spacing (in microns) |
| array[3] |
center to center y spacing (in microns) |
If the operation fails, 0 is returned. This function will fail if the
handle passed is not a handle to an object list.
- (int) SetInstanceArray(object_handle, array)
This function will change the array parameters of the instance
referenced by the handle to the indicated values. The array
values are in the format as returned from GetInstanceArray.
Only physical mode subcells can be changed by this function, arrays
are not supported in electrical mode. If the operation succeeds, 1 is
returned, otherwise 0 is returned. This function will fail if the
handle passed is not a handle to an object list.
- (string) GetInstanceXform(object_handle)
This function returns a string giving the CIF transformation code for
the instance referenced by the handle. If the object is not an
instance, a null string is returned. This function will fail if the
handle passed is not a handle to an object list.
- (string) GetInstanceXformA(object_handle, array)
This function fills in the array, which must have size 4 or
larger, with the components of the transformation of the instance
referenced by the handle. The values are:
| array[0] |
1 if mirror-y, 0 if no mirror-y |
| array[1] |
angle in degrees |
| array[2] |
translation x |
| array[3] |
translation y |
This is the same data as provided by the GetInstanceXform
function, but in numerical rather than string form. The transform
components are applied in the order as found in the array, i.e.,
mirror first, then rotate, then translate. The function returns 1 if
successful, 0 otherwise. It will fail if the handle passed is not a
handle to an object list.
- (int) SetInstanceXform(object_handle, transform)
This function applies the given transform to the instance
referenced by the handle. The transform is in the form of a CIF
transformation string, as returned by GetInstanceXform. Note
that coordinates in the transform string are in internal units (1 unit
= .001 micron). Only physical-mode subcells can be modified by this
function. If the operation succeeds, 1 is returned, otherwise 0 is
returned. This function will fail if the handle passed is not a
handle to an object list.
- (int) SetInstanceXformA(object_handle, array)
This function applies the given transform parameters in the array to the instance referenced by the handle. The parameters are:
| array[0] |
1 if mirror-y, 0 if no mirror-y |
| array[1] |
angle in degrees |
| array[2] |
translation x |
| array[3] |
translation y |
Only physical-mode subcells can be modified by this function. If the
operation succeeds, 1 is returned, otherwise 0 is returned. The
transform components are applied in the order as found in the array,
i.e., mirror first, then rotate, then translate. The function returns
1 if successful, 0 otherwise. It will fail if the handle passed is
not a handle to an object list.
- (string) GetInstanceMaster(object_handle)
Note: prior to 4.2.12, this function was called GetInstanceName.
This function returns the master cell name of the instance referenced
by the handle. If the object is not an instance, a null string is
returned. This function will fail if the handle passed is not a
handle to an object list. The cell instance can be electrical or
physical, and operation is identical in electrical and physical mode.
- (int) SetInstanceMaster(object_handle, newname)
Note: prior to 4.2.12, this function was called SetInstanceName.
This currently works with physical cell data only.
This function will replace the instance referenced by the handle with
an instance of the cell given as newname, in the parent cell of
the referenced instance. The current transform is added to the
transform of the new instance. This function will fail if the handle
passed is not a handle to an object list. If successful, 1 is
returned, otherwise 0 is returned.
- (string) GetInstanceName(object_handle)
Note: prior to 4.2.12, this function returned the name of the
instance master cell. The
GetInstanceMaster function now
performs that operation.
This function returns a name for the electrical cell instance
referenced by the handle. This is the name of the object, as would
appear in a generated SPICE file.
For unnamed (missing name property) electrical instances, a null
string is returned.
For physical cell instances, an instance name is returned, which
consists of the master name followed by a colon separator and an index
number. The index is a 0-based sequence for instances with a
particular master. The index count advances by the size of the array
for arrayed instances, leaving room in the sequence for individual
elements. The index is in database order (top to bottom then left to
right of the upper left corner of the instance bounding box), and is
stable and reproducible as long as instance sizes and placement
locations remain the same.
Internally, electrical names are generated in the following way. Each
device has a prefix, as specified in the technology file. The prefix
for subcircuits is ``X'', which is defined internally. The prefixes
follow (or should follow) SPICE conventions. The database of instance
placements is scanned in order of the placement location (upper-left
corner of the instance bounding box) top to bottom, then left to
right. Each instance encountered is given an index number as a count
of the same prefix previously encountered in the scan. The prefix
followed by the index forms the instance name. This will identify
each instance uniquely, and the sequencing is predictable from spatial
location in the schematic. For example. X1 will be above or to
the left of X2.
Rather than the internal electrical name. this function will return
an assigned name, if one has been given using SetInstanceName or
by setting the name property,
The index number can be obtained as an integer with GetInstanceIdNum. See also
GetInstanceAltName for a
different subcircuit name style.
- (int) SetInstanceName(object_handle, newname)
Note: prior to 4.2.12, this function would re-master the instance,
the same as the present
SetInstanceMaster function.
This will set a name for the electrical instance referenced by the
handle, which is in effect applying a name property to the instance.
this makes sense for devices, subcircuits, and terminal devices. The
new name will be used when generating netlist output, so should
conform to any requirements, for example SPICE conventions, being in
force.
If the string is null or 0, any applied name will be deleted,
equivalent to ``removing'' a name property.
Physical instance names can not be changed, an attempt to do so fails
silently.
The return value is 1 on success, 0 otherwise.
- (string) GetInstanceAltName(object_handle)
This returns an alternative instance name for the electrical
subcircuit cell instance referenced by the handle. The format is the
master cell name, followed by an underscore, followed by an integer.
The integer is zero-based and sequential among instances of a given
master. For example, instances of master ``foo'' would have
names foo_0, foo_1, etc. This is more useful an some
cases than the SPICE-style names X1, X2, ... as returned
by GetInstanceName.
For electrical device instances, this function returns the same
name As the GetInstanceName function.
The GetInstanceAltIdNum function returns the index number used,
as an integer. This is different from the regular index, where every
instance, of whatever type, has a unique index. Here, instances of
each master each have an index count starting from zero. The order
that instances appear, however, is the same in both lists.
Presently, this function returns a null string for physical instances.
- (string) GetInstanceType(object_handle)
This function will return a string consisting of a single letter that
indicates the type of cell instance referenced by the handle. The
function will fail if the handle is of the wrong type. A null string
is returned it the object referenced is not a cell instance.
Otherwise, the following strings may be returned.
These apply to electrical cell instances.
- ``b''
The instance is ``bad''. There has been an error.
- ``n''
The instance type is ``null'' meaning that it has no electrical
significance in a schematic.
- ``g''
The instance is a ground pin. It has a ``hot spot'' that when placed
forces a ground contact at that location.
- ``t''
This is a terminal device, which has a name label and hot spot. When
placed, it forces a contact to a net named in the label at the hot
spot location.
- ``d''
The instance represents a device, such as a resistor, capacitor, or
transistor.
- ``m''
This is a macro, which implements a subcircuit that is placed in the
schematic, as a ``black box''. Unlike a subcircuit, a macro has no
sub-structure.
- ``s''
This is an instance of a circuit cell, i.e., a subcircuit. Its master
contains instances of devices and other objects representing a
circuit.
For physical instances, at present there is only one return.
- ``p''
This is a physical instance.
- (int) GetInstanceIdNum(object_handle)
This function returns the integer index number used in electrical
device and subcircuit instance names. See the GetInstanceName
description for information about how the numbers are computed. Each
subcircuit will have a unique number. Devices are numbered according
to their prefix strings, each unique prefix has its own number
sequence. These values are always non-negative.
The return for all physical instances is similarly created, and is the
same index used in the instance name returned by GetInstanceName.
This function will return -1 on error.
- (int) GetInstanceAltIdNum(object_handle)
This returns an alternative index for electrical subcircuits, as used
in the GetInstanceAltName function. Every subcircuit master
will have its instances numbered sequentially starting with 0. The
ordering is set by the instance placement location in the schematic,
top to bottom then left to right, with the upper-left corner of the
bounding box being the reference location.
For physical instances, an internal indexing number used by the
extraction system is returned. This is a unique 0-based sequence
applied to all instances of a cell, in database order. The count is
incremented by the array size for arrayed instances.
For other instances, the return value is the same as GetInstanceIdNum.
