EXTRACT EXIT
Obtain the address and length of a global work area.
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.