Ingres CL DS
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - DS
Abstract
This is the specification of the DS facility provided by the compatibility library for writing data structures to files that can be compiled into loadable object. This is used by vifred to compile forms and by ABF.
Revision: 1.1, 11-Nov-1997
Document History
- Revision 1.1, last modified 11-Nov-1997
- Changed to html.
- Revision 1.0, last modified 27-Aug-91
- Clarified use of DSL_C and DSA_C.
Specification
Introduction
DS is used to create instances of data structures in a compilable source. An example of this usage is the compiled form file created by vifred, which provides users with non-database copies of their forms to compile and link into their programs.
Producing source file instances of structures involves use of the DSbegin, DSinit, DSwrite, DSfinal and DSend routines.
The language used to write the data structure is a parameter as is the alignment used in the data structure. The constants for the languages are DSL_MACRO (for assembler) and DSL_C (for C).
An implementation need only implement one of these languages. On UNIX, for instance, only DSL_C is supported. Client code must be written in a way allowing the use of any of the supported languages.
For DSL_MACRO, the setting of alignment determines how the data structure is aligned. It can either be DSA_UN to be unaligned, or it can be DSA_C to align the structure as the native C compiler will. If DSL_C is used, DSA_C is assumed.
The DSV_GLOB and DSV_LOCAL parameters are used to specify visibility of a structure, ie. to make it visible outside the source file, or only a local definition.
The basic sequence of events to write a group of data structures to a source file is as follows:
DSbegin( ... ); ... DSinit( ... ); /* start of new data structure */ DSwrite( ... ); /* items */ DSwrite( ... ); ... DSfinal(); ... DSinit( ... ); /* next structure */ DSwrite( ... ); DSwrite( ... ); ... DSfinal(); ... DSend( ... );
Header File <ds.h>
The header file <ds.h> must be included before using any of the functions provided. It also defines the following.
Language Constants:
| DSL_C | C language source |
| DSL_MACRO | Assembler language source |
Type constants
| DSD_I4 | for an i4 |
| DSD_I2 | for an i2 |
| DSD_I1 | for an i1 |
| DSD_F4 | for an f4. |
| DSD_F8 | for an f8. |
| DSD_CHAR | for a single character |
| DSD_STR | for a string (The length must be given) |
| DSD_SPTR | for a null terminated string |
| DSD_ADDR | for the address of a label. |
| DSD_IADDR | for the address of an integer. |
| DSD_ARYADR | for the address of an array. |
| DSD_PTADR | for the address of an object to be cast to a VTREE *. |
| DSD_PLADR | for the address of an object to be cast to a VLIST *. |
| DSD_VRADR | for the address of an object to be cast to a ABRTSVAR *. |
| DSD_FRADR | for the address of an object to be cast to a FRAME *. |
| DSD_MENU | for the address of an object to be cast to a MENU *. |
| DSD_FNADR | for the address of an object to be cast to a pointer to function returning a i4. |
| DSD_NAT | for the address of an object to be cast to a i4. |
| DSD_FORP | for the address of an object to be cast to a ABRTSFO *. |
| DSD_PTR | for the address of an object to be cast to a PTR. |
| DSD_NULL | for the NULL pointer. |
| DSD_NATARY | address of an object to be cast to a (i4 *). |
Alignment Type Constants:
| DSA_C | Align as C language structure |
| DSA_UN | Unaligned data. |
Visibility Constants:
| DSV_GLOB | Globally visible |
| DSV_LOCAL | Visible only within this file |
Executable Interface
The following functions are provided.
DSbegin - begin writing structure definitions to an open file
Write necessary code to mark start of file as a valid source file for lang. Name is the name to give the module written.
Inputs:
| file | Open SI file being written. |
| lang | The source language in question, one of DSL_C or DSL_MACRO. |
| name | The name to be given to the file module, appropriate for the language. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS DSbegin(file, lang, name) FILE *file i4 lang; char *name;
DSclose - close a file
DSclose closes the shared data region. sh_desc is the shared data region descriptor. "This routine is obsolete and should not be called"
Inputs:
| sh_desc | Shared region descriptor. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS DSclose(sh_desc) SH_DESC *sh_desc;
DSend - note end writing definitions to an open file
Write code to end the source file file is the language lang.
Inputs:
| file | the SI file being written. |
| lang | the language of the file, one of DSL_C or DSL_MACRO. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS DSend(file, lang) FILE *file; i4 lang;
DSfinal - end writing the current definition
Close the current data structure, and reset so that other data structures can be used.
Inputs:
| None |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS DSfinal()
DSinit - start writing a new definition into an open file
Begin outputting a new data structure in file. The data structure is written in the source language lang with the alignment align. The data structure is given the name label. Label's visibility is specified with vis. Vis can be one of DSV_GLOB if the name of the data structure should be global, or DSV_LOCAL if the name should be local. If the lang is 'C', type should be a valid C data type string. All subsequent calls to DSwrite place the values in the data structure initialized with this call.
Inputs:
| file | the SI file being written |
| lang | the language of the file, one of DSL_C or DSL_MACRO |
| align | for DSL_MACRO the alignment required, either DSA_UN (unaligned) or DSA_C (as C would align). For DSL_C, the argument is ignored. |
| label | the label to be given the structure. |
| vis | the visibilitiy, either DSV_GLOB or DSV_LOCAL |
| type | With DSL_C, a string to be used as the type of the object. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition
STATUS DSinit(file, lang, align, label, vis, type) FILE *file; i4 lang; i4 align; char *label; i4 vis; char *type;
DSwrite - write element of a definition into an open file
Output a value of type type in the current structure. Val is a pointer to the value, and is interpreted according to type. Len is only used with character strings to determine the length of the string. A length of zero with a character string means use all the string.
Inputs:
| type | Constant specifying the type of object being written (DSL_I4, etc.). |
| val | A pointer to the value to be written. |
| len | The length of the value to be written (relevant only for strings). |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS DSwrite(type, val, len) i4 type; char *val; i4 len;
|
Ingres Compatability Library |
