Verbs and Built-in Functions › &VARTABLE DELETE

&VARTABLE DELETE

Allows an NCL procedure to delete an entry from an existing vartable. The delete can be optionally synchronized with any concurrent updating.

&VARTABLE DELETE ID=tablename 
               [ SCOPE={ PROCESS | REGION | SYSTEM | AOM } ] 
               [ KEY=fieldname ] 
               [ FIELDS=fieldlist VARS=varlist ]

Operands:

ID=tablename

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

SCOPE= { PROCESS | REGION | SYSTEM | AOM }

An optional parameter, indicating the scope of the table you wish to delete. Allowed values are:

PROCESS

(Default) Indicates that the table is a private table allocated by this NCL process.

REGION

Indicates that the table has been allocated a scope of REGION.

SYSTEM

Indicates that the table has been allocated by all NCL procedures executing in the same system.

AOM

Indicates that this statement refers to a mirrored vartable. The entry is deleted from the mirrored copy if AOM is started.

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

KEY=fieldname

(Mandatory) Indicates the name of the NCL variable that contains the value of the key of the table entry you wish to delete. 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 contains KF, the contents of variable KF are 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. If the value is longer, an error response is set and the entry not added. KEYFMT=UCHAR performs on 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.

FIELDS=fieldlist VARS=varlist

These parameters let you specify a user correlator value for validation against the current table contents. You must specify both these parameters, or omit both. If specified, the two parameters must have one entry in each list.

FIELDS=fieldlist nominates the information you want to delete. fieldlist is a list of names in one of the following formats:

name

(name)

(name,name,...)

where each name is an unduplicated user correlator value (.USERCORR) from a previous &VARTABLE GET supplied to check synchronization (the value corresponds to that for the variable in the VARS list).

VARS=varlist nominates the NCL variables that contain the information for each entry in fieldlist. There is a one-to-one correspondence between each entry in varlist and the same entry in fieldlist. Thus the first entry in varlist nominates the variable containing the data for the first entry in fieldlist. 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= above).

Examples: &VARTABLE DELETE

&K = KEY001 &VARTABLE DELETE ID=MYTABLE KEY=K

This example deletes the entry with key value KEY001, in the private vartable (SCOPE=PROCESS), called MYTABLE. If there is no entry with that key, &ZFDBK is set to 4.

Return Codes:

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

0

The entry was deleted successfully.

4

No entry with the nominated key value exists.

8

The value of the supplied user correlator does not match the value in the table entry.

12

The supplied key value was longer than the table key length.

16

No table of this name exists in this scope.

32

SCOPE=AOM table has been disabled due to a storage error.

&ZFDBK value 32 is only possible with AOM tables.

Notes:

Syntax errors in a &VARTABLE DELETE statement will cause the NCL procedure to terminate.

You must always specify SCOPE=REGION to refer to a table of that scope.