NetMaster REXX Commands › VARTABLE › VARTABLE ALLOC Command—Define New Vartable

VARTABLE ALLOC Command—Define New Vartable

The VARTABLE ALLOC command defines a new memory-resident vartable. The table, as defined, contains no entries. After this table is defined, other VARTABLE operations can refer to the table.

Specifying USERCORR indicates that the user wants to have synchronized correlation protection on entries in the table. This operand allows control over the use of the USERCORR field in table entries when performing VARTABLE UPDATE, VARTABLE DELETE, or VARTABLE PUT operations.

This command has the following format:

VARTABLE ALLOC ID=tablename [SCOPE=scope] [KEYLEN=klen] 
              [AGE={NO | NEW | ALL | UPDATE | GET}] [DELOLD={NO | YES}]
              [KEYFMT={CHAR | UCHAR | NUM}] [DATA=dn] [LIMIT=ln]
              [USERCORR={NO | YES}]

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

KEYLEN=klen

Specifies the length of the keys in this table. This value is required if KEYFMT=CHAR is specified or assumed.

Range: 1 through 256

AGE={NO | NEW | ALL | UPDATE | GET}

Specifies whether to age entries when certain operations are performed on them. For all specifications, an added entry is always marked as the newest. Aging allows a table to be used as a cache to keep frequently referenced entries in the table and to allow automatic deletion of old entries.

NO or NEW

Indicates that only entries added to the table become the newest entries. All other references leave an entry in relative age order.

ALL

Indicates that any reference to a table entry makes that entry the newest. This reference includes GET, PUT, ADD, or UPDATE.

UPDATE

Indicates that an entry updated by PUT or UPDATE is also made the newest entry.

GET

Indicates that an entry retrieved by GET is also made the newest entry.

Default: NO

DELOLD={NO|YES}

Specifies whether VARTABLE ADD and VARTABLE PUT can delete the oldest entry automatically when the table is full.

Default: NO

KEYFMT={CHAR | UCHAR | NUM}

Specifies whether the table has a numeric or character format key:

CHAR

Indicates that the key is a character string. The table is ordered for sequential retrieval based on the character value of the key and blank padded if necessary. KEYLEN is required for this value.

UCHAR

Is the same as KEYFMT=CHAR except that lowercase characters are translated to uppercase. KEYLEN is required for this value.

NUM

Indicates that the key is a signed number. The table is ordered based on the numeric value of the key (largest negative through 0 to largest positive). Key values must always be a valid, optionally signed number, from -2147483648 to 2147483647. KEYLEN cannot be specified for this value.

Default: CHAR

DATA=dn

Specifies how many data fields can be stored in each table entry.

Range: 1 through 16

Default: 1

LIMIT=ln

Specifies whether the table has a limit on the number of entries.

Range: 0 through 1,000,000

Default: 0 indicates that the table can have any number of entries.

USERCORR={NO|YES}

Specifies whether the USERCORR field can be used in table entries when performing VARTABLE UPDATE and VARTABLE PUT operations.

Default: NO

Example: VARTABLE ALLOC

'vartable alloc id=rxtest scope=region keylen=11 data=4 limit=5'

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.

16

Indicates that a table of this name exists in this scope.