File control EXEC interface SPI exits XFCAREQ and XFCAREQC

The XFCAREQ exit allows you to intercept a file control system programming interface (SPI) request before any action has been taken on it by file control. The XFCAREQC exit allows you to intercept the response after a file control SPI request has completed.

Note:
For information about the XFCREQ and XFCREQC exits that are invoked for file control API requests, see File control EXEC interface API exits XFCREQ and XFCREQC.

The file control SPI requests intercepted are:

Using XFCAREQ, you can:

Using XFCAREQC, you can:

You can also:

If you make changes to file states (that is, if you open, close, enable, or disable a file) it is possible that exits in the file state change program (XFCSREQ and XFCSREQC) could modify situations set up by XFCAREQ. Therefore you must consider the order in which the exits are invoked. If all four exits are enabled, the order of invocation is as follows:

Exit XFCAREQ

When invoked
Before CICS® processes a file control SPI request.
Exit-specific parameters
UEPCLPS
Address of a copy of the SPI command parameter list. See The command-level parameter structure.
UEPFATOK
Address of a 4-byte area that can be used to pass information between XFCAREQ and XFCAREQC on a single file control SPI request.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code EIBRCODE. For details of EIB return codes, see 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 which can be used to pass information between successive file control requests within the same task (for example, between successive invocations of the XFCAREQC exit).
UEPRECUR
Address of a halfword recursion counter. The counter is set to zero when the exit is first invoked and is incremented for each recursive call.
Return codes
UERCBYP
Bypass this request.
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI commands
All can be used.
API and SPI commands
All can be used, except for:
Note:
Take care when using recursive commands. For example, you must avoid entering a loop when issuing a file control SPI request from the XFCAREQ exit. Use of the recursion counter UEPRECUR is recommended.

Exit XFCAREQC

When invoked
After a file control SPI request has completed, before return from the file control SPI EXEC interface program.
Exit specific parameters:
UEPCLPS
Address of a copy of the API command parameter list. See The command-level parameter structure.
UEPFATOK
Address of a 4-byte area that can be used to pass information between XFCAREQ and XFCAREQC on a single file control SPI request.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code EIBRCODE. For details of EIB return codes, see 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 which can be used to pass information between successive file control requests within the same task (for example, between successive invocations of the XFCAREQC exit).
UEPRECUR
Address of a halfword recursion counter. The counter is set to zero when the exit is first invoked and is incremented for each recursive call.
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI commands
All can be used.
API and SPI commands
All can be used, except for:

You can update the copies of EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list. If you update the values, file control copies the new values into the application program’s EXEC interface block (EIB) after the completion of XFCAREQC or if you specify a return code of UERCBYP in XFCAREQ.

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. CICS does not check the consistency of the values you set. If EIBRCODE is set to a non-zero value and EIBRESP is set to zero, CICS overrides EIBRESP with a non-zero value. To help you set values for EIBRCODE, EIBRESP, and EIBRESP2, the values used by file control for SPI requests are specified in DSECT DFHFAUED.

Note:
Take care when using recursive commands. For example, you must avoid entering a loop when issuing a file control SPI request from the XFCAREQ exit. Use of the recursion counter UEPRECUR is recommended.

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.

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.

Note:
The relationship between arguments, keywords, data types, and input/output types on the file control SPI commands is summarized in the following tables:

The UEPCLPS exit-specific parameter

The UEPCLPS exit-specific parameter is passed to both XFCAREQ and XFCAREQC. It is the address of the command-level parameter structure. The command-level parameter list contains 58 addresses, FCIS_ADDR0 through FCIS_ADDR57. These are described in DSECT DFHFAUED, which you should copy into your program by including the statement COPY DFHFAUED.

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

FCIS_ADDR0
is the address of an 13-byte area called the EID which is made up as follows:
FCIS_GROUP
Always X'4C', indicating that this is a file control SPI request.
FCIS_FUNCT
One byte that defines the type of request:
X'02'
INQUIRE FILE
X'04'
SET FILE.
FCIS_EIDOPT2
Not used by file control.
FCIS_EIDOPT3
Not used by file control.
FCIS_EIDOPT4
Not used by file control.
FCIS_BITS1
Existence bits which specify which arguments were specified. To obtain the argument associated with a keyword, you need to obtain 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 argument was not specified in the request and the address should not be used.
X'80'
Set if the request contains an argument for the FILE keyword. If set, FCIS_ADDR1 is meaningful.
X'40'
Set if the request contains an argument for the DSNAME keyword. If set, FCIS_ADDR2 is meaningful.
X'20'
Set if the request contains an argument for the FWDRECSTATUS keyword. If set, FCIS_ADDR3 is meaningful.
X'10'
Set if the request contains an argument for the STRINGS keyword. If set, FCIS_ADDR4 is meaningful.
X'08'
Set if the request contains an argument for the BASEDSNAME keyword. If set, FCIS_ADDR5 is meaningful.
X'04'
Set if the request contains an argument for the LSRPOOLID keyword. If set, FCIS_ADDR6 is meaningful.
X'02'
Set if the request contains an argument for the READ keyword. If set, FCIS_ADDR7 is meaningful.
X'01'
Set if the request contains an argument for the UPDATE keyword. If set, FCIS_ADDR8 is meaningful.
FCIS_BITS2
Existence bits which specify which arguments were specified. The comments below FCIS_BITS1 also apply to FCIS_BITS2.
X'80'
Set if the request contains an argument for the BROWSE keyword. If set, FCIS_ADDR9 is meaningful.
X'40'
Set if the request contains an argument for the ADD keyword. If set, FCIS_ADDR10 is meaningful.
X'20'
Set if the request contains an argument for the DELETE keyword. If set, FCIS_ADDR11 is meaningful.
X'10'
Set if the request contains an argument for the DISPOSITION keyword. If set, FCIS_ADDR12 is meaningful.
X'08'
Set if the request contains an argument for the EMPTYSTATUS keyword. If set, FCIS_ADDR13 is meaningful.
X'04'
Set if the request contains an argument for the OPENSTATUS keyword. If set, FCIS_ADDR14 is meaningful.
X'02'
Set if the request contains an argument for the ENABLESTATUS keyword. If set, FCIS_ADDR15 is meaningful.
X'01'
Set if the request contains an argument for the RECOVSTATUS keyword. If set, FCIS_ADDR16 is meaningful.
FCIS_BITS3
Existence bits which specify which arguments were specified. The comments below FCIS_BITS1 also apply to FCIS_BITS3.
X'80'
Set if the request contains an argument for the ACCESSMETHOD keyword. If set, FCIS_ADDR17 is meaningful.
X'40'
Set if the request contains an argument for the TYPE keyword. If set, FCIS_ADDR18 is meaningful.
X'20'
Set if the request contains an argument for the OBJECT keyword. If set, FCIS_ADDR19 is meaningful.
X'10'
Set if the request contains an argument for the REMOTESYSTEM keyword. If set, FCIS_ADDR20 is meaningful.
X'08'
Set if the request contains an argument for the REMOTENAME keyword. If set, FCIS_ADDR21 is meaningful.
X'04'
Set if the request contains an argument for the RECORDFORMAT keyword. If set, FCIS_ADDR22 is meaningful.
X'02'
Set if the request contains an argument for the BLOCKFORMAT keyword. If set, FCIS_ADDR23 is meaningful.
X'01'
Set if the request contains an argument for the KEYLENGTH keyword. If set, FCIS_ADDR24 is meaningful.
FCIS_BITS4
Existence bits which specify which arguments were specified. The comments below FCIS_BITS1 also apply to FCIS_BITS4.
X'80'
Set if the request contains an argument for the KEYPOSITION keyword. If set, FCIS_ADDR25 is meaningful.
X'40'
Set if the request contains an argument for the RECORDSIZE keyword. If set, FCIS_ADDR26 is meaningful.
X'20'
Set if the request contains an argument for the RELTYPE keyword. If set, FCIS_ADDR27 is meaningful.
X'10'
Set if the request contains an argument for the EXCLUSIVE keyword. If set, FCIS_ADDR28 is meaningful.
X'08'
Set if the request contains an argument for the BLOCKKEYLEN keyword. If set, FCIS_ADDR29 is meaningful.
X'04'
Set if the request contains an argument for the BLOCKSIZE keyword. If set, FCIS_ADDR30 is meaningful.
X'02'
Not used by file control.
X'01'
Not used by file control.
FCIS_BITS5
Existence bits which specify which arguments were specified. The comments below FCIS_BITS1 also apply to FCIS_BITS5.
X'80'
Set if the request contains an argument for the TABLE keyword. If set, FCIS_ADDR33 is meaningful.
X'40'
Set if the request contains an argument for the MAXNUMRECS keyword. If set, FCIS_ADDR34 is meaningful.
X'20'
Set if the request contains an argument for the READINTEG keyword. If set, FCIS_ADDR35 is meaningful.
X'10'
Set if the request contains an argument for the RLSACCESS keyword. If set, FCIS_ADDR36 is meaningful.
X'08'
Not used by file control.
X'04'
Not used by file control.
X'02'
Not used by file control.
X'01'
Not used by file control.
FCIS_BITS6
Specifies whether certain keywords were specified on the File control SPI command.
X'80'
Set if the request contains the START keyword.
X'40'
Set if the request contains the NEXT keyword.
X'20'
Set if the request contains the END keyword.
X'10'
Set if the request contains the WAIT keyword.
X'08'
Set if the request contains the NOWAIT keyword.
X'04'
Set if the request contains the FORCE keyword.
X'02'
Set if the request contains the ENABLED keyword.
X'01'
Set if the request contains the DISABLED keyword.
FCIS_BITS7
Specifies whether certain keywords were specified on the File control SPI command. Also contains the existence bit for JOURNALNUM.
X'80'
Set if the request contains the OPEN keyword.
X'40'
Set if the request contains the CLOSED keyword.
X'20'
Set if the request contains the EMPTY keyword.
X'10'
Set if the request contains an argument for the JOURNALNUM keyword. If set, FCIS_ADDR52 is meaningful.
X'08'
Set if the request contains the LOADTYPE keyword.
X'04'
Set if the request contains the POOL keyword.
X'02'
Set if the request contains the TABLENAME keyword.
X'01'
Set if the request contains the UPDATEMODEL keyword.
FCIS_BITS8
X'80'
Set if the request contains the REMOTETABLE keyword.
X'40'
Not used by file control.
X'20'
Not used by file control.
X'10'
Not used by file control.
X'08'
Not used by file control.
X'04'
Not used by file control.
X'02'
Not used by file control.
X'01'
Not used by file control.
FCIS_ADDR1
is the address of an 8-byte area containing the name from FILE.
FCIS_ADDR2
is the address of a 44-byte area containing the name from DSNAME.
FCIS_ADDR3
is the address of a 4-byte area containing the CVDA from FWDRECOVSTATUS.
FCIS_ADDR4
is the address of a 4-byte area containing the data from STRINGS.
FCIS_ADDR5
is the address of a 44-byte area containing the name from BASEDSNAME.
FCIS_ADDR6
is the address of a 4-byte area containing the data from LSRPOOLID.
FCIS_ADDR7
is the address of a 4-byte area containing the CVDA from READ.
FCIS_ADDR8
is the address of a 4-byte area containing the CVDA from UPDATE.
FCIS_ADDR9
is the address of a 4-byte area containing the CVDA from BROWSE.
FCIS_ADDR10
is the address of a 4-byte area containing the CVDA from ADD.
FCIS_ADDR11
is the address of a 4-byte area containing the CVDA from DELETE.
FCIS_ADDR12
is the address of a 4-byte area containing the CVDA from DISPOSITION.
FCIS_ADDR13
is the address of a 4-byte area containing the CVDA from EMPTYSTATUS.
FCIS_ADDR14
is the address of a 4-byte area containing the CVDA from OPENSTATUS.
FCIS_ADDR15
is the address of a 4-byte area containing the CVDA from ENABLESTATUS.
FCIS_ADDR16
is the address of a 4-byte area containing the CVDA from RECOVSTATUS.
FCIS_ADDR17
is the address of a 4-byte area containing the CVDA from ACCESSMETHOD.
FCIS_ADDR18
is the address of a 4-byte area containing the CVDA from TYPE.
FCIS_ADDR19
is the address of a 4-byte area containing the CVDA from OBJECT.
FCIS_ADDR20
is the address of a 4-byte area containing the name from REMOTESYSTEM.
FCIS_ADDR21
is the address of an 8-byte area containing the name from REMOTENAME.
FCIS_ADDR22
is the address of a 4-byte area containing the CVDA from RECORDFORMAT.
FCIS_ADDR23
is the address of a 4-byte area containing the CVDA from BLOCKFORMAT.
FCIS_ADDR24
is the address of a 4-byte area containing the CVDA from KEYLENGTH.
FCIS_ADDR25
is the address of a 4-byte area containing the data from KEYPOSITION.
FCIS_ADDR26
is the address of a 4-byte area containing the data from RECORDSIZE.
FCIS_ADDR27
is the address of a 4-byte area containing the CVDA from RELTYPE.
FCIS_ADDR28
is the address of a 4-byte area containing the CVDA from EXCLUSIVE.
FCIS_ADDR29
is the address of a 4-byte area containing the data from BLOCKKEYLEN.
FCIS_ADDR30
is the address of a 4-byte area containing the data from BLOCKSIZE.
FCIS_ADDR31
is not used by file control.
FCIS_ADDR32
is the address of a 4-byte area containing the data from BUSY.
FCIS_ADDR33
is the address of a 4-byte area containing the CVDA from TABLE.
FCIS_ADDR34
is the address of a 4-byte area containing the data from MAXNUMRECS.
FCIS_ADDR35
is the address of a 4-byte area containing the CVDA from READINTEG.
FCIS_ADDR36
is the address of a 4-byte area containing the CVDA from RLSACCESS.
FCIS_ADDR37 to FCIS_ADDR51
are not used by file control.
FCIS_ADDR52
is the address of a 4-byte area containing the data from JOURNALNUM.
FCIS_ADDR53
is the address of a 4-byte area containing the data from LOADTYPE.
FCIS_ADDR54
is the address of a 4-byte area containing the data from CFDTPOOL.
FCIS_ADDR55
is the address of a 4-byte area containing the data from TABLENAME.
FCIS_ADDR56
is the address of a 4-byte area containing the data from UPDATEMODEL.
FCIS_ADDR57
is the address of a 4-byte area containing the data from REMOTETABLE.

Modifying fields in the command-level parameter structure

Some fields that are passed to file control SPI requests are used as input to the request and some are used as output to the request. The method that your user exit program uses to modify a field depends on the usage of the field. As a general rule:

For a full description of the parameters to INQUIRE FILE, see Table 5. For a full description of the parameters to SET FILE, see Table 6.

Table 5. INQUIRE FILE requests The relationship between arguments, keywords, data types, and input/output types.
Argument Keyword Data Type Input/Output
Arg1 FILE CHAR(8) See note.
Arg2 DSNAME CHAR(44) Output
Arg3 FWDRECSTATUS BIN(31) Output
Arg4 STRINGS BIN(31) Output
Arg5 BASEDSNAME CHAR(44) Output
Arg6 LSRPOOLID BIN(31) Output
Arg7 READ BIN(31) Output
Arg8 UPDATE BIN(31) Output
Arg9 BROWSE BIN(31) Output
Arg10 ADD BIN(31) Output
Arg11 DELETE BIN(31) Output
Arg12 DISPOSITION BIN(31) Output
Arg13 EMPTYSTATUS BIN(31) Output
Arg14 OPENSTATUS BIN(31) Output
Arg15 ENABLESTATUS BIN(31) Output
Arg16 RECOVSTATUS BIN(31) Output
Arg17 ACCESSMETHOD BIN(31) Output
Arg18 TYPE BIN(31) Output
Arg19 OBJECT BIN(31) Output
Arg20 REMOTESYSTEM CHAR(4) Output
Arg21 REMOTENAME CHAR(8) Output
Arg22 RECORDFORMAT BIN(31) Output
Arg23 BLOCKFORMAT BIN(31) Output
Arg24 KEYLENGTH BIN(31) Output
Arg25 KEYPOSITION BIN(31) Output
Arg26 RECORDSIZE BIN(31) Output
Arg27 RELTYPE BIN(31) Output
Arg28 EXCLUSIVE BIN(31) Output
Arg29 BLOCKKEYLEN BIN(31) Output
Arg30 BLOCKSIZE BIN(31) Output
Arg31 * * *
Arg32 BUSY BIN(31) Output
Arg33 TABLE BIN(31) Output
Arg34 MAXNUMRECS BIN(31) Output
Arg35 READINTEG BIN(31) Output
Arg36 RLSACCESS BIN(31) Output
Arg37 to Arg51 * * *
Arg52 JOURNALNUM BIN(15) Output
Arg53 LOADTYPE BIN(31) Output
Arg54 CEDTPOOL CHAR(8) Output
Arg55 TABLENAME CHAR(8) Output
Arg56 UPDATEMODEL BIN(31) Output
Arg57 REMOTETABLE BIN(31) Output
Note:
The file parameter on INQUIRE FILE commands is:
Table 6. SET FILE requests The relationship between arguments, keywords, data types, and input/output types.
Argument Keyword Data Type Input/Output
Arg1 FILE CHAR(8) Input
Arg2 DSNAME CHAR(44) Input
Arg3 FWDRECSTATUS BIN(31) Input
Arg4 STRINGS BIN(31) Input
Arg5 * * *
Arg6 LSRPOOLID BIN(31) Input
Arg7 READ BIN(31) Input
Arg8 UPDATE BIN(31) Input
Arg9 BROWSE BIN(31) Input
Arg10 ADD BIN(31) Input
Arg11 DELETE BIN(31) Input
Arg12 DISPOSITION BIN(31) Input
Arg13 EMPTYSTATUS BIN(31) Input
Arg14 OPENSTATUS BIN(31) Input
Arg15 ENABLESTATUS BIN(31) Input
Arg16 RECOVSTATUS BIN(31) Input
Arg17 * * *
Arg18 * * *
Arg19 * * *
Arg20 * * *
Arg21 * * *
Arg22 * * *
Arg23 * * *
Arg24 * * *
Arg25 * * *
Arg26 * * *
Arg27 * * *
Arg28 EXCLUSIVE BIN(31) Input
Arg29 * * *
Arg30 * * *
Arg31 * * *
Arg32 * * *
Arg33 TABLE BIN(31) Input
Arg34 MAXNUMRECS BIN(31) Input
Arg35 READINTEG BIN(31) Input
Arg36 RLSACCESS BIN(31) Input

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 the EID

It is not possible to modify the EID to make major changes to requests. It is not possible, for example, to change an INQUIRE FILE request to a SET FILE request. However, you can make minor changes to requests, such as to turn on the existence bit for a variable that had not been specified on the current request. The following paragraph lists the bits in the EID that can be modified. Any attempt to modify any other part of the EID is ignored.

Your exit program can modify any bit in FCIS_BITS1, FCIS_BITS2, FCIS_BITS3, FCIS_BITS4, FCIS_BITS5, FCIS_BITS6 and FCIS_BITS7, except for:

Your program can provide its own command-level parameter structure and EID, in which case you should modify UEPCLPS and TS_ADDR0 respectively to point to the new structures.

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

Note:
If you modify the EID, you must be careful not to create inconsistent parameters. For example, if the original request specified SET FILE OPEN and your exit turned on the EID bit for CLOSED, the resulting SET FILE request would specify both OPEN and CLOSED. In this case, the results of the command would be unpredictable.

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, UEPFATOK 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 XFCAREQ exit, UEPTSTOK provides a means of doing this.

Modifying user arguments

User exit programs can modify user arguments as follows:

Adding user arguments

Your exit program can add user arguments, provided that it is allowed to modify the corresponding existence bit in the EID. Assuming that the argument to be added does not already exist, your exit program must:

  1. Obtain storage for the argument to be added
  2. Initialize the storage to the required value
  3. Select and set up the appropriate pointer from the parameter list
  4. Select and set up the appropriate existence bit in Arg0
  5. If necessary, modify the parameter list to reflect the new end-of-list indicator.

Removing user arguments

Your exit program can remove user arguments, provided that it is allowed to modify the corresponding existence bit in the EID. Assuming that the argument to be removed exists, your exit program must:

  1. Switch the corresponding argument existence bit in Arg0 to zero
  2. Modify the parameter list to reflect the new end-of-list indicator.

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 ]]