The EXCI options table, generated by the DFHXCOPT macro, enables you to
specify a number of parameters that are required by the external CICS® interface.
The format
of the DFHXCOPT options table is changed by APAR PK 17426. If you have applied
APAR PK 17426, the table now includes, for example, a version number, which
is intended to allow more flexibility for future extensions. To distinguish
between the old and newer formats, the new-format table is link-edited with
an alias called "DFHXCOPE".
The following sequence is used to load the options
table:
- CICS tries to load the DFHXCOPT table using its alias name of DFHXCOPE.
If it finds a load module named DFHXCOPE, and successfully loads it, CICS
assumes that the table is in the new format.
- If CICS does not find a load module named DFHXCOPE (or finds it but fails
to load it), it tries to load the table using its "base" name of DFHXCOPT.
In this case, CICS assumes that the table is in the older format.
CICS provides a default DFHXCOPT table. The source code of the default
table, which you can tailor to your own requirements, is supplied in the CICSTS31.CICS.SDFHSAMP
library. The load module of the default DFHXCOPT table, with its alias DFHXCOPE,
is in the CICSTS31.CICS.SDFHEXCI library.
If you create your own, customized, DFHXCOPT
table, ensure that you link-edit it using the DFHXCOPE alias. (Using
the standard DFHAUPLE procedure, described below, ensures that this happens.)
If you reassemble and link-edit your table without the alias, CICS will load
the default table (found by means of its DFHXCOPE alias), rather than your
customized table.
You assemble and link-edit the modified DFHXCOPT table into a suitable
library in the STEPLIB concatenation of the job that runs the MVS™ client program. You can use your own
version of the CICS DFHAUPLE procedure to assemble and link-edit your
customized options table. The DFHAUPLE procedure is supplied in CICSTS31.CICS.SDFHINST.
Unlike the tables you specify for CICS regions, the DFHXCOPT table cannot be
suffixed.
Table 22 shows the format of the DFHXCOPT macro and its parameters.
Table 22. The DFHXCOPT macro parameters
|
DFHXCO |
TYPE={CSECT|DSECT} |
 |
 |
[,ABENDBKOUT={NO|YES}] |
|
|
[,CICSSVC={0|number}] |
|
|
[,CONFDATA={SHOW|HIDETC}] |
|
|
[,DURETRY={30|number-of-seconds}] |
|
|
[,GTF={OFF|ON}] |
|
|
[,MSGCASE={MIXED|UPPER}] |
|
|
[,SURROGCHK={YES|NO}] |
|
|
[,TIMEOUT={0|number}] |
|
|
[,TRACE={OFF|1|2}] |
|
|
[,TRACESZE={16|number-of-kilobytes}] |
|
|
[,TRAP={OFF|ON}] |
|
|
|
|
|
You must terminate your parameters with the
following END statement. |
|
|
|
|
END |
DFHXCOPT |
|
|
|
- TYPE={CSECT|DSECT}
- Indicates the type of table to be generated.
- CSECT
- A regular control section that is normally used.
- DSECT
- A dummy control section.
ABENDBKOUT={NO|YES}
Specifies whether a task that abends within the CICS server is to trigger
an automatic rollback of the global unit of work. A global unit of work exists
when an EXCI client program is controlling resource recovery through MVS RRS
(that is, SYNCONRETURN is not specified on the DPL request). In this case
you may well want the global unit of work to be marked for rollback if the
CICS server program abends.
Note:
ABENDBKOUT has no effect when
SYNCONRETURN is specified on the DPL request.
- NO
- The global unit of work is not marked for rollback.
- YES
- When processing the abend of the server program, the CICS mirror program
marks the global unit of work for backout.
In both cases the EXCI client program receives a return code of 422,
SERVER_ABENDED, on the EXCI DPL request.
- CICSSVC={0|number}
- Specifies the CICS type 3 SVC number being used for MRO communication.
The external CICS interface must use the same SVC number that is in use by the CICS MRO regions
that reside in the MVS image in which the client program is running.
If you do not specify a specific CICS SVC number, the external CICS interface determines
the SVC in use for MRO by means of an MVS VERIFY command.
- 0
- Specify zero to indicate that the external CICS interface is to obtain the CICS SVC number
from MVS. This is the default.
You should only specify 0 when you are sure
that at least one CICS region has logged on to DFHIRP during the life of
the MVS IPL.
- number
- Specify the CICS SVC number, in the range 200--255, that is in
use for CICS interregion communications. This must be the SVC number that is
installed in the MVS image in which the client program is running (the local MVS).
If no MRO CICS regions have ever logged on to DFHIRP in the local MVS during the life
of the IPL, you must specify the SVC number. If you allow this parameter to
default, and the external CICS interface requests the SVC from MVS, the request
will fail if no CICS region has logged on to DFHIRP.
This parameter
is required in those MVS images that do not run any CICS regions, and the client program is issuing
DPL requests to a server CICS region that resides in another MVS. In these circumstances,
the client program logs on to the local DFHIRP using the locally defined SVC,
and communicates with the remote CICS region using XCF/MRO.
Note:
All CICS regions using MRO within the same MVS image
must use the highest level of both DFHIRP and the CICS SVC, DFHCSVC. If your MRO CICSplex consists
of CICS regions at different release levels, the DFHIRP and DFHCSVC installed
in the LPA must be from highest release level of CICS within the CICSplex.
MVS client programs
using the external CICS interface can communicate only with server regions
running under CICS for MVS/ESA 4.1 or later.
- CONFDATA={SHOW|HIDETC}
- Code this parameter to indicate whether the external CICS interface is
to suppress (hide) user data that might otherwise appear in EXCI trace entries
output to GTF or in EXCI dumps. This option applies
to the tracing of the COMMAREA flowing between the EXCI client program and
the CICS server program.
- SHOW
- Data suppression is not in effect. User data is traced.
- HIDETC
- This specifies that you want EXCI to ‘hide’ user COMMAREA data
from trace entries. Instead of the COMMAREA data, the trace entry contains
a character string stating that the data has been suppressed.
- DURETRY={30|number-of-seconds|0}
- Specifies the total time, in seconds, that the external CICS interface is
to continue trying to obtain an MVS system dump using the SDUMP macro.
DURETRY allows you
to control whether, and for how long, the external CICS interface is to reissue the SDUMP if
another address space in the same MVS system is already taking an SDUMP when
the external CICS interface issues an SDUMP request.
In the event of an SDUMP
failure, the external CICS interface reacts as follows:
- If MVS is already taking an SDUMP for another address space, and the DURETRY
parameter is nonzero, the external CICS interface issues an MVS STIMERM macro
to wait for five seconds, before retrying the SDUMP macro. The external CICS interface issues a message to say that it will retry the SDUMP every
five seconds until the DURETRY time limit.
- If the SDUMP fails for any other reason such as:
- There are no SYS1.DUMP data sets available, or
- There are I/O errors preventing completion of the dump, or
- The DURETRY limit expires while retrying SDUMP
the external CICS interface issues a message to inform you that the
SDUMP has failed, giving the reason why.
- 30
- 30 seconds allows the external CICS interface to retry up to six times (once
every five seconds).
- number-of-seconds
- Code the total number of seconds (up to 32767 seconds) during which
you want the external CICS interface to continue retrying the SDUMP macro. The
external CICS interface retries the SDUMP, once every five seconds, until successful
or until retries have been made over a period equal to or greater than the
DURETRY value.
- 0
- Code a zero value if you do not want CICS to retry the SDUMP.
- GTF={OFF|ON}
- Specifies whether all trace entries normally written to the external CICS interface internal trace table are also
to be written to an MVS generalized trace facility (GTF) data set (if GTF tracing
is active).
- OFF
- Code this if trace entries are not to be written to GTF.
- ON
- Code this if trace entries are to be written to GTF.
- MSGCASE={MIXED|UPPER}
- Specifies whether the DFHEXxxxx messages are to be issued in
mixed or uppercase.
- MIXED
- Code this if messages are to be issued in mixed case.
- UPPER
- Code this if messages are to be issued in uppercase.
- SURROGCHK={YES|NO}
- Specifies whether the external CICS interface is to perform surrogate user
checks against the client job user id (the user ID under which the EXCI job
is running).
- YES
- The external CICS interface is to perform a surrogate user check to
verify that the user ID under which the EXCI client job is running is authorized
as a surrogate for the user ID specified on a DPL call. The check is made
only when the client user ID is different from the user ID on the DPL call.
The client user ID must be authorized to the appropriate profile in the SURROGAT
general resource class. You do this by giving the client user ID READ authority
to a profile named userid.DFHEXCI in the SURROGAT
general resource class, where userid is the user ID
specified on the DPL call.
See Surrogate user checking for an example
of how to authorize the batch region user ID as a surrogate user for a DPL
user ID.
- NO
- Surrogate user checks are not to be performed.
- TIMEOUT={0|number}
- Specifies the time interval, in hundredths of a second, during which
the external CICS interface waits for a DPL command to complete.
- 0
- Specifies that you do not want any time limit applied, and that the
external CICS interface is to wait indefinitely for a DPL command to complete.
- number
- Specifies the time interval, in hundredths of a second, that the external CICS interface is to wait for a DPL command to complete. The number represents
hundredths of a second, from 1 up to a maximum of 2 147 483 647.
For example:
- 6000
- Represents a timeout value of one minute
- 30000
- Represents a timeout value of five minutes
- 60000
- Represents a timeout value of ten minutes.
- TRACE={OFF|1|2}
- Specifies whether you want external CICS interface internal tracing, and at what
level.
- OFF
- External CICS interface internal tracing is not required. However,
even with normal tracing switched off, exception trace entries are always
written to the internal trace table.
- 1
- Exception and level-1 trace entries are written to the internal trace
table.
- 2
- Exception, level-1, and level-2 trace entries are written to the internal
trace table.
- TRACESZE={16|number-of-kilobytes}
- Specifies the size in kilobytes of the internal trace table for use
by the external CICS interface. This table is allocated in virtual storage
above the 16MB line. You should ensure that there is enough virtual
storage for the trace table by specifying a large enough region size on the MVS REGION
parameter.
- 16
- 16KB is the default size of the trace table, and also the minimum size.
- number-of-kilobytes
- The number of kilobytes of storage to be allocated for the internal
trace table, in the range 16KB through 1 048 576KB. Subpool
1 is used for the trace table storage, which exists for the duration of the
jobstep TCB. The table is page-aligned and occupies a whole number of pages.
If the value specified is not a multiple of the page size (4KB), it is rounded
up to the next multiple of 4KB.
- TRAP={OFF|ON}
- Specifies whether the service trap module, DFHXCTRA, is to be used.
DFHXCTRA is supplied as a user-replaceable module, in which IBM® service personnel
can add code to trap errors.
- OFF
- Code this if you do not want to use DFHXCTRA.
- ON
- Code this if you require DFHXCTRA.

[[ Contents Previous Page | Next Page Index ]]