Using the EXCI options table, DFHXCOPT

The format of the DFHXCOPT options table has changed since it was first introduced. In CICS TS for z/OS®, Version 3.2 (and, by APAR, also in CICS TS 2.1, CICS TS 2.2, and CICS TS 3.1) the table now includes a version number, to allow more flexibility for future extensions. You need to be aware of this change if, for example, you plan to migrate a customized DFHXCOPT table from an earlier release of CICS to CICS TS for z/OS, Version 3.2.

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 CICSTS52.CICS.SDFHSAMP library. The load module of the default DFHXCOPT table, with its alias DFHXCOPE, is in the CICSTS52.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 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 must assemble and link-edit your customized 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 do this. The DFHAUPLE procedure is supplied in CICSTS52.CICS.SDFHINST.

Unlike the tables you specify for CICS regions, the DFHXCOPT table cannot be suffixed.

The following table shows the format of the DFHXCOPT macro and its 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}]
	REMOVED [,SURROGCHK={YES|NO}]
	[,TIMEOUT={0|number}]
	[,TRACE={OFF|1|2}]
	[,TRACESZE={16|number-of-kilobytes}]
	[,TRAP={OFF|ON}]
	[,XCFGROUP={DFHIR000|name}]
	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 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}

REMOVED: The SURROGCHK parameter has been removed. Surrogate checking is always done. If you want the option of SURROGCHK=NO, you need to request a usermod from IBM support.

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 internal tracing for the external CICS interface, and at what level.

OFF

Internal tracing for the external CICS interface is not required. However, even with normal tracing switched off, exception trace entries are always written to the external CICS interface trace table in the CICS region.

1

Exception and level-1 trace entries are written to the external CICS interface trace table.

2

Exception, level-1, and level-2 trace entries are written to the external CICS interface trace table.

TRACESZE={16|number-of-kilobytes}

Specifies the size in kilobytes of the trace table that is used by the external CICS interface. This trace table is allocated in 31-bit storage (above the line) in the CICS region. .

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 trace table, in the range 16 KB through 1 048 576 KB. Subpool 1 is used for the trace table storage, which exists for the duration of the job step 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 (4 KB), it is rounded up to the next multiple of 4 KB.

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.

XCFGROUP={DFHIR000|name}

Specifies the name of the cross-system coupling facility (XCF) group to be joined by this client program.

Note: XCF groups allow CICS regions in different MVS images within the same sysplex to communicate with each other across multi-region operation (MRO) connections. For introductory information about XCF/MRO, and instructions on how to set up XCF groups, see Cross-system multiregion operation (XCF/MRO) .

Each client program can join a maximum of one XCF group.

DFHIR000

The default XCF group name.

name

The group name must be eight characters long, padded on the right with blanks if necessary. The valid characters are A-Z 0-9 and the national characters $ # and @. To avoid using the names IBM uses for its XCF groups, do not begin group names with the letters A through C, E through I, or the character string SYS. Also, do not use the name UNDESIG, which is reserved for use by the system programmer in your installation.

It is recommended that you use a group name beginning with the letters DFHIR.