Cell Geometry Digest

(string) OpenCellGeomDigest(idname, string, type)
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 created.

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 limitations.

In this mode, the string argument can be one of the following:

1. A layout (archive) file. The file will be read and the geometry extracted.
2. The access name of a Cell Hierarchy Digest (CHD) in memory. The CHD will be used to read the geometry from the file it references.
3. 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.
4. A saved CGD file name. The file will be read into an in-memory CGD.

Files are opened from the library search path, if a full path is not provided.

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

hostname[:port]/idname

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 cell geometry.

(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, new_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 returned.

(int) CgdIsValidLayer(cgd_name, cellname, layername)
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 returned.

(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, layername)
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, cells_list)
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, cellname, layername)
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 be effective.

If the arguments are unresolved, the return value is a scalar 0.

(gs_handle) CgdOpenGeomStream(cgd_name, cellname, layername)
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 CgdContents.

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 stream.

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 this function.

(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.