File control EXEC interface API exits XFCREQ and XFCREQC

The XFCREQ exit allows you to intercept a file control application programming interface (API) request before any action has been taken on it by file control. The XFCREQC exit allows you to intercept a file control API request after file control has completed its processing.

Note:
For information about the XFCAREQ and XFCAREQC exits that are invoked for file control SPI requests, see File control EXEC interface SPI exits XFCAREQ and XFCAREQC.
Important

The XFCREQ and XFCREQC exits are not invoked, on the target region, for function-shipped requests. That is, if a file control API request is function-shipped to a remote region, the exits are not invoked on the remote region. To intercept a function-shipped file control API request on the target region, use the XFCFRIN exit--see File control domain exits, XFCFRIN and XFCFROUT.

The file control API commands intercepted are:

The XFCREQ and XFCREQC exits can be written only in assembler language.

Using XFCREQ, you can:

Using XFCREQC, you can:

Both exits are passed nine parameters as follows:

The command-level parameter structure

The command-level parameter structure consists of a series of addresses. The first address points to the EXEC interface descriptor (EID), which consists of a bit string that describes the type of request and identifies each keyword specified with the request. The remaining addresses point to pieces of data associated with the request. (For example, the second address always points to the file name.)

Only the first 8 addresses and the last address can be referenced by the user exit. The ninth through eleventh addresses are reserved for CICS internal use.

You can examine the EID to determine the type of request and the keywords specified. You can examine the other parameters in the list to determine the values of the keywords. You can also modify values of keywords specified on the request. (For example, you could change the name of the file involved in the request.)

End of parameter list indicator

The high-order bit is set on in the last address set in the parameter list to indicate that it is the last one in the list. On return from your user exit program, CICS scans the parameter list for the high-order bit to find the last parameter. Therefore, if you modify the length of the parameter list, you must also reset the high-order bit to indicate which is the new last address.

The original parameter list, as it was before XFCREQ was invoked, is restored after the completion of XFCREQC. It follows that the execution diagnostic facility (EDF) displays the original command before and after execution. EDF does not display any changes made by the exit.

The UEPCLPS exit-specific parameter

The UEPCLPS exit-specific parameter is included in both exit XFCREQ and exit XFCREQC. It is the address of the command-level parameter structure. The command-level parameter structure contains 12 addresses, FC_ADDR0 through FC_ADDRB. It is defined in the DSECT FC_ADDR_LIST, which you should copy into your exit program by including the statement COPY DFHFCEDS.

The command-level parameter list is made up as follows:

FC_ADDR0
is the address of a 9-byte area called the EID, which is made up as follows:

The name of the DSECT mapping the EID is FC_EID.

FC_GROUP
Always X'06', indicating that this is a file control request.
FC_FUNCT
One byte that defines the type of request:
X'02'
READ
X'04'
WRITE
X'06'
REWRITE
X'08'
DELETE
X'0A'
UNLOCK
X'0C'
STARTBR
X'0E'
READNEXT
X'10'
READPREV
X'12'
ENDBR
X'14'
RESETBR
FC_BITS1
Existence bits that define which keywords that contain values were specified. To obtain the value associated with a keyword, you need to use the appropriate address from the command-level parameter structure. Before using this address, you must check the associated existence bit. If the existence bit is set off, the keyword was not specified in the request and the address should not be used.
X'80'
Set if the request contains the keyword FILE. If set, FC_ADDR1 is meaningful.
X'40'
Set if the request contains any of the keywords INTO, SET, or FROM. If set, FC_ADDR2 is meaningful.
X'20'
Set if the request specifies LENGTH or NUMREC, or if a STARTBR, RESETBR, or ENDBR request specifies REQID. If set, FC_ADDR3 is meaningful.
X'10'
Set if the request specifies RIDFLD. If set, FC_ADDR4 is meaningful.
X'08'
Set if the request specifies KEYLENGTH. If set, FC_ADDR5 is meaningful.
X'04'
Set if the request is READNEXT or READPREV and specifies REQID. If set, FC_ADDR6 is meaningful.
X'02'
Set if the request specifies SYSID. If set, FC_ADDR7 is meaningful.
X'01'
Not used by file control.
FC_BITS2
Second set of existence bits.
X'20'
Set if the request specifies TOKEN. If set, FC_ADDRB is meaningful.
FC_EIDOPT5
Indicates whether certain keywords that do not take values were specified on the request.
X'04'
MASSINSERT specified.
X'02'
RRN specified.
X'01'
SET (and not INTO) was specified.
Note:
Your program must test for keywords at the bit level, because there may be more than one of these keywords present.
FC_EIDOPT6
Indicates whether certain keywords that do not take values were specified on the request.
X'80'
RBA specified.
X'40'
GENERIC specified.
X'20'
GTEQ specified.
X'10'
UNCOMMITTED specified.
X'08'
CONSISTENT specified.
X'04'
REPEATABLE specified.
X'01'
NOSUSPEND specified (on READ, READNEXT, READPREV, WRITE, DELETE, or REWRITE).
Notes:
  1. If the read integrity bits (for UNCOMMITTED, CONSISTENT, and REPEATABLE) are off (zero) on the command, the read integrity options specified on the file resource definition are used. If you need to know what these are, you can issue an EXEC CICS INQUIRE FILE command.
  2. Your program must test for keywords at the bit level, because there may be more than one of these keywords present.
FC_EIDOPT7
Indicates whether certain keywords that do not take values were specified on the request.
X'04'
UPDATE specified. This setting is meaningful only for READ requests. For other requests, X'04' may or may not be set.
X'01'
Either DEBREC or DEBKEY specified (see FC_EIDOPT8). This setting is meaningful only for READ requests. For other requests, X'01' may or may not be set.
Note:
Your program must test for keywords at the bit level, because there may be more than one of these keywords present.
FC_EIDOPT8
Indicates whether certain keywords that do not take values were specified on the request.
X'80'
DEBKEY specified.
X'40'
DEBREC specified.
X'20'
TOKEN specified.
FC_ADDR1
is the address of an 8-byte area containing the name specified on the FILE keyword.
FC_ADDR2
is the address of one of the following:
FC_ADDR3
is the address of one of the following:
FC_ADDR4
is the address of an area containing the value of the RIDFLD keyword.
FC_ADDR5
is the address of the halfword value of KEYLENGTH.
FC_ADDR6
is the address of the halfword value of REQID (if the request is READNEXT or READPREV).
FC_ADDR7
is the address of an area containing the value of SYSID.
FC_ADDR8
is the address of a value intended for CICS internal use only. It must not be used.
FC_ADDR9
is the address of a value intended for CICS internal use only. It must not be used.
FC_ADDRA
is the address of a value intended for CICS internal use only. It must not be used.
FC_ADDRB
is the address of the fullword value of TOKEN (if the request is READ, READNEXT, READPREV, REWRITE, DELETE, or UNLOCK).

Modifying fields in the command-level parameter structure

Some fields that are passed to file control are used as input to the request, some are used as output fields, and some are used for both input and output. The method your user exit program uses to modify a field depends on the usage of the field.

A list of input and output fields

The following are always input fields:

The following are always output fields:

Whether LENGTH and RIDFLD are input or output fields depends on the request, as shown in Table 4. A dash (--) means that the keyword cannot be specified on the request.

Table 4. LENGTH and RIDFLD as input and output fields
Request LENGTH RIDFLD
READ Output See Note 1.
WRITE Input See Note 2.
REWRITE Input --
DELETE -- See Note 3.
UNLOCK -- --
STARTBR -- Input
READNEXT Output Output
READPREV Output Output
ENDBR -- --
RESETBR -- Input
Notes:
  1. Normally, this is an input field. However, if UPDATE is specified and the file is a BDAM file using extended key search, RIDFLD is used for both input and output.
  2. The use of RIDFLD on a WRITE request depends on the file type. For a VSAM KSDS or RRDS, or a fixed-format BDAM file, RIDFLD is an input field. For all other file types, it is used either for output only, or for both input and output, and should be treated like an output field.
  3. RIDFLD is an input field on DELETE requests that are not preceded by a READ UPDATE. It is not specified on requests that are preceded by a READ UPDATE.

Modifying input fields

The correct method of modifying an input field is to create a new copy of it, and to change the address in the command-level parameter list to point to your new data.

Note:
You must never modify an input field by altering the data that is pointed to by the command-level parameter list. To do so would corrupt storage belonging to the application program and would cause a failure when the program attempted to reuse the field.

Modifying output fields

The technique described in Modifying input fields is not suitable for modifying output fields. (The results would be returned to the new area instead of the application’s area, and would be invisible to the application.)

An output field is modified by altering the data that is pointed to by the command-level parameter list. In the case of an output field, you can modify the application’s data in place, because the application is expecting the field to be modified anyway.

Modifying fields used for both input and output

An example of a field that is used for both input and output is LENGTH on a READ request that specifies INTO. You can treat such fields in the same way as output fields, and they are considered to be the same.

Modifying the EID

It is not possible to modify the EID to make major changes to requests. It is not possible, for example, to change a WRITE request to a READ request.

However, you can make minor changes to requests, such as to turn on the existence bit for SYSID so that the request can be changed into one that is shipped to a remote system.

The list that follows shows the bits in the EID that can be modified. Any attempt to modify any other part of the EID is ignored.

FC_BITS1
X'20'
The existence bit for LENGTH, NUMREC, or (if the request is STARTBR, RESETBR, or ENDBR) REQID.
X'08'
The existence bit for KEYLENGTH.
X'04'
The existence bit for REQID if the request is READNEXT or READPREV.
X'02'
The existence bit for SYSID.
FC_BITS2
X'20'
Token specified.
FC_EIDOPT5
X'04'
MASSINSERT specified.
FC_EIDOPT6
X'40'
GENERIC specified.
X'20'
GTEQ specified.
X'10'
UNCOMMITTED specified.
X'08'
CONSISTENT specified.
X'04'
REPEATABLE specified.
X'02'
UPDATE specified on READNEXT or READPREV.
X'01'
NOSUSPEND specified (on READ, READNEXT, READPREV, WRITE, DELETE, or REWRITE).

Bits in the EID should be modified in place. You should not modify the pointer to the EID: any attempt to do so is ignored by CICS.

The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the file control request only.

If more than one of UNCOMMITTED, CONSISTENT, or REPEATABLE is specified, CONSISTENT takes precedence over UNCOMMITTED, and REPEATABLE takes precedence over CONSISTENT and UNCOMMITTED.

Example of modifying read integrity bits

You might want all RLS read requests from all programs against a specific file to specify CONSISTENT read. You could code a user exit program that turns on the bit for CONSISTENT and turns off the other two read integrity bits in all requests to the file. You could partially achieve this effect by specifying CONSISTENT on the FILE definition. However, that would only override requests that did not explicitly specify a level of read integrity. Using a global user exit program for this purpose also overrides programs that explicitly specify UNCOMMITTED or REPEATABLE.

Warnings:
  1. If a global user exit program changes a file request to request a higher level of read integrity (for example, it changes the request from UNCOMMITTED to REPEATABLE), this could cause CICS either to acquire extra read locks, or to keep its read locks for a longer period of time. This may degrade system throughput, by causing other transactions to wait, or introduce deadlocks.
  2. If a global user exit program changes the request to one that requests a lower level of read integrity (for example, it changes the request from REPEATABLE to UNCOMMITTED), this could cause application logic errors to occur in the program that originated the request. The errors could occur because the application program may be relying on the record to remain unchanged while it reads a series of other, related, records. This can be guaranteed with REPEATABLE, but not if the option is changed to UNCOMMITTED.
  3. Your user exit program is prevented from making major changes to the EID. However, you must take great care when making the minor modifications that are permitted. For instance, it is possible to change a DELETE into a GENERIC DELETE, but to make such a change may be dangerous.

Use of the task token UEPTSTOK

UEPTSTOK provides the address of a 4-byte area that you can use to pass information between successive file control requests in the same task. (By contrast, UEPFCTOK is usable only for the duration of a single file control request, because its contents may be destroyed at the end of the request.) For example, if you need to pass information between successive invocations of the XFCREQ exit, UEPTSTOK provides a means of doing this.

Use of the parameter UEPFSHIP

UEPFSHIP contains the address of a 16-byte area. This area consists of 4 characters, followed by 3 fullwords. If the first byte contains 'Y', this request has been function shipped to this region. In this case, if your exit program wants to bypass file control (by setting a return code of UERCBYP), it must set the 3 fullwords as follows:

Fullword 1
The length of the buffer area
Fullword 2
The length of the record
Fullword 3
The length of the modified RIDFLD.

Doing this ensures that the data and RIDFLD are correctly shipped back.

The EIB

Copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 are passed to the exit, so that you can:

You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list. File Control copies your values into the real EIB after the completion of XFCREQC; or if you specify a return code of ‘bypass’ in XFCREQ.

You must set valid file control responses. You must set all three of EIBRCODE, EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by File Control to describe a valid completion. File Control does not police the consistency of EIBRCODE, EIBRESP, and EIBRESP2. To aid you in setting the values of EIBRCODE, EIBRESP, and EIBRESP2, the values used by File Control are specified in DFHFCEDS.

Example of how XFCREQ and XFCREQC can be used

XFCREQ and XFCREQC can be used for a variety of purposes. One example of a possible use is given below.

In this example, XFCREQ and XFCREQC are used to obtain a record containing compressed data, to decompress the data, and to return it to the area specified by the user program as INTO. The example shows only the capabilities of the exits; it is not intended to indicate an ideal way of achieving the function.

In XFCREQ:
  1. Issue an EXEC CICS GETMAIN to obtain an area large enough to hold the decompressed data.
  2. Change the INTO pointer to point to this new area, so that File Control uses it when it processes the request. (The decompressed data is copied to the user’s INTO area, and the INTO pointer reset, before return to the application program--see stages 4 and 7 of the processing to be done by XFCREQC.)
  3. Set UEPFCTOK to be the address of the new area so that XFCREQC can also use this area.
  4. Return to CICS.
In XFCREQC:
  1. Check ‘UEPRCODE’ to make sure that the file control request completed without error.
  2. Use UEPFCTOK to find the address of the area. This area now holds the compressed data.
  3. Decompress the data in place.
  4. Copy the data from the new area to the user’s INTO area. Use the user-specified LENGTH (from the command-level parameter list) to ensure that the data fits and that the copy does not cause a storage violation.
  5. Set ‘LENGERR’ in UEPRESP, UEPRESP2, and UEPRCODE if the data does not fit.
  6. Use EXEC CICS FREEMAIN to free the work area pointed to by UEPFCTOK.
  7. At this point the command-level parameter list points to the now free area as the address for INTO. This is not a problem, because after completion of XFCREQC File Control restores this pointer to point to the area supplied by the user program.
  8. Return to CICS.

Exit XFCREQ

When invoked
Before CICS processes a file control API request.
Note:
The exit is not invoked, on the target region, for function-shipped requests.
Exit-specific parameters
UEPCLPS
Address of the command-level parameter structure. See The UEPCLPS exit-specific parameter.
UEPFCTOK
Address of the 4-byte token to be passed to XFCREQC. This allows you, for example, to pass a work area to exit XFCREQC.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’. For details of EIB return codes, refer to the CICS Application Programming Reference manual.
UEPRESP
Address of a 4-byte binary copy of the EIB response code ‘EIBRESP’.
UEPRESP2
Address of a 4-byte binary copy of the EIB response code ‘EIBRESP2’.
UEPTSTOK
Address of a 4-byte token that is valid throughout the life of a task. See Use of the task token UEPTSTOK.
UEPRECUR
Address of a halfword recursion counter. The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call.
UEPFSHIP
Address of a 16 byte area. See Use of the parameter UEPFSHIP.
UEPRSRCE
Address of an 8-character copy of the EIB resource value, EIBRSRCE.
Return codes
UERCNORM
Continue processing.
UERCBYP
The file control EXEC interface program should ignore this request.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead.

API and SPI calls
All can be used, except for:
Notes:
  1. Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when a file control request is issued from the XFCREQ exit. Use of the recursion counter UEPRECUR is recommended.
  2. Exit programs that issue EXEC CICS commands must first address the EIB. See Using CICS services.
  3. Exit programs that issue EXEC CICS commands, and that use the DFHEIENT macro, should use the DFHEIRET macro to set a return code and return to CICS. See Returning values to CICS.

Exit XFCREQC

When invoked
After a file control API request has completed, and before return from the file control EXEC interface program.
Note:
The exit is not invoked, on the target region, for function-shipped requests.
Exit-specific parameters
UEPCLPS
Address of the command-level parameter structure. See The UEPCLPS exit-specific parameter.
UEPFCTOK
Address of the 4 byte token passed from XFCREQ.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’. For details of EIB return codes, refer to the CICS Application Programming Reference manual.
UEPRESP
Address of a 4-byte binary copy of the EIB response code ‘EIBRESP’.
Note:
If the file that has just been accessed is remote, the addressed field contains zeros (even if UEPRCODE is non-zero).
UEPRESP2
Address of a 4-byte binary copy of the EIB response code ‘EIBRESP2’.
Note:
If the file that has just been accessed is remote, the addressed field contains zeros (even if UEPRCODE is non-zero).
UEPTSTOK
Address of a 4-byte token that is valid throughout the life of a task. See Use of the task token UEPTSTOK.
UEPRECUR
Address of a halfword recursion counter. The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call.
UEPRSRCE
Address of an 8-character copy of the EIB resource value, EIBRSRCE.
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead.

API and SPI calls
All can be used, except for:

Notes:
  1. Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when a file control request is issued from the XFCREQC exit. Use of the recursion counter UEPRECUR is recommended.
  2. Exit programs that issue EXEC CICS commands must first address the EIB. See Using CICS services.
  3. Exit programs that issue EXEC CICS commands, and that use the DFHEIENT macro, should use the DFHEIRET macro to set a return code and return to CICS. See Returning values to CICS.

Example program

CICS supplies, in CICSTS31.CICS.SDFHSAMP, an example program, DFH$XTSE, that shows how to modify fields in the command-level parameter structure passed to EXEC interface exits. DFH$XTSE is listed in topic Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE.

Related concepts
Overview -- what is a global user exit?
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Writing global user exit programs
Making an XPI call
Related reference
List of global user exit points
The XPI functions
[[ Contents Previous Page | Next Page Index ]]