Interval control EXEC interface program exits XICEREQ, XICERES, and XICEREQC

XICEREQ
XICEREQ is invoked on entry to the interval control program before CICS® processes an interval control request. Using XICEREQ, you can:
Note:
The XICEREQ exit is invoked by internal requests made by CICS code, as well as by requests made by applications.
XICERES
XICERES is invoked by the interval control program, before CICS processes a non-terminal-related EXEC CICS START request that has been dynamically routed to this region.

Note that XICERES is invoked:

The XICERES exit is not invoked:

You can use XICERES to check that all resources required by the transaction to be started are available on the target region. If, for example, the transaction is disabled, or a required file is missing, your exit program can give the distributed routing program the opportunity to route the request to a different region. To do this, set a return code of UERCRESU. This causes CICS to:

  1. Set the DYRERROR field of the distributed routing program’s communications area to 'F'--resource unavailable.
  2. Reinvoke the routing program, on the routing region, for route selection failure.
  3. Return a RESUNAVAIL condition on the EXEC CICS START command executed by the mirror on the target region. (This condition is not returned to the application program.)

CICS ignores any changes made by the exit program to the values of any of the exit parameters. Your exit program can set a return code, but not change any parameters.

For guidance information about dynamically routing non-terminal-related EXEC CICS START requests, see the CICS Intercommunication Guide. For information about writing a distributed routing program to route non-terminal-related EXEC CICS START REQUESTS, see Routing non-terminal-related START requests.

XICEREQC
XICEREQC is invoked after an interval control program request has completed. Using XICEREQC, you can:
Note:
The XICEREQC exit is invoked by internal requests made by CICS code, as well as by requests made by applications.

Parameters passed to each of the exits

CICS passes ten parameters to these exits as follows:

Exit XICEREQ

When invoked
Before CICS processes an interval control API request.
Exit-specific parameters
UEPCLPS
Address of the command-level parameter structure. See The UEPCLPS exit-specific parameter.
UEPICTOK
Address of a 4-byte token to be passed to XICEREQC. This allows you, for example, to pass a work area to exit XICEREQC.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’. For details of EIB return codes, refer to 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 that is valid throughout the life of a task. See Using the task token UEPTSTOK.
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.
UEPRSRCE
Address of an 8-character copy of the EIB resource value, EIBRSRCE.
UEPDATE
Address of a fullword copy of the EIB date value, EIBDATE.
UEPTIME
Address of a fullword copy of the EIB time value, EIBTIME.
Return codes
UERCNORM
Continue processing.
UERCBYP
The interval control EXEC interface program should ignore this request.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used. You can also use EXEC CICS API commands at this user exit.

Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, you are recommended to use the EXEC CICS GETMAIN and FREEMAIN commands instead.

API and SPI commands
All can be used, except for:
Note:
Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when an interval control request is issued from the XICEREQ exit. Use of the recursion counter UEPRECUR is recommended.

Exit XICERES

When invoked
By the interval control program, before processing of a non-terminal-related EXEC CICS START request that has been dynamically routed to this region, where the routing region supports the "resource unavailable" condition (RESUNAVAIL).
Exit-specific parameters
Important

CICS ignores any changes made by the exit program to the values of any of the exit parameters. Your exit program can set a return code, but not change any parameters.

UEPCLPS
Address of the command-level parameter structure. See The UEPCLPS exit-specific parameter.
UEPICTOK
Address of a 4-byte token to be passed to XICEREQC.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’. For details of EIB return codes, refer to 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 that is valid throughout the life of a task. See Using the task token UEPTSTOK.
UEPRECUR
Address of a halfword recursion counter. Because the XICERES exit can never be called recursively in the same transaction, the value of this field is always 0.
UEPRSRCE
Address of an 8-character copy of the EIB resource value, EIBRSRCE.
UEPDATE
Address of a fullword copy of the EIB date value, EIBDATE.
UEPTIME
Address of a fullword copy of the EIB time value, EIBTIME.
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
UERCRESU
A required resource is unavailable. Setting this value causes CICS to reject the routed request, and to return a value of 'F' (resource unavailable) in the DYRERROR field of the routing program's communications area.
XPI calls
All can be used. You can also use EXEC CICS API commands at this user exit.

Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, you are recommended to use the EXEC CICS GETMAIN and FREEMAIN commands instead.

API and SPI commands
All except EXEC CICS SHUTDOWN and EXEC CICS XCTL can be used.

Exit XICEREQC

When invoked
After an interval control API request has completed, and before return from the interval control EXEC interface program.
Exit-specific parameters
UEPCLPS
Address of the command-level parameter structure. See The UEPCLPS exit-specific parameter.
UEPICTOK
Address of a 4-byte token passed from XICEREQ. This allows XICEREQ to, for example, pass a work area to XICEREQC.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’. For details of EIB return codes, refer to 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 that is valid throughout the life of a task. See Using the task token UEPTSTOK.
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.
UEPRSRCE
Address of an 8-character copy of the EIB resource value, EIBRSRCE.
UEPDATE
Address of a fullword copy of the EIB date value, EIBDATE.
UEPTIME
Address of a fullword copy of the EIB time value, EIBTIME.
Start of changeUEP_IC_REMOTE_SYSTEMEnd of change
Start of changeIf the request is to be sent to a remote region, is the address of an area containing the 4-byte name of the remote region. (The remote region may have been specified by, for example, the SYSID option of the START command, work-load management, or the REMOTESYSTEM option of the TRANSACTION definition.)

If the request is to be executed on the local region, this parameter is the address of a 4-byte area containing blanks.

End of change
Start of changeUEP_IC_REMOTE_NAMEEnd of change
Start of changeIf the transaction is to be executed in a remote system, is the address of an area containing the name of the transaction, as it is known in the remote system.

The remote system may be another CICS region, or an IMS™ system. If UEP_IC_REMOTE_SYSTEM names a CICS region, the name is 1 through 4 characters long. If UEP_IC_REMOTE_SYSTEM names an IMS system, the name is 1 through 8 characters long. IMS uses 8-character names: if UEP_IC_REMOTE_NAME has fewer than 8 characters, IMS translates it into a useable format.

End of change
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, you are recommended to use the EXEC CICS GETMAIN and FREEMAIN commands instead.

API and SPI commands
All can be used, except for:
Note:
Take care when issuing recursive commands. For example, you must avoid entering a loop when issuing an interval control request from the XICEREQC exit. Use of the recursion counter UEPRECUR is recommended.

The command-level parameter structure

Figure 1. The command-level parameter structure for interval control
 The picture shows, using a series of interconnected boxes, the relationships between the fields in the command-level parameter structure. The command-level parameter structure, and the relationships between its fields, are fully described in the text following the picture.

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 9-byte area 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. For example, the second address points to the interval for START requests.

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. For example, you could change the SYSID specified in the request.

End of parameter list indicator

The high-order bit is set on in the last address set in the parameter list to indicate that it is the last one in the list. On return from your user exit program, CICS scans the parameter list for the high-order bit to find the last parameter. Therefore, if you modify the length of the parameter list, you must also reset the high-order bit to indicate which is the new last address.

For example, if the parameter list specifies only the first four addresses (IC_ADDR0, the address of the EID, to IC_ADDR3, the address of the name of the transaction named in a START request), the high-order bit is set on in IPC_ADDR3. If you extend the parameter list by setting the address of a SYSID in IC_ADDR7, you must unset the high-order bit in IC_ADDR3 and set it on in IC_ADDR7 instead.

The maximum size of parameter list is supplied to the exit, thus allowing your exit program to add any parameters not already specified without needing to first obtain more storage.

The original parameter list, as it was before XICEREQ was invoked, is restored after the completion of XICEREQC. It follows that the execution diagnostic facility (EDF) displays the original command before and after execution: EDF does not display any changes made by the exit.

The UEPCLPS exit-specific parameter

The UEPCLPS exit-specific parameter is included in both exit XICEREQ and exit XICEREQC. It is the address of the command-level parameter structure. Start of changeThe command-level parameter structure contains 26 addresses, IC_ADDR0 through IC_ADDR1FEnd of change. It is defined in the DSECT IC_ADDR_LIST, which you should copy into your exit program by including the statement COPY DFHICUED.

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

IC_ADDR0
is the address of a 9-byte area called the EXEC interface descriptor (EID), which is made up as follows:
IC_GROUP
X'10'
This is an interval control request.
X'4A'
This is an ASKTIME or FORMATTIME command.
IC_FUNCT
One byte that defines the type of request.

If IC_GROUP = X'10':

X'02'
ASKTIME
X'04'
DELAY
X'06'
POST
X'08'
START
X'0A'
RETRIEVE
X'0C'
CANCEL

If IC_GROUP = X'4A':

X'02'
ASKTIME
X'04'
FORMATTIME
IC_BITS1
Existence bits that define which arguments were specified. To obtain the argument associated with a keyword, you need to use 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 INTERVAL or TIME arguments, or if a CANCEL request specifies REQID, or if a RETRIEVE request specifies SET or INTO. If set, IC_ADDR1 is meaningful.
X'40'
Set if the request other than CANCEL specifies REQID or if a RETRIEVE request specifies LENGTH. If set, IC_ADDR2 is meaningful.
X'20'
Set if the request specifies TRANSID or if a request other than RETRIEVE specifies SET or INTO. If set, IC_ADDR3 is meaningful.
X'10'
Set if the request specifies FROM. If set, IC_ADDR4 is meaningful.
X'08'
Set if a request other than RETRIEVE specifies LENGTH. If set, IC_ADDR5 is meaningful.
X'04'
Set if the request specifies TERMID. If set, IC_ADDR6 is meaningful.
X'02'
Set if the request specifies SYSID. If set, IC_ADDR7 is meaningful.
X'01'
Set if the request specifies RTRANSID. If set, IC_ADDR8 is meaningful.
IC_BITS2
Further argument existence bits.
X'80'
Set if the request specifies RTERMID, or if a FORMATTIME request specifies DATESEP. If set, IC_ADDR9 is meaningful.
X'40'
Set if the request specifies QUEUE. If set, IC_ADDRA is meaningful.
X'20'
Set if the request specifies HOURS. If set, IC_ADDRB is meaningful.
X'10'
Set if the request specifies MINUTES. If set, IC_ADDRC is meaningful.
X'08'
Set if the request specifies SECONDS. If set, IC_ADDRD is meaningful.
X'04'
Set if the request specifies USERID. If set, IC_ADDRE is meaningful.
X'02'
Set if the request specifies SYSNET. If set, IC_ADDRF is meaningful.
X'01'
Set if a FORMATTIME request specifies TIMESEP. If set, IC_ADDR10 is meaningful.
IC_BITS3
One byte not used by interval control.
IC_EIDOPT5
Indicates whether certain keywords were specified on the request.
X'80'
ABSTIME was specified on a FORMATTIME or ASKTIME command.
X'40'
YYDDD was specified on a FORMATTIME command.
X'20'
YYMMDD was specified on a FORMATTIME command.
X'10'
YYDDMM was specified on a FORMATTIME command.
X'08'
DDMMYY was specified on a FORMATTIME command.
X'04'
MMDDYY was specified on a FORMATTIME command.
X'02'
DATE was specified on a FORMATTIME command.
X'01'
On a RETRIEVE command, SET (and not INTO) was specified. On a START command, ATTACH was specified. On a FORMATTIME command, DATEFORM was specified. You cannot modify this field in your user exit.
IC_EIDOPT6
Existence bits that indicate whether certain keywords were specified on the request.
X'80'
DATESEP was specified on a FORMATTIME command.
X'40'
DAYCOUNT was specified on a FORMATTIME command.
X'20'
DAYOFWEEK was specified on a FORMATTIME command, or HOURS was specified.
X'10'
DAYOFMONTH was specified on a FORMATTIME command, or FMH was specified.
X'08'
MONTHOFYEAR was specified on a FORMATTIME command, or SECONDS was specified.
X'04'
YEAR was specified on a FORMATTIME command, or MINUTES was specified.
X'02'
TIME was specified on a FORMATTIME command, or PROTECT was specified.
X'01'
TIMESEP was specified on a FORMATTIME command, or NOCHECK was specified.
IC_EIDOPT7
Indicates whether certain functions or keywords were specified on the request.
X'F0'
CANCEL specified.
X'82'
RETRIEVE specified.
X'80'
YYYYDD specified on a FORMATTIME command.
X'40'
YYYYMMDD specified on a FORMATTIME command, or START specified.
X'30'
POST specified.
X'20'
YYYYDDMM specified on a FORMATTIME command, or DELAY, RTRANSID, RTERMID, or QUEUE specified, and/or FMH.
X'13'
ASKTIME specified.
X'10'
DDMMYYYY specified on a FORMATTIME command, or FROM, RTRANSID, or RTERMID specified, and/or QUEUE.
X'08'
MMDDYYYY specified on a FORMATTIME command, or TIME or WAIT specified.
X'04'
FULLDATE specified on a FORMATTIME command, or REQID specified.
X'01'
TERMID specified.
IC_EIDOPT8
Indicates whether certain keywords were specified on the request.
X'80'
FOR or AFTER specified.
X'40'
AT or UNTIL specified.
X'10'
BREXIT specified.
X'08'
BRDATA specified.
X'04'
BRDATALENGTH specified.
Start of changeX'02'End of change
Start of changeCHANNEL specified on a START command.End of change
IC_ADDR1
is the address of one of the following:
IC_ADDR2
is the address of one of the following:
IC_ADDR3
is the address of one of the following:
IC_ADDR4
is the address of one of the following:
IC_ADDR5
is the address of one of the following:
IC_ADDR6
is the address of one of the following:
IC_ADDR7
is the address of one of the following:
IC_ADDR8
is the address of one of the following:
IC_ADDR9
is the address of one of the following:
IC_ADDRA
is the address of one of the following:
IC_ADDRB
is the address of one of the following:
IC_ADDRC
is the address of one of the following:
IC_ADDRD
is the address of one of the following:
IC_ADDRE
is the address of one of the following:
IC_ADDRF
is the address of one of the following:
IC_ADDR10
is the address of a 1-byte area containing the value of TIMESEP.
IC_ADDR11
is the address of an area containing the value of YYYYDDD.
IC_ADDR12
is the address of an area containing the value of YYYYMMDD.
IC_ADDR13
is the address of an area containing the value of YYYYDDMM.
IC_ADDR14
is the address of an area containing the value of DDMMYYYY.
IC_ADDR15
is the address of an area containing the value of MMDDYYYY.
IC_ADDR16
is the address of an area containing the value of FULLDATE.
IC_ADDR1D
is the address of an area containing the value of BRDATA.
IC_ADDR1E
is the address of a fullword containing the value of BRDATALENGTH.
Start of changeIC_ADDR1FEnd of change
Start of changeis the address of a 16-byte area containing the value of CHANNEL.End of change

Modifying fields in the command-level parameter structure

Some fields that are passed to interval control are used as input to the request, some are used as output fields, and some are used for both input and output. The method your user exit program uses to modify a field depends on the usage of the field.

The following are always input fields:

The following are always output fields:

The following are input fields on a START request and output fields on a RETRIEVE request:

LENGTH is an input field on a START request, an output field on a RETRIEVE with SET specified, and an input/output field on a RETRIEVE with INTO specified.

ABSTIME is an input field on a FORMATTIME request, and an output field on an ASKTIME request. DATESEP and TIMESEP can be input fields on a FORMATTIME request.

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, such as changing a DELAY request to a START request.

However, you can make minor changes to requests, such as turning on the existence bit for SYSID so that the request can be changed into one that is shipped to a remote system.

Some interval control commands use 2 bits in the EID to indicate a single keyword; the EXEC CICS START command, for example, uses 2 bits to indicate TERMID. The first bit, in IC_BITS1, indicates that ADDR6 in the command parameter list is valid (ADDR6 points to TERMID) and the second, in IC_EIDOPT7, is the keyword existence bit to show that the TERMID keyword was specified on the command.

Where this occurs you must ensure that both bit settings are changed (consistently) if you wish to modify these commands from within a user exit program, or the results will be unpredictable.

The list that follows shows the bits in the EID that can be modified. Any attempt to modify any other part of the EID is ignored.

IC_BITS1
X'80'
The existence bit for REQID (if the request is CANCEL)
X'40'
The existence bit for LENGTH (if the request is RETRIEVE) or REQID
X'10'
The existence bit for FROM
X'08'
The existence bit for LENGTH
X'04'
The existence bit for TERMID
X'02'
The existence bit for SYSID
X'01'
The existence bit for RTRANSID.
IC_BITS2
X'80'
The existence bit for RTERMID
X'40'
The existence bit for QUEUE
X'20'
The existence bit for HOURS
X'10'
The existence bit for MINUTES
X'08'
The existence bit for SECONDS.
IC_EIDOPT6
X'20'
The secondary existence bit for HOURS
X'10'
The existence bit for FMH
X'08'
The secondary existence bit for SECONDS
X'04'
The secondary existence bit for MINUTES
X'02'
The existence bit for PROTECT
X'01'
The existence bit for NOCHECK.
IC_EIDOPT7
Bits in IC_EIDOPT7 should only be modified within the same functional group - that is, only those existence bits defined as valid for a START request should be set on a START request.
ASKTIME requests
X'13'
ASKTIME request. This value is fixed for all ASKTIME requests, and should not be modified.

DELAY requests

X'20'
DELAY request
X'08'
TIME specified
X'04'
REQID specified.

POST requests

X'30'
POST request
X'08'
TIME specified
X'04'
REQID specified.

START requests

X'40'
START request (without DATA)
X'50'
START with DATA request
X'70'
START with one or more of RTRANSID, RTERMID, QUEUE, or FMH specified.
X'08'
TIME specified
X'04'
REQID specified
X'01'
TERMID specified.
RETRIEVE requests

X'82'
RETRIEVE request.

CANCEL requests

X'F0'
CANCEL request
X'04'
REQID specified.
Start of changeIC_EIDOPT8End of change
Start of change
X'20'
Unused by CICS.
End of change

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

Note:
Your user exit program is prevented from making major changes to the EID. However, you must take great care when making the minor modifications that are permitted.

Using the interval control request token UEPICTOK

UEPICTOK provides the address of a 4-byte area that you can use to pass information between the XICEREQ and XICEREQC user exits for the same interval control request. For example, the address of a piece of storage obtained by the XICEREQ user exit, which is to be freed by the XICEREQC exit, can be passed in the UEPICTOK field.

Using the task token UEPTSTOK

UEPTSTOK provides the address of a 4-byte area that you can use to pass information between successive interval control requests in the same task. (By contrast, UEPICTOK is usable only for the duration of a single interval 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 the XICEREQ exit, UEPTSTOK provides a means of doing this.

The EIB

Copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 are passed to the exit, so that you can:

You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list. Interval control copies your values into the real EIB after the completion of XICEREQC; or if you specify a return code of ‘bypass’ in XICEREQ.

You must set valid interval control responses. You must set all three of EIBRCODE, EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by CICS interval control to describe a valid completion. CICS does not police the consistency of EIBRCODE, EIBRESP, and EIBRESP2. However, if EIBRCODE is set to a non-zero value and EIBRESP is set to zero, CICS overrides EIBRESP with a non-zero value. To aid you in setting the values of EIBRCODE, EIBRESP, and EIBRESP2, the values used by interval control are specified in DFHICUED.

Example of how XICEREQ and XICEREQC can be used

XICEREQ and XICEREQC can be used for a variety of purposes. One example of a possible use is given below.

In this example, XICEREQ and XICEREQC are used to route START requests to a number of different CICS regions to provide a simple load balancing mechanism. The example shows only the capabilities of the exits; it is not intended to indicate an ideal way of achieving the function.

In XICEREQ:
  1. Scan the global work area (GWA) to locate a suitable CICS region (for example, the region currently processing the least number of START requests).
  2. Having decided which system to route the request to, increment the use count for this system.
  3. Obtain a 4-byte area in which to store the SYSID for this request. This can be allocated from the GWA to avoid issuing a GETMAIN. If the area is obtained by issuing a GETMAIN, set UEPICTOK to the address of the storage obtained.
  4. Set IC_ADDR7 to be the address of the 4-byte area so that XICEREQC can also use this area.
  5. If setting IC_ADDR7 now makes it the last address, set the high-order bit in the address, and reset the high-order bit in what was previously the last address.
  6. Set the X'02' existence bit on in IC_BITS1 to indicate that a SYSID is specified.
  7. Return to CICS.
In XICEREQC:
  1. Scan the global work area (GWA) and locate the entry for the CICS region specified in the SYSID parameter.
  2. Decrement the use count for this system.
  3. If a GETMAIN was issued in XICEREQ to obtain an area to hold the SYSID, issue a FREEMAIN for the address held in UEPICTOK.
  4. Return to CICS.

Example and sample programs

CICS supplies two programs for use at the XICEREQ exit:

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