ddGetObj
ddGetObj(
{ t_libName / nil }
[ t_cellName / nil ]
[ t_viewName / nil ]
[ t_fileName / nil ]
[ b_contextId / nil ]
[ t_mode ]
)
=> b_ddId / nil
Description
Finds libraries, cells, views, and files, and creates cells, views, and files (you use ddCreateLib to create libraries).
ddGetObj is re-entrant; you can call if from inside a PreCreateObj or a PostCreateObj trigger function.
Any time you create a new placeholder file using ddGetObj and do not modify the contents, you should pair that call with a call to ddReleaseObj to check for and clean up the zero-size placeholder file.
If the file you want is a CDB cellview, do not use ddGetObj. Use dbOpenCellViewByType (see dbOpenCellViewByType), which will call ddGetObj for you.
ddGetObj can call triggers on FirstAccessLib, PreCreateObj, PostCreateObj, and PreObjAccess.
|
Triggers
|
Time invoked
|
|
FirstAccessLib
|
A post-trigger invoked the first time you access any object in each library. It gets invoked once per library (unless ddUpdateLibList changes the library's path). Posttriggers may not cause the function to fail and are expected to handle cleanup of user data or other bookkeeping tasks.
|
|
PreCreateObj
|
Invoked just before DDPI creates an object.
|
|
PostCreateObj
|
Invoked just after DDPI creates an object. The trigger will not be called when a cell is re-created or overwritten, or if a new library is being created.
|
|
PreObjAccess
|
A pre-trigger invoked to allow preparation of the user environment. It is invoked each time any object is accessed.
|
DDPI defines ddGetObj's behavior using the following concepts:
-
A master file is a file that the writing application believes to contain source data or data that cannot be recreated without user input. There can be only one master file per view. The master file may be identified by one of the following mechanisms:
-
It is the only file belonging to the library, cell, or view.
-
There is a file belonging to the view named
master.tag containing the name of the master file.
-
A co-master file is a file that the writing application believes to contain source data or data that cannot be recreated without user input, but it is useless without the master. For example, an index for the master file; sheets of a multi-sheet schematic, where the index is the master; or separation of graphics and property data into separate files.
-
If a file is not a master or a co-master, it is a derived file. Derived files can be recreated from master files, or master and co-master files, in the same view. Only the creating tool can distinguish between masters or co-masters and derived files.
-
To access a derived file correctly, the tool must specify b_contextId for the master. If writing or appending to the file, use the “d” modifier in t_mode. Use
ddMarkObjMaster to change the master file in a view.
-
A file's relative name is specified relative to a library. The name consists of [/cellName[/viewName]]/fileName. Files can belong to the library, cell, or view.
-
ddGetObj searches for the object under your specified library until it finds the first occurrence of the relative named object. If you requested read access, the function is done and returns an ID. It is an error if the tool does not have read access to that object. -
If you request any other access mode,
ddGetObj first searches the object in read mode, then proceeds differently depending upon whether or not the file exists.
-
If a library has a temporary directory (defined by putting a
TMP attribute on a library with an ASSIGN statement in a cds.lib file), the following rules apply:-
While reading data,
ddGetObj looks for the data in the temporary directory first. If it is not found in the temporary directory, it looks for it in the library (the library is also referred to as the master directory). -
ddGetObj always saves or creates master or co-master files in the library, regardless of whether a temporary directory exists. This is because a temporary directory can only contain derived data, it cannot contain source data. -
ddGetObj always saves or creates derived files in the temporary directory. It creates cell or view directories as needed. A temporary directory has the same directory structure (library/cell/view) as the library.
ddGetObj takes string names instead of ddIds as the input for its query because you use it to locate objects when you do not yet have their ddIds. You can supply a context object instead of specifying some of the names. DDPI takes the missing names from the context object for the query.
Arguments
|
t_libName
|
The library name to find the object you want. The named library must appear in the libList. If you do not specify t_libName (by specifying nil or "") but you do specify b_contextId, DDPI takes the libName from the context object.
|
|
t_cellName
|
The name of a cell in the path to the object you are looking for. ddGetObj looks for the cell in t_libName. If you do not specify t_cellName (by specifying nil or "") but you specify b_contextId, DDPI takes the cellname from the context object.
|
|
t_viewName
|
The name of a view in the path to the object you are looking for. ddGetObj looks for the view in t_libName, t_cellName. If you do not specify t_viewName, but you do specify b_contextId, DDPI takes the viewName from the context object.
|
|
|
Note: t_viewName may be a space-separated list of view names. If you use this option, then each time DDPI visits a place to look for an object, it looks for one with successive view names from the list. DDPI returns successfully if it finds a match with any of the view names. Thus you can prioritize which view to look for first by ordering the view list. DDPI checks all the views in each place. It does not repeat the entire search for each view.
|
|
t_fileName
|
The name of the file object that you are looking for. ddGetObj looks for the file in t_libname only.
|
|
|
For the convenience of applications like the design editor, de, (which need to find a master file without knowing the file's name), you can specify an asterisk (*) that opens the master file belonging to the view. This feature works only for view files. In addition, if you know the file’s name and its extension or a pattern of trailing characters, you can specify the filename as *pattern, for example, *arch.vhd, and it will return the master file that matches that pattern.
|
|
b_contextId
|
You can specify a contextId object to take the library, cell, and/or view names from. This parameter provides way to find an object that is in the same directory or has the same parents as some other object.
|
|
t_mode
|
A string representing the access mode desired. Controls side effects of ddGetObj. Valid values:
-
r
Gets the ID of an existing object in the specified library. If the library has a temporary directory, looks in the temporary directory first; if the object is not found in the temporary directory, looks in the library (the master directory) -
w
Gets the ID of a new object to be created. This option is for creating master data. If the object is the first file in a view, it is marked as the master object. This will fail if a master object already exists in the specified view.
The object is created in the master directory regardless of whether the library has a temporary directory and whether the object already exists in the temporary directory. -
wc
This option is for creating co-master data and is similar to w except that if the object is a view file, it is created without marking it as a master object. This will succeed even if there is a master object in the view.
The object is created in the master directory regardless of whether the library has a temporary directory and whether the object already exists in the temporary directory.
|
|
|
-
wd
This option is for creating derived data and is similar to w except that the object is created only if the object specified by b_contextId is a master. This file is co-located with the master object, unless there is a temporary directory for the library. If there is a temporary directory, the file is created in the corresponding cell/view in the temporary directory, regardless of whether it already exists in the master directory. -
a
Gets the ID of an existing object in the specified library. You can open it for modification. The object will be created if it does not exist.
The object is created regardless of whether the library has a temporary directory and whether the object already exists in the temporary directory.
|
|
|
-
ad
Gets the ID of an existing derived object in the specified library. You can open it for modification. The object will be created if it does not exist and behaves the same as wd.
If the library has a temporary directory, the derived object is always saved or created in the temporary directory, regardless of whether it already exists in the master directory. -
Default:
r (read)
|
ddGetObj creates new cells, views, and files as a side-effect to w, wd, a or ad mode requests when the object is created. It also calls the thePreCreateObj and PostCreateObj triggers, so you can know when it does this. You need to use ddCreateLib to create libraries.
To create a file, use ddGetObj to create the file ID, followed by filePointer = outfile( ddGetObjWritePath(fileDdId)). Register a PostCreateObj trigger if you want to avoid doing an fstat to see if the PI created an empty file for you.
|
To create or access:
|
You need to specify these fields:
|
|
a library
|
t_libName or b_contextId.
|
|
a library’s file
|
t_libName* or b_contextId and t_fileName.
|
|
a cell
|
t_libName* or b_contextId and t_cellName.
|
|
a cell’s file
|
t_libName, t_cellName, and t_fileName or b_contextId (of a library), t_cellName, t_fileName or b_contextId (of an object below the cell), t_fileName.
|
|
a view
|
t_libName*, t_cellName*, and t_viewName or b_contextId (of a library), t_cellName, and t_viewName or b_contextId (of an object below the cell, and t_viewName.
|
|
a view’s file
|
t_libName,t_cellName,t_viewName,and t_fileName or b_contextId (of a library), t_cellName,t_viewName, and t_fileName or b_contextId (of an object below the cell), t_viewName, and t_fileName or b_contextId (of a view), and t_fileName.
|
|
* If a contextId is specified, this field does not need to be specified. However, the libName MUST NOT be specified if a contextId is specified.
|
Value Returned
|
b_ddId
|
An ID for the requested object.
|
|
nil
|
The object could not be found.
|
Example
fileId = ddGetObj("myLib" "myCell" "myView" "myFile" nil "r")
cellId = ddGetObj("myLib" "myCell")
viewId = ddGetObj(nil nil "myView" nil cellId)
Additional Information
The ObjAccess trigger is a pre-trigger invoked to allow preparation of the user environment. It is invoked each time any object is accessed.
The PreObjAccess should avoid calling ddGetObj() on any object because it would be recursive and dangerous.
Registering a PreObjAccess Trigger
To register a trigger to be called by ddGetObj whenever access is requested for an object, use the following code:
ddRegTrigger( "PreObjAccess" ’exampleObjAccessTrigger )
where exampleObjAccessTrigger is the SKILL function that the user implements to perform the desired PreObjAccess operations.
The PreObjAccess trigger is called with the following arguments: t_libName, t_cellName, t_viewName, t_fileName, b_contextid, and t_mode. The lib, cell, view, and file name arguments are in the name space of the calling application. The PreObjAccess trigger may need to map these to the file system name space by using the nmpCDBAToFilesys function. The PreObjAccess trigger must also resolve the name arguments with respect to any contextId argument passed to the ddGetObj call.
Related Topics
ddGetObj
Return to top
