Retrieving information from the database

Retrieving ZEBRA datastructures

CALL CDUSE (PATH,*LSUP*,ISEL,CHOPT,IRC*)

PATH

Character string describing the pathname

LSUP

Address of the supporting link of the Keys bank(s) KYDB (input or output) N.B. LSUP must be protected against relocations or garbage collection, e.g. by using a link area.

ISEL

Integer vector specifying the instant of validity for which a database object is required. The length of the vector is equal to the number of validity range pairs, itself a database constant. For example, in the case when we select by run and event, the number of pairs is 2. ISEL then contains the specific run and event for which an object is required.

CHOPT

Character string with any of the following characters

A

Accept existing datastructure if one already exists in memory.

D

Drop datastructure at LSUP before retrieving new datastructure

F

Force retrieval of new datastructure even if current information as still valid

K

read only the keys (no data is required)

IRC

Integer return code  

0

Successful operation

1

Illegal character option

2

Illegal path name

3

Database structure in memory clobbered

4

Illegal key option

5

Error in DBCHLD in P3 communication

36

Data bank address zero on return from DBKXIN

37

Insufficient space in USER store array

Prepares the database data structure in memory for any required Pathname and set of Keys, unless already done. Returns (optionally) the addresses in memory for the corresponding Key banks and Data banks after checking their validity for the given time and keys.

If the pathname begins with a % character then it is assumed to be an alias and is automatically translated by the internal HEPDB routines.

Supplementary return information

IQUEST(2)

Return status (if IRC = 0)   

0

No disk I/O has been performed

1

Data have been refreshed from the disk

Retrieving multiple ZEBRA datastructures

CALL CDUSEM (PATH,LSUP*,ISEL,IMASK,KEYS,CHOPT,IRC*)

PATH

Character string describing the pathname

LSUP

Address of the supporting link of the Keys bank(s) KYDB N.B. LSUP must be protected against relocations or garbage collection, e.g. by using a link area.

ISEL

Integer vector specifying the instant of validity for which a database object is required. The length of the vector is equal to the number of validity range pairs, itself a database constant. For example, in the case when we select by run and event, the number of pairs is 2. ISEL then contains the specific run and event for which an object is required.

IMASK

Integer vector indicating which elements of KEYS are significant in selection. If an element of IMASK is non-zero, then the corresponding element of KEYS is used in selecting a dataset.

KEYS

Vector of keys. Only the elements for which the corresponding element of IMASK is non-zero are assumed to contain useful information.

If MASK corresponding to one of the fields of 'Beginning' validity range is set, it will select objects with start validity smaller than those requested in KEYS. If MASK corresponding to one of the fields of 'End' validity range is set, it will select objects with end validity larger than those in KEYS. If MASK corresponding to time of insertion is set, objects inserted earlier than KEYS(IDHINS) are selected.

CHOPT

Character string with any of the following characters

'A'

Accept existing datastructure if one already exists in memory. N.B. if this option is specified, ANY datastructure in memory for this path and validity instant will be accepted, regardless of other selections specified.

'K'

read only the keys (no data is required)

'D'

Drop datastructure at LSUP before retrieving new datastructure

'F'

Force retrieval of new datastructure even if current information is still valid

'M'

Perform multiple selection: select according to input keys banks, rather than KEYS vector. The user must prepare a linear chain of key banks prior to calling this routine using the routine CDBOOK.

'N'

If appropriate object does not exist, take nearest neighbour

'S'

Select all objects satisfying the input selection criteria

IRC

Integer return code  

0

Successful operation

1

Illegal character option

2

Illegal path name

3

Database structure in memory clobbered

4

Illegal key option

5

Error in DBCHLD in P3 communication

36

Data bank address zero on return from DBKXIN

37

Insufficient space in USER store array

Prepares the database data structure in memory for any required Pathname and set of Keys, unless already done. Returns (optionally) the addresses in memory for the corresponding Key banks and Data banks after checking their validity for the given time and keys.

If the pathname begins with a % character then it is assumed to be an alias and is automatically translated by the internal HEPDB routines.

Supplementary return information

IQUEST(2)

Return status (if IRC = 0)   

0

No disk i/o has been performed

1

Data have been refreshed from the disk

Retrieving data structure to user specified address

CALL CDGET (PATH,IXDIV,LSUP*,JBIAS,ISEL,KEYS,CHOPT,IRC*)

PATH

Character string describing the pathname

IXDIV

Index of the division in which the data structure should be returned

LSUP

Address of the data bank N.B. LSUP must be protected against relocations or garbage collection, e.g. by using a link area.

JBIAS

LSUP and JBIAS together specify the address at which the structure is to be inserted. If JBIAS < 1 it is used as an offset to the value of LSUP, so the structure will be connected at LQ(LSUP+JBIAS). If JBIAS = 1 the data-structure will be a top level data-structure connected at LSUP. If JBIAS = 2 the data-structure will be created as a standalone structure

ISEL

Integer vector specifying the instant of validity for which a database object is required. The length of the vector is equal to the number of validity range pairs, itself a database constant. For example, in the case when we select on run and event, the number of pairs is 2. ISEL then contains the specific run and event for which an object is required.

KEYS

Integer vector in which the keys vector associated with the retrieved data object are returned.

CHOPT

Character string with any of the following characters

'A'

Accept existing datastructure if one already exists in memory.

'K'

read only the keys (no data is required)

'D'

Drop datastructure at LSUP before retrieving new datastructure

'N'

Force retrieval of new datastructure even if current information is still valid

IRC

Integer return code  

0

Successful operation

1

Illegal character option

2

Illegal path name

3

Database structure in memory clobbered

4

Illegal key option

5

Error in DBCHLD in P3 communication

36

Data bank address zero on return from DBKXIN

37

Insufficient space in USER store array

In some cases, for example in existing applications, one may wish to retrieve a data structure to a user specified location. In this case, CDGET may be used. Note that the data caching provided by CDUSE and CDFREE is not supported by this routine.

If the pathname begins with a % character then it is assumed to be an alias and is automatically translated by the internal HEPDB routines.

Supplementary return information

IQUEST(2)

Return status (if IRC = 0)   

0

No disk i/o has been performed

1

Data have been refreshed from the disk