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.
The file control SPI requests intercepted are:
- EXEC CICS INQUIRE FILE
- EXEC CICS SET FILE.
Using XFCAREQ, you can:
- Analyze the SPI parameter list (function, keywords, argument values, and
responses)
- Modify any input parameter prior to execution of the request
- Prevent execution of a request and set appropriate responses.
Using XFCAREQC, you can:
- Analyze the SPI parameter list
- Modify any output parameter value and set responses after execution.
You can also:
- Pass data between your XFCAREQ and XFCAREQC exit programs when they are
invoked for the same request.
- Pass data between your file control exit programs when they are invoked
within the same task. You can pass data between successive invocations of
XFCAREQ and XFCAREQC and also between invocations of other EXEC-enabled user
exits.
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:
- For the SET FILE command:
- XFCAREQ
- XFCSREQ
- XFCSREQC
- XFCAREQC
- For the INQUIRE FILE command, only the XFCAREQ and XFCAREQC exits are
invoked:
- XFCAREQ
- XFCAREQC
- 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:
- EXEC CICS SHUTDOWN
- EXEC CICS XCTL
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.
- 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:
- EXEC CICS SHUTDOWN
- EXEC CICS XCTL
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 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
- FCIS_FUNCT
- FCIS_EIDOPT2
- FCIS_EIDOPT3
- FCIS_EIDOPT4
- FCIS_BITS1
- FCIS_BITS2
- FCIS_BITS3
- FCIS_BITS4
- FCIS_BITS5
- FCIS_BITS6
- FCIS_BITS7
- FCIS_BITS8
- 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.
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:
- On INQUIRE FILE requests, all fields except FILE are output fields.
- On SET FILE requests, all fields are input fields.
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:
- An input field if the request does not specify START, NEXT, or END
- An output field if the request specifies NEXT
- Omitted if the request specifies START or END.
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.
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:
- The existence bit for the FILE keyword.
- The bits for the START, NEXT, and END keywords.
- Any bits described as "not used by file control".
- Any bit corresponding to a keyword that is not applicable to the command
being executed. For example, the bit for the CLOSED keyword can be modified
on a SET FILE request but not on an INQUIRE FILE request, because CLOSED has
meaning only for a SET FILE request. See the descriptions in Table 5 and Table 6.
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.
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.
User exit programs can modify user arguments as follows:
- For input arguments, your exit program should obtain sufficient storage
to hold the modified argument, set up the required value, and set the associated
pointer in the parameter list to the address of the newly acquired area.
- For output and input/output arguments, your exit program can update the
argument in place, because the area of storage is represented in the application
by a variable that is expected to receive a value from CICS.
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:
- Obtain storage for the argument to be added
- Initialize the storage to the required value
- Select and set up the appropriate pointer from the parameter list
- Select and set up the appropriate existence bit in Arg0
- 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:
- Switch the corresponding argument existence bit in Arg0 to zero
- Modify the parameter list to reflect the new end-of-list indicator.
[[ Contents Previous Page | Next Page Index ]]