&VARTABLE GET

Verbs and Built-in Functions › &VARTABLE GET

&VARTABLE GET

Allows an NCL procedure to retrieve an entry from an existing vartable. The exact key of the record is not required.

&VARTABLE GET ID=tablename
              KEY=fieldname 
            [ SCOPE={ PROCESS | REGION | SYSTEM | AOM } ] 
            [ AGE={ YES | NO } ] 
            [ DELETE={ YES | NO } ] 
            [ FIELDS=fieldlist { VARS=(var1, var2, ... varn) |
              VARS=prefix* [ RANGE=( start, end ) ] |
              ARGS [ RANGE=( start, end ) ] |
              MDO=mdoname } ] 
            [ OPT={ KEQ | KGE | KLE | KGT | KLT | GEN |
                    IGEN | FIRST | LAST | OLDEST | NEWEST } ]

Operands:

ID=tablename

(Mandatory) Indicates the name of the table you want to retrieve the entry from. The table must have been previously allocated, although not necessarily by this procedure (particularly if SCOPE=REGION is specified).

SCOPE= { PROCESS | REGION | SYSTEM | AOM }

An optional parameter, indicating the scope of the table. Allowed values are:

PROCESS

Indicates the table is a private table, visible only to the NCL process that allocated it.

REGION

Indicates the table is visible to all NCL procedures executing in the current region.

SYSTEM

Indicates that the table is visible to all NCL procedures executing in the same system.

AOM

Indicates that this statement refers to a mirrored vartable. Entries added or updated from the screening table can also be retrieved.

Note: SCOPE=AOM is available only if your region includes Automation Services products.

AGE={ YES | NO }

(Optional) Indicates whether to make the retrieved entry the newest in the table (AGE=YES). The default depends on the value for the AGE parameter specified on the &VARTABLE ALLOC statement for this table. If the table has been allocated with aging on GET, using AGE=NO on an &VARTABLE GET lets you access entries for maintenance without aging entries.

DELETE={ YES | NO }

Indicates whether to delete the entry retrieved. DELETE=NO indicates the entry is not deleted. DELETE=YES indicates the retrieved entry is deleted from the table.

KEY=fieldname

(Must not be specified if OPT=FIRST, LAST, OLDEST, or NEWEST is specified) Indicates the name of the NCL variable that contains the value of the search key. Do not code an ampersand (&) unless the name of the variable containing the key is stored in the variable specified on the KEY= operand. For example:

KEY=KEYFIELD means extract the contents of NCL variable &KEYFIELD, and use those contents as the key value.
KEY=&KEYFLDNM means extract the contents of NCL variable &KEYFLDNM, and use those contents as the name of an NCL variable that contains the key value. If &KEYFLDNM contained KF, the contents of variable KF is used as the key value.

If the table was allocated with KEYFMT=CHAR, the nominated key value is padded with blanks, if shorter than the declared key length of this table. If the value is longer, an error response is set. KEYFMT=UCHAR performs an uppercase translation before using the supplied key value.

If the table was allocated with KEYFMT=NUM, the key value must be a valid, signed number. That is, it must satisfy an &TYPECHK of SIGNNUM.

FIELDS=fieldlist VARS=varlist

Defines the source variables from the vartable to retrieve by the GET operation. If specified, the FIELDS and VARS operands must have the same number of entries in their lists. If VARS=, ARGS or MDO= is specified and the FIELDS= operand is not specified, the equivalent of FIELDS=DATA* is assumed.

FIELDS=fieldlist nominates the information you want to retrieve. fieldlist is a list of names in one of the following formats:

name

(name)

(name,name,...)

Each name is one of the following (you cannot duplicate any of these names in the list):

DATAn

Indicates that you are operating on a data value for the nth data field in this entry. n must be from 1 to the value specified on the DATA= parameter when the table was allocated. You can have several DATAn entries, as long as each has a unique number n.

DATA*

Indicates that you are operating on the data for all the data fields in this entry, from 1 to the value specified on the DATA= parameter when the table was allocated. The accompanying variable name in the VARS= list must be in the format prefix*, and the suffixes generated to access the variables are 1 to the number of allocated data fields.

MDO

Indicates that you want to place the entire entry into an MDO. An MDO name must be located in the corresponding position in the VARS list.

Note: When MDO access is used, individual data fields cannot be requested.

MAP

Indicates that you want to retrieve the map name for the corresponding entry. A single NCL variable must be located in the corresponding position of the VARS list. For entries containing NCL variables, the map name returned is always $NCL, regardless of whether the vartable was allocated as mapped or not. For entries containing MDOs, the map name returned is that associated with the MDO when the entry was last updated.

.KEY

Indicates that you want to retrieve the actual key value of this entry. This value is different from the supplied search key (KEY=) if you are not using OPT=KEQ. If the same variable as the search key is used in the field list, its value is updated after the search key value is extracted.

.COUNTER

Indicates that you want to retrieve the current value of the counter field for this entry.

.USERCORR

Indicates that you want to retrieve the user correlator value for this entry. This value is used in a later UPDATE, PUT, or DELETE operation to help ensure that no other updates have taken place.

AOM tables can have the following additional field names specified:

.AOMID: Indicates the AOM ID value. The associated variable is set to the stored AOM ID value. If the stored ID is blank, the value is null.
.AOMATTR: Is the AOM attribute string. A full 30-character string is always returned.
.AOMCOUNT: Is the AOM count for this entry. If the COUNT option is specified, a LOOKUP statement that matches an entry increments this counter. If GAOM is stopped, a zero value is always returned.

VARS=(var1,var2,...,varn) nominates the target structures for the GET operation against the vartable. Each entry in varlist corresponds to the same entry in fieldlist. Thus the first entry in varlist nominates the variable containing the data for the first entry in fieldlist. varlist must be in one of the following formats:

varname

(varname)

(varname,varname,...)

varname is a valid NCL variable name, without the ampersand (&), unless you want to refer to the variable containing the data indirectly (see the example for the KEY operand). If DATA* or D* was specified in the FIELDS list, the matching variable name must be specified as prefix*.

VARS | ARGS | MDO defines the target data structures for the GET operation against the vartable.

The FIELDS keyword is optional, and if not specified, defaults to FIELDS=DATA*.

If the FIELDS operand is specified, then the VARS operand must be specified, and must be a list of variables to contain the source fields. The list must contain one of the following:

The names of known VARTABLE fields (such as COUNTER and ADJUST).
An operand of the form DATAn. n is any integer within the range 1 through 999 for a DATA=MAPPED vartable. Otherwise n is in the range1 to the data limit (as determined by the DATA operand on the &VARTABLE ALLOC statement).
The operand DATA* (meaning all data fields).
The operand MDO (meaning the entire data object in the VARTABLE entry).

Each entry in the VARS list must parallel an entry in the FIELDS list and must be one of the following:

An NCL token name
A generic name (for example, ABC*) if it parallels the DATA* entry in the FIELDS list
An MDO name (for example, RECORD.) if it parallels the MDO operand (or DATA* operand) in the FIELDS list

When the FIELDS operand is omitted (or specified as FIELDS=DATA*), the target variables are specified by the usual NCL syntax (that is, ARGS [RANGE=], VARS=varslist, VARS=prefix [ RANGE= ], or MDO=mdoname).

When VARS or ARGS are the target of a GET operation, but the vartable entry was created as an MDO (and not mapped by $NCL), the target variables are segmented from the MDO contents.

If an MDO is nominated as the target data structure, all data from the vartable entry is placed in the single MDO. If no map name is supplied on the GET operation, the map name specified for the MDO on the PUT operation is supplied as the default. If the entry was created from NCL variables and not an MDO, the $NCL map maps the resulting MDO.

OPT={KEQ | KGE | KLE | KGT | KLT | GEN | IGEN | FIRST | LAST | OLDEST | NEWEST}

Indicates the relationship between the supplied search key and the matching table entry (if one is found).

KEQ: (Default) Indicates that you want to retrieve the table entry with an exact match on the supplied search key.
KGE: Indicates that you want to retrieve the table entry with the lowest key value greater than or equal to the supplied search key.
KLE: Indicates that you want to retrieve the table entry with the highest key value less than or equal to the supplied search key.
KGT: Indicates that you want to retrieve the table entry with the lowest key value greater than the supplied search key.
KLT: Indicates that you want to retrieve the table entry with the highest key value less than the supplied search key.
GEN: Indicates that you want to retrieve the table entry with the lowest key value generically equal to the search key value for its non-blank length, but possibly with other characters after it.
IGEN: Indicates that you want to retrieve the table entry with the longest non-blank key value that matches the search argument.
FIRST: Indicates that you want to retrieve the table entry with the lowest key. If this option is specified, you cannot specify the KEY operand.
LAST: Indicates that you want to retrieve the table entry with the highest key. If this option is specified, you cannot specify the KEY operand.
OLDEST: Indicates that you want to retrieve the oldest table entry, that is, the entry that was first added, updated, or retrieved (depending on the ALLOC AGE= option). If this option is specified, you cannot specify the KEY operand.
NEWEST: Indicates you want to retrieve the newest table entry, that is, the entry that was last added, updated, or retrieved (depending on the ALLOC AGE= option). If this option is specified, you cannot specify the KEY operand.

If no entry is found that matches the passed key, &ZFDBK is set to 4, and none of the nominated variables are updated.

Examples: &VARTABLE GET

&K = KEY001 
&VARTABLE GET ID=MYTABLE KEY=K FIELDS=DATA1 VARS=D 
&WRITE DATA FOR KEY &K IS &D

This example retrieves the entry from the private (SCOPE=PROCESS) vartable named MYTABLE. The field, &D, contains the returned user data in that entry.

&VARTABLE GET ID=GTABLE SCOPE=SYSTEM OPT=FIRST +
    FIELDS=(KEY,DATA1) VARS=(K,D)  
&DOWHILE &ZFDBK = 0
    .
    ...  process entry, key in &K, data in &D
    .
    &VARTABLE GET ID=GTABLE SCOPE=SYSTEM OPT=KGT KEY=K +
                  FIELDS=(KEY,DATA1) VARS=(K,D)  
&DOEND

This example illustrates a technique to read sequentially through a table. The first GET, using OPT=FIRST, retrieves the entry with the lowest key, and the key value is returned in &K. The second GET, using OPT=KGT, retrieves the entry with the next higher key, and sets that key value into &K.

Use OPT=LAST and OPT=KLT for backward retrieval.

&VARTABLE GET ID=FRED SCOPE=GLOBAL OPT=KGT KEY=#OS$STARTKEY +
              FIELDS=(KEY,MDO) VARS=(#OS$NEWKEY,#OS$MDO.)

This example reads a vartable record that is mapped into an MDO, and obtains the key of the vartable record at the same time. Note the period after the MDO name in the VARS list.

Return Codes:

System variable, &ZFDBK, is set after an &VARTABLE GET statement to indicate the result of the operation:

0: The entry was retrieved successfully. Any nominated variables are updated.
4: No entry with the requested key value exists.
12: The supplied key value was longer than the table key length.
16: No table of this name exists in this scope.
32: SCOPE=AOM table has been disabled due to a storage error. &ZFDBK value 32 is possible only with AOM tables.

Notes:

Syntax errors in a &VARTABLE GET statement cause the NCL procedure to terminate.

Always specify SCOPE=REGION to refer to a table of that scope.