Exit XFCSREQ
This exit is invoked before a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE is attempted.
- When invoked
- Before a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE is
attempted. Note: For function shipped requests, the exit is invoked on the system where the file is local.
- Exit-specific parameters
-
- UEPFSREQ
- Address of a 2-byte field that indicates the type of file request.
The first byte contains one of the following values:
- UEPFSOPN
- Open request
- UEPFSCLS
- Close request
- UEPFSENB
- Enable request
- UEPFSDIS
- Disable request
- UEPFSCAN
- Cancel close file request.
If the first byte indicates an open request (UEPFSOPN), the second byte shows the type of open:- UEPFSNOP
- Normal open
- UEPFSOFB
- Open for backout.
If the first byte indicates a close request (UEPFSCLS), the second byte shows the type of close:- UEPFSNC
- Normal close
- UEPFSCP
- Close pending
- UEPFSELM
- End of load mode close
- UEPFSIMM
- Immediate close
- UEPFSICP
- Immediate close pending
- UEPFSQU
- RLS quiesce close.
- UEPFILE
- Address of the 8-byte file name.
- UEPFINFO
- Address of a storage area containing information about the file.
The area can be mapped using the DSECT DFHUEFDS, which contains the
following fields:
- UEFLNAME
- The 8-character file name.
- UEDSNAME
- The 44-character dsname of the data set associated with the file, if this has been set before the file request was issued.
- UEFSERV
- One byte indicating the SERVREQ settings for this file. The possible
values are:
- UEFRDIM
- Read valid
- UEFUPDIM
- Update valid
- UEFADDIM
- Add valid
- UEFDELIM
- Delete valid
- UEFBRZIM
- Browse valid.
- UEFDSJL
- One byte indicating the automatic journaling options set for this
file. The possible values are:
- UEFJRO
- Journal read-only
- UEFJRU
- Journal read for update
- UEFJWU
- Journal write update
- UEFJWA
- Journal write add
- UEFJDSN
- Dsname has been journaled
- UEFJSYN
- Journal read synchronously
- UEFJASY
- Journal write asynchronously.
- UEFDSVJL
- One byte indicating a further automatic journaling option which
applies to VSAM files only. The value is:
- UEFJWAC
- Write add complete.
- UEFDSJID
- One byte containing the number of the journal to be used for automatic journaling, if any.
- UEFDSACC
- One byte indicating the access method of the file. The possible
values are:
- UEFVSAM
- VSAM file
- UEFBDAM
- BDAM file
- UEFCFDT
- Coupling facility data table
- UEFBCRV
- Set to nulls for this exit.
- UEFFRLOG
- Set to nulls for this exit.
- UEFFRCLG
- Set to blanks for this exit.
- UEFCDATE
- Set to nulls for this exit.
- UEFCTIME
- Set to nulls for this exit.
- UEFBCAS
- Set to nulls for this exit.
- UEFACBCP
- This field is set to nulls in this exit.
Note: Only the first seven fields of UEPFINFO are set for this exit. Of the remaining fields, URFFRCLG is set to blanks, and the others are set to nulls. - 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.
- Return codes
-
- UERCNORM
- Continue processing.
- UERCBYP
- Suppress the file request. You cannot use UERCBYP:
- To suppress a CLOSE request if the second byte of UEPFSREQ indicates
it is one of the following types of close:
- End of load-mode close (UEPFSELM)
- Immediate close (UEPFSIMM)
- Immediate close pending (UEPFSICP)
- To suppress an OPEN request if a file is being opened to carry out backout processing, because this would cause a backout failure. The second byte of UEPFSREQ is set to UEPFSOFB if the file is being opened for backout.
In the case of a valid suppression, CICS® issues message DFHFC0996:
- To suppress a CLOSE request if the second byte of UEPFSREQ indicates
it is one of the following types of close:
Open/Close/Enable/Disable/Cancel of close of file filename suppressed due to intervention of user exit- UERCPURG
- Task purged during XPI call.
- XPI calls
- All can be used.
- API and SPI calls
- All except EXEC CICS SHUTDOWN and EXEC CICS XCTL can be used.
Note:
- 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 XFCSREQ exit. Use of the recursion counter UEPRECUR is recommended.
- Exit programs that issue EXEC CICS commands must first address the EIB. See Using CICS services.
- 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 programs can invoke EXEC CICS SET commands against the file whose state change has led to the exit being invoked. However, dependent upon other concurrent activity within the CICS system, there is the potential for a deadlock to occur between tasks that are manipulating the state of the file by means of such SPI commands.