Table of Contents Previous Chapter

5.10 Port Functions

5.10.1 cfidrPortGetOwner

DECLARATION
cfidrObjectIdT cfidrPortGetOwner(
cfidrPortIdT port,
cfidrErrorT *error)
This function returns the object (View or PortBundle) at the end of the Owner relationship for the Port specified by port.

The return value is a cfidrObjectIdT referring to the View or PortBundle at the end of the Owner relationship. If an error occurs, a Null OID is returned.

port (input) The OID of the Port whose Owner relationship is to be followed.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
port is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
port is not the OID of a Port

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The Owner relationship is defined when an object is created but can be modified later by the cfidrPortSetOwnerView() and cfidrPortSetOwnerPortBundle() functions.

POST-CONDITIONS
Use the cfidrObjectGetObjectType() function to determine the Owner's object type.

REFERENCE
cfidrObjectGetObjectType()
cfidrPortSetOwnerPortBundle()
cfidrPortSetOwnerView()

5.10.2 cfidrPortGetPosition

cfidrInt32T cfidrPortGetPosition(
cfidrPortIdT port,
cfidrErrorT *error)
This function returns the position of the specified port in its owner.

The return value is a cfidrInt32T. If an error occurs, a -1 is returned.

port (input) The OID of a Port.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
port is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
port is not the OID of a Port.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The owner of the Port may be either the View or a PortBundle (or PortBus).

POST-CONDITIONS
The returned position will be 0 for the first Port in the owner up to size-1 for the last position, where size is the number of ports in the list of ports owned by port's owner.

REFERENCE
cfidrPortSetOwnerPortBundle()
cfidrPortBundleCreatePortBundle()
cfidrNetlistViewCreatePortBundle()

5.10.3 cfidrPortSetOwnerPortBundle

DECLARATION
cfidrVoidT cfidrPortSetOwnerPortBundle(
cfidrPortIdT port,
cfidrPortBundleIdT owner,
cfidrInt32T position,
cfidrErrorT *error)
This function changes the Owner of the specified Port to the PortBundle specified by owner and inserts it at the specified position. The port is removed from its previous parent (either PortBundle or View) in the process.

port (input) The OID of the Port whose owner is to be changed.

owner (input) The OID of the new owning PortBundle.

position (input) The desired location of the port within its new owner PortBundle. If position is less than 0 or greater than or equal to the number of members in the list of Ports owned by owner, the new Port is appended as the last member of the list. Otherwise, it is inserted at the specified position in the list (0 is the first member).

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating memory for this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
port is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
port is not the OID of a Port.

CFIDR_UNUSABLE_PORTBUNDLE_OID:
owner is not a usable OID.

CFIDR_INVALID_PORTBUNDLE_TYPE:
owner is not the OID of a PortBundle

CFIDR_NAME_IN_USE:
the name of the Port matches the name of a Port already owned by the PortBundle.

NOTE: This code is not returned when only the position is being changed but not the owner.
CFIDR_CROSS_VIEW_OPERATION:
the owner PortBundle and the port member belong to different Views.

CFIDR_MEMBER_RECURSION:
the owner and port OIDs refer to the same object.

CFI_READ_ONLY:
the containing View has not been opened for update.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
Both the Port and PortBundle must belong to the same parent View.

The name of the Port must be unique with respect to all other Ports owned by the owner PortBundle.

It is not permitted to add a Port as a member of itself.

The port may already be a member of the specified owner PortBundle. In this case only the position is changed (if it is different from the previous Position). Do not return the code CFIDR_NAME_IN_USE in this case.

POST-CONDITIONS
If port is already a member of a PortBundle, it will be removed from the list of members of its current owner. All remaining members of that list will be moved down one position.

If port is a member of a NetlistView, it will be removed from the list of members of that NetlistView. All remaining members of that list will be moved down one position.

The Port is added to the list of Ports owned by owner at position. If position = 0, the new Port will be added as the first member of the list. If position is less than 0 or greater than or equal to the number of members in the list, the new Port is appended to the end of the list. Otherwise, the Port is inserted at the specified position (0 based). The position of all members whose positions were greater than or equal to position, will have their position incremented by 1.

For example, presume a View has Port members:
View Ports = {A, B, C0, 1, 2}

and PortBundle B has members:
B's Port members = {b1, b2, b3}

Setting the owner of Port C0 to position 1 of B results in:
View ports = {A, B, 1, 2}
B's port members = {b1, C0, b2, b3}.

Position specifies the position of the Port *AFTER* the function executes, even in the case where Owner specifies the current owner of Port.

If the Port is connected to a Net, then an implicit detach of the parent bundles will result if that was the last such connection, and an implicit attach of the new parent bundles will result if it is the first such connection.

See the discussion, "NetBundle Connection to Port[Inst]Bundle is a Derived Relationship" on page 4-35, for additional implications.

REFERENCE
cfidrPortSetOwnerView()
cfidrPortBundleGetPorts()
cfidrPortBundleCreatePortBundle()
cfidrNetlistViewCreatePortBundle()

5.10.4 cfidrPortSetOwnerView

DECLARATION
cfidrVoidT cfidrPortSetOwnerView(
cfidrPortIdT port,
cfidrInt32T position,
cfidrErrorT *error)
This function changes the Owner of a Port owned by a PortBundle to the NetlistView which was its ultimate, indirect owner. If the Port is already owned by a NetlistView the Owner is not changed. The Port specified by port is then moved (if necessary) such that its final position in the Ports of the NetlistView is position.

port (input) The OID of the Port whose Owner is to be changed.

position (input) The desired location of the port within the NetlistView. If position is less than 0 or greater than or equal to the number of members in the list of Ports owned by owner, the new Port is appended as the last member of the list. Otherwise, it is inserted at the specified position in the list (0 is the first member).

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating memory for this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
port is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
port is not the OID of a Port (PortBundle, PortBus, or PortScalar).

CFIDR_NAME_IN_USE:
the name of the Port matches the name of a Port already owned by the NetlistView.

CFIDR_READ_ONLY:
the containing View has not been opened for update.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
If the Port is owned by a PortBundle, the name of the Port must be unique with respect to all other Ports owned by the NetlistView which is the ultimate owner of the PortBundle.

The Port may be owned by a NetlistView. In this case only the Position will be changed (if the specified position is different than the current Position). Do not return the code CFIDR_NAME_IN_USE in this case.

POST-CONDITIONS
If port is owned by a PortBundle, it is removed from that PortBundle.

If port is owned by a PortBundle the ultimate owning NetlistView is determined by getting the Owner of the PortBundle. If Owner is a PortBundle then Owner of that PortBundle is obtained. This is repeated until an Owner of type NetlistView is returned.

The positions of all Ports within its previous Owner that are greater than or equal to the port's original Position will be decremented by one.

The Port is then inserted in the list of Ports of the NetlistView at position. If position = 0, the new Port will be added as the first member of the list. If position is less than 0 or greater than or equal to the number of members in the list, the new Port is appended to the end of the list. Otherwise, the Port is inserted at the specified position (0 based). The position of all members whose positions were greater than or equal to position, will have their position incremented by 1.

For example, presume a View has Port members:
View Ports = {A, B, C0, 1, 2}

and PortBundle B has members:
B's Port members = {b1, b2, b3}

Setting the owner of Port b2 to position -1 of the NetlistView results in:
View ports = {A, B, C0, 1, 2, b2}
B's port members = {b1, b3}.

Position specifies the position of the Port *AFTER* the function executes, even in the case where Owner specifies the current owner of Port.

If the Port is connected to a Net, then an implicit detach of the parent bundles will result if that was the last such connection.

See the discussion, "NetBundle Connection to Port[Inst]Bundle is a Derived Relationship" on page 4-35, for additional implications.

REFERENCE
cfidrPortSetOwnerPortBundle()
cfidrPortBundleGetPorts()
cfidrPortBundleCreatePortBundle()
cfidrNetlistViewCreatePortBundle()

5.10.5 cfidrPortBundleCreatePortBundle

DECLARATION
cfidrPortBundleIdT cfidrPortBundleCreatePortBundle(
cfidrPortBundleIdT owner,
cfidrStringT name,
cfidrInt32T position,
cfidrErrorT *error)
This function creates a PortBundle object owned by the PortBundle specified via owner.

The return value is a cfidrPortBundleIdT referring to the PortBundle object just created. If an error occurs, a Null OID is returned.

owner (input) The OID of the PortBundle owning the PortBundle being created.

name (input) The string representing the name of the PortBundle being created.

position (input) The integer specifying the position of the PortBundle in the list of Ports owned by owner. A position value less than 0 or greater than or equal to the number of ports indicates the new PortBundle is put at end of the list. Any other value, including 0, indicates the actual position in the list.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a PortBundle.

CFIDR_READ_ONLY:
the containing View has not been opened for update.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_NAME_IN_USE:
the name parameter specifies a name already in use in the same name scope but not for a PortBundle.

CFIDR_OBJECT_ALREADY_EXISTS:
a PortBundle with the same name already exists for this owner.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The name argument must conform to the character set rules for name strings.

A Port named name that is owned by the same PortBundle as specified by owner cannot already exist.

POST-CONDITIONS
The PortBundle is created with no members initially. Later, Ports or PortBundles may either be created in or have their owner changed to be this PortBundle. Furthermore, this PortBundle may later have its owner changed to the View or to another PortBundle.

The PortBundle is created and added to the list of Ports owned by the PortBundle specified by owner at the position specified by position. If position = 0, the new PortBundle will be added as the first member of the list. If position is less than 0 or greater than or equal to the number of members in the list, the new PortBundle is appended to the end of the list. Otherwise, the PortBundle is inserted at the specified position (0 based). The position of all Ports whose positions were greater than or equal to position, will have their position incremented by 1. For example, presume the owner initially has Ports:
A, B, C0, 1, 2.

Adding a new member X at position 1 results in:
A, X, B, C0, 1, 2
Note that B had position 1 before and has position 2 after X is created.

Adding X at position 0 causes X to be at the beginning of the list:
X, A, B, C0, 1, 2

Adding X at an invalid position such as -1 (or any value greater than 4) causes creation of the new member at the end of the list:
A, B, C0, 1, 2, X

REFERENCE
cfidrPortBundleGetOwner()
cfidrPortBundleGetPorts()
cfidrPortSetOwnerPortBundle()
cfidrPortSetOwnerView()
cfidrNetlistViewCreatePortBundle()
cfidrNetlistViewCreatePortScalar()
cfidrNetlistViewGetPorts()

5.10.6 cfidrPortBundleCreatePortBus

DECLARATION
cfidrPortBusIdT cfidrPortBundleCreatePortBus(
cfidrPortBundleIdT owner,
cfidrStringT name,
cfidrInt32T position,
cfidrInt32T start
cfidrInt32T step
cfidrErrorT *error)
This function creates a PortBus object located at the position position in the list of Ports owned by the PortBundle specified via owner. The PortBus Name attribute is set to name. The PortBus Start attribute is set to start. The PortBus Step attribute is set to step.

The return value is a cfidrPortBusIdT referring to the PortBus object just created. If an error occurs, a Null OID is returned.

owner (input) The OID of the PortBundle owning the PortBus being created.

name (input) The string representing the name of the PortBus being created.

position (input) The integer specifying the position of the PortBus in the list of Ports owned by owner. A position value less than 0 or greater than or equal to the number of ports indicates the new PortBus is put at end of the list. Any other value, including 0, indicates the actual position in the list.

start (input) The Int32 defining the index of position 0 in the bus.

step (input) The Int32 defining the difference in indexes of positions n and n+1 in the bus. This number must be non-zero.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a PortBundle.

CFIDR_READ_ONLY:
the containing View has not been opened for update.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_NAME_IN_USE:
the name parameter specifies a name already in use in the same name scope but not for a PortBus.

CFIDR_OBJECT_ALREADY_EXISTS:
a PortBus with the same name already exists.

CFIDR_INVALID_VALUE
Step is 0.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The name argument must conform to the character set rules for name strings.

A Port (PortScalar, PortBundle, or PortBus) with the given name cannot already exist in the PortBundle specified by owner.

POST-CONDITIONS
The newly created PortBus will initially have no members and a size of 0.

The PortBus created by this function can later be changed to have a different PortBundle as its owner using the cfidrPortSetOwnerPortBundle() function or to have a View as its owner using the cfidrPortBundleSetOwnerView() function.

The Start and Step attributes may be changed later by use of the cfidrPortBusSetStart() and cfidrPortBusSetStep() functions.

REFERENCE
cfidrPortBundleGetSize()
cfidrPortBundleGetNets()
cfidrPortBundleGetPorts()
cfidrPortBundleSetOwnerView()
cfidrPortBusGetStart()
cfidrPortBusGetStep()
cfidrPortBusSetStart()
cfidrPortBusSetStep()
cfidrPortSetOwnerPortBundle()
cfidrNetlistViewGetPorts()

5.10.7 cfidrPortBundleCreatePortScalar

DECLARATION
cfidrPortScalarIdT cfidrPortBundleCreatePortScalar(
cfidrPortBundleIdT owner,
cfidrStringT name,
cfidrInt32T position,
cfidrPortDirectionT direction,
cfidrErrorT *error)
This function creates a PortScalar object owned by the PortBundle specified via owner and located at position in the list of Ports owned by owner. The PortScalar name attribute is set to name. The PortScalar direction attribute is set to direction.

The PortScalar is created with all required attributes set including the derived attribute of position.

The return value is a cfidrPortScalarIdT referring to the PortScalar just created. If an error occurs a Null OID is returned.

owner (input) The OID of the PortBundle owning the PortScalar to be created.

name (input) The string representing the name of the PortScalar.

position (input) The integer specifying the position of the PortScalar in the list of Ports owned by owner. A position value less than 0 or greater than or equal to the number of ports indicates the new Port is put at end of the list. Any other value, including 0, indicates the actual position in the list.

direction (input) The Direction attribute to assign to the created PortScalar.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a PortBundle.

CFIDR_READ_ONLY:
the containing View has not been opened for update.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_NAME_IN_USE:
the name parameter specifies a name already in use in the same name scope but not for a PortScalar.

CFIDR_OBJECT_ALREADY_EXISTS:
a PortScalar with the same name already exists for owner.

CFIDR_INVALID_DIRECTION:
direction is not a legal PortDirection.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The name argument must conform to the character set rules for name strings.

A Port (Scalar, Bundle, or Bus) with the given name cannot already be owned by the PortBundle specified by owner. However, a Port with the same name may exist indirectly in the View or in another PortBundle. This is allowed since the scope of Port names is the owning View or the owning PortBundle.

POST-CONDITIONS
The owner of the PortScalar created by this function can later be changed to the View or to a PortBundle provided no other Port has the same name in the new owner.

The PortScalar is created and added to the list of Ports owned by the NetlistView specified by owner at the position specified by position. If position = 0, the new PortScalar will be added as the first member of the list. If position is less than 0 or greater than or equal to the number of members in the list, the new PortScalar is appended to the end of the list. Otherwise, the PortScalar is inserted at the specified position (0 based). The position of all Ports whose positions were greater than or equal to position, will have their position incremented by 1. For example, presume a View has Ports:
A, B, C0, 1, 2.

Adding a new member X at position 1 results in:
A, X, B, C0, 1, 2
Note that B had position 1 before and has position 2 after X is created.

Adding X at position 0 causes X to be at the beginning of the list:
X, A, B, C0, 1, 2

Adding X at an invalid position such as -1 (or any value greater than 4) causes creation of the new member at the end of the list:
A, B, C0, 1, 2, X

REFERENCE
cfidrPortBundleCreatePortBundle()
cridrPortBundleCreatePortScalar()
cfidrPortBundleGetOwner()
cfidrPortBundleGetPorts()
cfidrPortSetOwnerPortBundle()
cfidrPortSetOwnerView()
cfidrNetlistViewGetPorts()

5.10.8 cfidrPortBundleFindPortByName

DECLARATION
cfidrPortIdT cfidrPortBundleFindPortByName(
cfidrPortBundleIdT portBundle,
cfidrStringT name,
cfidrErrorT *error)
This function returns the Port with the specified name that is within the Ports relationship defined for the PortBundle specified by portBundle.

The return value is a cfidrPortIdT referring to the Port just found. If an error occurs, a Null OID is returned.

portBundle (input) The OID of the PortBundle from which the Port is to be found.

name (input) The name of the Port.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating memory for this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portBundle is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portBundle is not the OID of a PortBundle.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_OBJECT_NOT_FOUND:
no Port with the specified name exists.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
Only the immediate list of Ports directly owned by the specified portBundle is searched by this function. Thus a Port that is indirectly owned by this portBundle will not be returned by this function.

5.10.9 cfidrPortBundleFindPortByPosition

cfidrPortIdT cfidrPortBundleFindPortByPosition(
cfidrPortBundleIdT portBundle,
cfidrInt32T position
cfidrErrorT *error)
This function returns the Port at the specified position within the specified portBundle. The "leftmost" or first position is numbered 0 and the "rightmost" or last position is numbered one less than the size of the bundle.

The return value is a cfidrPortIdT referring to the Port just found. If an error occurs, a Null OID is returned.

portBundle (input) The OID of the PortBundle being accessed.

position (input) The position of the returned Port in the PortBundle. A value of 0 will return the Port at the first position. A value one less than the size of the bundle will return the Port at the last position. A value greater than or equal to the size of the bundle or any negative value will cause an error.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portBundle is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portBundle is not the OID of a PortBundle.

CFIDR_INVALID_POSITION:
the position parameter is not in the range 0 to one less than the size of the bundle.

NOTE: If the bundle size is 0, this code is returned since no position is valid.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

REFERENCE
cfidrPortSetOwnerPortBundle()
cfidrPortBundleCreatePort()
cfidrNetlistViewCreatePortBundle()

5.10.10 cfidrPortBundleGetNetBundles

DECLARATION
cfidrNetBundlesIdT cfidrPortBundleGetNetBundles(
cfidrPortBundleIdT portBundle,
cfidrErrorT *error)
This function initiates a traversal of all of the NetBundles at the end of the NetBundles relationship defined for the PortBundle specified by portBundle. These are the NetBundles to which this PortBundle connects.

The return value is a cfidrNetBundlesIdT referring to an Iterator ID that iterates over NetBundles. A valid Iterator ID is always returned, even when an error occurs. In the case of an error, calling the cfidrIterNextNetBundle() function returns a Null OID.

portBundle (input) The OID of a PortBundle for which the NetBundles relationship is to be traversed.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portBundle is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portBundle is not the OID of a PortBundle.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
Returns all the NetBundles which are connected to the PortBundle passed in via portBundle. Essentially, this returns the NetBundles which directly or indirectly contain any NetScalars connected to PortScalars owned directly or indirectly by the PortBundle.

POST-CONDITIONS
The cfidrIterNextNetBundle() function returns the next NetBundle OID in the NetBundles relationship.

If no objects are currently present in the NetBundles relationship, an error is not returned but the first call to cfidrIterNextNetBundle() returns a Null OID.

REFERENCE
cfidrIterNextNet()
cfidrIterNextNetBundle()

5.10.11 cfidrPortBundleGetPorts

DECLARATION
cfidrPortsIdT cfidrPortBundleGetPorts(
cfidrPortBundleIdT portBundle,
cfidrIterModeT mode,
cfidrErrorT *error)
This function initiates a traversal of all of the Ports (PortBundles, PortBusses, or PortScalars) at the end of the Ports relationship defined for the PortBundle specified by portBundle.

The return value is a cfidrPortsIdT referring to an Iterator ID that iterates over Ports. A valid Iterator ID is always returned, even when an error occurs. In the case of an error, calling the cfidrIterNextPort() function returns a Null OID.

portBundle (input) The OID of a PortBundle for which the Ports relationship is to be traversed.

mode (input) The mode that determines which Ports are returned. The current valid values are CFIDR_ITER_SCALARS, CFIDR_ITER_BUNDLES, CFIDR_ITER_TOP, and CFIDR_ITER_ALL. See the Pre-Conditions below for more detail on how these modes behave.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portBundle is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portBundle is not the OID of a PortBundle.

CFIDR_INVALID_ITERMODE:
mode is not a valid IterMode.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
Ports directly in a PortBundle each have a unique Position in the list of Ports owned by the PortBundle. The positions in this list are numbered from 0 for the "leftmost" or first position monotonically increasing by 1 up to one less than the size of the list. The order in which the Ports are returned from any given PortBundle is by increasing position starting with 0. The Position of a given Port at a given time is determined by the various operations that have been performed on the list of Ports including:
(1) the position specified when a Port is created in the PortBundle,
(2) the position specified when the Port had its Owner set to this PortBundle,
(3) appearances and disappearances of Ports at or to the "left" of the Position of the given Port due to changes in those Port's Owner.

This function can also be used for PortBusses since they are a subtype of PortBundle.

POST-CONDITIONS
The returned list of Ports is accessed by using calls to cfidrIterNextPort() on the iterator returned by this function. Each iteration returns another Port OID that is directly or indirectly in the Ports relationship based on

(1) the value of the mode parameter and
(2) the Position of that Port in its Owner's Ports relationship and (other than for mode =CFIDR_ITER_TOP) any intervening levels of PortBundles.

If no objects are currently present in the Ports relationship under the specified mode, an error is not returned but the first call to cfidrIterNextPort() returns a Null OID.

The Ports that are included when iterating over the cfidrPortsIdT iterator returned from this function depends on the mode argument specified.

mode=CFIDR_ITER_TOP
Returns all those Ports (PortBundles, PortBusses, or PortScalars) which are directly owned by the PortBundle.

mode=CFIDR_ITER_SCALARS
Returns the PortScalars directly owned by portBundle and recursively owned by PortBundles owned by portBundle. No PortBundles are output with this mode, only PortScalars. The order is based on a depth-first recursion.

mode=CFIDR_ITER_BUNDLES
Returns all the PortBundles (including PortBusses) owned directly by portBundle and recursively by those PortBundles (and PortBusses). No PortScalars are output. The order is determined by depth-first recursion.

mode=CFIDR_ITER_ALL
Returns all the Ports (PortBundles, PortBusses, or PortScalars) directly or indirectly owned by portBundle. This mode combines the PortScalars returned when mode=CFIDR_ITER_SCALARS with the PortBundles returned when mode=CFIDR_ITER_BUNDLES.

For all values of mode except mode=CFIDR_ITER_TOP, note that the Port Name scoping rules state that Port Names need only be unique within the Ports of their Owner, which is either the View or a PortBundle. Thus, a Port may exist in the View while others with the same name exist in different PortBundles. Thus, in the Ports returned via these modes, the same name may appear more than once even though they are different Ports and have different OIDs. The function cfidrObjectIsSame() must be used in this case to determine if two Ports with the same name are actually the same object.

REFERENCE
cfidrIterNextPort()
cfidrObjectIsSame()
cfidrPortSetOwnerPortBundle()
cfidrPortSetOwnerView()

5.10.12 cfidrPortBundleGetSize

DECLARATION
cfidrInt32T cfidrPortBundleGetSize(
cfidrPortBundleIdT portBundle,
cfidrErrorT *error)
This function returns the number of Ports currently in the specified portBundle. This is only the number at the next level and not a count of the total number of scalars in the bundle.

The return value is a cfidrInt32T. If an error occurs, a -1 is returned.

portBundle (input) The OID of a PortBundle.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portBundle is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portBundle is not the OID of a PortBundle.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
PortBundles are created initially with Size zero. PortBundle members are created using cfidrPortBundleCreatePortBundle() and cfidrPortBundleCreatePortScalar(). PortBundle members are added and deleted via cfidrPortSetOwnerPortBundle() and cfidrPortSetOwnerView().

REFERENCE
cfidrPortSetOwnerPortBundle()
cfidrPortSetOwnerView()
cfidrPortBundleCreatePortBundle()
cfidrPortBundleCreatePortScalar()
cfidrNetlistViewCreatePortBundle()

5.10.13 cfidrPortBusGetStart

DECLARATION
cfidrInt32T cfidrportBusGetStart(
cfidrportBusIdT portBus,
cfidrErrorT *error)
This function returns the start attribute of the specified portBus. This specifies the first index value for this bus.

The return value is a cfidrInt32T. If an error occurs, a 0 is returned.

portBus (input) The OID of a PortBus.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portBus is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portBus is not the OID of a PortBus.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The start attribute of a PortBus is set at creation time or changed using cfidrPortBusSetStart().

REFERENCE
cfidrPortBundleCreatePortBus()
cfidrPortBusSetStart()
cfidrNetlistViewCreatePortBus()

5.10.14 cfidrPortBusGetStep

DECLARATION
cfidrInt32T cfidrPortBusGetStep(
cfidrPortBusIdT portBus,
cfidrErrorT *error)
This function returns the step attribute of the specified portBus. This specifies the numeric increment between positions for the index.

The return value is a cfidrInt32T. If an error occurs, a 0 is returned.

portBus (input) The OID of a PortBus.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portBus is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portBus is not the OID of a PortBus.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The Step attribute of a PortBus is set at creation time or changed using cfidrPortBusSetStep().

REFERENCE
cfidrPortBundleCreatePortBus()
cfidrPortBusSetStep()
cfidrNetlistViewCreatePortBus()

5.10.15 cfidrPortBusSetStart

DECLARATION
cfidrVoidT cfidrPortBusSetStart(
cfidrPortBusIdT portBus,
cfidrInt32T start,
cfidrErrorT *error)
This function sets the start attribute of the specified portBus. This specifies the first index value for this bus.

portBus (input) The OID of a PortBus.

start (input) The 32 bit integer number for the first (leftmost) index of the bus.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portBus is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portBus is not the OID of a PortBus.

CFIDR_READ_ONLY:
the containing View has not been opened for update.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
The Start attribute of the PortBus may be accessed using the function cfidrPortBusGetStart().

REFERENCE
cfidrPortBundleCreatePortBus()
cfidrPortBusGetStart()
cfidrNetlistViewCreatePortBus()

5.10.16 cfidrPortBusSetStep

DECLARATION
cfidrVoidT cfidrPortBusSetStep(
cfidrPortBusIdT portBus,
cfidrInt32T step,
cfidrErrorT *error)
This function sets the step attribute of the specified portBus. This specifies the numeric increment between positions for the index.

portBus (input) The OID of a PortBus.

step (input) The 32 bit integer number for the step. This number must be non-zero.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portBus is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portBus is not the OID of a PortBus.

CFIDR_INVALID_VALUE:
step is zero.

CFIDR_READ_ONLY:
the containing View has not been opened for update.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
The Step attribute of the PortBus may be accessed using the function cfidrPortBusGetStep().

REFERENCE
cfidrPortBundleCreatePortBus()
cfidrPortBusGetStep()
cfidrNetlistViewCreatePortBus()

5.10.17 cfidrPortScalarGetDirection

DECLARATION
cfidrPortDirectionT cfidrPortScalarGetDirection(
cfidrPortScalarIdT portScalar,
cfidrErrorT *error)
This function returns the Direction attribute of the PortScalar specified by portScalar.

The return value is a cfidrPortDirectionT enumerated type representing the value of the Direction attribute.

On error the function returns CFIDR_UNDEFINED_PORTDIRECTION.

portScalar (input) The OID of the PortScalar whose Direction attribute is desired.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portScalar is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portScalar is not the OID of a PortScalar.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

5.10.18 cfidrPortScalarGetNetScalar

DECLARATION
cfidrNetScalarIdT cfidrPortScalarGetNetScalar(
cfidrPortScalarIdT portScalar,
cfidrErrorT *error)
This function retrieves the NetScalar at the end of the NetScalar relationship defined for the PortScalar specified by portScalar.

The return value is a cfidrNetScalarIdT referring to the NetScalar at the end of the NetScalar relationship. If an error occurs or if there is no NetScalar attached to this PortScalar, a Null OID is returned.

portScalar (input) The OID of the PortScalar containing the NetScalar relationship which is being traversed.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portScalar is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portScalar is not the OID of a PortScalar

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

REFERENCE
cfidrNetGetPorts()

5.11 PortInst Functions

5.11.1 cfidrPortInstBundleFindPortInstByDescriberName

DECLARATION
cfidrPortInstIdT
cfidrPortInstBundleFindPortInstByDescriberName(
cfidrPortInstBundleIdT portInstBundle,
cfidrStringT describerName,
cfidrErrorT *error)
This function returns the PortInst with the specified describerName that is within the PortInsts relationship defined for the PortInstBundle specified by portInstBundle.

The return value is a cfidrPortInstIdT referring to the PortInst just found. If an error occurs, a Null OID is returned.

portInstBundle (input) The OID of the PortInstBundle from which the PortInst is to be found.
describerName (input) The DescriberName of the PortInst.
error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
portInstBundle is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInstBundle is not the OID of a PortInstBundle.

CFIDR_INVALID_NAME:
the describerName parameter is not a valid string or is not a legal name.

CFIDR_OBJECT_NOT_FOUND:
no PortInst with the specified describerName exists.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
Only the immediate list of PortInsts directly owned by the specified portInstBundle is searched by this function. Thus a PortInst that is only indirectly owned by this portInstBundle will not be returned by this function

5.11.2 cfidrPortInstBundleGetNetBundles

DECLARATION
cfidrNetBundlesIdT cfidrPortInstBundleGetNetBundles(
cfidrPortInstBundleIdT portInstBundle,
cfidrErrorT *error)
This function initiates a traversal of all of the NetBundles at the end of the NetBundles relationship defined for the PortInstBundle specified by portInstBundle. These are the NetBundles to which this PortInstBundle connects.

The return value is a cfidrNetBundlesIdT referring to an Iterator ID that iterates over NetBundles. A valid Iterator ID is always returned, even when an error occurs. In the case of an error, calling the cfidrIterNextNetBundle() function returns a Null OID.

portInstBundle (input) The OID of a PortInstBundle for which the NetBundles relationship is to be traversed.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInstBundle is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInstBundle is not the OID of a PortInstBundle.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
Returns all the NetBundles which are connected to the PortInstBundle passed in via portInstBundle. Essentially, this returns the NetBundles which directly or indirectly contain any NetScalars connected to PortInstScalars directly or indirectly owned by the PostInstBundle.

POST-CONDITIONS
The cfidrIterNextNetBundle() function returns the next NetBundle OID in the NetBundles relationship.

If no objects are currently present in the NetBundles relationship, an error is not returned but the first call to cfidrIterNextNetBundle() returns a Null OID.

REFERENCE
cfidrIterNextNet()
cfidrIterNextNetBundle()

5.11.3 cfidrPortInstBundleGetPortInsts

DECLARATION
cfidrPortInstsIdT cfidrPortInstBundleGetPortInsts(
cfidrPortInstBundleIdT portInstBundle,
cfidrIterModeT mode,
cfidrErrorT *error)
This function initiates a traversal of all of the PortInsts (PortInstBundles, PortInstBusses, or PortInstScalars) at the end of the PortInsts relationship defined for the PortInstBundle specified by portInstBundle.

The return value is a cfidrPortInstsIdT referring to an Iterator ID that iterates over PortInsts. A valid Iterator ID is always returned, even when an error occurs. In the case of an error, calling the cfidrIterNextPortInst() function returns a Null OID.

portInstBundle (input) The OID of a PortInstBundle for which the PortInsts relationship is to be traversed.

mode (input) The mode that determines which PortInsts are returned. The current valid values are CFIDR_ITER_SCALARS, CFIDR_ITER_BUNDLES, CFIDR_ITER_TOP, and CFIDR_ITER_ALL. See the Pre-Conditions below for more detail on how these modes behave.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInstBundle is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInstBundle is not the OID of an PortInstBundle.

CFIDR_INVALID_ITERMODE:
mode is not a valid IterMode.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The PortInsts returned depends on the mode argument specified.

mode=CFIDR_ITER_TOP
Returns only those PortInsts (PortInstBundles, PortInstBusses, or PortInstScalars) which are owned directly by the PortInstBundle.

mode=CFIDR_ITER_SCALARS
Returns all the PortInstScalars owned directly or indirectly by the PortInstBundle. No PortInstBundles are output with this mode.

mode=CFIDR_ITER_BUNDLES
Returns all the PortInstBundles owned directly or indirectly by the PortInstBundle. No PortInstScalars are output with this mode.

mode=CFIDR_ITER_ALL
Returns all the PortInsts (PortInstBundles, PortInstBusses or PortInstScalars) owned directly or indirectly by the PortInstBundle. This is the union of all the PortInsts returned by the CFIDR_ITER_SCALARS and CFIDR_ITER_BUNDLES modes.

Depth first recursion is used for all modes except CFIDR_ITER_TOP.

POST-CONDITIONS
The cfidrIterNextPortInst() function returns the next PortInst OID in the PortInsts relationship.

If no objects are currently present in the PortInsts relationship, an error is not returned but the first call to cfidrIterNextPortInst() returns a Null OID.

The PortInst name scoping rules (inherited from the Port name scoping rules) state that PortInst names are only unique within their immediate owner (either an Inst or a PortInstBundle). Thus, two PortInsts with the same name may exist and be completely different objects. Thus, PortInsts returned via any mode except CFIDR_ITER_TOP may have the same name but in fact be different objects. The cfidrObjectIsSame() function can be used to determine if any two of these PortInsts are the same.

REFERENCE
cfidrIterNextPortInst()
cfidrObjectIsSame()
cfidrPortBundleGetPorts()

5.11.4 cfidrPortInstBundleGetSize

DECLARATION
cfidrInt32T cfidrPortInstBundleGetSize(
cfidrPortInstBundleIdT portInstBundle,
cfidrErrorT *error)
This function returns the number of Ports currently in the specified portInstBundle. This is only the number at the next level and not a count of the total number of scalars in the bundle.

The return value is a cfidrInt32T. If an error occurs, a -1 is returned.

portInstBundle (input) The OID of a PortInstBundle.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInstBundle is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInstBundle is not the OID of a PortInstBundle.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
PortInstBundles are created only indirectly when Insts are created and the Describer NetlistView has PortBundles. The PortInstBundle size is that of the Describer PortBundle.

REFERENCE
cfidrPortBundleGetSize()
cridrPortInstGetDescriber()
cfidrNetlistViewCreateInst()

5.11.5 cfidrPortInstBusGetStart

DECLARATION
cfidrInt32T cfidrportInstBusGetStart(
cfidrPortInstBusIdT portInstBus,
cfidrErrorT *error)
This function returns the start attribute of the specified portInstBus. This specifies the first index value for this bus.

The return value is a cfidrInt32T. If an error occurs, a 0 is returned.

portInstBus (input) The OID of a PortInstBus.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInstBus is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInstBus is not the OID of a PortInstBus.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The start attribute of a PortInstBus is that of the start attribute of the Describer PortBus.

REFERENCE
cfidrPortInstGetDescriber()
cfidrPortBusGetStart()
cfidrNetlistViewCreateInst()

5.11.6 cfidrPortInstBusGetStep

DECLARATION
cfidrInt32T cfidrPortInstBusGetStep(
cfidrPortInstBusIdT portInstBus,
cfidrErrorT *error)
This function returns the step attribute of the specified portInstBus. This attribute specifies the numeric increment between positions for the index.

The return value is a cfidrInt32T. If an error occurs, a 0 is returned.

portInstBus (input) The OID of a PortInstBus.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInstBus is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInstBus is not the OID of a PortInstBus.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The Step attribute of a PortInstBus is that of the Describer PortBus.

REFERENCE
cfidrPortBusGetStep()
cfidrPortInstGetDescriber()
cfidrNetlistViewCreatePortBus()

5.11.7 cfidrPortInstCheckDescriber [2]

DECLARATION
cfidrBooleanT cfidrPortInstCheckDescriber(
cfidrPortInstIdT portInst,
cfidrErrorT *error)
This function checks for discrepancies between PortInst specified via portInst and its Describer Port.

If portInst is a PortInstBundle or Bus, checking is performed on all PortInsts owned either directly or indirectly by the PortInst (as returned by cfidrPortInstBundleGetPortInsts with mode ITER_ALL).

[2] NOTE: This function can be written entirely using other DR-PI functions.
If no discrepancies are found between the PortInst and the Describer Port, CFIDR_FALSE is returned. Otherwise, CFIDR_TRUE is returned and the error output argument will denote the discrepancy.

portInst (input) The OID of the PortInst to check against its Describer Port.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInst is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInst is not the OID of a PortInst.

CFIDR_DESCRIBER_VIEW_NOT_FOUND:
could not find or access the Describer View for the Instance on which portInst resides.

CFIDR_DESCRIBER_PORT_NOT_FOUND:
there is no Port corresponding to portInst on the Describer View.

CFIDR_PORT_MEMBERS_DIFFER:
portInst is a bundle and the members differ from the members of the corresponding Describer PortBundle OR the corresponding Describer is a PortScalar. This error is also returned if the PortInst is a PortInstScalar, but the corresponding Describer is a PortBundle. This error is also returned if the owner of the describer of a PortInst is not the same object as the describer of the owner of that PortInst.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
If the Describer View is not opened yet, then this function will open it for CFIDR_READ. If the open fails, the error returned from this function will be the error returned from the failed open.

REFERENCE
cfidrNetlistViewCreateInst()

5.11.8 cfidrPortInstGetDescriber

DECLARATION
cfidrPortIdT cfidrPortInstGetDescriber(
cfidrPortInstIdT portInst,
cfidrErrorT *error)
This function returns the Port at the end of the Describer relationship for the PortInst specified by portInst.

The return value is a cfidrPortIdT referring to the Port at the end of the Describer relationship. If an error occurs, a Null OID is returned.

portInst (input) The OID of the PortInst whose Describer relationship is to be followed.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInst is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInst is not the OID of a PortInst.

CFIDR_DESCRIBER_VIEW_NOT_FOUND:
could not find or access the Describer View for the Inst on which portInst resides.

CFIDR_DESCRIBER_PORT_NOT_FOUND:
there is no Port corresponding to portInst on the Describer View either because the Describer port does not exist or because it is inconsistent with the PortInst due to scalar versus bundle of differing bundle membership. The function cfidrPortInstCheckDescriber() can be used for more information if this error occurs.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
If the Describer View is not opened yet, then this function will open it for CFIDR_READ. If the open fails, the error returned from this function will be the error returned from the failed open.

5.11.9 cfidrPortInstGetDescriberName [2]

DECLARATION
cfidrStringT cfidrPortInstGetDescriberName(
cfidrPortInstIdT portInst,
cfidrErrorT *error)
This function returns the DescriberName (derived) attribute of the PortInst specified by portInst.

[2] NOTE: this function can be written entirely using other DR-PI functions.
The return value is a cfidrStringT representing the string value of the DescriberName attribute. On error, the function returns "".

portInst (input) The OID of the PortInst whose DescriberName attribute is desired.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInst is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInst is not the OID of a PortInst.

CFIDR_DESCRIBER_VIEW_NOT_FOUND:
could not find or access the Describer View for the Inst on which portInst resides.

CFIDR_DESCRIBER_PORT_NOT_FOUND:
there is no Port corresponding to portInst on the Describer View.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
If the Describer View is not opened yet, then this function will open it for CFIDR_READ. If the open fails, the error returned from this function will be the error returned from the failed open.

REFERENCE
cfidrNamedObjectGetName()
cfidrPortInstGetDescriber().

5.11.10 cfidrPortInstGetOwner

DECLARATION
cfidrObjectIdT cfidrPortInstGetOwner(
cfidrPortInstIdT portInst,
cfidrErrorT *error)
This function returns the object (Instance or PortInstBundle) at the end of the Owner relationship for the PortInst specified by portInst. The Owner relationship is defined when an object is created and cannot be modified.

The return value is a cfidrObjectIdT referring to the Inst or the PortInstBundle at the end of the Owner relationship. If an error occurs, a Null OID is returned.

portInst (input) The OID of the PortInst whose Owner relationship is to be followed.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInst is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInst is not the OID of a PortInst.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
Use the cfidrObjectGetObjectType() function to determine the Owner's object type.

REFERENCE
cfidrObjectGetObjectType()

5.11.11 cfidrPortInstScalarGetDescriberDirection [2]

DECLARATION
cfidrPortDirectionT
cfidrPortInstScalarGetDescriberDirection(
cfidrPortInstScalarIdT portInstScalar,
cfidrErrorT *error)
This function returns the DescriberDirection (derived) attribute of the PortInstScalar specified by portInstScalar.

[2] NOTE: this function can be written entirely using other DR-PI functions.
The return value is a cfidrPortDirectionT enumerated type representing the value of the DescriberDirection attribute.

On error the function returns CFIDR_UNDEFINED_PORTDIRECTION.

portInstScalar (input) The OID of the PortInstScalar whose DescriberDirection attribute is desired.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInstScalar is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInstScalar is not the OID of a PortInstScalar.

CFIDR_DESCRIBER_VIEW_NOT_FOUND:
could not find or access the Describer View for the Inst on which portInstScalar resides.

CFIDR_DESCRIBER_PORT_NOT_FOUND:
there is no PortScalar corresponding to portInstScalar on the Describer View.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
If the Describer View is not opened yet, then this function will open it for CFIDR_READ. If the open fails, the error returned from this function will be the error returned from the failed open.

REFERENCE
cfidrPortInstGetDescriber().

5.11.12 cfidrPortInstScalarGetNetScalar

DECLARATION
cfidrNetScalarIdT cfidrPortInstScalarGetNetScalar(
cfidrPortInstScalarIdT portInstScalar,
cfidrErrorT *error)
This function retrieves the NetScalar at the end of the NetScalar relationship defined for the PortInstScalar specified by portInstScalar.

The return value is a cfidrNetScalarIdT referring to the NetScalar at the end of the NetScalar relationship. If an error occurs or if there is no NetScalar attached to this PortInstScalar, a Null OID is returned.

portInstScalar (input) The OID of the PortInstScalar containing the NetScalar relationship which is being traversed.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
portInstScalar is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
portInstScalar is not the OID of a PortInstScalar

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

REFERENCE
cfidrNetGetPortInsts()
cfidrNetGetPorts()
Property Functions

5.12 Property Functions

5.12.1 cfidrPropGetBooleanValue

DECLARATION
cfidrBooleanT cfidrPropGetBooleanValue(
cfidrPropIdT prop,
cfidrErrorT *error)
This function returns the Boolean Value attribute of the Property specified by prop.

The return value is either CFIDR_TRUE or CFIDR_FALSE. If an error occurs the function returns CFIDR_FALSE.

prop (input) The OID of the Property whose Boolean Value attribute is desired.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
prop is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
prop is not the OID of a Boolean-valued Property.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred

REFERENCE
cfidrPropSetBooleanValue()

5.12.2 cfidrPropGetFloat32Value

DECLARATION
cfidrFloat32T cfidrPropGetFloat32Value(
cfidrPropIdT prop,
cfidrErrorT *error)
This function returns the Float32 Value attribute of the Property specified by prop.

The return value is a cfidrFloat32T representing a 32-bit floating point number. If an error occurs the function returns 0.0.

prop (input) The OID of the Property whose Float32 Value attribute is desired.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
prop is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
prop is not the OID of a Float32-valued Property.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
The float returned is guaranteed to be in the range CFIDR_MIN_FLOAT32 to CFIDR_MAX_FLOAT32.

REFERENCE
cfidrPropSetFloat32Value()

5.12.3 cfidrPropGetInt32Value

DECLARATION
cfidrInt32T cfidrPropGetInt32Value(
cfidrPropIdT prop,
cfidrErrorT *error)
This function returns the Int32 Value attribute of the Property specified by prop.

The return value is a cfidrInt32T representing a 32-bit integer number. If an error occurs the function returns 0.

prop (input) The OID of the Property whose Int32 Value attribute is desired.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
prop is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
prop is not the OID of a Int32-valued Property.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
The integer returned is guaranteed to be in the range CFIDR_MIN_INT32 to CFIDR_MAX_INT32.

REFERENCE
cfidrPropSetInt32Value()

5.12.4 cfidrPropGetOwner

DECLARATION
cfidrObjectIdT cfidrPropGetOwner(
cfidrPropIdT prop,
cfidrErrorT *error)
This function returns the object at the end of the Owner relationship for the Property specified by prop. The Owner relationship is defined when an object is created and cannot be modified.

The return value is a cfidrObjectIdT referring the object at the end of the Owner relationship. Since any object can have properties, the owner can be any object type. If an error occurs, a Null OID is returned.

prop (input) The OID of the Prop whose Owner relationship is to be followed.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
prop is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
prop is not the OID of a Property.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
Use the cfidrObjectGetObjectType() function to determine the Owner's object type.

REFERENCE
cfidrObjectCreateProp()
cfidrObjectGetObjectType()

5.12.5 cfidrPropGetStringValue

DECLARATION
cfidrStringT cfidrPropGetStringValue(
cfidrPropIdT prop,
cfidrErrorT *error)
This function returns the String Value attribute of the Property specified by prop.

The return value is a cfidrStringT representing a string. If an error occurs the function returns "" (the empty string).

prop (input) The OID of the Property whose String Value attribute is desired.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
prop is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
prop is not the OID of a String-valued Property.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
There are no restrictions on the length or characters used in the string. The memory for the string is managed by the DR-PI. The string's value remains valid until the next execution of any PI function which has a cfidrStringT return value.

REFERENCE
cfidrPropSetStringValue()

5.12.6 cfidrPropGetValueType

DECLARATION
cfidrValueTypeT cfidrPropGetValueType(
cfidrPropIdT prop,
cfidrErrorT *error)
This function returns the ValueType attribute of the Property specified by prop.

The return value is a cfidrValueTypeT enumerated type representing the value of the ValueType attribute. If an error occurs, the function returns CFIDR_UNDEFINED_VALUETYPE.

prop (input) The OID of the Property whose ValueType attribute is desired.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
prop is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
prop is not the OID of a Property.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The value type of a Prop is set by the type of the particular value set for the Prop. See the cfidrPropSet...Value() functions.

REFERENCE
cfidrPropSet...Value() functions.

5.12.7 cfidrPropSetBooleanValue

DECLARATION
cfidrVoidT cfidrPropSetBooleanValue(
cfidrPropIdT prop,
cfidrBooleanT value,
cfidrErrorT *error)
This function sets the Boolean Value attribute for the Property specified via prop.

prop (input) The OID of the Property to which the Value attribute is to be set.

value (input) The desired Boolean value for the Value attribute of prop.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
prop is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
prop is not the OID of a Property.

CFIDR_READ_ONLY:
the containing object (Lib or View) has not been opened for update.

CFIDR_INVALID_VALUE:
value is not a valid Boolean value.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The value argument must be either CFIDR_TRUE or CFIDR_FALSE. Any other value will not set the default value.

POST-CONDITIONS
The updated object must be saved in order to be persistent. Purging the object before saving it will result in the loss of the changes.

If the Property's Value attribute was other than a Boolean, the setting still takes place and the ValueType is changed to CFIDR_BOOLEAN.

REFERENCE
cfidrObjectCreateProp()

5.12.8 cfidrPropSetFloat32Value

DECLARATION
cfidrVoidT cfidrPropSetFloat32Value(
cfidrPropIdT prop,
cfidrFloat32T value,
cfidrErrorT *error)
This function sets the Float32 Value attribute for the Property specified via prop.

prop (input) The OID of the Property to which the Value attribute is to be set.

value (input) The 32-bit floating point number to set the Value attribute to.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
prop is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
prop is not the OID of a Property.

CFIDR_READ_ONLY:
the containing object (Lib or View) has not been opened for update.

CFIDR_INVALID_VALUE:
value is not a valid Float32 value.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The value argument must be within the range CFIDR_MIN_FLOAT32 to CFIDR_MAX_FLOAT32.

POST-CONDITIONS
The updated object must be saved in order to be persistent. Purging the object before saving it will result in the loss of the changes.

If the Property's Value attribute was other than a Float32, the setting still takes place and the ValueType is changed to CFIDR_FLOAT32.

REFERENCE
cfidrObjectCreateProp()

5.12.9 cfidrPropSetInt32Value

DECLARATION
cfidrVoidT cfidrPropSetInt32Value(
cfidrPropIdT prop,
cfidrInt32T value,
cfidrErrorT *error)
This function sets the Int32 Value attribute for the Property specified via prop.

prop (input) The OID of the Property to which the Value attribute is to be set.

value (input) The 32-bit integer number to set the Value attribute to.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
prop is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
prop is not the OID of a Property.

CFIDR_READ_ONLY:
the containing object (Lib or View) has not been opened for update.

CFIDR_INVALID_VALUE:
value is not a valid Int32 value.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The value argument must be within the range CFIDR_MIN_INT32 to CFIDR_MAX_INT32.

POST-CONDITIONS
The updated object must be saved in order to be persistent. Purging the object before saving it will result in the loss of the changes.

If the Property's Value attribute was other than a Int32, the setting still takes place and the ValueType is changed to CFIDR_INT32.

REFERENCE
cfidrObjectCreateProp()

5.12.10 cfidrPropSetStringValue

DECLARATION
cfidrVoidT cfidrPropSetStringValue(
cfidrPropIdT prop,
cfidrStringT value,
cfidrErrorT *error)
This function sets the String Value attribute for the Property specified via prop.

prop (input) The OID of the Property to which the Value attribute is to be set.

value (input) The string to set the Value attribute to. The caller is responsible for managing the memory of this string.

NOTE: DR-PI functions which return cfidrStringT values guarantee those strings to not be updated until the next call to a PI function that returns another cfidrStringT. These strings can be used as the value argument because the cfidrPropSetStringValue() function will not affect these strings returned from other PI functions.
error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
prop is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
prop is not the OID of a Property.

CFIDR_READ_ONLY:
the containing object (Lib or View) has not been opened for update.

CFIDR_INVALID_VALUE:
value is not a valid String.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
No limitations exists as far as the length or character set used in the string defined by the value argument.

POST-CONDITIONS
The updated object must be saved in order to be persistent. Purging the object before saving it will result in the loss of the changes.

POST-CONDITIONS If the Property's Value attribute was other than a String, the setting still takes place and the ValueType is changed to CFIDR_STRING.
REFERENCE
cfidrObjectCreateProp()

5.13 View Functions

5.13.1 cfidrEncapsulatedViewGetKey

DECLARATION
cfidrStringT cfidrEncapsulatedViewGetKey(
cfidrEncapsulatedViewIdT encapsulatedView,
cfidrErrorT *error)
This function returns the Key attribute of the EncapsulatedView specified by encapsulatedView.

The return value is a cfidrStringT representing the value of the Key attribute. On error the string "CFIDR_UNDEFINED_KEY" is returned.

encapsulatedView (input) The OID of the EncapsulatedView whose Key attribute is desired.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
encapsulatedView is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
encapsulatedView is not the OID of a EncapsulatedView.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The Key attribute is set by the cfidrCellCreateEncapsulatedView() function.

REFERENCE
cfidrCellCreateEncapsulatedView()

5.13.2 cfidrNetlistViewCreateInst

DECLARATION
cfidrInstIdT cfidrNetlistViewCreateInst(
cfidrNetlistViewIdT owner,
cfidrNetlistViewIdT describer,
cfidrStringT name,
cfidrErrorT *error)
This function creates an Inst object owned by the NetlistView specified via owner. The Inst is an instantiation of another NetlistView specified via describer. The Inst is referred to by name.

The return value is a cfidrInstIdT which refers to the Inst object just created. If an error occurs, a Null OID is returned.

owner (input) The OID of the NetlistView owning the Inst being created.

describer (input) The OID of the NetlistView describing the Inst being created.

name (input) The string representing the Name of the Inst to create.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a NetlistView.

CFIDR_READ_ONLY:
the View has not been opened for update.
CFIDR_UNUSABLE_DESCRIBER_OID:
describer is not a usable OID.

CFIDR_INVALID_DESCRIBER_TYPE:
describer is not the OID of a NetlistView.

CFIDR_DESCRIBER_RECURSION:
describer is the same NetlistView object as owner or recursively contains an Instance of owner.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_OBJECT_ALREADY_EXISTS:
an Inst with the Name name already exists.

CFIDR_INTRA_CELL_INSTANTIATION:
The owner of describer is the same object as the owner of owner.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The NetlistView OID specified by describer must refer to a usable NetlistView (i.e., top-down design by creating Insts without a describer NetlistView is disallowed). This also implies that the describer NetlistView has been previously created or opened.

The name argument must conform to the character set rules for name strings.

An Inst with the given name cannot already exist in the NetlistView specified by owner.

POST-CONDITIONS
Creating an Inst automatically creates PortInsts (PortInstBundles, PortInstBusses, and PortInstScalars) owned by the Inst. These PortInsts correspond 1-for-1 to Ports in the describer NetlistView. They may be retrieved as soon as the Inst is successfully created.

REFERENCE
cfidrNetlistViewGetInsts()

5.13.3 cfidrNetlistViewCreateNetBundle

DECLARATION
cfidrNetBundleIdT cfidrNetlistViewCreateNetBundle(
cfidrNetlistViewIdT owner,
cfidrStringT name,
cfidrErrorT *error)
This function creates a NetBundle object owned by the NetlistView specified via owner. The NetBundle is referred to by name.

The return value is a cfidrNetBundleIdT referring to the NetBundle object just created. If an error occurs, a Null OID is returned.

owner (input) The OID of the NetlistView owning the NetBundle being created.

name (input) The string representing the Name of the NetBundle being created.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a NetlistView.

CFIDR_READ_ONLY:
the owner View has notbeen opened for update.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_NAME_IN_USE:
the name parameter specifies a name already in use in the same name scope but not for a NetBundle.

CFIDR_OBJECT_ALREADY_EXISTS:
a NetBundle with the same name already exists.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The name argument must conform to the character set rules for name strings.

A Net (NetScalar, NetBundle, or NetBus) with the given name cannot already exist in the NetlistView specified by owner.

POST-CONDITIONS
The newly created NetBundle will initially have no members and a size of zero.

The NetBundle created by this function can later be inserted into one or more NetBundle(s).

REFERENCE
cfidrNetBundleGetNets()
cfidrNetBundleInsertNet()
cfidrNetBundleRemoveNet()
cfidrNetlistViewGetNets()

5.13.4 cfidrNetlistViewCreateNetBus

DECLARATION
cfidrNetBusIdT cfidrNetlistViewCreateNetBus(
cfidrNetlistViewIdT owner,
cfidrStringT name,
cfidrInt32T start
cfidrInt32T step
cfidrErrorT *error)
This function creates a NetBus object owned by the NetlistView specified via owner. The NetBus name attribute is set to name. The NetBus start attribute is set to start. The NetBus step attribute is set to step.

The return value is a cfidrNetBusIdT referring to the NetBus object just created. If an error occurs, a Null OID is returned.

owner (input) The OID of the NetlistView owning the NetBundle being created.

name (input) The string representing the name of the NetBundle being created.

start (input) The Int32 defining the index of position 0 in the bus.

step (input) The Int32 defining the difference in indexes of positions n and n+1 in the bus. This number must be non-zero.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a NetlistView.

CFIDR_READ_ONLY:
the owner View has not been opened for update.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_NAME_IN_USE:
the name parameter specifies a name already in use in the same name scope but not for a NetBus.

CFIDR_OBJECT_ALREADY_EXISTS:
a NetBus with the same name already exists.

CFIDR_INVALID_VALUE
Step is 0.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The name argument must conform to the character set rules for name strings.

A Net (NetScalar, NetBundle, or NetBus) with the given name cannot already exist in the NetlistView specified by owner.

POST-CONDITIONS
The newly created NetBus will initially have no members and a size of 0.

The NetBus created by this function can later be inserted into one or more NetBundle(s).

The Start and Step attributes may be changed later by use of the cfidrNetBusSetStart() and cfidrNetBusSetStep() functions.

REFERENCE
cfidrNetBundleGetSize()
cfidrNetBundleGetNets()
cfidrNetBundleInsertNet()
cfidrNetBundleRemoveNet()
cfidrNetBusGetStart()
cfidrNetBusGetStep()
cfidrNetBusSetStart()
cfidrNetBusSetStep()
cfidrNetlistViewGetNets()

5.13.5 cfidrNetlistViewCreateNetScalar

DECLARATION
cfidrNetScalarIdT cfidrNetlistViewCreateNetScalar(
cfidrNetlistViewIdT owner,
cfidrStringT name,
cfidrErrorT *error)
This function creates a NetScalar object owned by the NetlistView specified via owner. The NetScalar is referred to by name.

This function only allows NetScalars to be created and owned by the NetlistView. The NetScalar can be subsequently contained in a NetBundle.

The return value is a cfidrNetScalarIdT referring to the NetScalar just created. If an error occurs, a Null OID is returned.

owner (input) The OID of the NetlistView owning the NetScalar to be created.

name (input) The string representing the name of the NetScalar.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a NetlistView.

CFIDR_READ_ONLY:
the owner View has not been opened for update.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_NAME_IN_USE:
the name parameter specifies a name already in use in the same name scope but not for a NetScalar.

CFIDR_OBJECT_ALREADY_EXISTS:
a NetScalar with the same name already exists.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The name argument must conform to the character set rules for name strings.

A Net (NetScalar, NetBundle, or NetBus) with the given name cannot already be owned by the NetlistView specified by owner.

POST-CONDITIONS
The NetScalar created by this function can be later inserted into one or more NetBundle(s).

The IsGlobal attribute is initially set to CFIDR_FALSE. Use the function cfidrNetScalarSetIsGlobal() to change it.

REFERENCE
cfidrNetScalarSetIsGlobal()
cfidrNetlistViewGetNets()
cfidrNetBundleGetNets()
cfidrNetBundleInsertNet()
cfidrNetBundleRemoveNet()

5.13.6 cfidrNetlistViewCreatePortBundle

DECLARATION
cfidrPortBundleIdT cfidrNetlistViewCreatePortBundle(
cfidrNetlistViewIdT owner,
cfidrStringT name,
cfidrInt32T position,
cfidrErrorT *error)
This function creates a PortBundle object owned by the NetlistView specified via owner.

The return value is a cfidrPortBundleIdT referring to the PortBundle object just created. If an error occurs, a Null OID is returned.

owner (input) The OID of the NetlistView owning the PortBundle being created.

name (input) The string representing the name of the PortBundle being created.

position (input) The integer specifying the position of the PortBundle in the list of Ports owned by owner. A position value less than 0 or greater than or equal to the number of ports indicates the new PortBundle is put at end of the list. Any other value, including 0, indicates the actual position in the list.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a NetlistView.

CFIDR_READ_ONLY:
the owner View has not been opened for update.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_NAME_IN_USE:
the name parameter specifies a name already in use in the same name scope but not for a PortBundle.

CFIDR_OBJECT_ALREADY_EXISTS:
a PortBundle with the same name already exists for this owner.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The name argument must conform to the character set rules for name strings.

A Port named name that is owned by the same NetlistView as specified by owner cannot already exist.

POST-CONDITIONS
The PortBundle is created with no members initially. Later, Ports or PortBundles may either be created in or have their owner changed to be this PortBundle. Furthermore, this PortBundle may later have its owner changed to a PortBundle instead of the NetlistView.

The PortBundle is created and added to the list of Ports owned by the NetlistView specified by owner at the position specified by position. If position = 0, the new PortBundle will be added as the first member of the list. If position is less than 0 or greater than or equal to the number of members in the list, the new PortBundle is appended to the end of the list. Otherwise, the PortBundle is inserted at the specified position (0 based). The position of all Ports whose positions were greater than or equal to position, will have their position incremented by 1. For example, presume a NetlistView initially has Ports:
A, B, C0, 1, 2.

Adding a new member X at position 1 results in:
A, X, B, C0, 1, 2
Note that B had position 1 before and has position 2 after X is created.

Adding X at position 0 causes X to be at the beginning of the list:
X, A, B, C0, 1, 2

Adding X at an invalid position such as -1 (or any value greater than 4) causes creation of the new member at the end of the list:
A, B, C0, 1, 2, X

REFERENCE
cfidrPortBundleCreatePortBundle()
cridrPortBundleCreatePortScalar()
cfidrPortBundleGetOwner()
cfidrPortBundleGetPorts()
cfidrPortSetOwnerPortBundle()
cfidrPortSetOwnerView()
cfidrNetlistViewGetPorts()

5.13.7 cfidrNetlistViewCreatePortBus

DECLARATION
cfidrPortBusIdT cfidrNetlistViewCreatePortBus(
cfidrNetlistViewIdT owner,
cfidrStringT name,
cfidrInt32T position
cfidrInt32T start
cfidrInt32T step
cfidrErrorT *error)
This function creates a PortBus object located at the position position in the list of Ports owned by the NetlistView specified via owner. The PortBus Name attribute is set to name. The PortBus Start attribute is set to start. The PortBus Step attribute is set to step.

The return value is a cfidrPortBusIdT referring to the PortBus object just created. If an error occurs, a Null OID is returned.

owner (input) The OID of the NetlistView owning the PortBus being created.

name (input) The string representing the name of the PortBus being created.

position (input) The integer specifying the position of the PortBus in the list of Ports owned by owner. A position value less than 0 or greater than or equal to the number of ports indicates the new PortBus is put at end of the list. Any other value, including 0, indicates the actual position in the list.

start (input) The Int32 defining the index of position 0 in the bus.

step (input) The Int32 defining the difference in indexes of positions n and n+1 in the bus. This number must be non-zero.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a NetlistView.

CFIDR_READ_ONLY:
the owner View has not been opened for update.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_NAME_IN_USE:
the name parameter specifies a name already in use in the same name scope but not for a PortBus.

CFIDR_OBJECT_ALREADY_EXISTS:
a PortBus with the same name already exists.

CFIDR_INVALID_VALUE
Step is 0.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The name argument must conform to the character set rules for name strings.

A Port (PortScalar, PortBundle, or PortBus) with the given name cannot already exist in the NetlistView specified by owner.

POST-CONDITIONS
The newly created PortBus will initially have no members and a size of 0.

The PortBus created by this function can later be changed to have a PortBundle as its owner using cfidrPortBundleSetOwnerPortBundle().

The Start and Step attributes may be changed later by use of the cfidrPortBusSetStart() and cfidrPortBusSetStep() functions.

REFERENCE
cfidrPortBundleGetSize()
cfidrPortBundleGetNets()
cfidrPortBundleSetOwnerPortBundle()
cfidrPortBundleSetOwnerView()
cfidrPortBusGetStart()
cfidrPortBusGetStep()
cfidrPortBusSetStart()
cfidrPortBusSetStep()
cfidrNetlistViewGetPortBundles()

5.13.8 cfidrNetlistViewCreatePortScalar

DECLARATION
cfidrPortScalarIdT cfidrNetlistViewCreatePortScalar(
cfidrNetlistViewIdT owner,
cfidrStringT name,
cfidrInt32T position,
cfidrPortDirectionT direction,
cfidrErrorT *error)
This function creates a PortScalar object owned by the NetlistView specified via owner and located at position in the list of Ports owned by owner. The PortScalar Name attribute is set to name. The PortScalar Direction attribute is set to direction.

The PortScalar is created with all required attributes set including the derived attribute of position.

The return value is a cfidrPortScalarIdT referring to the PortScalar just created. If an error occurs a Null OID is returned.

owner (input) The OID of the NetlistView owning the PortScalar to be created.

name (input) The string representing the name of the PortScalar.

position (input) The integer specifying the position of the PortScalar in the list of Ports owned by owner. A position value less than 0 or greater than or equal to the number of ports indicates the new Port is put at end of the list. Any other value, including 0, indicates the actual position in the list.

direction (input) The Direction attribute to assign to the created PortScalar.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a NetlistView.

CFIDR_READ_ONLY:
the owner View has not been opened for update.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_NAME_IN_USE:
the name parameter specifies a name already in use in the same name scope but not for a PortScalar.

CFIDR_OBJECT_ALREADY_EXISTS:
a PortScalar with the same name already exists for owner.

CFIDR_INVALID_DIRECTION:
direction is not a legal PortDirection.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
The name argument must conform to the character set rules for name strings.

A Port (PortScalar, PortBundle, or PortBus) with the given name cannot already be owned by the NetlistView specified by owner. However, a Port with the same name may exist in a PortBundle. This is allowed since the scope of Port names is the owning NetlistView or the owning PortBundle.

The owner of the PortScalar created by this function can be later be changed to a PortBundle provided no other member of that PortBundle has the same name.

POST-CONDITIONS
The PortScalar is created and added to the list of Ports owned by the NetlistView specified by owner at the position specified by position. If position = 0, the new PortScalar will be added as the first member of the list. If position is less than 0 or greater than or equal to the number of members in the list, the new PortScalar is appended to the end of the list. Otherwise, the PortScalar is inserted at the specified position (0 based). The position of all Ports whose positions were greater than or equal to position, will have their position incremented by 1. For example, presume a NetlistView has Ports:
A, B, C0, 1, 2.

Adding a new member X at position 1 results in:
A, X, B, C0, 1, 2
Note that B had position 1 before and has position 2 after X is created.

Adding X at position 0 causes X to be at the beginning of the list:
X, A, B, C0, 1, 2

Adding X at an invalid position such as -1 (or any value greater than 4) causes creation of the new member at the end of the list:
A, B, C0, 1, 2, X

REFERENCE
cfidrPortBundleCreatePortBundle()
cridrPortBundleCreatePortScalar()
cfidrPortBundleGetOwner()
cfidrPortBundleGetPorts()
cfidrPortSetOwnerPortBundle()
cfidrPortSetOwnerView()
cfidrNetlistViewCreatePortBundle()
cfidrNetlistViewGetPorts()

5.13.9 cfidrNetlistViewFindInstByName

DECLARATION
cfidrInstIdT cfidrNetlistViewFindInstByName(
cfidrNetlistViewIdT netlistView,
cfidrStringT name,
cfidrErrorT *error)
This function returns the Inst with the specified name that is within the Insts relationship defined for the NetlistView specified by netlistView.

The return value is a cfidrInstIdT referring to the Inst just found. If an error occurs, a Null OID is returned.

netlistView (input) The OID of the NetlistView from which the Inst is to be found.

name (input) The name of the Inst.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating memory for this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
netlistView is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
netlistView is not the OID of a NetlistView.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_OBJECT_NOT_FOUND:
no Inst with the specified name exists.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

5.13.10 cfidrNetlistViewFindNetByName

DECLARATION
cfidrNetIdT cfidrNetlistViewFindNetByName(
cfidrNetlistViewIdT netlistView,
cfidrStringT name,
cfidrErrorT *error)
This function returns the Net (either NetBundle or NetScalar) with the specified name that is within the Nets relationship defined for the NetlistView specified by netlistView. All Nets are scoped to the NetlistView, therefore Nets contained in NetBundles are also searched by this function.

The return value is a cfidrNetIdT referring to the Net just found. If an error occurs, a Null OID is returned.

netlistView (input) The OID of the NetlistView from which the Net is to be found.

name (input) The name of the Net.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating memory for this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
netlistView is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
netlistView is not the OID of a NetlistView.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_OBJECT_NOT_FOUND:
no Net with the specified name exists.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

5.13.11 cfidrNetlistViewFindPortByName

DECLARATION
cfidrPortIdT cfidrNetlistViewFindPortByName(
cfidrNetlistViewIdT netlistView,
cfidrStringT name,
cfidrErrorT *error)
This function returns the Port (either PortBundle or PortScalar) with the specified name that is within the Ports relationship defined for the NetlistView specified by netlistView. All Ports are scoped to their Owner (either NetlistView or PortBundle), therefore Ports contained in PortBundles are not searched by this function.

The return value is a cfidrPortIdT referring to the Port just found. If an error occurs, a Null OID is returned.

netlistView (input) The OID of the NetlistView from which the Port is to be found.

name (input) The name of the Port.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating memory for this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
netlistView is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
netlistView is not the OID of a NetlistView.

CFIDR_INVALID_NAME:
the name parameter is not a valid string or is not a legal name.

CFIDR_OBJECT_NOT_FOUND:
no Port with the specified name exists.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

5.13.12 cfidrNetlistViewGetInsts

DECLARATION
cfidrInstsIdT cfidrNetlistViewGetInsts(
cfidrNetlistViewIdT netlistView,
cfidrErrorT *error)
This function initiates a traversal of all the Insts at the end of the Insts relationship for the NetlistView specified by netlistView.

The return value is a cfidrInstsIdT referring to an Iterator ID that iterates over Insts. A valid Iterator ID is always returned, even when an error occurs. In the case of an error, calling the cfidrIterNextInst() function returns a Null OID.

netlistView (input) The OID of a NetlistView for which the Insts relationship is to be traversed.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
netlistView is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
netlistView is not the OID of a NetlistView.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
The cfidrIterNextInst() function returns the next Inst OID in the Insts relationship.

If no objects are currently present in the Insts relationship, an error is not returned but the first call to cfidrIterNextInst() returns a Null OID.

REFERENCE
cfidrIterNextInst()

5.13.13 cfidrNetlistViewGetNets

DECLARATION
cfidrNetsIdT cfidrNetlistViewGetNets(
cfidrNetlistViewIdT view,
cfidrIterModeT mode,
cfidrErrorT *error)
This function initiates a traversal of all of the Nets (NetBundles, NetBusses, or NetScalars) at the end of the Nets relationship defined for the View specified by view.

The return value is a cfidrNetsIdT referring to an Iterator ID that iterates over Nets. A valid Iterator ID is always returned, even when an error occurs. In the case of an error, calling the cfidrIterNextNet() function returns a Null OID.

view (input) The OID of a NetlistView for which the Nets relationship is to be traversed.

mode (input) The mode that determines which Nets are returned. The current valid values are CFIDR_ITER_SCALARS, CFIDR_ITER_BUNDLES, CFIDR_ITER_TOP, and CFIDR_ITER_ALL. See the Pre-Conditions below for more detail on how these modes behave.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
view is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
view is not the OID of a NetlistView.

CFIDR_INVALID_ITERMODE:
mode is not a valid IterMode.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
Returns all Nets owned by the NetlistView. The Nets returned depends on the mode argument specified.

mode=CFIDR_ITER_TOP
Returns all those Nets (NetBundles, NetBusses, or NetScalars) which are not contained in a NetBundle.

mode=CFIDR_ITER_SCALARS
Returns all the NetScalars owned by the NetlistView, regardless of whether they are contained in a NetBundle or not. No NetBundles are output with this mode, only NetScalars. This mode lets the application effectively see the View as a scalar netlist.

mode=CFIDR_ITER_BUNDLES
Returns all the NetBundles owned by the NetlistView. No NetScalars are output.

mode=CFIDR_ITER_ALL
Returns all the Nets (NetBundles, NetBusses, or NetScalars) owned by the NetlistView. This mode differs from CFIDR_ITER_TOP in that NetScalars contained in a Bundle are also returned. This mode is a combination of the SCALARS and BUNDLES modes.

POST-CONDITIONS
The cfidrIterNextNet() function returns the next Net OID in the Nets relationship. The next Net returned must obey the return mode as specified via the mode argument.

If no objects are currently present in the Nets relationship, an error is not returned but the first call to cfidrIterNextNet() returns a Null OID.

REFERENCE
cfidrIterNextNet()

5.13.14 cfidrNetlistViewGetPorts

DECLARATION
cfidrPortsIdT cfidrNetlistViewGetPorts(
cfidrNetlistViewIdT view,
cfidrIterModeT mode,
cfidrErrorT *error)
This function initiates a traversal of all of the Ports (PortBundles, PortBusses, or PortScalars) at the end of the Ports relationship defined for the NetlistView specified by view.

The return value is a cfidrPortsIdT referring to an Iterator ID that iterates over Ports. A valid Iterator ID is always returned, even when an error occurs. In the case of an error, calling the cfidrIterNextPort() function returns a Null OID.

view (input) The OID of a NetlistView for which the Ports relationship is to be traversed.

mode (input) The mode that determines which Ports are returned. The current valid values are CFIDR_ITER_SCALARS, CFIDR_ITER_BUNDLES, CFIDR_ITER_TOP, and CFIDR_ITER_ALL. See the Pre-Conditions below for more detail on how these modes behave.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
view is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
view is not the OID of a NetlistView.

CFIDR_INVALID_ITERMODE:
mode is not a valid IterMode.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
Returns all or some of the Ports directly or indirectly owned by the NetlistView.

Ports in a View each have a unique position in the list of Ports owned by the NetlistView. The positions in this list are numbered from 0 for the "leftmost" or first position monotonically increasing by 1 up to one less than the size of the list. The order in which the Ports are returned is by increasing position starting with 0. Note that the Position of a given Port at a given time is determined by the various operations that have been performed on this list including:
(1) the position specified when a Port is created in a View,
(2) the position specified when a Port's owner is changed to the View, and
(3) the appearance (from inside PortBundles) and disappearance (into PortBundles) of Ports at or to the "left" of the position of the given Port.

The Ports returned depends on the mode argument specified.

mode=CFIDR_ITER_TOP
Returns all those Ports (PortBundles, PortBusses, or PortScalars) which are owned directly by view (i.e., not owned by a PortBundle).

mode=CFIDR_ITER_SCALARS
Returns all the PortScalars in view, regardless of whether they are contained in a PortBundle or not. No PortBundles are output with this mode.

mode=CFIDR_ITER_BUNDLES
Returns all the PortBundles owned directly or indirectly by view. No PortScalars are output with this mode.

mode=CFIDR_ITER_ALL
Returns all the Ports (PortBundles, PortBusses, or PortScalars) directly or recursively in view. This mode differs from CFIDR_ITER_TOP in that Ports contained indirectly in PortBundles are also returned.

The order for all modes except CFIDR_ITER_TOP is determined by depth-first recursion.

The Port name scoping rules state that Port names need only be unique within their owner (either the View or a PortBundle). Thus, in any mode except CFIDR_ITER_TOP two Ports with the same name may be returned that are completely different objects. The function cfidrObjectIsSame() can be used to determine if any two ports are the same.

POST-CONDITIONS
The cfidrIterNextPort() function returns the next Port OID in the Ports relationship.

If no objects are currently present in the Ports relationship, an error is not returned but the first call to cfidrIterNextPort() returns a Null OID.

REFERENCE
cfidrIterNextPort()
cfidrPortSetOwnerPortBundle()
cfidrPortSetOwnerView()

5.13.15 cfidrViewGetOwner

DECLARATION
cfidrCellIdT cfidrViewGetOwner(
cfidrViewIdT view,
cfidrErrorT *error)
This function returns the Cell at the end of the Owner relationship for the View specified by view. The Owner relationship is defined when an object is created and cannot be modified.

The return value is a cfidrCellIdT referring the Cell at the end of the Owner relationship. If an error occurs, a Null OID is returned.

view (input) The OID of the View whose Owner relationship is to be followed.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
view is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
view is not the OID of a View.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

REFERENCE
cfidrCellGetViews()

5.13.16 cfidrViewGetViewType

DECLARATION
cfidrStringT cfidrViewGetViewType(
cfidrViewIdT view,
cfidrErrorT *error)
This function returns the ViewType attribute of the View specified by view.

The return value is a cfidrStringT representing the value of the ViewType attribute. On error the string "" is returned.

view (input) The OID of the View whose ViewType attribute is desired.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
view is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
view is not the OID of a View.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

REFERENCE
cfidrCellCreateEncapsulatedView()
cfidrCellCreateNetlistView()

5.13.17 cfidrViewPurge

DECLARATION
cfidrVoidT cfidrViewPurge(
cfidrViewIdT view,
cfidrErrorT *error)
This function purges the View specified by view. The purge operation removes any changes made to an object since the last save or open. See the POST-CONDITIONS for more specific information.

view (input) The OID of the View to purge. The View hierarchy owned by view is also purged.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
view is not a usable OID.

CFIDR_INVALID_OBJECTTYPE:
view is not the OID of a View.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

PRE-CONDITIONS
A View can be purged regardless of the access mode of any object.

POST-CONDITIONS
Any OIDs referring to the purged view are made unusable. They may be reused to refer to other Views at some point, so the application cannot assume that if the purged View is again made available (via open, create, etc.), that it will have the same OID.

It is neither required nor precluded that whatever encapsulated information referenced by the EncapsulatedView be purged since this can be system dependent.

The effect of purging a NetlistView is to also purge the entire object hierarchy owned by that NetlistView.

Policy: The purge operation removes any changes made to the View since the last save or open. The View then becomes unavailable and its OID becomes unusable. Opening the View again assigns the View an OID and makes it available for updating.

An example implementation that provides this behavior would make an in-memory copy of the view when it was opened. Any changes to the view, or to any of its contained objects, would be made to the in-memory copy of the view. The effect of a "purge" is to delete the in-memory copy of the view, leaving the on-disk persistent view data unchanged.

Policy: Similar to open, purge also recursively walks the ownership hierarchy of Objects rooted by the specified View and purges all the Objects in this hierarchy. Unlike open, purge continues walking the ownership hierarchy when it encounters an Object which can be purged individually. Thus, purge behaves similarly to save in this respect.

Rationale: Consider the information model and take into account the policy that only Libraries and Views can be purged. Purging a View removes the View's Objects (Nets, Ports, Insts, and Props). Purging a Lib not only purges the Lib and Cells, it also purges all the Views as well.

Rationale: When opening a Lib, opening all the Views automatically is probably undesirable in most situations. However, when purging a Lib, it does not make sense to only purge the Lib and Cells and not the Views.

Policy: Purging a NetlistView "A" (and its owned Ports) that is referenced in another NetlistView "B" via the Describer relationship of an Inst (and of its PortInsts) only breaks the Describer relationships from the Inst (to "A") and the PortInsts. The Inst and PortInsts are not themselves purged nor is NetlistView "B".

REFERENCE
cfidrLibSave()
cfidrLibPurge()
cfidrViewSave()

5.13.18 cfidrViewSave

DECLARATION
cfidrVoidT cfidrViewSave(
cfidrViewIdT view,
cfidrErrorT *error)
This function saves the View specified via view. The effect of saving a View is to also save the entire Object hierarchy owned by the saved View. Saving a View makes all updates to objects in the View's hierarchy persistent. If the View has been opened for CFIDR_READ, changes to the Views contained in the View that are open for CFIDR_UPDATE will be made persistent.

view (input) The OID of the View to save. The Objects owned by view are also saved.

error (output) A pointer to the error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.

ERROR CODES
CFIDR_UNUSABLE_OID:
view is not a usable OID.

CFIDR_INVALID_OBECTTYPE:
view is not the OID of a View.

CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.

CFIDR_NO_ERROR:
no error occurred.

POST-CONDITIONS
Views cannot be saved completely independently of Libs because of the issue of referential integrity for the View's Cell's catalog entry in the Lib. Thus when a View is saved, some data associated with the owning Lib of the View will also likely have to be saved.

The Lib must also be saved such that the Cell with this View is saved. Depending on the implementation this may already be true and thus no further Lib save is needed. However, if this is a newly-created View since the last save of the Lib with the Cell containing this view, a partial save will be necessary to ensure that the Cell reference to this view is now persistent.

Other newly created but not yet saved Views are not included in the saved Lib until they are explicitly saved. However those Views still appear in "memory" unless the Cell containing them is purged.

Once a View is saved, it is known and available for opening across session boundaries until deleted via cfidrObjectDestroy().

Saving does not invalidate OIDs referring to the saved View.

REFERENCE
cfidrObjectDestroy()
cfidrPIQuit()
Table of Contents Next Chapter