Table of Contents 
Previous Chapter
View Selection allows selection between different, alternative but substitutable views in a design hierarchy. While the Describer attribute of an Inst is always a specific Cell and View (namely, the describerView parameter supplied to cfidrViewCreateInst() when the Inst is created), it is possible when traversing a design hierarchy to choose a different, equivalent View. Certainly as long as the Ports of the alternative describer View have the same name, number, and directions of the PortInsts on the Inst, it is reasonable to choose the alternative View.
- NOTE: While it is certainly allowed, there is no requirement specified in DR 1.0 that the Ports of multiple NetlistViews of Cell must match in name, number, direction, or types. Furthermore, it is by definition outside of the scope of DR 1.0 to specify what sort of "ports" are in an "outside" View that is encapsulated by a cfidrEncapsulatedView or to specify how those "ports" correspond to the Ports in any particular cfidrNetlistView.
View Selection provides rules for choosing alternatives that make it possible for the user to insure that the design hierarchy is traversed in the same manner by two different tools. View Selection does not, at this time guarantee that the Views selected are equivalent to the original describer. That is up to the user of the system and, in particular, the creator of the selector objects. As with the other features of the CFI DR-PI, a mechanism is defined but methodology and policies are left to the CAD system integrator.
It is anticipated that the typical use of this mechanism will be to selectively specify the use of substructure versus available behavioral descriptions when a design is being expanded for simulation. As such, it will work naturally with the Encapsulated View mechanism, allowing either choices of multiple connectivity models (in the scope of the CFI 1.0 DR Information Model and Programming Interface) or alternative "foreign" models which must be manually synchronized to the (interface) Ports in the other connectivity views.
This overview first describes the additional objects needed for view selection and then describes the types of routines needed for view selection. It is followed by a more formal description of the Information Model and then by the function descriptions for the DR-PI.
This is a very preliminary version of a more general capability for ViewSelection anticipated to be in CFI 2.0 Design Representation. That version of CFI DR is expected to support versioning and rebinding of View references and therefore a more general concept of instantiation. There will also likely be a CFI-defined standard mechanism for mapping between Views and the objects inside of them.
The object types that are used to support view selection are:
- SelectorSet---this object contains a set of prioritized ViewSelectors and a set of prioritized LibrarySelectors. The ViewSelectors are used to specify which Views should be selected and the LibrarySelectors are used to specify where to look for Views.
LibrarySelector---this specifies which Libraries (Libs) may contain possible Cells to be selected.
ViewSelector---this specifies which View to select. A ViewSelector may be either a ViewNameSelector or a ViewTypeSelector. A ViewSelector consists of source attributes and destination attributes. The source attributes specify that a ViewSelector should only be applied in selecting a View for a Cell if the Cell matches the source attributes. Currently the source attributes are LibName and CellName. The destination attributes specify which ViewName or ViewType to select.
ViewNameSelector---this is a subtype of selector which contains selectors that specify particular ViewNames upon which to select. It may also specify a source LibName and/or source CellName which must match the Name attribute of the Cell for which we are selecting a View in order for the rule to be applied.
ViewTypeSelector---this is a subtype of a selector which contains selectors that specify particular ViewTypes to select upon. It may also specify a source LibName and/or source CellName which must match the Name attribute of the Cell for which we are selecting a View in order for the rule to be applied.
View Selection is accomplished with a set of LibrarySelectors which specify where Cells and their Views may be found and a set of ViewSelectors which specify which Cells and their Views should be selected. The selection routine cfidrSelectorSetSelectView() looks for the View in the Libraries (Libs) specified by the LibrarySelectors. cfidrSelectorSetSelectView() starts at the first ViewSelector and sees whether it selects a particular View. It continues through the ViewSelectors in order of creation until it finds a Selector which selects exactly one View. When cfidrSelectorSetSelectView() finds a ViewSelector that specifies a particular View it returns that cfidrViewIdT to the calling program.
There are four types of view selection routines, CREATION, PERSISTENCY, ATTRIBUTE ACCESS, AND SELECTION:
- CREATION: The creation routines create the SelectorSets and the various kinds of selectors in the SelectorSets.
cfidrPICreateSelectorSet();
cfidrSelectorSetCreateLibrarySelector();
cfidrSelectorSetCreateViewNameSelector();
cfidrSelectorSetCreateViewTypeSelector();
PERSISTENCY:
cfidrPIOpenSelectorSet();
cfidrSelectorSetPurge();
cfidrSelectorSetSave();
ATTRIBUTE ACCESS: The attribute access routines access the created SelectorSets and selectors. It is currently not possible to modify the attributes of an existing selector.
cfidrIterNextLibrarySelector();
cfidrIterNextViewSelector();
cfidrLibrarySelectorGetLibName();
cfidrViewNameSelectorGetCellName();
cfidrViewNameSelectorGetLibName();
cfidrViewNameSelectorGetViewName();
cfidrViewTypeSelectorGetCellName();
cfidrViewTypeSelectorGetLiblName();
cfidrViewTypeSelectorGetViewType();
SELECTION: This routine is used to select a particular view given a SelectorSet and a cell.
cfidrSelectorSetSelectView();
- ViewNameSelector with specified LibName and CellName
SrcLibName:mylib
SrcCellName:AND2
DestViewName:beh
This ViewNameSelector selects any View named "beh" for a Cell with the CellName "AND2" and a Lib with LibName "mylib" if a View with the name "beh" exists for the Cell "AND2" in any of the Libraries specified by the LibrarySelectors.
ViewNameSelector with no specified LibName and CellName
SrcLibName:
SrcCellName:
DestViewName:netlist
If the user has Libraries (Libs) whose Name attrributes are: "LibA", "LibB", and "LibC" (created in this order) specified in the LibrarySelector and "LibA" has a View whose Name attribute is "schematic," "LibB" has a View named "netlist," and "LibC" has Views named "netlist" and "schematic" for the Cell this rule would return the "LibB" View named "netlist."
ViewNameSelector with specified CellName but no specified LibName.
SrcLibName:
SrcCellName:Adder
DestViewName:schematic
This works like example 2 except that it is only applied to Cells whose Name attribute is "Adder," this time looking for Views whose Name attribute is "schematic."
ViewNameSelector with specified LibName but no specified CellName.
SrcLibName:VendorLib
SrcCellName:
DestViewName:VendorSim
This works like example2 except that it is only used with Cells whose Lib Name attribute is "VendorLib."
Figure 7.1 View Selection Information Model
6.2.2 Entity: SelectorSet
ENTITY cfidrSelectorSet
SUBTYPE OF (cfidrNamedObject);
ViewSelectors: LIST[0:?] of
UNIQUE cfidrViewSelector;
LibrarySelectors: LIST[0:?] of
UNIQUE cfidrLibrarySelector;
END_ENTITY;
6.2.3 Entity: ViewSelector
ENTITY cfidrViewSelector
SUBTYPE OF (cfidrObject)
ABSTRACT SUPERTYPE OF (ONEOF
(cfidrViewNameSelector, cfidrViewTypeSelector));
Owner: cfidrSelectorSet
END_ENTITY;
6.2.4 Entity: ViewNameSelector
ENTITY cfidrViewNameSelector
SUBTYPE OF (cfidrViewSelector);
LibName: OPTIONAL cfidrStringT;
CellName: OPTIONAL cfidrStringT;
ViewName: cfidrStringT;
END_ENTITY;
The LibName and CellName are optional attributes which are used to limit the application of a particular Selector to only those cells whose LibName and/or ViewName matches the cell whose view selection is desired.
6.2.5 Entity: ViewTypeSelector
ENTITY cfidrViewTypeSelector
SUBTYPE OF (cfidrSelector);
LibName: OPTIONAL cfidrStringT;
CellName: OPTIONAL cfidrStringT;
ViewType: cfidrStringT;
END_ENTITY;
The LibName and CellName are optional attributes which are used to limit the application of a particular Selector to only those cells whose LibName and/or ViewName matches the cell whose view selection is desired.
6.2.6 Entity: LibrarySelector
ENTITY cfidrLibrarySelector
SUBTYPE OF (cfidrObject);
libraryName: cfidrStringT;
Owner: cfidrSelectorSet
END_ENTITY;
typedef cfidrObjectIdT cfidrSelectorSetIdT;
typedef cfidrObjectIdT cfidrViewSelectorIdT;
typedef cfidrObjectIdT cfidrViewNameSelectorIdT;
typedef cfidrObjectIdT cfidrViewTypeSelectorIdT;
typedef cfidrObjectIdT cfidrLibrarySelectorIdT;
typedef cfidrIterIdT cfidrViewSelectorsIdT;
typedef cfidrIterIdT cfidrLibrarySelectorsIdT;
Additions to cfidrObjectTypeT
typedef enum {
= 0, CFIDR_UNDEFINED_OBJECTTYPE
= 1, CFIDR_LIB
= 2, CFIDR_CELL
= 3, CFIDR_PORTBUNDLE
= 4, CFIDR_PORTBUS
= 5, CFIDR_PORTSCALAR
= 6, CFIDR_INST
= 7, CFIDR_PORTINSTBUNDLE
= 8, CFIDR_PORTINSTBUS
= 9, CFIDR_PORTINSTSCALAR
= 10, CFIDR_NETBUNDLE
= 11, CFIDR_NETBUS
= 12, CFIDR_NETSCALAR
= 13, CFIDR_PROP
= 14, CFIDR_NETLISTVIEW
= 15, CFIDR_ENCAPSULATEDVIEW
= 16, CFIDR_SELECTORSET
= 17, CFIDR_LIBSELECTOR
= 18, CFIDR_VIEWNAMESELECTOR
= 19, CFIDR_VIEWTYPESELECTOR
= 20 CFIDR_MAX_OBJECTTYPE
} cfidrObjectTypeT;
DECLARATION
- cfidrLibrarySelectorIdT cfidrIterNextLibrarySelector(
- cfidrLibrarySelectorsIdT iterator,
cfidrErrorT *error)
The function returns another LibrarySelector object from the Iterator ID specified via iterator.
If there are any more LibrarySelectors in the iterator, the return value is an OID of type cfidrLibrarySelectorIdT for the next LibrarySelector. If an error occurs or there are no more LibrarySelectors, a Null OID is returned. If there are no more LibrarySelectors this is not an error.
iterator (input) The Iterator ID of an Iterator over LibrarySelector objects.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.
ERROR CODES
CFIDR_INVALID_ITER:
iterator is not a valid Iterator.
CFIDR_INVALID_ITER_TYPE:
iterator is not an Iterator of LibrarySelectors.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
DECLARATION
- cfidrSelectorSetIdT cfidrIterNextSelectorSet(
- cfidrSelectorSetsIdT iter,
cfidrErrorT *error)
This function returns another Selector Set object from the Iterator ID specified via iter.
The return value is a cfidrSelectorSet referencing the Selector Set object just iterated.
If an error occurs or there are no more Selector Sets to iterate, a Null OID is returned. If there are no more Selector Sets to iterate, this is not an error.
iter (input) The Iterator ID representing an Iterator of Selector Set objects.
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_INVALID_ITER:
iter is not the ID of a valid Iterator.
CFIDR_INVALID_ITER_TYPE:
iter is not the ID of an Iterator of Selector Set objects.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
PRE-CONDITIONS
The iter argument must have been returned via a previous call to cfidrPIGetSelectorSets().
POST-CONDITIONS
If the Selector Set is not already open, this function will attempt to open it. If the open fails, the error return for this function will be the error return of the open. The iteration sequence can continue after a failed Selector Set open.
REFERENCE
cfidrPIGetSelectorSets()
DECLARATION
- cfidrViewSelectorIdT cfidrIterNextViewSelector(
- cfidrViewSelectorsIdT iterator,
cfidrErrorT *error)
The function returns another ViewSelector object from the Iterator ID specified via iterator.
If there are any more ViewSelectors in the iterator, the return value is an OID of type cfidrViewSelectorIdT for the next ViewSelector. If an error occurs or there are no more ViewSelectors, a Null OID is returned. If there are no more ViewSelectors this is not an error.
iterator (input) The Iterator ID representing an Iterator ViewSelector objects.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory used by this parameter.
ERROR CODES
CFIDR_INVALID_ITER:
iterator is not a valid Iterator.
CFIDR_INVALID_ITER_TYPE:
iterator is an Iterator of ViewSelectors.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
DECLARATION
- cfidrStringT cfidrLibrarySelectorGetLibraryName(
- cfidrLibrarySelectorIdT librarySelector,
cfidrErrorT *error)
Returns the LibraryName attribute of the LibrarySelector specified in librarySelector.
The return value is of type cfidrStringT and is the value of the LibraryName attribute of librarySelector. On error a Null string (" ") is returned.
librarySelector (input) The OID of the LibrarySelector whose LibraryName attribute is desired.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
librarySelector is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
librarySelector is not the OID of a LibrarySelector.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
DECLARATION
- cfidrSelectorSetIdT cfidrPICreateSelectorSet(
- cfidrStringT name,
cfidrErrorT *error)
Creates a SelectorSet with the specified name. The SelectorSet may contain a prioritized/ordered list of ViewSelectors and LibrarySelectors. The Selectors are prioritized based on the order of creation. The first Selector created will have the highest priority. The second Selector created will have the next highest priority.
The return value is an OID of type cfidrSelectorSetIdT for the SelectorSet just created. If an error occurs a Null OID is returned.
name (input) The string representing the name of the SelectorSet to be created.
error (output) The error returned if this function fails. The caller is responsible for allocating memory for this parameter.
ERROR CODES
CFIDR_INVALID_NAME
the name parameter is not a valid string or is not a legal name.
CFIDR_OBJECT_ALREADY_EXISTS:
a SelectorSet with the same name already exists.
CFIDR_INTERNAL_SYSTEM_ERROR
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
PRE-CONDITIONS
The name of the SelectorSet must conform to the character set for name strings. No SelectorSet with the same name may exist.
The system implementing the DR-PI is responsible for knowing about all SelectorSets created and saved in previous sessions or created in the current session when determining whether the SelectorSet already exists. The SelectorSet need not be opened to be considered as existing.
Each system implementing the DR-PI is responsible for creating and maintaining the SelectorSet's data-storage area. The application using the PI need not have any prior knowledge of where the data physically resides.
If cfidrPIINIT() has not been called previously, it is called automatically before this function.
POST-CONDITIONS
A SelectorSet is created with no ViewSelectors or LibrarySelectors.
A created SelectorSet is not persistent across session boundaries until it is saved.
DECLARATION
- cfidrSelectorSetsIdT cfidrPIGetSelectorSets(
- cfidrErrorT *error)
This function initiates a traversal of all the Selector Sets known by the DR-PI.
The return value is a cfidrSelectorSetsIdT referring to an Iterator ID that iterates over Selector Sets.
If an error occurs in cfidrPIGetSelectorSets(), the error output argument is set and a valid Iterator ID is returned. In this case, calling the cfidrIterNextSelectorSet() function returns the Null OID.
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_INTERNAL_SYSTEM_ERROR:
a system error occurred.
CFIDR_NO_ERROR:
no error occurred.
POST-CONDITIONS
The cfidrIterNextSelectorSet() function returns the OID of the next Selector Set known by the DR-PI.
If no Selector Sets are known by the PI, an error is not returned but the first call to cfidrIterNextSelectorSet() returns the Null OID.
If cfidrPIInit() has not been called before, this function will call it before proceeding.
REFERENCE
cfidrIterNextSelectorSet()
cfidrPIInit()
DECLARATION
- cfidrSelectorSetIdT cfidrPIOpenSelectorSet(
- cfidrStringT name,
cfidrErrorT *error)
This function opens a SelectorSet specified via name and allows it to be updated.
The return value is an OID of type cfidrSelectorSetIdT for the SelectorSet just opened. If an error occurs, a Null OID is returned.
name (input) A string representing the name of the SelectorSet to be opened.
error (output) The error returned if this function fails. The caller is responsible for allocating memory used by this parameter.
ERROR CODES
CFIDR_INVALID_NAME:
name parameter is not a valid string or is not a legal name.
CFIDR_OBJECT_NOT_FOUND:
no SelectorSet with the specified name exists.
CFIDR_OPEN_FOR_UPDATE_FAILED:
a SelectorSet with the specified name exists or is open already but it is not possible to update it.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occured.
PRE-CONDITIONS
If the SelectorSet does not exist, it is not created automatically.
If cfidrPIINIT() has not been called previously, it is called automatically before this function.
POST-CONDITIONS
If the SelectorSet has been previously opened but not purged in the current session, then opening it again returns the same OID. In this case, the error output argument should be set to CFIDR_NO_ERROR to denote this fact even thought it is not an error.
DECLARATION
- cfidrLibrarySelectorIdT
cfidrSelectorSetCreateLibrarySelector(
- cfidrSelectorSetIdT owner,
cfidrStringT libraryName,
cfidrErrorT *error)
Creates a LibrarySelector in the SelectorSet specified by owner and adds it to the end of the list in the LibrarySelectors attribute of owner. The LibrarySelector defines which Libs are used for view selection.
The return value is an OID of type cfidrLibrarySelectorIdT for the LibrarySelector just created. If an error occurs a Null OID is returned.
owner (input) The OID of the SelectorSet owning the Selector to be added.
libraryName (input) The string representing the LibraryName of the LibrarySelector.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a SelectorSet.
CFIDR_INVALID_NAME:
the libraryName parameter is not a valid string or is not a legal name.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
DECLARATION
- cfidrViewNameSelectorIdT
cfidrSelectorSetCreateViewNameSelector(
- cfidrSelectorSetIdT owner,
cfidrStringT libName,
cfidrStringT cellName,
cfidrStringT viewName,
cfidrErrorT *error)
Creates a ViewNameSelector in the owner SelectorSet. This routine adds the newly created selector to the end of the list of ViewSelectors associated with the SelectorSet specified by owner.
This ViewNameSelector may then be used by cfidrSelectorSetSelectView() to select a particular view. Both the libName and cellName parameters are optional. They are used to specify whether a ViewSelector should be used for a particular Cell. If the libName and/or the cellName attributes are not Null strings in the newly created ViewNameSelector then they must match the Cell passed to cfidrSelectorSetSelectView() in order for this ViewNameSelector to be used.
The return value is an OID of type cfidrViewNameSelectorIdT for the ViewNameSelector just created. If an error occurs a Null OID is returned.
owner (input) The OID of the SelectorSet owning the Selector to be added.
libName (input) A cfidrStringT representing the Name of a Lib to be used as a match for the function cfidrSelectorSetSelectView().
cellName (input) A cfidrStringT representing the Name of a Cell to be used as a match for the function cfidrSelectorSetSelectView().
viewName (input) A cfidrStringT representing the ViewName of a View to be used as a match for the function cfidrSelectorSetSelectView().
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a SelectorSet.
CFIDR_INVALID_NAME:
either the libName, cellName, or viewName parameter is not a valid string or is not a legal name.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred
PRE-CONDITIONS
If the libName is a Null string, it acts like a wildcard and matches any Lib's Name.
If the cellName is a Null string, it acts like a wildcard and matches any Cell's Name.
POST-CONDITIONS
This ViewNameSelector cannot have its attributes changed later. If incorrect attributes are present, the application writer must destroy the Selector then create new selector(s) with the new attributes(s).
REFERENCE
cfidrSelectorSetSelectView()
cfidrObjectDestroy()
DECLARATION
- cfidrViewTypeSelectorIdT
cfidrSelectorSetCreateViewTypeSelector(
- cfidrSelectorSetIdT owner,
cfidrStringT libName,
cfidrStringT cellName,
cfidrStringT viewType,
cfidrErrorT *error)
Creates a ViewTypeSelector in the owner SelectorSet. This routine adds the newly created selector to the end of the list of ViewSelectors associated with the SelectorSet specified by owner.
This ViewTypeSelector may then be used by cfidrSelectorSetSelectView() to select a particular view. Both the libName and cellName parameters are optional. They are used to specify whether a ViewSelector should be used for a particular Cell. If the libName and/or the cellName attributes are not Null strings in the newly created ViewTypeSelector then they must match the Cell passed to cfidrSelectorSetSelectView() in order for this ViewTypeSelector to be used.
The return value is in OID of type cfidrViewTypeSelectorIdT for the ViewTypeSelector just created. If an error occurs a Null OID is returned.
owner (input) The OID of the SelectorSet owning the Selector to be added.
libName (input) A cfidrStringT representing the Name of a Lib to be used as a match for the function cfidrSelectorSetSelectView().
cellName (input) A cfidrStringT representing the Name of a Cell to be used as a match for the function cfidrSelectorSetSelectView().
viewType (input) A cfidrStringT representing the ViewType of a View to be used as a match for the function cfidrSelectorSetSelectView().
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
owner is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
owner is not the OID of a SelectorSet.
CFIDR_INVALID_NAME:
either the libName or cellName parameter is not a legal name, or the viewType parameter is not a valid string.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred
PRE-CONDITIONS
If the libName is a Null string, it acts like a wildcard and matches any Lib's Name.
If the cellName is a Null string, it acts like a wildcard and matches any Cell's Name.
POST-CONDITIONS
This ViewTypeSelector cannot have its attributes changed later. If incorrect attributes are present, the application writer must destroy the entire Selector then create new selector(s) with the new attributes(s).
REFERENCE
cfidrSelectorSetSelectView()
cfidrObjectDestroy()
DECLARATION
- cfidrLibrarySelectorsIdT
cfidrSelectorSetGetLibrarySelectors(
- cfidrSelectorSetIdT selectorSet,
cfidrErrorT *error)
This function initiates traversal of all the LibrarySelectors in the LibrarySelectors list in the SelectorSet specified by selectorSet.
The return value is a cfidrLibrarySelectorsIdT referring to an Iterator ID that iterates over LibrarySelectors. If an error occurs, a Null OID is returned, but the first call to cfidrIterNextLibrarySelector() returns a Null OID.
selectorSet (input) The OID of the selectorSet for which the Selectors relation is to be traversed.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
selectorSet is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selectorSet is not the OID of a SelectorSet.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
POST-CONDITIONS
The cfidrIterNextLibrarySelector() function returns the OID of the next LibrarySelector known by the LibrarySelector relationship.
REFERENCE
cfidrIterNextLibrarySelector()
DECLARATION
- cfidrViewSelectorsIdT cfidrSelectorSetGetViewSelectors(
- cfidrSelectorSetIdT selectorSet,
cfidrErrorT *error)
This function initiates traversal of all the ViewSelectors at the end of the ViewSelectors relationship defined for the SelectorSet specified by selectorSet.
The return value is a cfidrViewSelectorsIdT referring to an Iterator ID that iterates over ViewSelectors. If an error occurs, a valid Iterator is returned, but the first call to cfidrIterNextViewSelector() returns a Null OID.
selectorSet (input) The OID of the selectorSet for which the Selectors relation is to be traversed.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
selectorSet is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selectorSet is not the OID of a SelectorSet.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
REFERENCE
cfidrIterNextViewSelector()
DECLARATION
- cfidrVoidT cfidrSelectorSetPurge(
- cfidrSelectorSetIdT selectorSet,
cfidrErrorT *error);
This function purges the SelectorSet specified by selectorSet. The effect of purging a SelectorSet is also to purge the entire Object hierarchy (all the selectors it contains) owned by the purged SelectorSet.
selectorSet (input) The OID of the SelectorSet to purge. All ViewSelectors and LibrarySelectors in the SelectorSet are also purged.
error (output) The error returned if this function fails. The caller is responsible for allocating memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
selectorSet is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selectorSet is not the OID of a SelectorSet.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
PRE-CONDITIONS
A SelectorSet can be purged regardless of the access mode of any object.
POST-CONDITIONS
Any OIDs referring to purged SelectorSets are made unusable. They may be reused to refer to other SelectorSets at some point, so the application cannot assume that if the purged SelectorSet is again made available (via, open, create, etc.) that it will have the same OID.
Policy: The purge operation removes any changes made to an object since the last save or open. The object then becomes unavailable and its OID becomes unusable. Opening the SelectorSet again assigns the SelectorSet an OID and makes it available for updating.
An example implementation that provides this behavior would make an in-memory copy of the SelectorSet when it was opened. Any changes to the SelectorSet, or to any of its contained objects, would be made to the in-memory copy of the SelectorSet. The effect of a "purge" is to delete the in-memory copy of the SelectorSet, leaving the on-disk persistent SelectorSet data unchanged.
Policy: Similar to open, purge also recursively walks the ownership hierarchy rooted by the specified SelectorSet and purges all Objects (LibrarySelectors and ViewSelectors) 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.
REFERENCE
cfidrSelectorSetSave()
DECLARATION
- cfidrVoidT cfidrSelectorSetSave(
- cfidrSelectorSetIdT selectorSet,
cfidrErrorT *error)
This function saves the SelectorSet specified via selectorSet. The effect of saving a SelectorSet is also to save the entire Object hierarchy (all selectors it contains) owned by the saved selectorSet. Saving a SelectorSet makes all updates to objects (selectors) in the SelectorSet's hierarchy persistent.
selectorSet (input) The OID of the SelectorSet to save. The ViewSelectors and LibrarySelectors of the selectorSet are also saved.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
selectorSet is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selectorSet is not the OID of a SelectorSet.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
DECLARATION
- cfidrViewIdT cfidrSelectorSetSelectView(
- cfidrSelectorSetIdT selectorSet,
cfidrCellIdT cell,
cfidrErrorT *error)
Uses the information in a Cell and a SelectorSet to compute the selected view. This routine uses the LibrarySelectors in the SelectorSet to determine which libraries contain views for selection and ViewSelectors to determine which selector should be selected.
This routine looks for the view in the libraries specified by the LibrarySelectors. cfidrSelectorSetSelectView() starts at the first ViewSelector and determines whether it selects a particular view. It continues through the ViewSelectors in order of creation until it finds a Selector which selects exactly one view. When cfidrSelectorSetSelectView() finds a ViewSelector that specifies a particular view, it returns that view to the calling program. If multiple views are selected by a ViewSelector the error CFIDR_MULTIPLE_VIEWS_MATCH is set and a Null OID is returned.
The ViewSelector specifies the selection of a particular ViewName or ViewType in the libraries specified by the LibrarySelector.
The following pseudo-code illustrates a possible algorithm for this routine. It is intended to demonstrate functionality rather than require this particular algorithm.
viewSelectorIterator =
cfidrSelectorSetGetViewSelectors(selectorSet, &error);
viewSelector =
cfidrIterNextViewSelector(viewSelectorIterator, &error);
error = CFIDR_NO_VIEW_MATCHES;
// *** iterate through the ViewSelectors to choose a View ***
while (cfidrObjectIsUsable(viewselector) == CFIDR_TRUE)
{
// *** if we should look at this selector
if ((viewSelector's LibName is null or
matches cells LibName) AND
(viewSelector's CellName is null or
matches cells CellName))
{
// look at libraries in SelectorSet
libraryIterator =
cfidrSelectorSetGetLibrarySelectors(
selectorSet, &error);
librarySelector = cfidrIterNextLibrarySelector(
libraryIterator, &error);
while (cfidrObjectIsUsable(libraryselector,
&error) ==CFIDR_TRUE)
{
if (exactly 1 view exists in
Lib/CellName with specified name/type)
{
error = CFIDR_NO_ERROR
return view
}
if (>1 view found)
{
error = CFIDR_MULTIPLE_VIEWS_MATCH;
return(cfidrPIGetNullId());
}
}
}
}
// *** no object found
return(cfidrPIGetNullId());
The return value is an OID of type cfidrViewIdT for the View selected. If an error occurs, a Null OID is returned.
selectorSet (input) The OID of the SelectorSet used to do view selection.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
selectorSet is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selectorSet is not the OID of a SelectorSet.
CFIDR_NO_VIEW_MATCHES:
No matches were found for views meeting the view selection criteria specified by the selectorSet.
CFIDR_MULTIPLE_VIEWS_MATCH:
If a ViewTypeSelector finds multiple views of the same type in the same cell owned by library then this error will be returned.
CFIDR_UNUSABLE_CELL_OID:
cell is not a usable OID.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
DECLARATION
- cfidrStringT cfidrViewNameSelectorGetCellName(
- cfidrViewNameSelectorIdT selector,
cfidrErrorT *error)
Gets the CellName attribute of a ViewNameSelector
The CellName of the ViewNameSelector. This may legally be a Null string if cfidrSelectorSetCreateViewNameSelector() was called with a Null CellName string. A Null string is also returned if there is an error, therefore the value at error must be checked whenever a Null string is returned to determine if the Null string is the correct return or if an error has occurred.
selector (input) The OID of the ViewNameSelector whose CellName attribute is desired.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
selector is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selector is not the OID of a ViewNameSelector.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred
REFERENCE
cfidrSelectorSetCreateViewNameSelector()
DECLARATION
- cfidrStringT cfidrViewNameSelectorGetLibName(
- cfidrViewNameSelectorIdT selector,
cfidrErrorT *error)
Gets the LibName attribute of a ViewNameSelector
The LibName of the ViewNameSelector. This may legally be a Null string, if cfidrSelectorSetCreateViewNameSelector() was called with a Null LibName string. A Null string is also returned if there is an error, therefore the value at error must be checked whenever a Null string is returned to determine if the Null string is the correct return or if an error has occurred.
selector (input) The OID of the ViewNameSelector whose LibName attribute is desired.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
selector is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selector is not the OID of a SelectorSet.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
REFERENCE
cfidrSelectorSetCreateViewNameSelector()
DECLARATION
- cfidrStringT cfidrViewNameSelectorGetViewName(
- cfidrViewNameSelectorIdT selector,
cfidrErrorT *error)
Gets the ViewName attribute of a ViewNameSelector
The ViewName of the ViewNameSelector. This may legally be a Null string, if cfidrSelectorSetCreateViewNameSelector() was called with a Null ViewName string. It will be a Null string if there is an error. If there is an error a Null string is also returned, therefore the value at error must be checked whenever a Null string is returned to determine if the Null string is the correct return or if an error has occurred.
selector (input) The OID of the ViewNameSelector whose ViewName attribute is desired.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
CFIDR_UNUSABLE_OID:
selector is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selector is not the OID of a ViewNameSelector.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
REFERENCE
cfidrSelectorSetCreateViewNameSelector()
DECLARATION
- cfidrStringT cfidrViewTypeSelectorGetCellName(
- cfidrViewTypeSelectorIdT selector,
cfidrErrorT *error)
Gets the CellName attribute of a ViewTypeSelector.
The CellName of the ViewTypeSelector. This may legally be a Null string if cfidrSelectorSetCreateViewTypeSelector() was called with a Null CellName string. If there is an error a Null string is also returned, therefore the value at error must be checked whenever a Null string is returned to determine if the Null string is the correct return or if an error has occurred.
selector (input) The OID of the ViewTypeSelector whose CellName attribute is desired.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
selector is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selector is not the OID of a ViewTypeSelector.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
REFERENCE
cfidrSelectorSetCreateViewTypeSelector()
DECLARATION
- cfidrStringT cfidrViewTypeSelectorGetLibName(
- cfidrViewTypeSelectorIdT selector,
cfidrErrorT *error)
Gets the LibName attribute of a ViewTypeSelector.
The LibName of the ViewTypeSelector. This may legally be a Null string if cfidrSelectorSetCreateViewTypeSelector() was called with a Null LibName string. If there is an error a Null string is also returned, therefore the value at error must be checked whenever a Null string is returned to determine if the Null string is the correct return or if an error has occurred.
selector (input) The OID of the ViewTypeSelector whose LibName attribute is desired.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
selector is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selector is not the OID of a ViewTypeSelector.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
REFERENCE
cfidrSelectorSetCreateViewTypeSelector()
DECLARATION
- cfidrStringT cfidrViewTypeSelectorGetViewType(
- cfidrViewTypeSelectorSetIdT selector,
cfidrErrorT *error)
Gets the ViewType attribute of a ViewTypeSelector.
The ViewType of the ViewTypeSelector. It will be a Null string if there is an error.
selector (input) The OID of the ViewTypeSelector whose ViewType attribute is desired.
error (output) The error returned if this function fails. The caller is responsible for allocating the memory for this parameter.
ERROR CODES
CFIDR_UNUSABLE_OID:
selector is not a usable OID.
CFIDR_INVALID_OBJECTTYPE:
selector is not the OID of a ViewTypeSelector.
CFIDR_INTERNAL_SYSTEM_ERROR:
some other error occurred.
CFIDR_NO_ERROR:
no error occurred.
REFERENCE
cfidrSelectorSetCreateViewTypeSelector()
Table of Contents 
Next Chapter
