ISMF - ISC IP Message Formats

  --
  
  The name of this header is defined in constant ISHH_NAME. It is
  the main HTTP header present on all protocol(IPIC) HTTP requests
  and responses.
  
  The IS HTTP header is added by the ISSR send_request and
  send_response functions and inspected by the ISRR
  process_input_queue function to determine what action to take on
  receipt of incoming IPIC data.
  
  It has a prefix and a data component.
  
  The conversation ID, ishh_conv_id, relates the message to its
  session. If a new conversation is to be started on a particular
  previous session, for example to implement the CICS RM Implicit
  Forget protocol, the ishh_prev_conv_id field must be set to the
  conversation ID that used that session previously. Otherwise it
  should be left blank.
  
  The ishh_msg_seqno is incremented for each new request within a
  conversation. This number is allowed to wrap back to 1 after
  999999. The reply carries the same ishh_msg_seqno as the request
  to which it relates.
  
  There may be multiple chain elements within an IS request or
  response. Each IS chain element is an HTTP request or response
  message.
  
  The first or only chain element within a request should have
  ishh_chain_seqno = 1.
  
  A sender must wait for a pacing response after every four
  messages. A pacing message carries no body data.
  
  IS HTTP msgs are:
  
  ISHH_DATA
  half duplex flip-flop, conversation level messages. Change
  direction is implied at the end of every message, or chain of
  messages.
  ISHH_EXPD
  expedited conversation level command messages that carry no body
  data; may be sent with or against the conversation level flow.
  ishh_conv_state should be set to ishh_end, indicating that no
  reply to the conversation level command is expected.
  ISHH_CMD
  connection level command messages are at the IPCONN level and
  carry no body data; the ishh_conv_id and ishh_conv_state are
  ignored.
  
  --------------------------------------------------------------------

  --
  
  This name of this header is defined in constant ISUH_NAME.
  
  It should only be present when using CICS recovery protocol.
  
  The IS HTTP uowid header is added by the ISSR send_request
  function when a new transaction is to be attached in the partner
  system.
  
  The data it contains is binary data, unpacked and converted to
  ASCII for transmission over HTTP.
  
  --------------------------------------------------------------------

  --
  
  This name of this header is defined in constant ISAH_NAME.
  
  It should only be present when a START has been issued where a
  TRUE set adapter data and that START was found to be remote. If
  this header is present there will not be an ODR header.
  
  The IS HTTP adapter header is added by the ISSR send_request
  function when a new transaction is to be attached in the partner
  system.
  
  The data it contains is binary data, unpacked and converted to
  ASCII for transmission over HTTP.
  
  --------------------------------------------------------------------

  --
  
  The generic field header format.
  
  --------------------------------------------------------------------

  --
  
  The Capability Exchange request message (Type 1).
  
  When an IPIC connection is established between two CICS systems,
  or between CICS and a JCA client, an instance of the capability
  exchange message is sent by the initiator, immediately after the
  first socket (WB session) is opened, before the connection can be
  used for any other work.
  
  The Capability Exchange both identifies the partner and defines
  any functional constraints it may have.
  
  The IS HTTP headers (ISHH) associated with the capability exchange
  messages have a convid of 0.
  
  When the initiator of a connection is a CICS system, this message
  is triggered by SET IPCONN ACQUIRED. This SPI command attaches
  transaction CISC which issuse DFHISCO acquire_connection to create
  a socket and send a Capability Exchange to the partner.
  
  The partner CICS attaches the IPIC TCPIPSERVICE protocol
  transaction, CISS by default, to issue DFHISCO
  initialize_connection. The initialize_connection function calls
  the acquire_connection routine to create a similar connection back
  to the initiator, to allow work to be started from the partner
  back to the connection initiator.
  
  If the connection initiator has no requirement for a return
  connection e.g because it doesn't support inbound requests, the
  isce_callback_port should be set to ISCE_NO_PORT. (This is
  currently only supported for recovery protocol XA).
  
  If the partner supports multiple sockets per IPCONN, a capability
  exchange request is sent for each socket opened. Second and
  subsequent capex requests use the isce_reqd_sessions field to
  indicate how many IS sessions are to be allocated to the new
  socket. Data following the comment isce_primary_data is ignored in
  secondary capex requests.
  
  --------------------------------------------------------------------

   isce_primary_data. Data after this point in the isce is ignored
   for secondary capex requests.

  --
  
  The Capability Exchange response message (Type 2).
  
  When iscer_response is iscer_exception, iscer_reason may take any
  of the following values:
  
  REASON(AUTOINSTALL_FAILED)
  No IPCONN was found to match an incoming IPIC connection and
  capability exchange and the subsequent autoinstall attempt was
  disallowed or failed.
  REASON(INVALID_PARTNER_STATE)
  A capability exchange request was received for an IPCONN whose
  state is invalid. The IPCONN must be inservice and not already
  acquired.
  REASON(INVALID_IPCONN_STATE)
  An ISCO ACQUIRE_CONNECTION has been issued for an IPCONN whose
  state is invalid. The IPCONN must be inservice and released.
  REASON(IPCONN_NOT_FOUND)
  An ISCO ACQUIRE_CONNECTION has been issued for an IPCONN which
  no longer exists.
  REASON(ISCE_ERROR)
  The capability exchange request was determined to be invalid and
  rejected by the partner CICS.
  REASON(ISCE_INVALID_APPLID)
  The server_applid, or its high level qualifier, in the
  capability exchange message does not match the partner CICS's
  local applid and high level qualifier.
  REASON(ISCE_TIMED_OUT)
  The TCPIPSERVICE transaction (CISS by default) has been attached
  to initialize a connection for an ipconn but it has not received
  its initial data, the capability exchange request, within the
  timeout period defined in its transaction profile.
  REASON(ISCE_BAD_RECOV)
  A capability exchange request has been received that contains an
  unsupported isce_preferred_recovery value and no matching
  isce_in.isce_supported_protocols flags are set to fallback to.
  REASON(ISCER_BAD_RESPONSE)
  The callback capability exchange response contains a bad isco
  response and reason from the partner CICS.
  REASON(ISCER_ERROR)
  The callback capability exchange response was determined to be
  invalid.
  REASON(ISCER_HTTP_ERROR)
  The callback capability exchange response contained a bad http
  status code.
  REASON(ISCER_TIMED_OUT)
  DFHISCO acquire_connection has not received a response to its
  capability exchange request within the timeout period specified.
  REASON(SESSION_OPEN_FAILED)
  While acquiring an ipconn, DFHISCO has failed to open a web
  session to the partner host defined in the ipconn.
  REASON(SHUTDOWN)
  A call has been made to DFHISCO to acquire or initialize an
  ipconn but CICS has been shutdown before the function completed.
  REASON(TCPIP_CLOSED)
  DFHISCO acquire_connection has been called for an ipconn but
  tcpip is closed.
  REASON(TCPIPSERVICE_MISMATCH)
  A capability exchange request was received for an IPCONN which
  is defined as using a different tcpipservice from that used for
  the capability exchange.
  REASON(TCPIPSERVICE_NOT_FOUND)
  Either acquire_connection has been called for an ipconn but the
  tcpipservice named in the ipconn is not installed or
  release_connection has been called for a tcpipservice that is no
  longer installed.
  REASON(TCPIPSERVICE_NOT_OPEN)
  DFHISCO acquire_connection has been called for an ipconn but the
  tcpipservice named in the ipconn is not open.
  REASON(NO_IPCONN)
  DFHISCO acquire or release_connection has been called for a
  tcpipservice that has no ipconn referencing it.
  REASON(ISCER_ONE_WAY_IPCONN)
  The caller requires a two-way connection but the partner IPCONN
  is defined as one-way.
  REASON(ISCER_SECURITY_VIOLATION)
  The security credentials of the caller are not
  REASON(ISCER_SEC_SOCK_ERROR)
  An error occured while attempting to obtain a secondary socket.
  REASON(ISCER_CLIENT_CONNECTION_CLOSED)
  The client connection has been closed.
  REASON(ISCER_INVALID_HA_TCPIPSERVICE)
  TCPIPS attributes in server region are invalid for HA.
  REASON(ISCER_HA_RESOURCE_MISMATCH)
  Resource definitions in client and server regions to establish a
  high availability connection do not match.
  
  --------------------------------------------------------------------

  --
  
  The Bracket Initiation Stopped (BIS) request message (Type 3)
  and the Bracket Initiation Stopped (BISR) response message
  (Type 4) have the same format.
  
  When an IPIC connection between two CICS systems is released, a
  drain command is sent by the initiator causing both sides to
  quiesce: current and queued work is processed, no new work is
  accepted. Once all activity on the ipserver connection has
  terminated, a BIS message and response is exchanged prior to
  closing the web session (socket) IF any send session is flagged
  send or receive forget pending i.e if any conversation on that
  session has terminated leaving an RM link pending.
  
  The BIS message carries a list of conversations for which forget
  is pending.
  
  --------------------------------------------------------------------

  --
  
  The Syncpoint Command field (Type 6).
  
  The normal syncpoint exchange is as follows:- Initiator
  -----------Prepare----------> Agent 1 <------Request
  Commit--------
  Initiator -------Request Commit-------> Agent 2 (=last agent)
  <----------Committed--------- ------------Forget---------->
  Initiator -----------Committed--------> Agent 1
  <-----------Forget-----------
  
  Alternate flows - When the decision is to roll back the UOW, then
  the coordinator sends an FMH7 as the data portion of the Type 6
  field.
  
  Resync Flows - Type 6 fields are also used in resync messages,
  exchanged between CICS regions. The are preceeded by a Type A
  field except in the case of a Forget flow, which contains only the
  Type 6 forget field.
  
  XA Resync Flows - An XA client may scheule a resync attempt with
  CICS by calling the CISX transaction and passing it a message
  containing a Type 6 field followed by a Type C field. The Type 6
  field indicates the decision for the UOW, which must either be
  COMMITTED or FMH7 (= ROLLBACK).
  
  --------------------------------------------------------------------
     Structure of the PS Header used for 2PC protocol messages

  --
  
  The Conversation Error field (Type 7).
  
  IS7 messages are similar in intent and content to the SNA FMH7.
  Their purpose is to notifiy a partner of an error situation. They
  can be sent from client to server or server to client at any time
  during a conversation whether the sending partner is in send or
  receive state.
  
  SENSE CODES
  
  Many of the sense codes used are equivalent, and have the same
  value as those used previously in SNA FMH7 messages (see the SNA
  Formats manual). However, as this function is developed it is
  expected that new IS domain specific sense codes will be
  introduced. Those beginning 0000 are IPIC specific.
  
  - 00000001 ROUTED_TRANS_ABENDED
  
  transaction routed task abended
  
  - 080F0983 ACCESS_DENIED
  
  security error.
  
  - 080F6051 SECURITY_NOT_VALID
  
  security error.
  
  - 08240000 TASK_BACKED_OUT
  
  conversation id no longer valid; task was backed out.
  
  - 08390000 IPCONN_QUIESCING
  
  transaction attach rejected; the partner system is quiescing.
  
  - 084C0000 NOT_AVAIL_NO_RETRY
  
  transaction attach rejected; trans id known but disabled.
  
  - 08640001 DEALLOCATE_ABEND_SVC
  
  mirror has abended.
  
  - 1008600B RESOURCE_FAILURE
  
  system error.
  
  - 10086021 TPN_NOT_RECOGNIZED
  
  transaction attach rejected; unknown transid.
  
  Subfields
  
  - Type 1 - the text of an associated error message.
  
  --------------------------------------------------------------------

  --
  
  The Security field (Type 8).
  
  Subfields
  
  - Type 1 - Userid
  
  - Type 2 - Password
  
  --------------------------------------------------------------------

        including this subfield header

     Fields at is8_string

  --
  
  The External Security Interface field (Type 9).
  
  Subfields
  
  - Type 1 - Userid
  
  - Type 2 - Password (1-8 chars) or Password Phrase (9-100 chars)
  
  --------------------------------------------------------------------

  ------------------------------------------------------------------
  Input_TP_LLID
  The Input_TP_LLID consists of a second LLID pair and data
  TP_LL is the total length of the TP record.
  TP_ID is the indicator for SIGN-ON or SIGN-ON/CHANGE_PASSWORD.
  TP_Data contains the data for this LLID. It is a series of
  variable length subfields.
  
  The Input_TP_LLID has the following format:
  ----------------------------------------------
  | L | I | Input_Data | Input_Data | Input_Data |
  | L | D | SF(1) | SF(2) | SF(3) |
  ----------------------------------------------
  ------------------------------------------------------------------

  ------------------------------------------------------------------
  Input_SF_LID
  Each Input_SF_LID consists of a one byte length, an Id field
  and a variable length data field.
  SF_L is the total length of the SF record.
  SF_Id indicates which subfield type it is.
  SF_Data contains the data for this subfield.
  
  The subfields have the following format:
  ------------
  |L|I| SF_Data|
  | |d| |
  ------------
  ------------------------------------------------------------------

  ------------------------------------------------------------------
  Output_GDS_LLID
  The Output Data consists of an initial LLID pair and data
  GDS_LL is the total length of Output Data.
  GSD_ID is the indicator for SIGN-ON data.
  GDS_Data contains the data to be passed to the partner.
  
  The Output_GDS_LLID has the following format:
  ---------------------------------------------------------
  | L | I | Output_GDS_Data |
  | L | D | |
  ---------------------------------------------------------
  
  Within the Output_GDS_Data exists a second LLID pair called the
  TP record
  TP_LL is the total length of the TP record.
  TP_ID is the indicator for SIGN-ON reply data.
  TP_Data contains the data for this LLID. It is a series of
  variable length subfields.
  
  The Output_TP_LLID has the following format:
  -------------------------------------------------
  | L | I | Output_Data | Output_Data | Output_Data |
  | L | D | SF(1) | SF(2) | SF(3) |
  -------------------------------------------------
  
  Each subfield has the following format:
  -------------
  |L|I| SF_Data |
  | |d| |
  -------------
  
  ------------------------------------------------------------------

  --
  
  The ICRX Security field (Type 19).
  
  This field may appear together with or without an IS-8 field in a
  message.
  
  The format of the ICRX data is not known to the IS domain, and can
  be found in the IRRPICRX macro.
  
  --------------------------------------------------------------------

     Need to pull in the GDS structure from ISXS at some point
  --
  
  The UOWID recovery field (Type A).
  
  The Type A field is included as part of a DPL request between CICS
  regions. It contains the coordinating UOWID, that is then added to
  the participant's RM link for its principle facility.
  
  The Type A field also forms the first part of a resync message,
  sent between CICS regions. If the corresponding UOW, or an RM link
  containing it, cannot be found then the response sent back
  contains only a Type A field with the unresolved UOWID in it,
  indicating the resync attempt for that UOW has failed.
  
  --------------------------------------------------------------------

  --
  
  The XID recovery field (Type B).
  
  A Type B field is included in a DPL request from an XA client when
  the request is intended to form part of an extended UOW. CICS
  takes the XID from the Type B field and stores it with the
  corresponding UOW. It can then be matched to a resync attempt
  should one be necessary.
  
  --------------------------------------------------------------------

  --
  
  The XID recovery list field (Type C).
  
  An XA client can request that CICS carrys out a search for any
  in-doubt UOWs that have XIDs associated with them. It does so by
  sending a message to CICS to start transaction CISX, passing it no
  data. The transaction runs and returns a Type C field. The field
  consists of 0 to N xidrl_item blocks of data.
  
  An XA client can ask CICS to carry out a resync attempt for a
  specific UOW, by calling the CISX transaction and passing it a
  message containing a Type 6 field followed by a Type C field. The
  Type 6 field contains the UOWs decision, and the Type C contains a
  single recovery list item - UOW token + XID. The UOW token may be
  set to null when the XA client does not have access to this
  information.
  
  --------------------------------------------------------------------

  --
  
  The ReSync Outcome field (Type C).
  
  The Type C field is exchanged by a pair of CICS regions that are
  involved in a resync attempt relating to a particular connection.
  One region initiates the resync attempt and, when it has completed
  processing the RM links that it has found, sends a message
  comprising only of this field to the partner region. The partner
  then processes any RM links that it has and responds with its own
  Type C message.
  
  --------------------------------------------------------------------

  --
  
  The API Request/Response field (Type 43). Note that the length
  field for the fixed length part is one byte rather than two to
  maintain consistency with SNA FMH43 so that the transformer code
  ported into DFHISXF can work unchanged. The same header is used
  for requests and responses. Request flows include subfields for
  the input parameters. Response flows include subfields for the
  output parameters.
  
  Subfield types are assigned to all fields on a particular command
  that can be shipped, as follows:
  FOR EXEC CICS LINK 02 program 04 length 06 commarea 08 transid 0A
  hex transid
  
  --------------------------------------------------------------------

  --
  
  The Channel header field (Type 44). This structure MUST match the
  definition of DFHCHAN in DFHAPCR. If present, this field will
  always follow an IS43, and will be followed by zero or more IS45s.
  
  --------------------------------------------------------------------

  --
  
  The Container field (Type 45). This structure MUST match the
  definition of DFHCHDR in DFHAPCR. The container data follows
  immediately after the DFHCHDR fields. Note that the upper size
  limit for an individual container is currently 2G-1. The bin(32)
  length in the IS45 header allows for containers up to
  4G-1-length(isfld)-length(dfhchdr), so it is sufficient for the
  time being. If containers longer than this are ever supported, a
  new IS field that allows splitting of a container into multiple
  fields will be required. Every instance of this field will always
  be preceded by either another IS45 or an IS44.
  
  --------------------------------------------------------------------

  --
  
  The Transaction Routing Attach field (Type 50).
  
  This IS field is used to identify a request by a routing region
  for a transaction routed transaction to be attached.
  
  It carries transaction identification and terminal identification
  parameters together with other parameter information for the
  transaction that is to be attached in an AOR.
  
  It is also followed by argument fields that are created and
  interpreted by the IPIC Transaction Routing Transformer DFHAPRX.
  
  --------------------------------------------------------------------

  --
  
  The Transaction Routing Inquire Request field (Type 51).
  
  This IS field is used to identify a request issued by an
  application owning region to a routing region for terminal
  definition parameters. It also identifies a response.
  
  For a response, this IS field carries AP domain parameter
  information in argument fields. This parameter information is a
  Builder Parameter Set that is supplied by ZC Builder modules
  (DFHBSxxx modules) from a DFHZCQ function INQUIRE and used as
  input to ZC Builder modules with a DFHZCQ function INSTALL to
  install a terminal definition in the AP domain of an application
  owning region.
  
  --------------------------------------------------------------------

  --
  
  The Transaction Routing Relay Request field (Type 55).
  
  This IS field is used to identify a terminal request issued in an
  application owning region that is to be relayed to a routing
  region. It also identifies a response.
  
  It carries AP domain parameter information in argument fields that
  identify the terminal request or response. The argument fields are
  created and interpreted by the IPIC Transaction Routing
  Transformer DFHAPRX.
  
  --------------------------------------------------------------------

  --
  
  The Transaction Routing Schedule Request field (Type 60).
  
  This IS field is used to identify a remote schedule request. This
  could be a remote terminal request issued in response to a
  terminal START and flowing from the AOR to the TOR, or a remote
  delete request for a badly-disconected terminal that had been
  running CRTE flowing from the TOR to the AOR.
  
  The flow is sent by and receieved by DFHCRS.
  
  --------------------------------------------------------------------

        (CRSTRNID)

        (CRSFQTID)

  --
  
  The Transaction Routing Schedule Response field (Type 61).
  
  This IS field is used to identify a remote schedule response. This
  is the response to the IS60 remote schedule request described
  above.
  
  The flow is sent by and receieved by DFHCRS.
  
  --------------------------------------------------------------------

  --
  
  The ACD field (Type 62).
  
  This field may appear if application context needs to be passed on
  a request.
  
  The format of the ACD data is not known to the IS domain, and can
  be found in DFHMNAC.
  
  --------------------------------------------------------------------

Constants for the IS HTTP header names.

The HTTP header names and character data will be converted to
ASCII for transmission.

--------------------------------------------------------------------

   Values of major_version

   Values of minor_version

   Values of ishh_chain

   Values of ishh_conv_state

   Values of ishh_msg_type

   Values of ishh_request_type

   ishh_ccsid, required for msg_type=D & conv_state=B, has value:
   - a 5 digit decimal IBM CCSID supported by dfhcnv or
   - blanks for no data conversion for e.g DPL commareas or
   - minus one for the default client code page (CLINTCP) to be used
     e.g. for when the input CCSID can not be determined

   Values of ishh_endian for msg_type=D if conv_state=B

   Values of ishh_cmd_id for ishh_msg_type=ISHH_CMD

   Both the connection level ping flows consist of an IS Header and a
   zero length message body.
   Values of ishh_cmd_id for ishh_msg_type=ISHH_EXPD

Constants for the types of the IS message fields. All data within
the request or response message is preceded by a header containing
one of these types.

--------------------------------------------------------------------
   TYPE 1 - CAPABILITIY EXCHANGE REQUEST

   TYPE 2 - CAPABILITIY EXCHANGE RESPONSE

TYPE 3 - BRACKET INITIATION STOPPED (BIS) REQUEST

   TYPE 4 - BRACKET INITIATION STOPPED (BIS) RESPONSE

   TYPE 6 - SYNCPOINT COMMAND (= SNA PS Header)

   TYPE 7 - CONVERSATION ERROR (= SNA FMH7)

   TYPE 8 - SECURITY

   TYPE 9 - ESI

   TYPE 10 - UNIT OR WORK ID RECOVERY DATA

   TYPE 11 - XID RECOVERY DATA

   TYPE 12 - XID RECOVERY LIST

   TYPE 13 - RESYNC OUTCOME

   TYPE 19 - ICRX = ID-propagation

   TYPE 43 - API REQUEST/RESPONSE (= SNA FMH43)

   TYPE 44 - CHANNEL HEADER

   TYPE 45 - CONTAINER

   TYPE 46 - FREE REQUEST

   TYPE 50 - TRANSACTION ROUTING ATTACH REQUEST

   TYPE 51 - TRANSACTION ROUTING INQUIRE REQUEST/RESPONSE

   TYPE 55 - TRANSACTION ROUTING RELAY REQUEST/RESPONSE

   TYPE 60 - TRANSACTION ROUTING SCHEDULE REQUEST

   TYPE 61 - TRANSACTION ROUTING SCHEDULE RESPONSE

   TYPE 62 - APPLICATION CONTEXT HEADER

   Values of isce_sub_type

   Values of major_version

   Values of minor_version

   Values of isce_callback_port (1-65535 or IS_NO_PORT)

   Values of isce_recovery

   Values of iscer_sub_type

   Values of iscer_response

   Values of iscer_reason

     NOTE - remember to change the logic in dfhisco_check_iscer_reason
     when any new reason codes are added here.

   Values of isbis_conv_resp

     PS LL value is fixed for all messages

     Header Length constants for SP messages

     Default syncpoint control type - always 0001010b

     Flag byte values

     Command byte values

     SyncPoint Control Modifications

    FMH7 Sense Codes used by IS domain in IS7 fields.

   Values for is8_type

   Values for is8_string_password_type

     Various GDS field length constants

      Identifiers used for describing GDS input and output data

      Valid Subfield identifiers

      Reasons used for Unsuccessful Reply

      Invalid Data Format format errors

   Constant for chan_version

   Constant for chan_eye

   Constant for chdr_eye

   Values for chdr_datatype