&VARTABLE ALLOC

Verbs and Built-in Functions › &VARTABLE ALLOC

&VARTABLE ALLOC

Allows an NCL procedure to allocate a new vartable. Once allocated, other &VARTABLE statements can refer to the table. The table is defined without entries.

&VARTABLE ALLOC ID=tablename
              [ SCOPE={ PROCESS | REGION | SYSTEM | AOM } ] 
              [ AGE={ NO | NEW | ALL | UPDATE | GET } ]
              [ DATA={ 1 | n | MAPPED } ] 
              [ DELOLD={ YES | NO } ]
              [ KEYFMT={ CHAR | UCHAR | NUM } ]
              [ KEYLEN=keylen ]
              [ LIMIT={ 0 | n } ]
              [ USERCORR={ NO | YES } ]

Operands:

ID=tablename

(Mandatory) Names the table which other &VARTABLE statements can then refer to. tablename must be a 1- to 12-character name; the first character alphabetic or national, the rest alphanumeric or national.

SCOPE= { PROCESS | REGION | SYSTEM | AOM }

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

PROCESS

(Default) The table is visible only to the NCL process that allocates it. This includes any nested or higher-level EXECuted procedures.

REGION

Indicates the table is visible to all NCL procedures executing in the current region. This includes any EXECuted, STARTed, or &INTCMDed procedures in this region, and any procedures executing in another OCS window, if you have more than one window open.

SYSTEM

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

AOM

Indicates this statement allocates a mirrored vartable. If AOM is not started the actual mirrored copy is not allocated. When AOM is started the mirrored copy is built.

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

The amount of storage needed for the mirrored copy is determined by the LIMIT parameter. This parameter is required if SCOPE=AOM is specified. If the maximum amount of storage allowed for mirrored vartables is exceeded, as set by the SYSPARMS AOMMIRST command, the ALLOC command is rejected with an &ZFDBK of 24. This also happens when the maximum allowable storage is set to zero, to disable the use of mirrored vartables.

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

DATA={ 1 | n | MAPPED }

Indicates how many data fields is stored in each table entry. A number from 1 to 16 is specified. If omitted, this field defaults to 1. Each data field can hold up to 256 characters of data.

The number specified determines the maximum number of fields, which correspond to NCL variables, that is placed in a single vartable entry.

DATA=MAPPED

Specifies that each entry in the vartable is either an MDO, or can contain an unrestricted number of NCL variables.

DELOLD={ YES | NO }

Indicates whether &VARTABLE ADD or &VARTABLE PUT (when adding) can delete the oldest entry automatically when the table is full (for tables allocated with a LIMIT that is not zero; this option has no meaning if LIMIT=0 is specified or defaulted):

DELOLD=NO means that the ADD or PUT does not proceed; a &ZFDBK value of 24 is returned.
DELOLD=YES means that the ADD or PUT will proceed. The oldest entry is deleted and an &ZFDBK value of 1 is returned to warn the user.

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

KEYLEN=keylen

Must be provided if KEYFMT=CHAR or UCHAR is specified or defaulted, to indicate the key length of the entries in this table. keylen must be a number from 1 to 256. Key values supplied when adding entries to this table are padded with blanks to the nominated length, if shorter. If key values are longer, an error response is returned.

LIMIT={ 0 | n }

Indicates whether the table is to have a limit on the number of entries.

LIMIT=0: (Default) Indicates that the table can have any number of entries.
Limit=n: n is from 1 to 1,000,000 indicating that no more than n entries is added to the table. If an &VARTABLE ADD or &VARTABLE PUT operation exceeds this limit and DELOLD=NO is specified or defaulted on the ALLOC, the addition is not performed, and an &ZFDBK value of 24 is returned. If DELOLD=YES is specified, the addition is performed, and the oldest entry automatically deleted to make room.

USERCORR= { NO | YES }

An optional parameter, allowing control over the use of the USERCORR field in table entries when performing &VARTABLE UPDATE or &VARTABLE PUT operations.

USERCORR=NO (the default) means that use of the user correlator is optional.

USERCORR=YES means that use of the user correlator is required when updating table entries.

Examples: &VARTABLE ALLOC

&VARTABLE ALLOC ID=MYTABLE KEYLEN=20

This example allocates a private table called MYTABLE with a key length of 20.

&VARTABLE ALLOC ID=STABLE SCOPE=SYSTEM KEYLEN=30 LIMIT=50 USERCORR=YES

This example allocates a table called STABLE, which is visible to all NCL procedures running in this system. The key length is 30, and update operations require use of the user correlator. A limit of 50 entries is placed on the table.

Return Codes:

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

0: Indicates that the table was allocated successfully.
16: Indicates that a table of this name exists in this scope. A table of the same name is allocated in each of the three scopes. For example, an NCL procedure could allocate a table called TAB1 with a scope of PROCESS, another with a scope of REGION, and another with a scope of SYSTEM. All statements that want to refer to the REGION or SYSTEM level table must specify the SCOPE= parameter.
20: Indicates that 16 tables are already allocated.
24: Indicates that the allocation causes the total storage necessary for mirroring to exceed AOMMAXIS.

&ZFDBK values 20 and 24 are only possible with AOM tables.

Notes:

Syntax errors in a &VARTABLE ALLOC statement will terminate the NCL procedure.

AOM requires KEYLEN=16 and a nonzero limit value on an &VARTABLE ALLOC.