Exit XPCFTCH

XPCFTCH is invoked before a program defined to CICS® (including internal CICS modules) receives control, which could be because it is the first program in a transaction, or as a result of a LINK, XCTL, or HANDLE ABEND PROGRAM request.

You can use this exit to modify the entry address used when linking to the program. If the exit sets a return code of zero, or a modified address of zero, the entry address of the original application program is used.

You use this exit to pass control to an AMODE(64), AMODE(31), or AMODE(24) assembler application program or routine before the original program is invoked. After this assembler program finishes its processing, it should pass control back to the entry point of the original program by using a branch instruction. Do not use the exit to invoke any program other than the original program, because the results are unpredictable.

When XPCFTCH is invoked for a C or C++ program that is compiled with the XPLINK option, a flag is set to ignore any modification of the entry point address that the user exit might make.

If a modified entry address is supplied, the program that is invoked receives control in the execution key that the original application program would have received control in; that is, as specified on the EXECKEY option of the resource definition of the original program.

When invoked

Before an application program receives control.

Exit-specific parameters

UEPPCDS

Address of a storage area that contains program- and terminal-related information, and that can be mapped using the DSECT DFHPCUE. When XPCFTCH is invoked, the following DFHPCUE fields are significant:

PCUE_CONTROL_BITS

1-byte flag field. A setting of PCUECBTE indicates that the transaction is linked to a terminal.
A setting of PCUENOTX (X'40') indicates that the program is not command level.
A flag, PCUE_NO_MODIFY, in PCUE_CONTROL_BITS indicates that a modified entry address is not supported. When set, any return code of UERCMEA from XPCFTCH is ignored. CICS sets this flag before invoking XPCFTCH for C and C++ programs compiled with the XPLINK option.
A setting of PCUE_REAL (X'20') indicates that a real entry point is set in PCUE_REAL_ENTRY.

PCUE_TASK_NUMBER

3-character packed decimal field that contains the task number.

PCUE_TRANSACTION_ID

4-character field that contains the ID of the original transaction. This ID might differ from the current transaction ID.

PCUE_TERMINAL_ID

4-character field that contains the terminal ID (if any).

PCUE_PROGRAM_NAME

8-character field that contains the name of the program that is to receive control.

PCUE_PROGRAM_LANGUAGE

3-character field that contains the language of the program that is to receive control.

PCUE_LOAD_POINT

The load point of the program.

PCUE_ENTRY_POINT

The entry point of the program.

PCUE_AMOD

The addressing mode of the program is AMODE(31). This field is provided for compatibility with existing exit programs.

PCUE_AMOD_31

The addressing mode of the program is AMODE(31). Use this field in preference to PCUE_AMOD.

PCUE_AMOD_64

The addressing mode of the program is AMODE(64).

PCUE_PROGRAM_SIZE

Fullword that contains the size of the program, in bytes.

PCUE_COMMAREA_ADDRESS

Address of the communication area of the program, if the program has one.

PCUE_COMMAREA_SIZE

Fullword that contains the length of the communication area of the program, if the program has one.

PCUE_LOGICAL_LEVEL

Fullword that contains the program logical level.

PCUE_BRANCH_ADDRESS

Fullword. Use this field to supply an alternative entry address. Set the top bit to specify that the alternative program is to run AMODE (31).

PCUE_REAL_ENTRY

From z/OS® 1.7 onwards, this field provides the real entry point for Language Environment® conforming programs. Previously, only PCUE_ENTRY_POINT was available to you, but for Language Environment conforming programs, this field did not contain the entry point that you needed to know about.

Note: With z/OS 1.7, this field provides a solution to the problem raised by APAR PQ43992.

PCUE_CHANNEL_NAME

Address of a 16-byte field that contains the name of the channel with which the application program is to be invoked (that is, the current channel of the program). If there is no channel, this field is set to blanks.

Return codes

UERCNORM: Continue processing.
UERCPURG: Task purged during XPI call.
UERCMEA: Entry address has been modified.

XPI calls

All can be used.