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:
(Mandatory) Indicates the name of the table to which you wish to add a variable entry. The table must have been previously allocated, although not necessarily by this procedure (particularly if SCOPE=REGION is specified).
(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:
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 will be set, and the entry not added if the value is longer. KEYFMT=UCHAR performs an upper case 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.
An optional parameter, indicating the scope of the table. Allowed values are:
(Default) Indicates the table is visible only to the NCL process that allocates it. This includes any nested or higher-level executed procedures.
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.
Indicates the table is visible to all NCL procedures executing in the same system.
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.
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 below). 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.
These parameters let you specify the information you wish 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 in the list):
Indicates you are supplying a data value for the nth data field in this entry. n must be from 1 to the value specified on the DATA= parameter of the &VARTABLE ALLOC statement for this table (the maximum is 999). You can have several DATAn entries, as long as each has a unique number n.
Indicates you are supplying data for all the data fields in this entry, from 1 to the number specified when the table was allocated (the DATA= parameter on &VARTABLE ALLOC). 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 n.
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.
Indicates you are supplying an initial value for the counter field in this entry. Mutually exclusive with .ADJUST and COUNTER= or ADJUST=.
Indicates you are supplying an initial value for the counter field in this entry. Mutually exclusive with .COUNTER and COUNTER= or ADJUST=.
Indicates you are supplying a user correlator check value. Since 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:
Indicates the AOM ID value. The associated variable must be null, or contain a value from 1 to 12 characters. The value will be folded to uppercase.
Is the AOM attribute string.
VARS=(var1,var2,...,varn) nominates the NCL variables that contain the information for each entry in the fieldlist. There is a one-to-one correspondence 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 discussion under 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:
Each entry in the VARS list must parallel an entry in the FIELDS list and must be one of the following:
When the FIELDS operand is omitted (or specified as FIELDS=DATA*) the source variables is 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 will maintain 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 will add an entry to the private (SCOPE=PROCESS) vartable called MYTABLE. The entry will have 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:
The entry was added successfully.
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.
An entry with the nominated key value already exists.
The supplied key value was longer than the table key length.
No table of this name exists in this scope.
The table is already at the limit specified by &VARTABLE ALLOC. The entry could not be added.
Variable specified for .AOMID is longer the 12 characters.
SCOPE=AOM table has been disabled due to a storage error.
Variable specified for .AOMATTR is longer than 30 characters.
Variable specified .AOMATTR has an invalid value at the position indicated by 130 subtracting 100 from the &ZFDBK code.
&ZFDBK values 28, 32, 100, and 101 to 130 are possible only with AOM tables. &ZFDBK value 1 cannot occur with AOM.
Syntax errors in a &VARTABLE ADD statement will terminate the NCL procedure. You must always specify SCOPE=REGION or SCOPE=SYSTEM to refer to a table of that scope.