- (string) OpenCellGeomDigest(idname, string,
This function returns an access name to a new Cell Geometry Digest
(CGD) which is created in memory. A CGD is a data structure that
provides access to cell geometry saved in compact form, and does not
use the main cell database. The CGD refers to physical data only.
The new CGD will be listed in the Cell Geometry Digests panel,
and the access name is used by other functions to access the CGD.
See the table in 14.1 for the features that apply during a
call to this function. In particular, the names of cells saved in the
CGD reflect any aliasing that was in force at the time the CGD was
The first argument is a specified access name (which will be returned
on success). This name can not be in use, meaning that the name can
not access an existing CGD which is currently linked to a CHD. If
there is a name match to an unlinked CGD, the new CGD will replace the
old (which is destroyed). This argument can be passed 0 or an empty
string. If a null or empty string is passed, a new access name will
be generated and assigned.
The third argument is an integer 0-2 which specifies the type of CGD
to create. The second (string) argument depends on what type
of CGD is being created.
- Type 0 (actually, type not 1 or 2)
This will create a ``memory'' CGD, where all geometry data will be
stored in memory, in highly-compressed form. This provides the most
efficient access, but very large databases may exceed memory
In this mode, the string argument can be one of the following:
- A layout (archive) file. The file will be read and the
- The access name of a Cell Hierarchy Digest (CHD) in memory.
The CHD will be used to read the geometry from the file it
- A saved CHD file. The file will be read, and a new CHD will
be created in memory. This CHD will be used to read the geometry
from the file referenced.
- A saved CGD file name. The file will be read into an
Files are opened from the library search path, if a full path is
- Type 1
This will create a ``file'' CGD, where geometry data are stored in a
CGD file on disk, and geometry is retrieved when needed via saved
file offsets. This uses less memory, but is not quite as fast as
saving geometry data in memory. It is generally much faster than
reading geometry from the original layout file since 1) the data
are highly compressed, and 2) the objects are pre-sorted by layer.
In this mode, the string is a path to a saved CGD file, or to a
saved CHD file containing geometry records. The in-memory CGD will
access this file. The file is opened from the library search path, if
a full path is not provided.
- Type 2
This will create a stub CGD which obtains geometry information from a
remote host which is running Xic in server mode. The server must
have a CGD in memory, from which data are obtained.
In this mode, the string must be in the format
The [...] indicates ``optional'' and is not literal. The
hostname is the network name of the machine running the server.
If the server is using a non-default port number, the same port number
should be provided after the host name, separated by a colon.
Following the hostname or port is the access name on the server of the
CGD to access, separated by a forward slash. The entire string should
contain no white space.
On error, a null string is returned, and an error message may be
available with the GetError function.
- (string) NewCellGeomDigest()
This function creates a new, empty Cell Geometry Digest, and returns
the access name. The CgdAddCells function can be used to add
- (int) WriteCellGeomDigest(cgd_name, filename)
This function will write a disk file representation of the Cell
Geometry Digest (CGD) associated with the access name given as the
first argument, into the file whose name is given as the second
argument. Subsequently, the file can be read with OpenCellGeomDigest to recreate the CGD. The file has no other
use and the format is not documented.
The function returns 1 if the file was written successfully, 0
otherwise, with an error message likely available from GetError.
- (stringlist_handle) CgdList()
This function returns a handle to a list of access strings to Cell
Geometry Digests that are currently in memory. The function never
fails, though the handle may reference an empty list.
- (int) CgdChangeName(old_cgd_name,
This function allows the user to change the access name of an existing
Cell Geometry Digest (CGD) to a user-supplied name. The new name must
not already be in use by another CGD.
The first argument is the access name of an existing CGD, the second
argument is the new access name, with which the CGD will subsequently
be accessed. This name can be any text string, but can not be null.
The function returns 1 on success, 0 otherwise, with an error message
likely available from GetError.
- (int) CgdIsValid(cgd_name)
This function returns one if the string argument is an access name of
a Cell Geometry Digest currently in memory, zero otherwise.
- (int) CgdDestroy(cgd_name)
The string argument is the access name of a Cell Geometry Digest (CGD)
currently in memory. If the CGD is not currently linked to a Cell
Hierarchy Digest (CHD), then the CGD will be destroyed and its memory
freed. One is returned on success, zero otherwise, with an error
message likely available with GetError.
- (int) CgdIsValidCell(cgd_name, cellname)
This function will return 1 if a Cell Geometry Digest (CGD) with an
access name given as the first argument exists and contains data for
the cell whose name is given as the second argument. Otherwise, 0 is
- (int) CgdIsValidLayer(cgd_name, cellname,
This function returns 1 if the cgd_name is an access name of a
Cell Geometry Digest (CGD) in memory, which contains a cell cellname that has data for layer layername. Otherwise, 0 is
- (int) CgdRemoveCell(cgd_name, cellname)
This function will remove and destroy the data for the cell cellname from the Cell Geometry Digest (CGD) with access name cgd_name. This applies to all CGD types, as described for OpenCellGeomDigest. If the CGD is accessing geometry from a remote
server, the cell data are removed from the server.
The names of cells that have been removed are retained, and can be
checked with CgdIsCellRemoved.
If the CGD is found and it contains cellname, the cell data
are destroyed and the function returns 1. Otherwise, 0 is returned,
with an error message available from GetError.
- (int) CgdIsCellRemoved(cgd_name, cellname)
This function returns 1 if a CGD is found with access name as given in
cgd_name, and the cellname is the name of a cell that has
been removed from the CGD, for example with CgdRemoveCell.
Otherwise, the return value is 0.
- (int) CgdRemoveLayer(cgd_name, cellname,
If the Cell Geometry Digest (CGD) exists, and contains data for a cell
cellname that contains data for layername, the layername data will be deleted from the cellname record, and
the function returns 1. Otherwise, 0 is returned, with an error
message likely available from GetError.
This applies to memory and file type CGDs, as described for OpenCellGeomDigest. The data, if found, are freed, and (unlike CgdRemoveCell) no record of removed layers is retained. This
actually reduces memory use only for memory type CGDs.
- (int) CgdAddCells(cgd_name, chd_name,
This function will add a list of cells to the Cell Geometry Digest
(CGD) whose access name is given as the first argument. The cells
will be read using the Cell Hierarchy Digest (CHD) whose access name
is given as the second argument.
This, and the CgdRemoveCell function can be used to implement a
cache for cell data. When a CHD is used for access, and a CGD has
been linked to the CHD, the CHD will read geometry information for
cells in the CGD from the CGD, and cells not found in the CGD will be
read from the layout file. Thus, if memory is tight, one can put only
the heavily-used cells into the CGD, instead of all cells.
If the CGD already contains data for a cell to add, the data will be
overwritten with the new cell data.
For the cells_list argument, one can pass either a handle to a
list of strings that contain cell names, or a string containing
space-separated cell names. If a cell named in the list is not found
in the CHD, it will be silently ignored.
This applies to memory and file type CGDs, as described for OpenCellGeomDigest. The geometry records are saved in memory,
whether or not the CGD is file type. Individual records set the
access method, so it is possible to have mixed file access and memory
access records in the same CGD.
On success, 1 is returned. If an error occurs, 0 is returned, and a
message may be available from GetError.
- (stringlist_handle) CgdContents(cgd_name,
This function returns content listings from the Cell Geometry Digest
(CGD) whose access name is given in the first argument. The remaining
string arguments give the cell name and layer name to query. Either
or both of these arguments can be null (passed 0).
If the cellname is null, a handle to a list if strings giving
the cell names in the CGD is returned. otherwise, the cellname
must be a cell name from the CGD.
If layername is null, the return value is handle to a list of
layer name strings for layers used in cellname. If layername is not null, it should be one of the layer names contained
in the cellname.
The return value when both cellname and layername are
non-null is a handle to a list of two strings. The first string gives
the integer number of bytes of compressed geometry for the cell/layer.
The second string gives the size of the geometry string after
decompression. The compressed size can be 0, in which case
compression was not used as the block is too small for compression to
If the arguments are unresolved, the return value is a scalar 0.
- (gs_handle) CgdOpenGeomStream(cgd_name,
This function creates a handle to an iterator for decompressing the
geometry in a Cell Geometry Digest (CGD). The first argument is the
access name of the CGD. The second argument is the name of one of the
cells contained in the CGD. The third argument is the name of a layer
used by the cell. The cells and layers in the CGD can be listed with
The return value is a handle to an incremental reader, loaded with the
compressed geometry for the cell and layer. This can be passed to
GsReadObject to obtain the geometrical objects.
The Close function can be used to destroy the reader. It will
be closed automatically if
GsReadObject iterates through all objects contained in the
A scalar 0 is returned if the arguments are not resolved.
- (object_handle) GsReadObject(gs_handle)
This function takes the handle created with CgdOpenGeomStream
and returns an object handle which points to a single object. A
different object will be returned with each call until all objects
have been returned, at which time the geometry stream handle is
closed. Further calls will return a scalar 0.
The ConvertReply function can also return a handle for use by
- (int) GsDumpOasisText(gs_handle)
This function will dump the geometry stream in OASIS ASCII text
representation to the console window (standard output). The handle is
freed. This may be useful for debugging.