VARTABLE GET Command—Get a Vartable Entry

NetMaster REXX Commands › VARTABLE › VARTABLE GET Command—Get a Vartable Entry

VARTABLE GET Command—Get a Vartable Entry

The VARTABLE GET command retrieves an entry from an existing memory-resident vartable.

This command has the following format:

VARTABLE GET ID=tablename [SCOPE=scope] [KEY=key]
            [AGE={NO | YES}] [DELETE={NO | YES}]
            [FIELDS=(fldlist) VARS=(varlist)]
            [OPT=search-option]

ID=tablename

Specifies the name of the table.

Characters: A through Z, a through z, 0 through 9, #, $, and @

Limits: 1 through 12 characters

SCOPE={SYSTEM | PROCESS | REGION}

Specifies the scope of the vartable.

Default: PROCESS

KEY=key

Specifies the key for this table entry.

If the table is allocated with KEYFMT=CHAR and the key is shorter than the declared key length, the supplied key value is padded with blanks. If the key is longer, a return code of 12 is set in RC and no action is taken on the entry. If the key contains spaces, enclose the key between quotes, for example:

ThisKey = Feature||' '||Version||' '||PrdId
"VARTABLE …",
"       KEY='"||ThisKey||"'",
…

"VARTABLE …",
"       KEY='TPCF 99.99.99 MMGR-SQJ'",
…

If the table was allocated with KEYFMT=NUM, the key value must be a valid, signed number.

AGE={NO | YES}

Specifies whether to make the retrieved entry the newest in the table. The default depends on the value for the AGE parameter specified on the VARTABLE ALLOC command for this table. If the table has been allocated with aging on GET, using AGE=NO on a VARTABLE GET lets you access entries for maintenance without aging entries.

DELETE={NO | YES}

Specifies whether to delete the retrieved entry.

Default: NO

FIELDS=(fldlist)

Specifies the fields in the format fname[,…fname]. fname must be one of the following mutually exclusive values:

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

VARS=(varlist)

Specifies a list of valid REXX variables that holds values assigned to fldlist. A one-to-one correspondence exists between each entry in varlist to the same entry in fldlist. For example, the first entry in varlist specifies the variable containing the data for the first entry in fldlist. If fldlist includes DATA*, the associated varlist entry must be in the format prefix*. When values are returned, they are in variables prefix1 through prefixn.

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.

Example: VARTABLE GET

/* get the stem of IP connections from $IPLINK vartable              */ 
lk.0 = 0
lk.1 = 'a' 
'vartable query id=$IPLINKS scope=system fields=(total) vars=(lk.0)'    
If RC = 0 Then Do i = 1 to lk.0
  'vartable get id=$IPLINKS scope=system fields=(key) vars=(lk.i) ',  
  'opt=KGT key="'lk.i'"' 
End

Return Codes

The codes returned are the same as the &ZFDBK values as documented for the NCL &VARTABLE verb.

The return codes are as follows:

0: Indicates that the request was satisfied.
4: Indicates that no entry with the requested key value exists.
12: Indicates that the supplied key value was longer than the table key length.
16: Indicates that no table of this name exists in this scope.