12

---

CDBA Relative Object Design Functions

---

This chapter describes Relative Object Design (ROD) C database functions.

• For more information about ROD objects, refer to the Virtuoso Relative Object Design User Guide

Overview

Virtuoso relative object design (ROD) is functionality for defining simple and complex layout objects and their relationships to each other, without the need to use low-level Cadence SKILL language functions. ROD lets you create objects and define their relationships at a high level of abstraction, so you can concentrate on your design objectives. ROD automatically handles the intricacies of traversing the design hierarchy and simplifies the calculations required to create and align geometries.

With a single ROD function call, you can accomplish a task that otherwise would require several lower-level SKILL function calls. For example, creating a pin required a series of low-level SKILL function calls, but with ROD, you use a single function to create a shape and designate it as a pin. You can create entities such as guard rings, contact arrays, and transistors with one function call. You can also create an object from an existing object just by specifying the size of the new object.

About ROD Objects and ROD Object IDs

Every named database object, such as an instance, layout cellview, or named shape, automatically has relative object design information associated with it. This information is stored in a ROD object. A ROD object is also a database object, but it exists in relation to its associated named database object. A ROD object is identified by a unique ROD object ID.

A ROD object for a named shape, instance, or cellview contains the following information:

hierarchical name
cellview ID
database ID
transformation information (rotation, magnification, and offset)
alignment information, if any
number of segments (for shapes)
names and values of user-defined handles, if any
names of system-defined handles

A ROD object ID is similar to a database ID. The database ID for an object is the temporary address in memory for the object. A ROD object ID is the temporary address for the ROD object associated with a specific database object. When you look at these two IDs in the Command Interpreter Window (CIW) for a database object, the database ID might be db:98342974 and the ROD object ID rodObj:23970843.

cvId	ID of the top-level cellview containing the ROD object.
dbId	Database ID of the ROD object at the lowest level. For multipart paths, dbId identifies the master path.

Named Objects

ROD lets you assign a name to a zero-level object (an ordinary database shape, such as a rectangle or polygon) either by naming an existing object or by using a ROD function to create an object. You can access information through hierarchy about named objects, such as instances and named shapes.

Hierarchical Name

To access information about a named shape or instance through hierarchy, use its hierarchical name and the top-level cellview ID. A hierarchical name consists of the names of the instances through which you need to descend to reach the desired named shape or instance.

The following figure shows the hierarchy in a layout cellview containing the named shape polyRect. Its hierarchical name is INV1/ptr1/polyRect.

When you name an existing database shape using the ROD naming function, the function creates ROD information associated with the shape. This information is stored in a ROD object and is identified by a unique ROD object ID. The information contained in a ROD object includes its name and database ID. When you create a new shape with a ROD creation function, the function creates a named database shape and a ROD object.

Boolean Query Functions

rodIsMPPMaster

Boolean

rodIsMPPMaster(
dbId           id
);

Description

Determines if the specified id is the dbId for the master path of a ROD multipart path.

A multipart path (MPP) is a single ROD object consisting of one or more parts at level zero in the hierarchy on the same or on different layers.

A multipart path consists of a single master path and one or more subparts. The master path is an ordinary path; however, it is the defining part of a multipart path; all subparts are based on the master path. The subparts can be any combination of offset subpaths, enclosure subpaths, and sets of subrectangles.

Arguments

id	The database id for the master path of a ROD multipart path.

Return Values

Boolean

Returns TRUE if the specified id is the dbId for the master path of a ROD multipart path. Returns FALSE otherwise.

rodIsMPRMaster

Boolean

rodIsMPRMaster(
dbId           id
);

Description

Determines if the specified id is the dbId for the master rectangle of a ROD multipart rectangle.

A multipart rectangle (MPR) is a single ROD object consisting of one or more parts at level zero in the hierarchy on the same or on different layers.

A multipart rectangle consists of a single master rectangle and one or more subparts. The master rectangle is an ordinary rectangle; however, it is the defining part of a multipart rectangle; all subparts are based on the master rectangle. The subparts can be any combination of offset subrectangles, enclosure subrectangles, and sets of subrectangles.

Arguments

id	The database id for the master rectangle of a ROD multipart rectangle.

Return Values

Boolean

Returns TRUE if the specified id is the dbId for the master rectangle of a ROD multipart rectangle. Returns FALSE otherwise.

rodIsMPPMasterChoppable

Boolean

rodIsMPPMasterChoppable(
dbId           id
);

Description

Determines if the specified id is the dbId for the master path of a ROD multipart path and if that master path is choppable.

When the master path is choppable, then all of its subpaths and subrectangles must be choppable also. When the master path is not choppable, each subpath or set of subrectangles may be choppable or not choppable.

Arguments

id	The database id for the master path of a ROD multipart path.

Return Values

Boolean

Returns TRUE if the specified id is the dbId for the master path of a ROD multipart path and if that master path is choppable. Returns FALSE otherwise.

rodIsMPPSubShape

Boolean

rodIsMPPSubShape(
dbId           id
);

Description

Determines if the specified id is a dbId for a subshape that is part of a ROD multipart path. The master path is not considered a subshape.

Arguments

id	The database id for the master path of a ROD multipart path.

Return Values

Boolean

Returns TRUE if the specified id is a dbId for a subshape that is part of a ROD multipart path. Returns FALSE otherwise. The master path is not considered a subshape; if the specified id is the dbId for the master path of a ROD multipart path, FALSE is returned.

rodIsObj

Boolean

rodIsObj(
rodObjectId       objId
);

Description

Determines if the specified object objId is truly a ROD object.

Arguments

objId

ROD object id for the object tested.

Return Values

Boolean

Returns TRUE if the specified object objId is truly a ROD object. Returns FALSE otherwise.

rodIsObjAligned

Boolean

rodIsObjAligned(
rodObjectId           objId
);

Description

Determines if the specified ROD object objId is aligned.

Arguments

objId

ROD object id for the object tested.

Return Values

Boolean

Returns TRUE if the specified ROD object objId is aligned. Returns FALSE otherwise.

rodIsObjShape

Boolean

rodIsObjShape(
dbId           id
)

Description

Determines if the specified id is the database Id of a ROD object or is a subshape in a ROD multipart path or in a multipart rectangle.

Arguments

id	The dbId of a ROD object or a subshape in a ROD multipart path.

Return Values

Boolean

Returns TRUE if the specified id is the dbId of a ROD object or is a subshape in a ROD multipart path. Returns FALSE otherwise.

Object Query Functions

rodGetObjByDbId

rodObjectId

rodGetObjByDbId(
dbId           id
);

Description

Finds a ROD object specified by dbId.

The dbId is the database id of the ROD object at the lowest level. For multipart paths, dbId identifies the master path, for multipart rectangles it identifies the master rectangle.

Arguments

id	The dbId of a ROD object.

Return Values

rodObjectId

ROD object id for the object specified by dbId.

rodGetObjByName

rodObjectId

rodGetObjByName(
String         hierName,
dbCellViewId   cvId
);

Description

Finds a ROD object id specified by hierarchical name.

Arguments

hierName	The hierarchical name of a ROD object.
cvId	dbCellViewId, the top-level cellview containing the ROD object.

Return Values

rodObjectId

The ROD object id specified by the hierarchical name hierName.

rodGetObjDbId

dbId

rodGetObjDbId(
rodObjectId      objId
);

Description

Returns the dbId of the specified ROD object. It first checks to make sure the objId passed represents a ROD object.

Arguments

objId

ROD object id for the object.

Return Values

dbId	The database id for the associated object.

rodGetObjName

String

rodGetObjName(
rodObjectId      objId
);

Description

Returns the hierarchical name of the specified ROD object. The name is constructed in a static string. It first checks to make sure the objId passed in.

Arguments

objId

ROD object id for the object.

Return Values

String

The hierarchical name of the associated object.

rodGetObjTransform

dbTransform

rodGetObjTransform(
rodObjectId       objId
);

Description

Returns the transform of the specified ROD object.

Arguments

objId

ROD object id for the object.

Return Values

dbTransform

The transform of the associated object.

Multipart Path Functions

rodDeleteAllMPPs

Boolean

rodDeleteAllMPPs(
dbCellViewId     cvId,
Boolean          immediateUpdate
);

Description

Deletes all of the multipart paths (MPPs) in the specified cellview.

Arguments

cvId	The dbCellViewId, the id of the top-level cellview containing the ROD object.
immediateUpdate	The immediateUpdate flag.

Return Values

Boolean

Returns TRUE if successful. If the immediateUpdate flag is on, it also immediately calls rodiUpdate. Returns FALSE otherwise.

rodExplodeMPP

Boolean

rodExplodeMPP(
dbPathId       pathId
);

Description

Changes the MPP into an ordinary path and its subparts into ordinary paths and rectangles; all ROD attributes such as names and alignment are lost.

Arguments

pathId

The dbPathId of the MPP master path.

Return Values

Boolean

Returns TRUE if successful. Returns FALSE otherwise.

rodGetMPPSubShapeMaster

dbIdm

rodGetMPPSubShapeMaster(
dbId           id
);

Description

Returns the database id of the master path for the specified id if the id is a dbId for a subshape that is part of a ROD multipart path. The function returns dbcNullId otherwise. dbcNullId is returned if the specified id is the dbId for the master path of a ROD multipart path. The master path is not considered a subshape.

Arguments

id	The dbId for a subshape that is part of a ROD multipart path.

Return Values

dbIdm

The database id for the master path of a MMP for which the specified id identifies a subshape.

Multipart Path Subshape Generation Functions

rodStartGenMPPDbIds

rodMPPGenStateId

rodStartGenMPPDbIds(
dbPathId        pathId
);

Description

Generates the MPP subshape database ids.

Arguments

pathId

The database id of the MPP master path.

Return Values

rodMPPGenStateId

The MPP subshape database ids.

rodGenMPPDbId

dbId

rodGenMPPDbId(
rodMPPGenStateId   stateId
);

Description

Returns the a pointer to the next MPP subshape dbId. When done, returns dbcNullId.

Arguments

stateId

The stateId generated by the rodStartGenMPPDbIds function.

Return Values

dbId	The dbcNullId.

rodStopGen

void

rodStopGen(stateId)

Description

Frees the storage used by the generation control block.

Arguments

stateId

The stateId of the path.

Multipart Rectangle Functions

rodGetMPRSubShapeMaster

dbId

rodGetMPRSubShapeMaster(
dbId           id
);

Description

Returns the database id of the master rectangle for the specified id if the id is a dbId for a subpart that is part of a ROD multipart rectangle. The function returns dbcNullId otherwise. dbcNullId is returned if the specified id is the dbId for the master rectangle of a ROD multipart rectangle. The master rectangle is not considered a subpart.

Arguments

id	The dbId for a subshape that is part of a ROD multipart rectangle.

Return Values

dbId	The database id for the master rectangle of a MPR for which the specified id identifies a subpart.

rodExplodeMPR

Boolean

rodExplodeMPR(
dbRectId       rectId
);

Description

Changes the MPR into an ordinary rectangle and its subparts into ordinary parts and rectangles; all ROD attributes such as names and alignment are lost.

Arguments

rectId

The dbRectId of the MPR master rectangle.

Return Values

Boolean

Returns TRUE if successful. Returns FALSE otherwise.

rodReCreateMPR

Boolean

rodReCreateMPR(
dbRectId       rectId
);

Description

Re-creates a MPR. Removes all old dbIds and creates new ones.

Arguments

rectId

The dbRectId of the MPR master rectangle.

Return Values

Boolean

Returns TRUE if successful. Returns FALSE otherwise.

Multipart Rectangle Subshape Generation Functions

rodGetMPRRecId

rodMPRRecId

rodGetMPRRecId(
dbId           id
);

Description

Returns the MPR recId if the dbId is an MPR master.

Arguments

id	The dbId for a subpart that is part of a ROD multipart rectangle.

Return Values

rodMPRRecId

The MPR record id.

rodStartGenMPRSubParts

rodStartMPRSubParts(
dbId        Id
);

Description

Allocates a rodMPRGenState then fills it with an array of rodMPRSubPart pointers

Arguments

Id	The database id of the MPR master rectangle.

Return Values

Returns a null pointer.

rodStartGenModMPRSubParts

rodMPRGenStateId

rodStartGenModMPRSubParts(
rodMPRRecId        MPRRecId
dbBBox       *bBox
);

Description

Modifies the MPR structures according to the new bounding box.

Arguments

MPRRecId	The database id of the MPR master rectangle.
bBox	The database id of the MPR master rectangle bounding box.

Return Values

rodMPRGenStateId

The MPR genState Ids.

rodGenMPRSubParts

*rodMPRSubPart

rodGenMPRSubParts(
rodMPRGenStateId   stateId
);

Description

Returns the pointer to the next MPRSubPart dbId. When done, returns dbcNullId.

Arguments

stateId

The stateId generated by the rodStartGenMPRSubParts function.

Return Values

*rodMPRSubPart

The pointer to rodMPRSubPart.

rodGenMPRDbId

dbId

rodGenMPRDbId(
rodMPRGenStateId          stateId
);

Description

Returns the pointer to the next MPR dbId.

Arguments

stateId

The dbId for a subshape that is part of a ROD multipart rectangle.

Return Values

dbId	The database id.

rodStartGenMPRDbIds

rodMPRGenStateId

rodStartGenMPRDbIds(
dbRectId        rectId
);

Description

Starts to generates the MPR subshape database ids.

Arguments

rectId

The database id of the MPR master rectangle.

Return Values

rodMPRGenStateId

The MPR genState id.

rodStopGenMPR

void

rodStopGenMPR(
rodMPRenStateId           stateId
);

Description

Frees the storage used by the MPR generation control block.

Arguments

stateId

The stateId of the MPR.

rodIsMPRSubShape

Boolean

rodIsMPRSubShape(
dbId           id
);

Description

Determines if the specified id is a dbId for a subshape that is part of a ROD multipart rectangle. The master path is not considered a subshape.

Arguments

id	The dbId for the master path of a ROD multipart rectangle.

Return Values

Boolean

Returns TRUE if the specified id is a dbId for a subshape that is part of a ROD multipart rectangle. Returns FALSE otherwise. The master path is not considered a subshape; if the specified id is the dbId for the master path of a ROD multipart rectangle, FALSE is returned.

Name, Unalign, Unname Functions

rodNameShape

rodObjectId

rodNameShape(
String          name,
dbShapeId       shapeId
);

Description

Names the specified shapeId making it a ROD object.

Assigns a name to an unnamed database shape or renames a ROD shape. Creates (or updates) a ROD object containing information associated with the shape, including its name and database ID. The associated ROD object is identified by a ROD object ID. You can assign a name to any of the following shapes:

rectangle
polygon
path
line
dot
label
text-display object

You can refer to a named shape through hierarchy using its hierarchical name.

To assign a name to an unnamed shape, you must identify the shape by its database ID. You can specify a name that is unique within the cellview or let the system generate a name. If you attempt to assign a name to an object that already has a name, the system displays an error message.

Before assigning a name, you might want to verify that the string is a valid name and that it has not already been used in the cellview. To do this, use the rodIsFigNameUnused SKILL function.

Arguments

name	Character string or symbol specifying the name you want to assign to the shape.
	The name cannot contain hierarchy, where hierarchy is indicated by one or more slashes. For example, at the lowest level in the hierarchy (zero-level), you can assign the name polyRect. You cannot assign a name with implied hierarchy, such as I1/I2/polyRect.
	When you do not specify a name, the system determines whether the shape is a rectangle, polygon, path, line, dot, label, and/or text-display object and assigns a name indicating the shape. For rectangles, the system assigns rect0 to the first rectangle you name in the cellview, rect1 to the second, and so on. For polygons, the system assigns polygon0, polygon1, and so on; for paths, pathn. For a dot, line, label, and/or text-display object, the system assigns dotn, linen, labeln, or textn, respectively. For a shape other than these, the system issues a warning message and the function fails. Default: rectn, polygonn, pathn, dotn, linen, labeln, or textn, as determined by the system
shapeId	Database of unnamed shape. (Instances and mosaics are not shapes.) This argument is required.

Return Values

rodObjectId

The ROD object id for the named shape.

rodUnAlign

Boolean

rodUnAlign(
rodObjectId      objId1,
rodObjectId      objId2
);

Description

When you specify only one ROD object id, removes all alignments for the object specified. When you specify two ROD object ids, removes only the alignment between the two objects.

Arguments

objId1	ROD object id for the first or only object for which you want to remove alignments. When objId2 is specified, only the alignments between the two objects are removed. When objId2 is not specified, all alignments for objId1 are removed. This argument is required.
objId2	ROD object ID for the second object for which you want to remove alignments. When specified, only the alignment between objId2 and objId1 are removed.

Return Values

Boolean

Returns TRUE if successful. Returns FALSE otherwise.

rodUnNameShape

Boolean

rodUnNameShape(
rodObjectId      objId
);

Description

Removes the ROD name from the dbId of the specified ROD object, so afterwards it is no longer a named shape. The ROD object id for the shape and all other ROD information is deleted. If the object is an instance, the instance keeps its name but all other ROD information is deleted. Also removes all ROD alignment constraints that reference the shape.

Arguments

objId

ROD object id that identifies the shape for which you want to remove the name.

Return Values

Boolean

Returns TRUE if successful. Returns FALSE otherwise.

Handle Functions

rodGetHandle

Boolean

rodGetHandle(
rodObjectId      objId,
String           name,
rodHandleType    *pHandleType,
rodHandleValue   *pHandleValue
);

Description

Implements the ROD user function rodGetHandle.

The ROD user function rodGetHandle returns the value of a system- or user-defined handle. You specify the handle name and the ROD object id for the object with which the handle is associated.

For Boolean handles, the value can be either t or nil. When the value is nil, rodGetHandle returns an ambiguous result: nil could mean that the handle was not found or that the value of the handle is nil. To avoid ambiguity for Boolean handles, verify that the handle exists with the rodIsHandle function before you try to access it.

Arguments

objId	ROD object id for the object with which the handle is associated.
name	Character string or symbol specifying the name of the handle whose value is returned.
pHandleType	The type of handle returned.

Type of Handle	Applies to...
Bounding Box Handles	All ROD objects except dots, labels, and text display objects
Bounding Box Width and Length Handles	All ROD objects except dots, labels, and text display objects
ppBBox	ROD multipart paths
Segment Point Handles	ROD rectangles, polygons, and paths
Segment Length Handles	ROD rectangles, polygons, and paths

You can define your own handles to store points, calculations, and other information. When you define a new handle, you specify the name (or let it default) and assign a value. The values of user-defined handles are stored in the database. The information stored can have any of the following data types: point integer Boolean floating-point number string SKILL expression If you let the name of your new handle default, the system assigns a name unique within the cellview, as follows: handle0, handle1, handle2, and so on.

pHandleValue

The value of the handle returned.

Return Values

Boolean

Returns TRUE if successful. Returns FALSE otherwise.

rodGenStateId

rodGenStateId

rodStartGenNamedShape(
dbCellViewId    cvId
);

Description

Allocates a rodGenState control block and fills it in, setting things up for rodGenNamedShape, which returns one rodObjectId at a time when it is called.

Arguments

cvId	The cellview id in which to generate the ROD named shapes.

Return Values

rodGenStateId

Unique generator state id for use with subsequent calls to rodGenNamedShape.

rodGenNamedShape

Boolean

rodGenNamedShape(
rodGenStateId     stateId,
rodObjectId       objId
);

Description

Returns TRUE if there was another rodObjectId generated to fill in the return argument objId. Returns FALSE otherwise.

Arguments

stateId	The stateId generated by the rodGenNamedShape function.
objId	The ROD object id.

Return Values

Boolean

Returns TRUE if successful. Returns FALSE otherwise.

Return to top