DFHMAH field definitions

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 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 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 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. This is the format name of the application data that follows the DFHMAH structure or if using the Link3270 Passthrough, the STRUCID of the CICS® Service Flow Runtime header that follows (MAH2). 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 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 adapter request processing. The Compcode, Mode, Suspstatus, Abendcode and Message fields can contain additional information. The value is one of the following:
  • 0 = Normal
  • 9 = Error
  • 99 = Multiple errors
  • 999 = Abend

Depending on the processing mode (asynchronous, synchronous, or synchronous rollback), a value other than zero in this field can indicate an incomplete BTS process. This process will remain in an incomplete status until some action is taken. See the description of field DFHMAH-COMPCODE.

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

DFHMAH-COMPCODE
The completion status of the BTS process instance. This describes the outcome of the BTS process that implements an instance of the CICS Service Flow Runtime. This is an output field. The initial value of this field is zero. See the CICS Business Transaction Services manual for a description of the CHECK ACQPROCESS command.
DFHMAH-MODE
The processing state of the BTS process instance. This 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. The initial value of this field is zero. See the CICS Business Transaction Services manual for a description of the CHECK ACQPROCESS command.
DFHMAH-SUSPSTATUS
The suspend status of the BTS process. This is an output field. The initial value of this field is zero. See the CICS Business Transaction Services manual for a description of the CHECK ACQPROCESS command.
DFHMAH-ABENDCODE
This field contains the ABEND code if present. The value returned in this field is dependent on the DFHMAH-RETURNCODE field. This is an output field and the initial value is blanks. See CICS Messages and Codes for complete list.
DFHMAH-MESSAGE
The error message returned from CICS Service Flow Runtime. The value returned in this field is dependent on the DFHMAH-RETURNCODE field. This is an output field and the initial value is blanks. See Error messages 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 is the initial value of the field. A value of 0 indicates standard sequence flow processing of an adapter service that was modeled and generated from Service Flow Modeler and deployed to the CICS Service Flow Runtime environment, where a BTS process instance is created to execute an inbound request from a service requestor.

  • 2 = compensate

    A value of 2 indicates that should a BTS process instance fail, the process is cancelled and a compensating flow runs instead.

  • 3 = passthrough processing (applies only to Link3270 server adapters)

    A value of 3 indicates a passthrough processing mode, where no modeled, generated or deployed Adapter service are executed. Instead, the CICS Service Flow Runtime initiates and processes CICS target applications based on the information that was contained in the request message. This processing mode also creates a BTS process instance to execute the inbound passthrough request. This processing mode always requires the header structures DFHMAH2, CIA-SCREEN-HEADER and CIA-MAP-HEADER

  • 9 = cancel

    A value of 9 indicates that should a BTS process instance fail, the process is cancelled.

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

DFHMAH-PROCESSTYPE
This field categorizes and defines the type of the new process instance. It is controlled by the service requestor. The value in this field must be defined to CICS. The CICS definition is done through resource definition online (RDO) or through CICSPlex® SM Business Application Services (BAS) and assigns resources (repository, audit log). It is used on the BTS DEFINE PROCESS command in the DPL Stub program (DFHMADPL or DFHMADPP).

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.

This field does not need to be specified if the DFHMAH-UOWCONTROL field has a value of 9. Due to the relationship between 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. It is used on the BTS DEFINE PROCESS command in the DPL Stub program (DFHMADPL or DFHMADPP). This field ensures that each BTS process has a unique name. See the CICS Business Transaction Services manual for a description. This is an input or output field. The initial value of this field is blanks.

If no value is provided, the CICS Service Flow Runtime will generate a unique identifier and return it to the service requestor. When generated, the user id for which the Stub program is running, Eibtaskn, and the AbsTime values are concatenated in that order and are used as the process name.

This field does not need to be specified if the DFHMAH-UOWCONTROL field has a value of 9.

DFHMAH-REQUESTNAME
This field indicates the name of the request to process. The value specified is used to read the CICS Service Flow Runtime Properties file to determine processing flow and parameters. The value must correspond to the name on a TYPE=R Property file record. The name can specify either a new request name or a request name of a compensation request. A compensation request name means that the flow will be used to compensate for a previously failed CICS Service Flow Runtime process. This is an input field. See How compensation processing works for a description of compensation processing.

The initial value of this field is blanks. This field does not need to be specified if the DFHMAH-UOWCONTROL field has a value of 9.

Note: The request name (DFHMAH-REQUESTNAME) must be passed in as part of the request message in the message header structure (DFHMAH). In CICS Service Flow Runtime passthrough processing, the Properties file is not used. However, the request name still must be passed in as part of the request message as it is used as the activity name on the BTS DEFINE ACTIVITY command when defining the Passthrough Manager (DFHMALPT) activity.
DFHMAH-DATALENGTH
This field indicates the length of the inbound request or outbound reply data following this header structure data inclusive of any CICS Service Flow Runtime passthrough header structures, if present, and any application request/reply data. This length does not include the lengths of any WebSphere® MQ header structures and the length of this DFHMAH header structure.

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, XML declaration data, etc., if present.

For passthrough and non-passthrough XML request messages, this field value and definition are different depending on the type of request being processed by the CICS Service Flow Runtime as follows:
  • For non-passthrough XML requests, this field should indicate the length of the application request data in fixed format (i.e., the length of the COBOL fixed length group item copybook generated and deployed by the WebSphere Developer for System z® tool that maps this application request data used in the deployed Adapter service).
  • For XML and non-XML passthrough requests, this field should indicate the total of the fixed format length of the passthrough header structure, DFHMAH2 (+164 bytes), plus the fixed format length of the CIA-SCREEN-HEADER structure (+36 bytes) plus the fixed format length of the CIA-MAP-HEADER structure (+102 bytes) plus the fixed format length of any application data structure (ADS), 3270 datastream or unformatted application request data if present.

    This field should NOT indicate the length of the XML formatted request application data on input. The field value may be larger than the actual length of the request data passed but should not be smaller than required or data truncation may occur causing unexpected results.

This field is input on requests and output on replies. For inbound non-passthrough request messages, this field determines the length of the input data container that holds the request application data. The initial value of this field is zero. The request data length is determined by the service requestor. The reply data length is set by the CICS Service Flow Runtime.

DFHMAH-FAILED-PROCNAME
Failed process name. This field indicates the name of the failed process. This 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. It must be specified 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 is an input or output field. It is returned by the CICS Service Flow Runtime when RETURNCODE is not zero. It must be specified 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 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. It can be used by the application 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 requestor upon failure.
DFHMAH-REPLYTOQ
Name of the reply queue. This is the name of the message queue to which the CICS Service Flow Runtime should send reply messages. This is an input field. See the WebSphere MQ Application Programming Reference for a description. This field must be specified if the processing request mode indicates asynch, and the WebSphere MQ CICS bridge is being used to communicate between the CICS Service Flow Runtime and the service requestor. In this case, ReplyToQ should not be specified in the WebSphere MQ MQMD structure.

This field can be loaded if you are implementing early reply processing (MsgType = +2) with the queue name. The name will be used for any early reply issued. This field has no effect on MsgType +8 (Datagrams). MsgType + 8 requires the queue name be specified on the properties file.

DFHMAH-REPLYTOQMGR
This is the name of the queue manager to which the CICS Service Flow Runtime should send reply messages. This is an input field. Replytoq is the local name of a queue that is defined on this queue manager. See the WebSphere MQ Application Programming Reference for a description. This field must be specified if the processing request mode indicates asynch, and the WebSphere MQ-CICS bridge is being used to communicate between the CICS Service Flow Runtime and the service requestor. In this case, ReplyToQMgr should not be specified in the WebSphere MQ MQMD structure.

This field can be loaded if the customer is implementing early reply processing (MsgType = +2) with the queue manager name. The name will be used for any early reply issued. This field has no effect on MsgType +8 (Datagrams). MsgType + 8 requires the queue name be specified on the properties file.

DFHMAH-MSGID
This field can specify the unique message identifier (MSGID) used to put the CICS Service Flow Runtime request message on the WebSphere MQ-CICS bridge queue. During asynchronous (update) processing, CICS Service Flow Runtime handles the reply message itself, rather than allowing the bridge to return the reply message. The CICS Service Flow Runtime is not passed the WMQ headers (containing the MSGID) by the bridge. 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 PUT commands issued from CICS Service Flow Runtime server adapters and on any reply messages to the service requestor. It 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 WebSphere MQ-CICS bridge queue. CICS Service Flow Runtime is not passed the MQ headers (containing the CORRELID) by the bridge. Therefore, when you want your adapters to know what correlid the message was put with, you must explicitly supply a CORRELID, rather than allowing it to be generated by the queue manager. It is an input field. Note that the WebSphere MQ-CICS 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 is an input or output field. It is returned when the value of field DFHMAH-RETURNCODE is not zero. It can be used by the application 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 requestor upon failure.
DFHMAH-FAILED-NODE
This field indicates the name of the active node when an error occurred causing process failure. This 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 It can be used by the application 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 requestor upon failure. See the information on the Service Flow Modeler in the WebSphere Developer for System z information center for detailed information on defining nodes.
DFHMAH-LINKTYPE
This field indicates the behavior of the interface used to initiate the CICS Service Flow Runtime. The initial value of this field is zero. Acceptable values are as follows:
  • zero = asynchronous interface (MQSeries-CICS bridge)
  • +1 = synchronous interface (DPL, EXCI, ECI i.e., CICS or CICS Transaction Gateway)

The value specified in this field overrides the corresponding value on the properties file for the request. So, if the request type property is set to asynchronous (Request Type = 0) on the Properties file, but DFHMAH-LINKTYPE = 1 (synchronous) on the request message, then the request processing associated with this process, will be synchronous.

DFHMAH-MORE-DATA-IND
This field indicates if additional response data is available but could not be delivered. It is returned by the CICS Service Flow Runtime when the response data is larger than 32,000 bytes. This 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 mechanism 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 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 is an input and output field. It is returned when request processing is complete. It may be passed in on 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 CICS External Interface Guide Version 2 Release 2 or higher for more information on Link3270 bridge facilities.

DFHMAH-RESERVED2
Reserved.