VGET—retrieve variables from a pool or profile or system symbol

The VGET service copies values from dialog variables in the shared pool or the application profile pool to the function pool variables with the same names. If a named function variable already exists, it is updated. If not, it is created as an implicit function variable, and then updated.

The VGET service can also copy values from system symbols. By default each function variable is created with the same name as the corresponding system symbol, but you can specify a different name.

Command invocation format


                             .-ASIS----.   
>>-ISPEXEC--VGET--name-list--+---------+------------------------>
                             +-SHARED--+   
                             +-PROFILE-+   
                             '-SYMDEF--'   

>--+------------------------+----------------------------------><
   '-SYMNAMES(symname-list)-'

Call invocation format


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><


                                               .-'ASISbbbb'-.   
>>-CALL--ISPLINK--('VGETbbbb'--,--name-list--,-+-'b'--------+--->
                                               +-'SHAREDbb'-+   
                                               +-'PROFILEb'-+   
                                               '-'SYMDEFbb'-'   

>--,-+-symname-list-+-);---------------------------------------><
     '-'b'----------'

Parameters

name-list

Specifies the names of one or more dialog variables whose values are to be copied from the shared or profile pool to the function pool. The names are passed in the standard name-list format.

ASIS

Specifies that the variables are to be copied from the shared pool or, if not found there, from the profile pool.

SHARED

Specifies that the variables are to be copied from the shared pool.

PROFILE

Specifies that the variables are to be copied from the application profile. A shared pool variable with the same name is deleted, even if it is not found in the profile pool.

SYMDEF

The values for the variables defined by name-list are to be obtained from the system symbols.

SYMNAMES(symname-list)

symname-list lists the names of one or more system symbols that are to be obtained. It is specified in the same format as the name-list parameter. Where symname-list is omitted, the system symbols obtained are the same as those specified on the name-list parameter.

One reason why you might use the SYMNAMES parameter is that some system symbols may have the same name as a reserved or read-only dialog variable. In this case you must specify a different variable name in name-list and specify the actual symbol name in symname-list. For example, SYSCLONE is a read-only dialog variable in a CLIST. Therefore, this command would work within a REXX exec, but it would fail in a CLIST:

VGET (SYSCLONE) SYMDEF

Instead, you could specify the command to obtain the current value for the static symbol SYSCLONE and store it in a variable named CLONE:

ISPEXEC VGET (CLONE) SYMDEF SYMNAMES(SYSCLONE)

If there are fewer symbol names in symname-list than names in the name-list, then the symbol names are used from the symname-list until there are no more corresponding symbol names, then the remaining names in the name-list are used. In other words, if there are five names in name-list and only three symbol names, the symbol names are used for the first three symbols and the last two names in the name-list are used for the remaining symbols.

If the number of symbol names in symname-list exceeds the number of names in name-list, a severe error occurs.

This is an optional parameter. It is only valid when the SYMDEF parameter is also specified.

buf-len

Specifies a fullword fixed binary integer containing the length of "buffer".

buffer

Specifies a buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC call for a command procedure.

Return codes

These return codes are possible:

0: Normal completion.
8: Variable not found. If the SYMDEF parameter was specified: system symbol not found.
12: Validation failed.
16: Translation error or truncation occurred during data movement.
20: Severe error. If the SYMDEF parameter was specified: the number of symbol names in symname-list exceeds the number of names in name-list.

Note: If you issue a VGET request for a variable that does not exist in the pool from which you are trying to copy (shared or profile), the value of the function pool variable is still updated. Character variables are set to blanks. Fixed, bit, and hex variables are set to nulls (all zeros).

Examples

In a CLIST, copy from the shared pool to the function pool values for variables whose names are listed in variable VARLIST.

ISPEXEC VGET (&VARLIST) SHARED

In a PL/I program, VARLIST contains a list of variable names. Copy values for these variables from the shared pool to the function pool. The variable VARLIST has been made accessible to ISPF by a previous VDEFINE operation. Set the program variable BUFFER to contain:

VGET (&VARLIST) SHARED

Set program variable BUFLEN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('VGET    ',VARLIST,'SHARED  ');

In a CLIST, obtain the current value for the dynamic system variable LHHMMSS:

ISPEXEC VGET (LHHMMSS) SYMDEF

In a REXX exec, obtain the current values for the static symbols SYSNAME and SYSR1:

'VGET (SYSNAME SYSR1) SYMDEF'

In a REXX exec, obtain the current values for the dynamic symbols HHMMSS and LHHMMSS. Also obtain the current value for the static symbol SYSCLONE and store it in a variable named cl:

'VGET (cl hhmmss lhhmmss) SYMDEF SYMNAMES(sysclone)'