|
|
|
The &VARTABLE PUT statement allows an NCL procedure to add or update an entry within an existing vartable. The entry is added if there is no entry with a matching key, or updated if an entry with a matching key already exists.
The &VARTABLE UPDATE statement allows an NCL procedure to update an entry within an existing vartable.
&VARTABLE { PUT | UPDATE }
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 you wish to retrieve the entry from. 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 search key. 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. 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:
Indicates the table is a private table, visible only to the NCL process that allocated it.
Indicates the table is visible to all NCL procedures executing in the current region.
Indicates that the table is visible to all NCL procedures executing in the same system.
Indicates that this statement refers to a mirrored vartable. The entry is added to or updated in 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 for a new or existing entry. Only one is coded, and they are mutually exclusive with the use of COUNTER, .COUNTER, ADJUST, and .ADJUST field list values (described below). If none of these parameters is specified, the counter field is initialized to 0 when adding, or left as is when updating. n is any valid, signed number that will fit into a full word.
COUNTER=n will cause the counter field of the new or updated entry to be set to the value of n.
ADJUST=n adds n to the counter field value of the new or updated entry (n can be negative). If the table for updating does not contain a matching key entry, the old counter value is taken as 0.
These optional parameters let you specify the information you want to store in the new table entry, or to replace information in an existing table entry, specifying the NCL variables the information is to be extracted from. If specified, the FIELDS and VARS operands must have the same number of entries within 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):
Note: When an entry contains an MDO, individual fields cannot be accessed.
AOM tables can have the following additional field names specified:
VARS=varlist nominates the NCL variables that contain the information for each entry in fieldlist. There is a one-to-one correspondence from each entry in varlist to the same entry in fieldlist. Thus the first entry in varlist nominates the variable containing the data for the first entry in fieldlist, and so on. varlist 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 wish to indirectly refer to the variable containing the data (see discussion under KEY=).
If DATA* or D* is specified in the FIELDS= list, the associated VARS= list entry must be in the format 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 ADD operation.
Examples: &VARTABLE PUT
&K = KEY001 &D = DATA001 &VARTABLE PUT ID=MYTABLE KEY=K FIELDS=DATA VARS=D
This example adds or updates an entry in the private (SCOPE=PROCESS) vartable called MYTABLE. The entry has a key value of KEY001 and a data content of DATA001.
.LOOP &MSGREAD ARGS
&VARTABLE PUT ID=IDTABLE KEY=1 ADJUST=1 +
FIELDS=DATA VARS=ZMTEXT
&GOTO .LOOP
This example builds a table containing all uniquely identified messages received in a MSGPROC, the identifier being the first word. The data for each entry is the last complete message text with that identifier, and the counter field contains the count of messages with that identifier received.
This illustrates the ease with which event counting is performed. The NCL procedure need not be concerned with whether a particular event (message, and so on) has already been seen, as the PUT logic handles this.
Changing the scope in this example to REGION allows another NCL procedure in the NCL region to sequentially read the table and display information to an operator.
Examples: &VARTABLE UPDATE
&K = KEY001
&D1 = DATA001A
&D2 = DATA001B
&D3 = DATA001C
&VARTABLE UPDATE ID=MYTABLE KEY=K FIELDS=DATA* +
VARS=D* ADJUST=1
This example updates an entry in the private (SCOPE=PROCESS) vartable called MYTABLE. The entry has a key value of KEY001, and the data fields (three assumed) have a data content of DATA001A, DATA001B, and DATA001C. The counter has 1 added to it.
.LOOP &MSGREAD ARGS
&VARTABLE UPDATE ID=IDTABLE KEY=1 ADJUST=1 +
FIELDS=DATA VARS=&ZMTEXT
&GOTO .LOOP
This example updates a table containing all previously nominated uniquely identified messages received in a MSGPROC, the identifier being the first word. The data for each entry is the last complete message text with that identifier, and the counter field contains the count of messages received with that identifier.
Compare this example with the example for &VARTABLE PUT. Only message identifiers previously entered into in the table are counted. If an entry is not found &ZFDBK is set to 4, and the update is not performed.
Changing this example by giving the table a scope of PROCESS, another NCL procedure in the NCL region could sequentially read the table and write the counts, and so on, to a screen.
Return Codes:
System variable &ZFDBK is set after an &VARTABLE PUT statement to indicate the result of the operation:
The entry was added or updated successfully.
The entry was added successfully. The table was at the LIMIT specified on the &VARTABLE ALLOC, and the oldest entry was deleted to make room for this entry.
An entry with the nominated key value already exists, and the supplied user correlator value did not match the user correlator value in that entry.
The supplied key value was longer than the table key length.
No table of this name exists in this scope.
This table was allocated with USERCORR=YES specified, and no user correlator was supplied on the &VARTABLE PUT statement.
This table was allocated with USERCORR=YES specified, and no user correlator was supplied on the &VARTABLE PUT statement.
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 with AOM tables only. &ZFDBK value 1 cannot occur with AOM.
System variable &ZFDBK is set after an &VARTABLE UPDATE statement to indicate the result of the operation:
The entry was updated successfully.
No entry with the supplied key value exists.
An entry with the nominated key value exists, but the supplied user correlator value did not match the user correlator value in that entry.
The supplied key value was longer than the table key length.
No table of this name exists in this scope.
This table was allocated with USERCORR=YES specified, and no user correlator was supplied on the &VARTABLE UPDATE statement.
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 with AOM tables only.
Notes:
Syntax errors in &VARTABLE PUT and VARTABLE UPDATE statements cause an NCL procedure to terminate.
You must always specify SCOPE=REGION to refer to a table of that scope.
| Copyright © 2009 CA. All rights reserved. |
|