File control file state program exits XFCSREQ and XFCSREQC

Two user exits are provided in the file control state program. You can use XFCSREQ, which is invoked before a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE request is acted on, to gather information about the state of the file--for example, which file requests (SERVREQs) are valid, which journaling options are set. Based on this information, you can suppress the request, if appropriate. (See return code UERCBYP.)

You can use XFCSREQC, which is invoked after the file request has been acted on, to gather information about the data set associated with the file--for example, which recovery options are set. Note that XFCSREQC is invoked even if you have used XFCSREQ to suppress the file request.

For ENABLE, DISABLE, OPEN, and CANCEL CLOSE requests, each exit is invoked only once. However, for CLOSE requests, because a file can be quiesced before actual closure, the exits might be invoked more than once, as described below.

For a single CLOSE request, XFCSREQ and XFCSREQC are invoked more than once if closure is attempted while the file is being accessed by other tasks. For example, the result of a CLOSE NOWAIT command in these circumstances is that XFCSREQ is invoked before the closure is attempted. Because there are still users of the file, the closure is delayed. However, because it specified NOWAIT, the CLOSE request completes, and invokes XFCSREQC with UEPFSRSP set to ‘UEFSPEND’, meaning closure is pending. When all activity against the file is complete, the file is closed, and XFCSREQ and XFCSREQC are invoked under the task that actually closed it.

For a CLOSE WAIT command, the exits are invoked as follows. XFCSREQ is invoked, the task requests a closure of the file and waits for the closure to happen. When all activity against the file is complete, the file is closed, and XFCSREQ and XFCSREQC are invoked under the task that closed it. Finally, because the closure has now been completed, the task that issued the CLOSE WAIT is resumed, completes its CLOSE request, and invokes XFCSREQC.

A CANCEL CLOSE request is issued by CICS® in response to an UNQUIESCE command that cancels a pending QUIESCE command. A QUIESCE data set command immediately sets all files opened against the specified data set as unenabled, to prevent new tasks being allowed access to the data set. The close part of the operation, however, waits until the last user task finishes before a file is actually closed. (This is the same as any close operation against a file.) An UNQUIESCE issued while the close is still waiting causes a CANCEL CLOSE request and the invocation of the XFCSREQ and XFCSREQC exits. Note that a CANCEL CLOSE is issued only for close requests that were initiated by a QUIESCE command, not for any other close requests.

Note:
There are two occasions when the user exits XFCSREQ and XFCSREQC are not invoked during a close request:
  1. On a controlled, non-immediate shutdown of CICS, when CICS closes all files.
  2. After loading a user maintained data table. When the data table load has completed the source data set is no longer required. CICS subsequently closes and de-allocates the file, leaving the data table open.

Exit XFCSREQ

When invoked
Before a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE is attempted.
Note:
The exit is not invoked for function-shipped requests.
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.
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:

          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.
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 XFCSREQ 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.
  4. Start of changeExit 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.End of change

Exit XFCSREQC

When invoked
After a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE command has completed.
Note:
The exit is not invoked for function-shipped requests.
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 file close 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.
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.
UEFBCRV
One byte indicating the recovery attributes of the data set associated with this file. The possible values are:
UEFBCFR
Forward recovery specified
UEFBCLOG
Logging specified
UEFBCVAL
Flag indicating that recovery attributes are valid.
UEFFRLOG
A 1-byte field containing the forward recovery log identifier in the range 1--99, taken from the recovery attributes in the CICS file resource definition. This number corresponds to a CICS internal journal name of the form DFHJnn, where nn is the forward recovery log number. CICS maps this journal name to a forward recovery log stream.

The field is set to zero if forward recovery logging is not specified for the file, or if the forward recovery log stream name has been obtained from the ICF catalog.

UEFFRCLG
A 26-byte field containing the name of the forward recovery log stream taken from the ICF catalog, to be used for forward recovery. Set to blanks if not specified in the ICF catalog or if forward recovery is not being used for the file.
UEFCDATE
A date (YYYYDDD+) in packed decimal format. This field is set only when the file is the last file to close against the VSAM sphere with which it is associated. It contains the date when activity against the VSAM sphere was brought to an end (quiesced).
UEFCTIME
A time (HHMMSST+) in packed decimal format. This field is set only when the file is the last file to close against the VSAM sphere with which it is associated. It contains the time when activity against the VSAM sphere was brought to an end.
UEFBCAS
A flag-byte indicating the availability of this data set. If set, the value is:
UEPFBCAS
Data set marked unavailable.
UEFACBCP
Address of a read-only copy of the ACB for a VSAM file, or the DCB for a BDAM file. Set only after completion of a successful open.
UEPFSRSP
Address of a byte containing the return codes for the request. This has one of the following values:
UEFSNORM
Normal response.
UEFSWARN
Warning response.
UEFSFAIL
Failure response.
UEFSPEND
Pending response. The ‘Pending’ response can be returned only after a CLOSE request. It indicates that, as a result of the CLOSE request, a closure is pending on the file, the file is being quiesced. When all activity against the file has completed, it is closed. Note that, if enabled, the XFCSREQ and XFCSREQC exits are driven again, when the actual closure takes place.
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.
Notes:
  1. The first seven fields of UEPFINFO (UEFLNAME through UEFDSACC) are set for all requests; that is, following an OPEN, CLOSE, ENABLE, or DISABLE request.
  2. The next three fields (UEFBCRV, UEFFRLOG, and UEFFRCLG) are valid only after a successful OPEN request.
  3. The fields UEFCDATE through UEFCBCAS are set only after a successful CLOSE request. After all other requests, if the file is already closed, if the closure fails, or if the closure is pending, these fields are set to nulls.
Return codes
UERCNORM
Continue processing.
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.
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 XFCSREQC 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.
  4. Start of changeExit 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.End of change

The DFH$REQC sample global user exit program

DFH$REQC provides sample processing for the file control state program global user exit, XFCSREQC. The exit program, if enabled at the XFCSREQC exit point, is invoked after a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE request has been acted on.

There is more information about using the sample program in the comments in the DFH$REQC source code. In summary, DFH$REQC performs the following processing :

  1. Checks whether an open request for a VSAM data set has been acted on and that the ACB error flag (ACBERFLG) is non zero.
  2. If all are true, performs default processing. The ACBERFLG error code is checked. If it is equal to X'74', the following message and data areas are built into 690 bytes of contiguous storage, in such a way that they conform to the editing rules of the WRITE OPERATOR command:
    Message
    VSAM Open error has occurred -- VSAM error flag X'nn'     
    The ACBERFLG error code is converted from hex to character format and appended to the end of the message.
    Access method control block (ACB)
    The data starts with an 'ACB' eye-catcher. All the data within the ACB is converted into character format and added after the eye-catcher.
    Exec Interface Block (EIB)
    The data starts with an 'EIB' eye-catcher. All the data within the EIB is converted into character format and added after the eye-catcher.
    Parameter list passed to the exit program
    The data starts with a 'PLIST' eye-catcher. Only the exit-specific parameters are converted to character format and added after the eye-catcher.
    File Information
    The data starts with a 'FINFO' eye-catcher. This is followed by the 8-character file name and the 44-character dsname of the data set associated with the file, as described by fields UEFLNAME and UEDSNAME in the DFHUEFDS DSECT.
  3. Issues a WRITE OPERATOR command to write as much data as has been created in the 690 bytes of storage to the system console.
  4. Returns a normal response of zero in register 15.

The sample program contains logic to write the same messages and data areas that are written on the default processing path to a transient data queue. In this case, output is edited into lines of 132 bytes. Each line is written when it is full, at which point (or upon request) a new data area or message is started.

In addition, the program logic allows for other VSAM error codes to be tested. These can be actioned to follow existing paths within the program, or tailored to use all or part of the set of messages and data areas already defined. Alternatively, the sample program can be customized to expand the set of messages and data areas written.

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