- XICEREQ
- XICEREQ is invoked on entry to the interval control program before CICS® processes an interval control request. Using XICEREQ, you can:
- Analyze the request to determine its type, the keywords specified, and
their values.
- Modify any value specified by the request before the command is executed.
- Set return codes to specify that either:
- CICS should continue with the request, modified or unmodified.
- CICS should bypass the request. (Note that if you set this return code,
you must also set up return codes for the EXEC interface block (EIB), as if
you had processed the request yourself.)
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:
- After exit XICEREQ and before XICEREQC (if these exits are enabled). This
means that:
- If an XICEREQ exit program chooses to bypass the request, XICERES is not
invoked, even if it is enabled.
- If an XICEREQ exit program modifies the request, XICERES must deal with
the modified request.
- On the target region--that is, the region
to which the START request has been routed.
- Only if the routing region--the region on which the routing program
runs--supports the "resource unavailable" condition (RESUNAVAIL).
To support the "resource unavailable" condition, the routing region
must be one of the following:
- CICS TS OS/390, Version 1 Release 3, with APAR PQ73107 applied
- CICS TS for z/OS, Version 2.2, with APAR PQ74920 applied
- CICS TS for z/OS, Version 2.3 or later
- Only if it is enabled. It is strongly recommended that you enable this
exit only in application-owning regions to which non-terminal-related EXEC CICS START requests may be dynamically routed.
- By internal requests made by CICS code, as well as by requests made by
applications.
The XICERES exit is not invoked:
- For statically-routed requests.
- For terminal-related EXEC CICS START requests. (These always execute
in the terminal-owning region and cannot be routed.)
- For dynamically-routed transactions--only
dynamically-routed (non-terminal-related) START requests cause the exit to
be invoked. Thus, a dynamically-routed transaction that was initiated by a
terminal-related EXEC CICS START command does not cause the exit to be invoked.
- If it is disabled.
- If an XICEREQ exit program chooses to bypass the request.
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:
- Set the DYRERROR field of the distributed routing program’s communications
area to 'F'--resource unavailable.
- Reinvoke the routing program, on the routing region, for route selection
failure.
- 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:
- Analyze the request, to determine its type, the keywords specified, and
their values.
- Set return codes for the EIB.
Note:
The XICEREQC exit is invoked by internal requests made
by CICS code, as well as by requests made by applications.
CICS passes ten parameters to these
exits as follows:
- The address of the command-level parameter structure (UEPCLPS)
- The address of a token (UEPICTOK) used to pass 4 bytes of data from XICEREQ
to XICEREQC
- The addresses of copies of six pieces of return code, resource, date,
and time information from the EIB
- The address of a token (UEPTSTOK) that is valid throughout the life of
a task
- The address of an exit recursion count (UEPRECUR).
- 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:
- EXEC CICS SHUTDOWN
- EXEC CICS XCTL
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.
- 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.
- 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.
UEP_IC_REMOTE_SYSTEM
If 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.
UEP_IC_REMOTE_NAME
If 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.
- 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:
- EXEC CICS SHUTDOWN
- EXEC CICS XCTL
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 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.
The command-level parameter structure contains 26 addresses,
IC_ADDR0 through IC_ADDR1F
. 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
- IC_FUNCT
- IC_BITS1
- IC_BITS2
- IC_BITS3
- IC_EIDOPT5
- IC_EIDOPT6
- IC_EIDOPT7
- IC_EIDOPT8
- 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.
X'02'
CHANNEL specified on a START command.
- IC_ADDR1
- is the address of one of the following:
- An 8-byte area containing the value of the INTERVAL keyword (or TIME keyword
if IC_EIDOPT7 indicates that TIME is specified).
- An 8-byte area containing the value of REQID (if the request is CANCEL).
- An 8-byte area containing the value
of the ABSTIME keyword.
- Data returned for INTO (if the request is RETRIEVE, and if IC_EIDOPT5 indicates that this is not SET).
- A 4-byte address returned for SET (if the request is RETRIEVE and IC_EIDOPT5 indicates that this is SET).
- IC_ADDR2
- is the address of one of the following:
- IC_ADDR3
- is the address of one of the following:
- An area containing the value of TRANSID (if the request is CANCEL or START).
- A 4-byte address returned for SET (if the request is START or POST and IC_EIDOPT5 indicates that this is SET).
- An area containing the value of YYMMDD.
- IC_ADDR4
- is the address of one of the following:
- An area containing the data from FROM.
- An area containing the value of YYDDMM.
- IC_ADDR5
- is the address of one of the following:
- IC_ADDR6
- is the address of one of the following:
- An area containing the value of TERMID.
- An area containing the value of MMDDYY.
- IC_ADDR7
- is the address of one of the following:
- An area containing the value of SYSID.
- An area containing the value of DATE.
- IC_ADDR8
- is the address of one of the following:
- An area containing the value of RTRANSID.
- An area containing the value of DATEFORM.
- IC_ADDR9
- is the address of one of the following:
- An area containing the value of RTERMID.
- An area containing the value of DATESEP.
- IC_ADDRA
- is the address of one of the following:
- An area containing the value of QUEUE.
- A fullword containing the value of
DAYCOUNT.
- IC_ADDRB
- is the address of one of the following:
- An area containing the value of HOURS.
- A fullword containing the value of
DAYOFWEEK.
- IC_ADDRC
- is the address of one of the following:
- An area containing the value of MINUTES.
- A fullword containing the value of
DAYOFMONTH.
- IC_ADDRD
- is the address of one of the following:
- An area containing the value of SECONDS.
- A fullword containing the value of
MONTHOFYEAR.
- IC_ADDRE
- is the address of one of the following:
- An area containing the value of USERID.
- A fullword containing the value of
YEAR.
- IC_ADDRF
- is the address of one of the following:
- An 8-byte area containing the value of SYSNET.
- An area containing the value of TIME.
- 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.
IC_ADDR1F
is the address of a 16-byte area containing the value of CHANNEL.
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:
- INTERVAL
- TIME
- REQID
- FROM
- TERMID
- SYSID
- HOURS
- MINUTES
- SECONDS
- USERID
CHANNEL
The following are always output fields:
- DATE
- DATEFORM
- DAYCOUNT
- DAYOFMONTH
- DAYOFWEEK
- DDMMYY
- DDMMYYYY
- FULLDATE
- INTO
- MMDDYY
- MMDDYYYY
- MONTHOFYEAR
- SET
- TIME
- YEAR
- YYDDD
- YYDDMM
- YYMMDD
- YYYYDDD
- YYYYDDMM
- YYYYMMDD
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.
IC_EIDOPT8
- X'20'
- Unused by CICS.
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:
- Modify or set completion and resource information in XICEREQ and XICEREQC
- Examine completion and resource information in XICEREQC.
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:
-
- Scan the global work area (GWA) to locate a suitable CICS region (for
example, the region currently processing the least number of START requests).
- Having decided which system to route the request to, increment the use
count for this system.
- 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.
- Set IC_ADDR7 to be the address of the 4-byte area so that XICEREQC
can also use this area.
- 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.
- Set the X'02' existence bit on in IC_BITS1 to indicate that a
SYSID is specified.
- Return to CICS.
- In XICEREQC:
-
- Scan the global work area (GWA) and locate the entry for the CICS region specified
in the SYSID parameter.
- Decrement the use count for this system.
- If a GETMAIN was issued in XICEREQ to obtain an area to hold the SYSID,
issue a FREEMAIN for the address held in UEPICTOK.
- Return to CICS.
Example and sample programs
CICS supplies two programs for use at the XICEREQ exit:
- DFH$XTSE, supplied as a softcopy listing only (not as a source
code file), is an example program that shows how to modify fields in the command-level
parameter structure passed to all the EXEC interface exits. DFH$XTSE
is listed in topic Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE.
- DFH$ICCN is a sample program for use in a distributed routing environment,
where you want to cancel a previously-issued interval control request but
have no way of knowing to which region to direct the CANCEL. For examples
of situations which DFH$ICCN is designed to cope with, see the CICS Intercommunication Guide.
[[ Contents Previous Page | Next Page Index ]]