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

>>-CALL--ISPLINK--('VDEFINEb'--,--name-list,--variable,--------->

>--format,--length--,-+-options-list-+--,-+-user-data-+--------->
                      '-'b'----------'    '-'b'-------'   

>--,-+-'LFORMAT'-+-);------------------------------------------><
     '-'b'-------'      

name-list

Specifies the symbolic name or name-list to be used by ISPF when referencing the specified variables.

An asterisk, in conjunction with the USER format keyword, specifies that the exit routine, whose address is specified in the user-data parameter, is to be called for variables not found in the function pool.

An asterisk (*) in the name-list, in conjunction with an asterisk in the format parameter, specifies that the storage represented by the corresponding physical length in the length parameter is to be skipped when calculating the address of the next name in the name-list. When this facility is used, LIST must be specified in the options-list parameter.

variable

Specifies the variable whose storage is to be used. If a name list is passed, this storage contains an array of variables. The number of names in the list determines the dimension of the array.

When LIST is specified for options-list, this parameter is the name of a variable or structure whose storage is used for dialog variables in the name list. This storage is assigned to dialog variables in the order that they appear in the name-list, and according to the length array mapping.

format

Specifies the data conversion format.

When LIST is specified for options-list, this parameter is the name of an array of CHAR(8) fields, one for each variable in the name-list. Each element of this array defines the data format of the variable in the corresponding position in the name-list. Entries must be left-justified and padded with blanks. There must be at least as many array elements as there are names in the name-list. You can use an asterisk in the format list to have application storage not be considered by VDEFINE. See the previous discussion under the name-list parameter.

Valid formats are:

BINSTR—Binary String

ISPF provides the binary string data format to support dialog applications written in the C language. When a variable defined as BINSTR is updated in the function pool, ISPF pads with binary zeros. This is desirable within C function programs, because the C language uses binary zeros to mark the end of a character string.

In updating this type of variable, ISPF stores only up to "length - 1" amount of significant data and places a null terminator in the last position. Because the updated data contains the binary zero, the length of the variable should be greater than 1.

BIT

Bit string, represented by the characters 0 or 1. Within the variable, the data is left-justified and padded on the right with binary zeros. For these variables, a null value is stored as binary zeros and cannot be distinguished from a zero value.

CHAR

Character string. Within the variable, the data is left-justified and padded on the right with blanks.

No data conversion is performed when fetching and storing a CHAR variable, nor is there any checking for valid characters. In PL/I, a character string to be used as a dialog variable must be declared as fixed length, because VDEFINE cannot distinguish variable-length PL/I strings.

DBCS

DBCS string. Within the variable, the data is left-justified and padded on the right with blanks. The variable must not contain shift-out or shift-in characters and it must be even in length.

No data conversion is performed when fetching and storing a DBCS variable, nor is there any checking for valid characters.

FIXED

Fixed binary integer, represented by the characters 0-9.

Fixed variables that have a length of 4 bytes (fullword) are treated as signed, represented by the absence or presence of a leading minus sign (-). They can also have a null value, which is stored as the maximum negative number (X'80000000').

Fixed variables that have a length of less than 4 bytes are treated as unsigned. For these variables, a null value is stored as binary zeros, and cannot be distinguished from a zero value.

FLOAT—Floating Point

The floating point data format is used for variables consisting of numeric values stored in characteristic/mantissa form.

Format type FLOAT dialog variables are displayed (and stored in the shared and profile pool) in character representation with the decimal separator.

Floating point numbers are processed as real numbers. A single-precision number is processed as a 32-bit real number and can have 7 or 8 significant digits. A double-precision number is processed as a 64-bit real and can have 13 or 14 significant digits. For single-precision floating point numbers, up to 7 digits is displayed as a real number. Any number greater than 7 digits is represented in exponential notation.

For example, for short floating point numbers,

VALUE

REPRESENTATION

1234567

1234567

12345678

1.234568E+⁰⁷

123.4567

123.4567

123.45678

123.4568

For double-precision floating point numbers, the limit is 13 digits.

The length that you specify for this type must equal the total number of bytes of program storage that the variable uses. FLOAT variables can have a length of 4 or 8 bytes. A FLOAT variable defined with a length of 4 bytes is considered single precision and with 8 bytes is considered double precision.

The magnitude (M) of a floating point number supported by ISPF is:

5.4 × 10-⁷⁹ ≤ M ≤ 7.2 × 10+⁷⁵

ISPF converts floating point numbers between the real number and character formats. Because of this conversion, rounding is not predictable for single precision numbers when the digit being rounded is a 5.

HEX

Bit string, represented by the characters 0-9 and A-F. Within the variable, the data is left-justified and padded on the right with binary zeros. For these variables, a null value is stored as binary zeros and cannot be distinguished from a zero value.

PACK | PACK(n)—Packed Decimal

The packed decimal data format provides support for COBOL and corresponds to a COBOL COMP-3 data type. Packed decimal variables consist of right-justified numeric values stored such that each decimal digit takes up one-half byte. All bytes contain 2 decimal digits, except for the last byte in the variable. The last byte consists of the least significant decimal digit followed by a representation of the sign. The maximum number of digits in a PACKed variable is 18 as specified by ANSI COBOL standard. This results in the number of digits always being an odd number.

The valid values to represent the sign are the hexadecimal digits C for positive and D for negative. If the sign is any other hexadecimal digit, the value is considered to be unsigned.

The length that you specify for this type must equal the total number of bytes of program storage that the variable uses. PACK variables can have a length of 1-10 bytes.

When you define a variable as having a PACK(n) data format, n specifies the number of digits to appear to the right of the assumed decimal point. For example, the value of a variable when defined is 12345. The assumed decimal position would occur before the 1 if defined as PACK(5), after the 1 if defined as PACK(4), after the 2 if defined as PACK(3), and so on. PACK without (n) specified is equivalent to PACK(0).

Variables defined as PACK or PACK(n) are converted to character representation when retrieved from the function pool. If the variable is defined as PACK(n), and n is greater than zero, the converted number will contain a decimal separator followed by n digits after the assumed decimal point.

When a variable defined as PACK(n) is updated in the function pool, ISPF will pad the variable with zeros or truncate on either end to ensure the variable contains the correct number of digits to the right of the assumed decimal separator.

The value of n must be in the range 0-18.

USER

Specifies that the format is to be determined by the user. Any conversion format is allowed. A conversion routine must be specified and is specified by naming it in the user-data parameter.

length

Specifies the length of the variable storage, in bytes. This parameter must be a fullword fixed binary integer. The maximum length for a FIXED variable is 4 bytes, for PACK(n) variables is 10 bytes, and for FLOAT variables is 8 bytes. The maximum length for other types of variables is 32 767 bytes.

For character variables in a C program, this length should be one less than the length of the program variable. This allows for the null terminator at the end of the string. Always initialize variables for the length specified in this parameter, unless you are using the BINSTR parameter.

When LIST is specified as an option in the options-list, this parameter is the name of an array of fullword fixed binary integers. Each element of this array defines the data length of the variable in the corresponding position of the name-list. There must be at least as many array elements as there are names in the name-list.

options-list

Specifies initialization of the defined storage and/or retention of trailing blanks in variable data. The options-list parameters are COPY, NOBSCAN, and LIST. They are specified in the name-list format.

Note: Option-list parameters cannot be specified if the USER format keyword and a name-list of asterisk (*) have been selected.

COPY

Specifies that any dialog variable with the same name can be used to initialize the defined storage. The variable pools are searched in the standard function pool, shared pool, profile pool sequence.

Note: If the variable being defined is smaller than the retrieved value, the service request terminates and returns to the caller. In this case, if you have specified the LIST option, the remainder of the list is not processed.

NOBSCAN

Specifies that any trailing blanks in the variables are to remain in the variables.

LIST

Specifies that the variables in the name-list to be defined to ISPF are of varying formats (format array) and lengths (length array).

When the LIST option is used, programs can VDEFINE only selected application variables in a dialog application structure. This is accomplished by specifying an asterisk (*) as a placeholder in the name-list and in the corresponding position in the format definition array for those portions of dialog application storage that are not to be considered by VDEFINE. The asterisk place-holder (in the name-list and the format) allows ISPF to determine the address of the dialog application storage of the next true variable name in the name-list. This is determined by the corresponding length in the length array parameter.

user-data

Specifies the storage location that contains the entry point address of the conversion subroutine followed by any other data that should be passed to the routine.

The exit is given control in 31-bit mode if either the VDEFINE dialog service is invoked in 31-bit mode or the high-order bit of the user-exit address is on as specified for the VDEFINE service. The high-order bit contains the AMODE and the remainder of the word contains the address. If bit 0 contains 1, the exit routine is given control in 31-bit addressing mode.

This parameter is specified whenever the USER parameter is specified.

LFORMAT

Indicates the specified name-list variables all have the same format.

The dialog writer can specify an exit routine to define dialog variables when program variables are non-standard (other than BINSTR, BIT, CHAR, DBCS, FLOAT, FIXED, HEX, PACK, or PACK(N)). Then, when a variable is accessed by any DM component service, the exit routine is invoked to perform any conversion necessary between the program variable's format and the character string format required for a dialog variable.

The dialog writer must specify this information in the dialog function that VDEFINEs the variables to be formatted by the exit routine:

1. A storage location must be defined that contains the entry point address of the user exit and any other user data that should be passed to the exit routine. For example:

   DECLARE USERXT EXTERNAL ENTRY;  /*USERXT IS THE NAME OF THE*/
                                   /*EXIT ROUTINE             */
   DECLARE 1 XITINFOR,
             2 XITPTR ENTRY VARIABLE,
             2 USERDATA CHARACTER; /*CONTAIN ANY USER DATA TO */
                                   /*BE PASSED TO THE EXIT    */
                                   /*ROUTINE                  */

2. The VDEFINE must specify a format of USER and specify the area that contains the address of the exit routine and the user data field. If the defined variable name is '*', all unresolved dialog variable accesses result in the call of the exit routine. Unresolved dialog variables are those that were not implicitly entered or defined in the function pool.

   ISPLINK ('VDEFINE ', '(VAR )', VAR,
            'USER    ', 4, ' ', XITINFOR)

CALL XRTN( UDATA,     /* invoke exit and pass user area */
           SRVCODE,   /* request code                   */
           NAMESTR,   /* name length and name chars     */
           DEFLEN,    /* defined area length            */
           DEFAREA,   /* defined area                   */
           SPFDLEN,   /* ISPF data length               */
           SPFDATAP); /* ISPF data address              */