&VARTABLE ADD

Verbs and Built-in Functions › &VARTABLE ADD

&VARTABLE ADD

Allows an NCL procedure to add a vartable entry to an existing vartable.

&VARTABLE ADD ID=tablename KEY=fieldname
            [ SCOPE={ PROCESS | REGION | SYSTEM | AOM} ]
            [ ADJUST=n | COUNTER=n ] 
            [ FIELDS=fieldlist { VARS=(var1, var2, ...  varn) |
                                 VARS=prefix* [ RANGE=( start, end ) ] |
                                 ARGS [ RANGE=( start, end ) ] | MDO=mdoname } ]

Operands:

ID=tablename

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

KEY=fieldname

(Mandatory) Indicates the name of the NCL variable that contains the value of the key to assign to this table entry. 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 would be 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, or an error response is set and the entry not added if the value is longer. 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.

SCOPE= { PROCESS | REGION | SYSTEM | AOM }

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

PROCESS

(Default) Indicates 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 procedures executing in another window, if you have more than one window open.

SYSTEM

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

AOM

Indicates that this verb refers to a mirrored vartable. The entry is also added to the mirrored copy if AOM is started.

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

ADJUST=n | COUNTER=n

These parameters let you set or adjust the counter field of the new entry. Only one is coded, and they are mutually exclusive with the use of COUNTER or ADJUST as field list values (see later). If none of these parameters are specified, the counter field is initialized to 0. n must be an integer, optionally signed, that is valid for NCL arithmetic.

COUNTER=n sets the counter field of the new entry to the value of n.

ADJUST=n adds the value of n to the counter field of the new entry (n can be negative).

Because the counter field of a new entry is initialized to 0, ADJUST=n on an ADD operation is the same as COUNTER=n.

FIELDS=fieldlist { VARS=(var1, var2, ... varn) |

VARS=prefix* [ RANGE=( start, end ) ] |

ARGS [ RANGE=( start, end ) ] |

MDO=mdoname } ]

These parameters let you specify the information you want to store in the new table entry, and the NCL variables that the information is to be extracted from. 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 store. fieldlist is a list of names in one of the following formats:

name

(name)

(name,name,...)

where 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 the entire entry is to be updated from an MDO. An MDO name must be located in the corresponding position in the VARS list.
.COUNTER: Indicates that you are supplying an initial value for the counter field in this entry. The field is mutually exclusive with .ADJUST, and COUNTER= or ADJUST=.
.ADJUST: Indicates that you are supplying an adjustment value for the counter field in this entry. The field is mutually exclusive with .COUNTER, and COUNTER= or ADJUST=.
.USERCORR: Indicates that you are supplying a user correlator check value. Because a new entry cannot have a value to check against, the supplied value is ignored (but must be numeric).

AOM tables can have the following additional field names specified:

.AOMID: Indicates the AOM ID value. The associated variable must be null, or contain a value from 1 to 12 characters. The value is folded to uppercase.
.AOMATTR: Is the AOM attribute string.

VARS=(var1,var2,...,varn) nominates the NCL variables that contain the information for each entry in the fieldlist. A one-to-one correspondence exists from each entry in the variables list to the same entry in fieldlist. Thus the first entry in variables list nominates the variable containing the data for the first entry in fieldlist. The variables list must be in one of the following formats:

varname

(varname)

(varname,varname,...)

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

VARS | ARGS | MDO defines the source data structures for the ADD 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 that are the target of the ADD operation. 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, ABC.) 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 source variables are specified by the usual NCL syntax (that is, as ARGS [RANGE=], VARS=varslist, VARS=prefix [ RANGE= ], or MDO=mdoname).

If an MDO is nominated as the source data structure it is placed intact into the vartable as the vartable entry. Mapping Services maintains the mapping for a subsequent GET operation.

Examples: &VARTABLE

&K = KEY001 
&D = DATA001 
&VARTABLE ADD ID=MYTABLE KEY=K FIELDS=DATA1 VARS=D

This example adds an entry to the private (SCOPE=PROCESS) vartable named MYTABLE. The entry has a key value of KEY001 and a data1 content of DATA001.

Return Codes:

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

0: The entry was added successfully.
1: The entry was added successfully. The table was at the limit specified by the &VARTABLE ALLOC, and DELOLD=YES was also specified on the ALLOC. The oldest entry was deleted to make room for this entry.
4: An entry with the nominated 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.
24: The table is already at the limit specified by &VARTABLE ALLOC. The entry could not be added.
28: Variable specified for .AOMID is longer the 12 characters.
32: SCOPE=AOM table has been disabled due to a storage error.
100: Variable specified for .AOMATTR is longer than 30 characters.
101 to 130: Variable specified for .AOMATTR has an invalid value at the position indicated by 130 subtracting 100 from the &ZFDBK code.

&ZFDBK values 28, 32, 100, and 101 through 130 are possible only with AOM tables. &ZFDBK value 1 cannot occur with AOM.

Syntax errors in a &VARTABLE ADD statement terminate the NCL procedure. Always specify SCOPE=REGION or SCOPE=SYSTEM to refer to a table of that scope.