EXTRACT EXIT

Obtain the address and length of a global work area.

Syntax

Warning: System commands are powerful as they provide information about the state of the system and allow changes to be made to it. System commands should be used only by authorized applications and users.

Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).

EXTRACT EXIT

Conditions: INVEXITREQ, NOTAUTH

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations.

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.