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:
- On a controlled, non-immediate shutdown of CICS, when CICS closes all files.
- 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.
- 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:
- 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.
- 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:
- The first seven fields of UEPFINFO (UEFLNAME through UEFDSACC) are set
for all requests; that is, following an OPEN, CLOSE, ENABLE, or DISABLE request.
- The next three fields (UEFBCRV, UEFFRLOG, and UEFFRCLG) are valid only
after a successful OPEN request.
- 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:
- 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.
- 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.
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 :
- Checks whether an open request for a VSAM data set has been acted on and
that the ACB error flag (ACBERFLG) is non zero.
- 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.
- Issues a WRITE OPERATOR command to write as much data as has been created
in the 690 bytes of storage to the system console.
- 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.
[[ Contents Previous Page | Next Page Index ]]