VCOPY—create a copy of a variable

This service is used only with CALL ISPLINK or CALL ISPLNK calls.

The VCOPY service allows a program module to obtain a copy of dialog variables. The copied data is in character string format and can be accessed in either "locate" or "move" mode.

The variable names can be specified as a single 8-character value, a list enclosed in parentheses, or a name-list structure. In LOCATE mode an array of pointers must be supplied to receive the data address. An array of lengths must be supplied to receive the data lengths.

In locate mode, the VCOPY service automatically allocates storage for the data, and returns the address and length of each variable to the caller.

In move mode, an array of lengths must be supplied on input. Its values map the structured area which must be supplied to receive the data. The caller first allocates storage for the data, and then invokes VCOPY, passing the address and length of the storage area into which the data is to be copied. The length array is then set with the data lengths.

When a variable has been masked and is accessed by VCOPY, the output string will contain the mask characters. When specifying the length to receive these variables on the VCOPY call, the length should be as long as the mask, not the defined variable. See VMASK—mask and edit processing for a full description of the VMASK service.

As with other DM component services, the search for each variable starts with the defined area of the function pool, followed by the function's implicit area, followed by the shared pool, and then the profile pool. If a variable of the specified name is not found, VCOPY issues a return code of 8.

Command invocation format

ISPEXEC  *This service does not apply to APL2 or command
          procedures*

Call invocation format


>>-CALL--ISPLINK--('VCOPYbbb'--,--name-list,--length-array,----->

                  .-'LOCATEbb'-.       
>--value-array--,-+-'b'--------+--);---------------------------><
                  '-'MOVEbbbb'-'

Parameters

name-list

Specifies an area containing the names of dialog variables to be copied. The standard name-list format is used.

length-array

Specifies an array of fullword fields containing the lengths of the data areas for the dialog variable values. The array can consist of a single item. In move mode, each element of the array is set by the caller to the output area size. In move or locate mode, each element of the array is set by the service to the number of bytes of data for the corresponding variable. The length does not include trailing blanks unless the variable is defined to maintain blanks. For example:

VCOPYing a variable that was defined using VDEFINE with the NOBSCAN option
VCOPYing a REXX variable that was explicitly set with trailing blanks and then VPUT to the SHARED or PROFILE pool.

value-array

In locate mode, specifies the name of an array that contains pointers to fields into which the copied variables are placed. The array can consist of a single item. In move mode, specifies the name of a structure that is mapped by the length array.

LOCATE

Specifies locate mode. The address of the copied value is returned to the user invoking the service. This is the default mode.

MOVE

Specifies move mode. The copied value is returned to the user invoking the service.

Return codes

These return codes are possible:

0: Normal completion.
8: One or more variables do not exist.
12: Validation failed.
16: Truncation has occurred during data movement (move mode only).
20: Severe error.

Example

Copy the value in dialog variable QROW to a field named QROWSDATA in this PL/I program module. Perform the copy in move mode, as opposed to locate mode. Variable L8 contains a value of 8.

CALL ISPLINK ('VCOPY   ','QROW ',L8,QROWDATA,'MOVE    ');