VDEFINE exit routine

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:

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                  */

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)
```

ISPF invokes the exit routine using a call (BALR 14,15), and standard OS linkage conventions must be followed. The parameters passed by ISPF to the exit routine are shown on the call. The exit is invoked with:

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              */

UDATA

An area that follows the exit routine address parameter, specified on the VDEFINE statement. This area can contain any additional information the user desires. Its format is CHAR(*).

If more than one variable is defined using the same exit routine, the dialog must ensure that the length and address of the converted data for each variable are returned to ISPF in unique locations. Otherwise, unexpected results can occur if a service, such as TBADD, is called with two or more of these variables.

In the example, UDATA points to an area that contains addresses for SPFDLEN and SPFDATAP to be used for the variable VAR.

SRVCODE

Service request-type code, as a fullword fixed value. The allowable values are 0 for a read and 1 for a write. Other values should be accepted without error, to allow further extensions. Codes of 2 and 3 are used by the dialog test facility variable query function. Code 2 is a request for the number of variables to be returned in the SPFDLEN field. Code 3 is a request for the names of the variables to be returned in the buffer pointed to by SPFDATAP. The names are entered as contiguous 8-byte tokens.

NAMESTR

Name of the dialog variable being requested, preceded by the 1-byte name length.

DEFLEN

The length of the area specified to the VDEFINE service. Its format is a fullword fixed value.

DEFAREA

The area specified to the VDEFINE service. Its format is CHAR(*).

SPFDLEN

For a write request, the length of the SPFDATA area is supplied by ISPF to the exit routine. For a read request, the length of the data is returned to ISPF. It must be supplied by the exit routine. Its format is a fullword fixed value.

SPFDATAP

For a write request, the address of the data to be stored is supplied by ISPF to the exit routine. For a read request, the address of the data is returned to ISPF. Its format is a fullword pointer.