next up previous contents index
Next: Geometry Editing Functions 2 Up: Geometry Editing Functions 1 Previous: Derived Layers   Contents   Index


Object Management by Handles

The following functions provide a fairly complete interface to database objects.

Internally, most of the ``Set..." functions in this group modify objects via application of the pseudo-properties (see 10.1.2). This allows modification of most objects and types, with the restrictions listed in the table below. Without restrictions, the functions can act on database objects or the ``object copies'' which are memory objects not part of any cell. The objects can be from electrical or physical cells, and the containing cell (if any) need not be the current cell. However, a restriction when working with copies is that the object type can not be changed.

boxes no restrictions
polys no restrictions
wires can't accept electrical wires on the active (SCED) layer
labels no restrictions
instances can't accept electrical instances

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.


next up previous contents index
Next: Geometry Editing Functions 2 Up: Geometry Editing Functions 1 Previous: Derived Layers   Contents   Index
Stephen R. Whiteley 2024-09-29