DMCHECKOUT(5ICD)

NAME
dmCheckOut - initiate a DDM cell transaction

SYNOPSIS

#include "dmincl.h"
DM_CELL *dmCheckOut (dmproject, cell, versionstatus, versionnumber, view, mode)
DM_PROJECT *dmproject;
char *cell, *versionstatus, *view;
int versionnumber, mode;

PARAMETERS
is a pointer to a valid DM_PROJECT as obtained from dmOpenProject(). is a character string naming the cell to be checked out, this cell can not be an imported cell (or alias name). specifies the required versionstatus of the cell. Valid status types (as pre-defined in "dmincl.h") are:

WORKING -
the working version, not a member of the consistent tree. If updates are made to the primitive design data (as is determined with mode) and there is no working version, a working version will be created from the actual version.
ACTUAL -
the actual version which is a member of the consistent tree. This version parameter is the appropriate one to obtain design information of a cell when an expansion of this cell has to be created at a higher level. The primary data of the actual version may not be modified, to guarantee consistency.
BACKUP -
the backup version. Formerly, this version was an actual version. It has obtained the backup status on an install of a more recent working version as the actual.
DERIVED -
the derived version. The derived status is used for cells that have been produced by generator or extractor tools. This versionstatus is to be used as an argument value when a derived version has to be accessed for verification or when a new one has to be generated.
specifies the version to be used when versionstatus is BACKUP or DERIVED. If the versionstatus is ACTUAL or WORKING one may use DONTCARE (as pre-defined in "dmincl.h") since at most one actual or working version will be present. is the view from which design information will be read and written. Currently, valid views (as pre-defined in "dmincl.h") are LAYOUT, CIRCUIT and FLOORPLAN. Valid modes are:

READONLY -
this parameter must be used if you do not want to write at all, but only want to read some information.
UPDATE -
this parameter must be used if you want to update your primary design data. Also when a cell did not exist, it is created. This mode can only be used when versionstatus is WORKING or DERIVED.
ATTACH -
this parameter must be used to signal the DDM system that you do not want to create a new version of the module, but only want to produce or update some information giving another representation of the object (secondary information), e.g. vln-files or plot-files. This mode means that you won't (and can't) change the primitive design data.

DESCRIPTION
Function dmCheckOut() must be used to gain access to the design files of the specified version of the specified module. A pointer to a new DM_CELL key is returned. This key must be used subsequently by the functions dmOpenStream() which can then determine which object to access, and finally by the function dmCheckIn().

A cell in the DDM system is not uniquely identified by its cell name. For example, the cell adder in the project chip is another cell than the cell adder in the project test. This distinction is made in the DDM system through the DM_PROJECT key that is passed as an argument.

However, this still not completely identifies a cell. A cell adder of view-type layout is another one than the cell adder that was created in the circuit view. This distinction is made in the DDM system through the view parameter that is passed as an argument.

If the version is the WORKING version, a lock is set to prevent that other designers start working on the same cell.

Not all combinations of parameters are legal. The legal combinations of parameters match with the different types of tools that can act on the DDM system. Such tools work on primary design information within one specific view. It can update this information, which can be stored as a new (WORKING) version. The version parameter for an editor must always be WORKING and mode is UPDATE. (Cross-view tools). Such tools derive from a design description in one view a design description in another view. So, it generates equivalences between objects in different views. It has to perform at least two cell transactions, one for the existing cell and one for the generated cell. For the source design data, the version parameter may be ACTUAL, WORKING, BACKUP or DERIVED and mode is READONLY. For the generated design data the version parameter is DERIVED and mode is UPDATE. (like makevln, simulators, verifiers etc.). Such tools do not create new objects, yet derive additional information of a certain cell and attach this information to the cell. The version parameter may be ACTUAL, WORKING, BACKUP or DERIVED and the mode is ATTACH. (like show). Such tools don't write information to the DDM system at all. The version parameter can be ACTUAL, WORKING, BACKUP or DERIVED and the mode is READONLY.

SUMMARY:

TOOL | MODE | VERSION | NEW OBJECT
EDITOR | UPDATE | WORKING | YES
EXTRACTOR | READONLY | ALL | NO
EXTRACTOR | UPDATE | DERIVED | YES
DERIVE TOOLS | ATTACH | ALL | NO
READ-ONLY | READONLY | ALL | NO

DIAGNOSTICS
If properly executed, dmCheckOut() will return a pointer to a structure of type DM_CELL. If dmCheckOut() fails NULL will be returned, after a call to function dmError() is done, and dmerrno will be set to indicate the error.
This might happen in the following cases:

DME_BADKEY
    No legal project key.

DME_BADARG
    Bad arguments call.

DME_BADNAME
    Cell name not correct.

DME_BADVIEW
    Illegal view.

DME_NOCELL
    The cell does not exist in the specified view of the specified project.

DME_LOCK
    Cell is locked: cell has already been checked out by this process.

DME_SYS
    Cannot execute system call.

EXAMPLES
A plot program may initiate a cell transaction in the following way:

key = dmCheckOut (dmproject, cell, ACTUAL, DONTCARE, LAYOUT, READONLY);

1   cell is a character string containing the name of a cell in the database. This cell must be present in the layout view of the project identified by dmproject.

2   ACTUAL means that the program accesses the actual version of the module.

3   LAYOUT means that the program will access the layout description of the cell.

4   READONLY means that the program won't write data back to the database.

5   The function dmCheckOut() returns a pointer to a DM_CELL which must be used by the functions dmOpenStream(), dmCloseStream() and dmCheckIn().

The program 'makevln' may initiate a cell transaction in the following way:

key = dmCheckOut (dmproject, cell, ACTUAL, DONTCARE, LAYOUT, ATTACH);

1   ATTACH means that the program will add some information to the accessed version of the module. The DDM system will not create a new version.

2   Instead of the actual version, the program may also access the latest version if it wishes, using WORKING as the version parameter.

A layout editor may (must) initiate a cell transaction in the following way:

key = dmCheckOut (dmproject, cell, WORKING, DONTCARE, LAYOUT, UPDATE);

1   WORKING means that the program will access the latest version of the evolutionary chain of versions of the module. This is the so-called working version, or, if there is no working version, one is created where the editor stores the updated design description. A lock is set to prevent that other people start working on the same cell.

2   The view LAYOUT indicates that the program will write layout data back into the database.

An extractor may initiate its cell transactions in the following way:

key1 = dmCheckOut (dmproject, cell, WORKING, DONTCARE, LAYOUT, READONLY);
key2 = dmCheckOut (dmproject, cell, DERIVED, DONTCARE, CIRCUIT, UPDATE);

1   CIRCUIT indicates that the program will produce information for the circuit view.

SEE ALSO
dmCheckIn(5ICD).

NOTE
Since versioning is not yet supported in Release 3, ACTUAL, WORKING, BACKUP and DERIVED refer to the same data.