Host/API

Home	Starting	Environment	DBMS	VisualPQL	Procedures	SQL	Forms	Host/API	Index

Host/API

General Subroutine Information

Introduction

HOST consists of a set of FORTRAN callable functions written in ANSI standard FORTRAN. The user writes a main program to call the HOST routines which perform the requested retrieval functions. These routines are compiled by the standard FORTRAN compiler for each machine on which SIR/DBMS is available and are maintained as a standard library of FORTRAN routines on each machine.

See additional documentation and examples in the API subdirectory of the SIR installation directory.

There may be two HOST libraries available at your site. One of them, referred to as HOST or regular HOST, is intended for a single user environment. The other one, referred to as concurrent HOST, is intended to work in a multiple-user environment, in conjunction with the MASTER module. The user interface with these two versions is almost identical, such that almost no programming effort is required to switch between them. The small differences are documented below in Multiple User Support with HOST.

The HOST routines can be called by a main program written in a language other than FORTRAN (such as PL/1 or C), provided that FORTRAN functions can be called from that language.

If the language can call FORTRAN functions, but cannot test their return values, the user can use a common area called HERROR to get this value. The first variable of the HERROR common block is a R*8 containing the name of the last HOST function called (except for ZCALL which does not touch the variable). Note that this variable does not have the CHARACTER*8 FORTRAN type. The next variable of the HERROR common block is an I*4 which will contain the return code from the last called HOST function. The next variable is an I*4 which is reserved for future use. The length of the HERROR common area is the length of a R*8 plus the length of two I*4's.

The routines provided allow the HOST user to perform all the operations available in DBMS retrieval. Some DBMS commands are provided in a single HOST function call while others have been divided into several function calls.

Every HOST routine is a FORTRAN function which returns a value to the calling application program. If a function executes its task successfully, then it will return a requested value or the value zero or a positive status value to the calling program. If a function encounters an error or problem in performing its task, however, it will return a negative number and not perform the task. The absolute value of the returned value will be the error code detected. A list of all current error codes are listed in Environment appendix A. Some of the negative returned codes do not represent real errors, but some specific conditions such as "no more records found" or "a missing value has been stored".

Writing Programs with HOST

In order to use the routines effectively, the HOST programmer should have experience in writing DBMS Retrieval programs. We recommend that new HOST users write their retrievals in the DBMS Retrieval language and then translate them into HOST function calls. Once the user gains proficiency with HOST, this technique can be dispensed with.

As illustrated by the examples, a HOST program generally has many more statements than its DBMS counterpart. This is partly because each DBMS Retrieval command usually translates into several HOST function calls. HOST programs are also include statements that check the error codes returned by the HOST functions. It is very important to check the HOST error codes. If errors are ignored, the results of subsequent function calls will be unpredictable. If this occurs during a database modification run, the database could be damaged.

To help the programmer write code that performs all of the required returned values testing, a new function, ZCALL, has been introduced. ZCALL helps the programmer write programs that are easy to understand and maintain.

Initialisation

The HOST system is initialised by calling ZSTART. It must be the first HOST call in the user's program. If concurrent HOST is used, ZLOGIN should be called immediately after ZSTART.

One or more calls that open the databases to be used during the run follow. There can be more than one of these calls because, unlike DBMS, HOST allows simultaneous access to more than one database. The HOST routines that open databases are ZORDB (open a random database), and ZOSDB (open a sequential database).

These calls also allow the user to specify default read and write security passwords for each database. The defaults can be overridden by calling ZSECUR.

The Retrieval Stack

A HOST retrieval stack is an internal table containing one entry for each CIR and data record currently being processed. The entries are called blocks. The ordinal of a block in the retrieval stack is referred to as the level of the block. Each block is completely nested within the preceding blocks similar to the nesting in a DBMS retrieval program. In HOST, nesting is extended to include the nesting of databases as well as cases and records.

For example, consider the following schematic DBMS Retrieval with four levels of nesting:

RETRIEVAL
. PROCESS CASES ....
.   PROCESS REC 7....
.     CASE IS....
.       RECORD IS 9 ....
.       END RECORD IS
.     END CASE IS
.   END PROCESS REC
. END PROCESS CASES
END RETRIEVAL

Within the first level of nesting (PROCESS CASES block), the corresponding HOST retrieval stack would consist of

level 1 - CIR

Within the fourth level of nesting (RECORD IS block), the HOST retrieval stack would contain

level 1 - CIR
level 2 - record type 7
level 3 - CIR
level 4 - record type 9

Within a DBMS Retrieval block, the user can only refer to CIR variables or record variables that belong to the block. HOST, on the other hand, allows the user's program to access data at any level from any higher level in the retrieval stack. In the previous example, the user can refer to the CIR variables of level 1 from within levels 2, 3 or 4. Similarly one can refer to record type 7 variables from within levels 3 or 4. This is made possible by the retrieval stack and by the variable descriptors discussed in the next section.

Although the retrieval stack allows the user full access to all preceding levels, there are some operations that can only be performed on a level-by-level basis with HOST. Among these operations are record deletion, getting the next record and termination of record processing. For example, in order to terminate the CASE IS block (level 3 in the previous example) from within the RECORD IS block (level 4), the user must first terminate the RECORD IS block and then the CASE IS block.

In version 2.2, the routines that create blocks ( ZCCNT, ZCCNTD, ZCGDMY, ZCIS, ZCISD, ZCSAM, ZCSAMD, ZRCNT, ZRCNTD, ZRCNTL, ZRGDMD, ZRGDML, ZRGDMY, ZRIS, ZRISD, ZRISL, ZRSAM, ZRSAMD and ZRSAML) return the stack level of the created block rather than 0 (as they did in previous releases). The level can be used as the fourth piece of a variable descriptor. The level of a case block can also be used as the last argument of ZRCNTL, ZRGDML, ZRISL and ZRSAML to make a "record block" belong to a "case block" other than the closest above it. For example, the following structure is possible now:

level 1 - CIR
level 2 - CIR
level 3 - record type 5 "belonging" to the CIR on level 1
level 4 - record type 2 "belonging" to the CIR on level 2

Variable Descriptors

In HOST, database variables are accessed by variable descriptor rather than by name. The purpose of the descriptor is to identify uniquely a variable across all levels of the retrieval stack.

A variable descriptor contains four pieces of identifying information about a variable:

the database number (assigned by HOST in order of opening)
the record type number (the CIR is type zero)
the variable number (assigned automatically in same order as LIST SCHEMA)
the retrieval stack level

Note: The value of the database number should be left undefined. Opening and closing databases could cause a different sequence of values to be assigned.

Variable descriptors are created in HOST by the routines, ZDESC, ZDESCD, ZDESCM and ZSDESC. Routine ZDESCB breaks a descriptor in its 4 components. ZDESCD requires an explicit database name while ZDESC assumes the database is the one currently in use.

The recommended programming technique is to call ZDESCD at the beginning of the program for each variable to be referenced.

To illustrate, suppose we plan to retrieve data from two databases, CLIENT and PROSPECT. We want to retrieve the variables NAME, PHONE, and BILLED from record type 1 in the CLIENT database. We also want to retrieve NAME and PHONE from the CIR and SALESREP and CLDATE from record type 3 in the PROSPECT database.

The calls to ZDESCD would be placed at the beginning of the HOST program and would look like this in FORTRAN:

      IERR = ZDESCD (CNAME,  'CLIENT'  , 1,'NAME  '  , 0)
      IERR = ZDESCD (CPHONE, 'CLIENT'  , 1,'PHONE'   , 0)
      IERR = ZDESCD (CBILLD, 'CLIENT'  , 1,'BILLED'  , 0)
      IERR = ZDESCD (PNAME,  'PROSPECT', 0,'NAME'    , 0)
      IERR = ZDESCD (PPHONE, 'PROSPECT', 0,'PHONE'   , 0)
      IERR = ZDESCD (PSLSRP, 'PROSPECT', 3,'SALESREP', 0)
      IERR = ZDESCD (PDATE,  'PROSPECT', 3,'CLDATE'  , 0)

The FORTRAN variables CNAME, CPHONE, CBILLD, etc. contain the variable descriptors for the corresponding database variables NAME, PHONE, BILLED, etc. Once the descriptors are defined, they are used in all subsequent HOST calls. For example, to retrieve the value of the CIR variable NAME in the PROSPECT database, the appropriate HOST call would be

      IERR = ZRCTST (PNAME, PRONAM, 25)

ZRCTST transfers 25 characters of the CIR variable NAME (whose descriptor is stored in PNAME) into the FORTRAN character variable PRONAM.

Case and Record Processing

Case and record processing have been extended in HOST so that cases can be processed with the AFTER, FROM, THRU, UNTIL, and WITH clauses and records can be processed with the COUNT and SAMPLE options.

Case and record processing in HOST involves several steps:

Call the appropriate case or record-initialisation routine.

If necessary, call one or more key creation and key definition routines.

Use ZCNEXT or ZRNEXT as the first statement of the case or record-processing loop. These routines get a case or record from the database and make it available for use.
To loop through several cases or records, return to the start of the loop, ZCNEXT or ZRNEXT. These routines return a negative error code (-4xxx) when there are no more cases or records left.
Call ZCEXIT or ZREXIT when the loop is terminated.

To illustrate these concepts further, consider the following DBMS Retrieval commands:

.  PROCESS CASES ALL
.    WRITE CASEID NAME ADDRESS
.  END PROCESS CASES

The corresponding HOST program would look like this in FORTRAN:

      IERR = ZCCNT (-1, 1, 1)
100   IERR = ZCNEXT (0)
      IF (IERR .EQ. -4001 .OR. IERR .EQ. -4002) GO TO 200

....    (retrieve and print CASEID, NAME and ADDRESS)

      GO TO 100
200   IERR = ZCEXIT (DUM)

Errors -4001 and -4002 indicate that there are no more cases left to be processed.

Now suppose we want to run the same retrieval, but only for those cases whose case-ids lie in the range 5000 to 5999. We must add calls to the HOST routines that create and define the key values for the cases. The HOST program would then be written as follows:

      IERR = ZCCNT (-1, 1, 1)
      IERR = ZFROM (0)
      IERR = ZINTKY (5000)
      IERR = ZTHRU (0)
      IERR = ZINTKY (5999)
100   IERR = ZCNEXT (0)
      IF (IERR .EQ. -4001 .OR. IERR .EQ. -4002) GO TO 200

.....  (retrieve and print CASEID, NAME and ADDRESS)

      GO TO 100
200   IERR = ZCEXIT (0)

Note that the key creation (ZFROM, ZTHRU) and key definition (ZINTKY) routines are placed immediately after the initialisation routine ( ZCCNT) and before the actual start of the loop (ZCNEXT). Record processing in HOST is analogous to case-processing. For example, the following PROCESS REC loop:

.  PROCESS REC 3, WITH (1982, 100)
.    WRITE 'DEPT YTD TOTAL IS', YTDSALE
.  END PROCESS REC

might look like this in FORTRAN:

      IERR = ZRCNT (3, -1, 1, 1)
      IERR = ZWITH (0)
      IERR = ZINTKY (1982)
      IERR = ZINTKY (100)
100   IERR = ZRNEXT (0)
      IF (IERR .EQ. -4001 .OR. IERR.EQ. -4002) GO TO 200

..... (retrieve and print value of YTDSALE)

      GO TO 100
200   CALL ZREXIT (0)

Caseless Database Processing

If a database is caseless, some of the HOST routines cannot be used when accessing that database. If you attempt to use these routines with a caseless database, the routines will return an error code of -2053. No case block should ever be created. The following is a list of the routines that can only be used with "case" databases:

  ZCCNT  ZCCNTD ZCDEL  ZCEXIT ZCFIND ZCGDMY
  ZCIS   ZCISD  ZCLOCK ZCNEXT ZCRDMY ZCREST
  ZCSAM  ZCSAMD ZCWRIT ZNOR   ZNORD

If you want to find out if a database is caseless or not, your program should call ZNSIDS with the second argument 0. ZNSIDS returns the number of sort ids in the database for the specified record type, which is 0 for a caseless database. (Actually it returns the number of sort ids in the CIR for the caseless database).

ZNCASE also returns the number of cases in the specified database, and it will always return 0 for a caseless database. However, it cannot be used as a test for case structure in a database since it will return 0 for any empty database, and any caseless database regardless of the number of records.

Multiple Database Mode in HOST

As previously stated, HOST allows the user to access data from several databases simultaneously. This capability is not available in DBMS Retrieval.

A HOST program is in multiple-database mode when it contains more than one call to the database initialisation routines (ZORDB, ZOSDB). Note that multiple-database mode remains in effect even if all of the databases have been closed.

In multiple database mode, the routines that initialise case and record processing also establish the identity of the current database. These routines are described in the section called Database Switching.

All of the records processed within a case loop are assumed to belong to the current database.

In Variable Descriptors, we saw that variable descriptors allow the user to access data at higher levels of the retrieval stack from within lower levels. This concept also applies to stack levels from different databases.

For example, suppose the retrieval stack contains the following levels:

level 1 - database DB1, CIR
level 2 - database DB1, record type 5
level 3 - database DB2, CIR
level 4 - database DB2, record type 8

and we have defined the descriptor for the database variable, AGE, from record type 5 in DB1 with the call:

      IERR = ZDESCD (XAGE,'DB1     ',5, 'AGE     ',0)

Then, the database variable AGE can be retrieved at any level of the retrieval stack (except level 1) by using its descriptor stored in XAGE.

If the stack contains two process rec 1 blocks, then stack level 0 indicates the innermost process rec.

Multiple User Support with HOST

As mentioned in the Introduction, in addition to providing access to databases as a stand-alone program, HOST also provides access to the databases by multiple users. To use concurrent HOST, a MASTER process must be running and the user program must login to that MASTER. To do this, a typical application program will call ZLOGIN immediately after calling ZSTART. If the user program does not call ZLOGIN with the name of the MASTER explicitly, the system will do it, using the name of the default MASTER. A given application program can be logged-in to only one MASTER at a time. For regular HOST programs, the calling of ZLOGIN is optional.

To determine from within a program which of the two versions of HOST is used, the function ZVERS can be called. It will return 0 for regular HOST and 1 for concurrent HOST.

HOST 2.2 Lock Types

In HOST 2.2, (both regular and concurrent) there are 6 lock types defined:

Lock-type number       Lock type
0 or 14                protected read
1 or 16                exclusive
11                     null
12                     concurrent read
13                     concurrent write
15                     protected write

The locks ensure data integrity. They prevent other programs from updating records that you are updating. Several HOST programs feature the option to set and test the locks.

Routine Formal Parameters

When using the HOST routines great care must be taken to insure that the formal parameters match in both number and type. TABLE 1 below indicates the various argument types used by HOST. See the documentation in the API subdirectory for information and examples for the exact declarations and representations needed for each data type.

TABLE 1

  ABBREV  TYPE        DESCRIPTION
  B*n     BYTE        This is a CHARACTER*N structure as defined by the
                      FORTRAN 77 compiler on your machine. It
                      must be of the proper size to hold the character
                      strings to be passed to or from it.
  D*8     DESCRIPTOR  This is an (8 byte) area containing a set of values
                      that uniquely describe a data variable ( i.e. vari-
                      able number, record type number, database number,
                      stack location ). This data type may be stored as a
                      REAL*8 on some machines; in this case care should be
                      taken in transferring descriptors because it is not
                      a REAL*8 value but an 8 byte bit pattern and no
                      floating operations such as normalisation should be
                      performed.
  I*4     INTEGER     This is I*4 as defined in Machine Specifics
                      documentation.( It might be 4 or 8 bytes long. )
  N*8     NAME        This is a CHARACTER*8 created by a FORTRAN 77
                      compiler.
  R*n     REAL        This is R*4 or R*8 as defined in your Machine
                      Dependencies documentation.

Overview of the HOST Subroutines

A list of the standard routines available within HOST are listed below. Certain machines have additional routines available usually dealing with additional type conversions and other utilities to ease the use of the HOST package. See the documentation in the API subdirectory for more information on these routines.

Note that all of the HOST functions are of type INTEGER*4 regardless of the first letter of the names. Declare them as type INTEGER*4 in each routine that calls them. Also, the types of the function arguments do not correspond to standard FORTRAN usage ( i.e. first letter I through N is type INTEGER, otherwise REAL).

As already stated, these functions may return 0, a required value, a positive status value, or a negative error code. In Chapter 3, the return values for the functions will be documented only if they have a specific significance. If they are not documented, the assumption is that the function will return a positive or zero value for success and a negative value for failure.

Initialisation Routines

ZSTART Initialises the HOST system.

ZLOGIN login the current process into a specified MASTER.

ZSECUR Specifies security passwords for current stream.

ZORDB Initialises a specified random format database for use.

ZOSDB Initialises a specified sequential format database for use.

Control Routines

ZUSER Allows the switching of the current retrieval stack from one stream to another.

ZCALL Call HOST functions and test their return code.

Termination Routines

ZENDDB Terminates the use of a specified database. It closes and return the files for use by other jobs. In order to use the database again it must be reinitialised.

ZCLEAR Terminates all levels in the retrieval stack of a specified stream.

ZEND Terminates the HOST run. It cleans up tables and checks that the databases have been properly closed and all internal operations are completed. If any databases are still open, ZEND attempts to close them.

Case Processing Routines

ZCCNT Initialises a "PROCESS CASE" block with either the "ALL" or "COUNT" option.

ZCCNTD Initialises a "PROCESS CASE" block with either the "ALL" or "COUNT" option. It also provides the capability of changing databases.

ZCGDMY Initialise a case-processing block of an undefined type (dummy).It also provides the capability of changing databases.

ZCIS Initialises a "CASE IS" block.

ZCISD Initialises a "CASE IS" block. It also provides the capability of changing databases.

ZCSAM Initialises a "PROCESS CASE" block with a "SAMPLE" option.

ZCSAMD Initialises a "PROCESS CASE" block with a "SAMPLE" option. It also provides the capability of changing databases.

ZCREST Restores the common variables in the innermost case processing block.

ZCRDMY Terminates the current case-processing level and resets it to a dummy.

ZCFIND Finds a case, after a dummy case-processing block was initialised and some CIR variables specified.

ZCFRST Gets the first case in a case-processing block.

ZCLAST Gets the last case in a case-processing block.

ZCNEXT Gets the next case in a case-processing block.

ZCPREV Gets the previous case in a case-processing block.

ZCLOCK Returns the lock type of a case-processing block.

ZCDEL Deletes the current case in the innermost case-processing block.

ZCWRIT Writes the current innermost CIR to the database as a permanent change.

ZCEXIT Leaves the current case-processing block and pops the retrieval stack back one level of retrieval nesting.

Record Processing Routines

ZRCNT Initialises a "PROCESS RECORD" block with either the "ALL" or "COUNT" option.

ZRCNTD Initialises a "PROCESS RECORD" block with either the "ALL" or "COUNT" option. It also provides the capability of changing databases.

ZRCNTL Initialises a "PROCESS RECORD" block with either the "ALL" or "COUNT" option, belonging to a CIR on a specified level.

ZRGDMY Initialise a record-processing block of an undefined type (dummy). It also provides the capability of changing databases.

ZRGDMD Initialise a record-processing block of an undefined type (dummy). It also provides the capability of changing databases.

ZRGDML Initialises a record-processing of an undefined type (dummy) block, belonging to a CIR on a specified level.

ZRIS Initialises a "RECORD IS" block.

ZRISD Initialises a "RECORD IS" block. It also provides the capability of changing databases.

ZRISL Initialises a "RECORD IS" block belonging to a CIR on a specified level.

ZRSAM Initialises a "PROCESS RECORD" block with a "SAMPLE" option.

ZRSAMD Initialises a "PROCESS RECORD" block with a "SAMPLE" option. It also provides the capability of changing databases.

ZRSAML Initialises a "PROCESS RECORD" block with a "SAMPLE" option, belonging to a CIR on a specified level.

ZRREST Restores the record variables in the innermost record processing block.

ZRRDMY Terminates the current record-processing level and resets it to dummy.

ZRFIND Finds a record, after a dummy record-processing block was initialised and some record variables specified.

ZRFRST Gets the first case in a record-processing block.

ZRLAST Gets the last case in a record-processing block.

ZRNEXT Gets the next case in a record-processing block.

ZRPREV Gets the previous case in a record-processing block.

ZRLOCK Returns the lock type of a record-processing block.

ZRDEL Deletes the current record in the innermost record-processing block.

ZRWRIT Writes the current innermost record to the database as a permanent change.

ZREXIT Leaves the current record-block and pops the retrieval stack one level of retrieval nesting.

Key Creation Routines

ZAFTER Initialises the creation of a key for either case or record processing levels. It starts up a key of the form of the "AFTER" keyword on the PROCESS statement in DBMS.

ZBEGIN Initialises the creation of a key for either case or record processing levels. It starts up a key of an yet undefined form.

ZFROM Initialises the creation of a key for either case or record processing levels. It starts up a key of the form of the "FROM" keyword on the PROCESS statement in DBMS.

ZTHRU Initialises the creation of a key for either case or record processing levels. It starts up a key of the form of the "THRU" keyword on the PROCESS statement in DBMS.

ZUNTIL Initialises the creation of a key for either case or record processing levels. It starts up a key of the form of the "UNTIL" keyword on the PROCESS statement in DBMS.

ZWITH Initialises the creation of a key for either case or record processing levels. It starts up a key of the form of the "WITH" keyword on the PROCESS statement in DBMS.

Key Definition Routines

ZDTTKY Moves a date string into the next sort-id position of the current key.

ZFPTKY Moves a real value into the next sort-id position of the current key.

ZINTKY Moves an integer value into the next sort-id position of the current key.

ZSTTKY Moves a character string into the next sort-id position of the current key.

ZTMTKY Moves a time string into the next sort-id position of the current key.

Variable Modification Routines

ZBLTRC Stores a blank missing value in a variable.

ZDTTRC Moves a date string into a specified variable descriptor.

ZFPTRC Moves a real value into a specified variable descriptor.

ZINTRC Moves an integer value into a specified variable descriptor.

ZMSTRC Transfers a missing/undefined value to a specified variable descriptor.

ZRCTRC Transfers the value from one variable descriptor to another variable descriptor.

ZSTTRC Moves a string value into a specified variable descriptor.

ZTMTRC Moves a time string into a specified variable descriptor.

Variable Retrieval Routines

ZRCTDT Returns the value of a specified date variable descriptor.

ZRCTFP Returns the value of a specified real variable descriptor.

ZRCTIN Returns the value of a specified integer variable descriptor.

ZRCTST Returns the value of a specified string variable descriptor.

ZRCTTM Returns the value of a specified time variable descriptor.

General Routines

ZVERS Returns the version and revision numbers of HOST.

ZOPEN Returns an indication of whether a specified database is currently available for use or not.

ZUPLEV Returns the current update level of a database.

ZSECLV Returns the current security levels for a specified database.

ZLCKRT Sets/returns the record type lock for a specific record type.

ZNCASE Returns the number of cases in the database.

ZNRECS Returns the number of records of a specific type that are currently in the database.

ZNEW Returns an indication of whether the last CIR/record accessed was a new CIR/record or an existing CIR/record.

ZNOR Returns the number of records of a specific type that are currently in the innermost CIR.

ZNORD Returns the number of records of a specific type that are currently in the innermost CIR of a specified database.

ZRNAMD Returns the record name for a record number.

ZRNUM Returns the record number for a record name.

ZRNUMD Returns the record number for a record name in a specified database.

ZNVARS Returns the number of variables in a specific record type.

ZNSIDS Returns the number of sort ids in the key of a record of a specific type.

ZVARLB Returns the variable label of a variable specified by descriptor.

ZVNAME Returns the variable name for a variable specified by descriptor.

ZVTYPE Returns the storage type of the variable specified by descriptor.

ZLABLN Returns the value label for a value of a specified numeric variable descriptor.

ZLABLS Returns the value label for a value of a specified string variable descriptor.

ZMSLAB Returns the value label for a missing value.

ZDESC Builds the variable descriptor from a variable description.

ZDESCD Builds the variable descriptor from a variable description for a variable in a different database.

ZSDESC Returns the variable descriptor corresponding to the nth sortid of the specified record type.

ZDESCB Breaks a descriptor in its four components.

ZDESCM Makes a descriptor out of its four components.

ZEXIT Performs the equivalent of ZCEXIT for a case-processing block and of ZREXIT for a record-processing block.

Utility Routines

ZATTR Perform equivalent to DBMS ATTRIBUTE command.

ZCACHE Activates/deactivates the caching and sets/reads various caching parameters.

ZOPT Set or return various system options.

ZERMSG Returns a text string describing a specific numbered error. Optionally it can also file the error message in the job log.

ZDTXIN Converts a date string into a date integer.

ZINXDT Converts a date integer into a date string.

ZTMXIN Converts a time string into a time integer.

ZINXTM Converts a time integer into a time string.

ZTIME Returns the current date and time as julian integers.

Advanced Key Definition Routines

ZDTXKY Moves a date string into the next sort-id position of the current key.

ZFPXKY Moves a real value into the next sort-id position of the current key.

ZINXKY Moves an integer value into the next sort-id position of the current key.

ZSTXKY Moves a character string into the next sort-id position of the current key.

ZTMXKY Moves a time string into the next sort-id position of the current key.

Advanced Data Modification Routines

ZDTXRC Moves a date string into a specified variable descriptor.

ZFPXRC Moves a real value into a specified variable descriptor.

ZINXRC Moves an integer value into a specified variable descriptor.

ZSTXRC Moves a string value into a specified variable descriptor.

ZTMXRC Moves a time string into a specified variable descriptor.

Advanced Data Retrieval Routines

ZRCXDT Returns the value of a specified date variable descriptor.

ZRCXFP Returns the value of a specified real variable descriptor.

ZRCXIN Returns the value of a specified integer variable descriptor.

ZRCXST Returns the value of a specified string variable descriptor.

ZRCXTM Returns the value of a specified time variable descriptor.

Database Switching

In a multiple database environment, it is important to know which database is being used at any given time. This database is referred to as the "current database". While most of the routines refer to the current database, some routines can switch databases, making another database the current one. The following list describes how the HOST routines manipulate the databases. (The term "specified" refers to an item in the argument list of the subroutine):

ZCCNTD, ZCGDMY, ZCISD, ZCSAMD, ZRCNTD, ZRGDMD, ZRISD, ZRSAMD explicitly make the specified database be the current database.

ZRCNTL, ZRGDML, ZRISL, ZRSAML make the database at the specified level be the current database.

ZEXIT, ZCEXIT, ZEXIT pop back 1 level from the stack and make the database at the new level be the current database.

ZORDB, ZOSDB do not switch databases. However, if there is no current database, the specified database is made current.

ZENDDB does not switch databases. However, if the specified database is the current one, the "next" open database is made current.