DFHMAH field definitions

Stabilized feature: Service Flow Runtime and Service Flow Modeler capability in IBM Developer for z/OS 14.2.3 are stabilized. Consider exposing and orchestrating applications as API services by using z/OS Connect Enterprise Edition or CICS® web services, or by writing web applications in Java or Node.js. See also Stabilization notices and discontinued functions.

The following definitions describe the content of each field in the DFHMAH message header.

DFHMAH-STRUCID
The structure identifier. This value indicates the structure of the message header. This field is always an input field and the initial value is MAH. Acceptable input for this field can be any of the following values:
  • MAH, indicating that the message header is structured in flat file format
  • <?XM or <?xm, indicating that the message header is structured in XML format
  • <SOA or <soa, indicating that the message header is structured using Service Oriented Architecture (SOA) format
DFHMAH-VERSION
The structure version number. The value must be 2 for runtime processing. This field is always an input field and the initial value is 2.
DFHMAH-STRUCLENGTH
The length of the DFHMAH structure. The value must be 384. This field is always an input field and the initial value is 384.
DFHMAH-USERID
Reserved. This field is not implemented currently.
DFHMAH-FORMAT
The format name of the application data that follows the DFHMAH structure. The format name is also used for the reply message.

If the request message results in the generation of an error reply message, the error reply message has a format name of INCMPLTE. This field is an input field for requests and an output field for replies. The initial value of this field is blanks.

DFHMAH-RETURNCODE
The return code from CICS Service Flow Runtime processing. This return code describes the outcome of service flow request processing. The Compcode, Mode, Suspstatus, Abendcode, and Message fields can contain additional information. The value is one of the following:
0
Request processing completed normally.
9
An error occurred during request processing.
99
Multiple errors occurred during request processing.
999
An abend occurred during request processing.

Depending on the processing mode, a value other than zero in this field can indicate an incomplete BTS process. This process remains in an incomplete status until some action is taken. See the description of field DFHMAH-COMPCODE.

This field is an output field. The initial value of this field is zero.

DFHMAH-COMPCODE
The completion status of the BTS process instance. This field describes the outcome of the BTS process that implements an instance of the CICS Service Flow Runtime. This field is an output field and the initial value of this field is zero. See Developing with the BTS API for a description of the CHECK ACQPROCESS command.
DFHMAH-MODE
The processing state of the BTS process instance. This field describes the state (at the time that the reply was issued) of the BTS process that implements an instance of the CICS Service Flow Runtime. This is an output field and the initial value of this field is zero. See Developing with the BTS API for a description of the CHECK ACQPROCESS command.
DFHMAH-SUSPSTATUS
The suspend status of the BTS process. This field is an output field and the initial value of this field is zero. See Developing with the BTS API for a description of the CHECK ACQPROCESS command.
DFHMAH-ABENDCODE
This field contains the ABEND code if present. The value returned in this field depends on the DFHMAH-RETURNCODE field. This field is an output field and the initial value is blanks. See CICS messages for a complete list.
DFHMAH-MESSAGE
The error message returned from CICS Service Flow Runtime. The value returned in this field depends on the DFHMAH-RETURNCODE field. This field is an output field and the initial value is blanks. See Messages and codes for a description of potential errors and for information on the user response to the error message.
DFHMAH-UOWCONTROL
This field indicates the processing mode. The value is one of the following:
0
Normal or default processing. This value is the initial value of the field. A value of 0 indicates standard request processing of a service flow, where a BTS process instance is created to run a request from the service requester.
2
If the BTS process fails, the process is canceled and a compensating flow runs instead.
9
If the BTS process fails, the process is canceled.

If the field contains a value of 2 or 9, the FAILED-PROCNAME and FAILED-PROCTYPE fields must be specified.

DFHMAH-PROCESSTYPE
This field defines the type of the new process instance. It is controlled by the service requester. DFHMADPL uses the value in this field when it starts the navigation manager with the BTS DEFINE PROCESS command.

This is an input field and the initial value is blanks. This field is used to determine the following:

  • BTS repository and audit files used
  • The audit level

Do not specify this field if the DFHMAH-UOWCONTROL field has a value of 9. Because of the relationship between the audit level and BTS process type, you might want to define multiple process types for each audit level or request type.

DFHMAH-PROCESSNAME
This field indicates the name of the new process instance. DFHMADPL uses the process name on the BTS DEFINE PROCESS command. This field ensures that each BTS process has a unique name. See Developing with the BTS API for a description. This field is an input or output field. The initial value of this field is blanks.

If no value is provided, the CICS Service Flow Runtime generates a unique identifier and returns it to the service requester. When generated, the user ID under which DFHMADPL is running, Eibtaskn, and the AbsTime values are concatenated in that order and are used as the process name.

Do not specify this field if the DFHMAH-UOWCONTROL field has a value of 9.

DFHMAH-REQUESTNAME
This field value is the name of the service flow that should be processed. The CICS SFR interface program DFHMADPL uses this value to read the service flow repository file to determine how to run the service flow. The value must correspond to the name of a deployed and enabled service flow.

The initial value of this field is blanks. Do not specify this field if the DFHMAH-UOWCONTROL field has a value of 9.

DFHMAH-DATALENGTH
The length of the inbound request or outbound reply application data following the DFHMAH header structure. This value is used to determine the size of the input data-container that contains the request application data.

It represents the fixed-format length of the inbound application request data or outbound application reply data, not including the length of any XML tags or XML declaration data if present. For XML request messages, this field indicates the length of the application request data when it is converted to COBOL.

DFHMAH-FAILED-PROCNAME
Failed process name. This field indicates the name of the failed process and is an input or output field. It is returned by CICS Service Flow Runtime when the value of the DFHMAH-RETURNCODE field is not zero. The service requester must specify this field when the DFHMAH-UOWCONTROL field indicates cancel or compensate. It is used to acquire a failed process on a BTS ACQUIRE PROCESS command.
DFHMAH-FAILED-PROCTYPE
Failed BTS process type. This field indicates the type of the failed CICS Service Flow Runtime process. This field is an input or output field. It is returned by the CICS Service Flow Runtime when RETURNCODE is not zero. The service requester must specify this field when the DFHMAH-UOWCONTROL field indicates cancel or compensate. It is used to acquire a failed process on a BTS ACQUIRE PROCESS command.
DFHMAH-FAILED-TRANID
Failed CICS Service Flow Runtime transaction. This field indicates the active transaction ID when the error occurred causing process failure. This field is an input or output field. It is returned by the CICS Service Flow Runtime when the value of field DFHMAH-RETURNCODE is not zero. The application can use it in a compensating flow or custom error processing. The CICS Service Flow Runtime does not make use of this field other than to return a value to the service requester upon failure.
DFHMAH-REPLYTOQ
Name of the reply queue. This value is the name of the message queue to which the CICS Service Flow Runtime sends reply messages. This field is an input field. See IBM MQ applications reference for a description. The service requester must specify this field if the processing request mode is asynchronous and the CICS-MQ bridge is being used to communicate between the CICS Service Flow Runtime and the service requester. Do not specify the ReplyToQ in the IBM® MQ MQMD header structure.

This field can be loaded if you are implementing early reply processing with the queue name. The name is used for any early reply issued.

DFHMAH-REPLYTOQMGR
This is the name of the queue manager to which the CICS Service Flow Runtime sends reply messages. This field is an input field. Replytoq is the local name of a queue that is defined on this queue manager. See IBM MQ applications reference for a description. The service requester must specify this field when the processing mode is asynchronous and the CICS-MQ bridge is being used to communicate between the CICS Service Flow Runtime and the service requestor. Do not specify the ReplyToQMgr in the IBM MQ MQMD header structure.

This field can be loaded if the service requester is implementing early reply processing with the queue manager name. The name will be used for any early reply issued.

DFHMAH-MSGID
This field can specify the unique message identifier (MSGID) used to put the CICS Service Flow Runtime request message on the CICS-MQ bridge queue. During asynchronous processing, CICS Service Flow Runtime handles the reply message itself, rather than allowing the bridge to return the reply message. The bridge does not pass the IBM MQ headers to the CICS Service Flow Runtime. Therefore, when you want to correlate request and reply messages, you must explicitly supply a MSGID, rather than allowing it to be generated by the queue manager. When specified, the value is copied to the MQMD CorrelId on MQPUT commands issued from server adapters and on any reply messages to the service requester. This field is an input field.
DFHMAH-CORRELID
This field can specify the correlation identifier used to put the CICS Service Flow Runtime request message on the CICS-MQ bridge queue. The bridge does not pass the IBM MQ headers containing the CORRELID to the CICS Service Flow Runtime. Therefore, when you want your adapters to know the correlid with which the message was put on the queue, you must explicitly supply a CORRELID, rather than allowing it to be generated by the queue manager. This field is an input field. The CICS-MQ bridge requires a Correlid of MQCI-NEW-SESSION on the first message of any unit of work.
DFHMAH-FAILED-PROGRAM
Failed program name. This field indicates the name of the active program when an error occurred causing process failure. This field is an input or output field. It is returned when the value of field DFHMAH-RETURNCODE is not zero. The application can use it in a compensating flow or custom error processing. The CICS Service Flow Runtime does not make use of this field other than to return a value to the service requester upon failure.
DFHMAH-FAILED-NODE
This field indicates the name of the active node when an error occurred causing process failure. This field is an input or output field. It is returned by the CICS Service Flow Runtime when the value of field DFHMAH-RETURNCODE is not zero. The application can use it in a compensating flow or in custom error processing. The CICS Service Flow Runtime does not make use of this field other than to return a value to the service requester upon failure. See the information on the service flow project tool in the IBM Developer for z/OS documentation for detailed information on defining nodes.
DFHMAH-LINKTYPE
Reserved. Do not set a value for this field.
DFHMAH-MORE-DATA-IND
This field indicates that additional response data is available but not deliverable. It is returned by the CICS Service Flow Runtime when the response data is larger than 32 000 bytes. This field is an output field. The value is one of the following:
  • N = no additional response data
  • Y = additional response data
DFHMAH-BRIDGE-RC
This return code is returned by the Link3270 bridge to the CICS Service Flow Runtime. It is returned by the CICS Service Flow Runtime when the value of field DFHMAH-RETURNCODE is not zero. This field is an output field. The initial value of this field is zero.
DFHMAH-STATETOKEN
This field value, if present in a CICS Service Flow Runtime reply message, indicates that Link3270 server adapter processing has left an allocated Link3270 bridge facility with associated facility business state data stored for subsequent reuse. This field is an input and output field. It is returned when request processing is complete. It can be passed in subsequent input request messages to retrieve facility business state data for reuse in Link3270 server adapter processing. The initial value of this field is blanks.

See Administering the Link3270 bridge for more information on Link3270 bridge facilities.

DFHMAH-RESERVED2
Reserved. Do not set a value for this field.