EXTRACT EXIT

Obtain the address and length of a global work area.

EXTRACT EXIT

Read syntax diagramSkip visual syntax diagramEXTRACT EXIT PROGRAM( data-value)ENTRYNAME( data-value)GALENGTH( data-area)GASET( ptr-ref)

Conditions: INVEXITREQ, NOTAUTH

Description

The EXTRACT EXIT command obtains the address and length of the global work area that is owned by, or shared by, a user exit.

Note: To enable the use of application programs written for earlier releases that specify DSNCEXT1 or DSN2EXT1 on the EXTRACT EXIT command to inquire on the status of the CICS-DB2 interface, CICS® automatically substitutes the correct name, DFHD2EX1. CICS does this by setting argument 1 in the parameter list to address the new name, and no application program storage is altered. This allows existing application programs to work unchanged.

Options

ENTRYNAME(data-value)
Specifies the 8-character name of the global or task-related user exit for which you want global work area information. If you omit ENTRYNAME, CICS assumes that the name of the exit is the same as the name of the load module given in the PROGRAM option. Therefore, you must use the same combination of ENTRYNAME and PROGRAM values as was specified on the ENABLE PROGRAM command that defined the exit.
GALENGTH(data-area)
Returns the length in bytes of the global work area, in halfword binary form.
Note: If a GALENGTH greater than 32767 has been defined (see GALENGTH for ENABLE PROGRAM for details), the response to this command reflects that higher value as follows:
  • If you issued the EXTRACT EXIT command at your terminal, the response shows a negative value for GALENGTH.
  • If you issued the EXTRACT EXIT command from a program, the high order bit of the response for GALENGTH is set. You must allow for this possibility when deciding what operation to perform next on the returned value.
GASET(ptr-ref)
Returns the address of the global work area. The global work area can be in 31-bit storage (above 16 MB) or 24-bit storage (below 16 MB), depending on the location that was specified using the GALOCATION option on the ENABLE PROGRAM command that defined the exit.
PROGRAM(data-value)
Specifies the name of the load module containing the entry point of the exit. This name is also used as the name of the exit when ENTRYNAME is not specified; see the ENTRYNAME option.

Conditions

INVEXITREQ
The INVEXITREQ condition of the EXTRACT EXIT command is indicated by X'80' in the first byte of EIBRCODE. The exact cause of the error can be determined by examining the second and third bytes of EIBRCODE. For further information on EIBRCODE, see EXEC interface block (EIB) response and function codes.
X'800200'
The exit is not enabled.
X'800400'
The exit has no global work area.
X'808000'
The load module named in the PROGRAM option is not the same as the one used when the exit specified in the ENTRYNAME option was enabled.
NOTAUTH
RESP2 values:
100
The user associated with the issuing task is not authorized to use this command.
101
The user associated with the issuing task is not authorized to access this particular resource in the way required by this command.