API header fields

A description of each field in the API header follows:

msg_type

Indicates the type and format of message to which this header is attached. An API message can be an indication, a confirmation, or an OSI error. Messages of type API_MSG, API_REG_ACCEPT, API_SVC_COMPLETE, or API_SVC_ERROR contain a formatted string immediately following the API header. This formatted string ends with X'00'.

API_TERMINATE_INSTANCE does not have a string, but X'00' is stored after the local identifier for the convenience of the application program.

CMIP services uses additional values internally for the msg_type field. These values can appear in buffer trace records generated when an application program calls a API function to send data to CMIP services.

Each of the possible msg_type values for APIhdr structure that can be received by an application program is described in the following list.

API_MSG

A CMIP string or a response to a VTAM-specific request or response. An example of a response to a VTAM-specific request is ACF.SubscribeRsp. API_MSG is defined in ACYAPHDH. For a listing, see C language header file (ACYAPHDH).

API_REG_ACCEPT

Sent by CMIP services to indicate that the MIBSendRegister request succeeded. API_REG_ACCEPT is defined in ACYAPHDH. For a listing, see C language header file (ACYAPHDH).

API_SVC_COMPLETE

Sent by CMIP services to indicate that the associated request was processed correctly. This message is returned for unconfirmed CMIP requests. API_SVC_COMPLETE is defined in ACYAPHDH. For a listing, see C language header file (ACYAPHDH).

API_SVC_ERROR

Sent by CMIP services to indicate that the associated request could not be processed. Examples of why it could not be processed are that the string was incorrectly formatted or that there is no network path available to the destination. A specific error code is provided in the message to assist in diagnosing the problem.

In many cases, CMIP services records additional diagnostic information in CMER VIT entry of the VTAM® internal trace. See z/OS Communications Server: SNA Diagnosis Vol 2, FFST Dumps and the VIT for information about the CMER VIT entry. See z/OS Communications Server: SNA Diagnosis Vol 1, Techniques and Procedures for information about how to use the VTAM internal trace.

API_SVC_ERROR is defined in ACYAPHDH. For a listing, see C language header file (ACYAPHDH).

API_TERMINATE_INSTANCE

Sent by CMIP services to indicate that the object has been deregistered.

API_TERMINATE_INSTANCE is defined in ACYAPHDH. For a listing, see C language header file (ACYAPHDH).

api_version

Reserved for use by CMIP services.

origin

Indicates where the message was generated and how the message should be used. Each of the possible origin field values is described in the following list:

ORIGIN_OBJ: Response to a request that was previously submitted by the object receiving the message. The receiving object can use the invoke identifier to look up the previous request.
ORIGIN_REMOTE: Generated by another object and is a form of unsolicited request or linked reply. The object receiving this message should use the invoke identifier from the API header and the association data from the string to respond to the message.

invokeId

Can be used to correlate requests and responses. If the origin field is set to ORIGIN_OBJ, the invoke identifier field was generated by the application program when a previous request was sent to CMIP services. If the origin field is set to ORIGIN_REMOTE, the invoke identifier field was generated by a remote object and must be returned in a response along with the association handle so that the remote object can use it for correlation.

connectId

The connect identifier field is reserved for use by the API.

timestamp

Set by the API when a message is sent to CMIP services.

numLocalIds

Specifies the number of local identifiers following the fixed-size portion of the API header. This field is always zero or one.

resultCode

For API_SVC_ERROR messages, the error code is stored here. The same error code also appears in the string.

localIds

Can contain a local identifier. A local identifier is a unique identifier for an object and was provided to MIBSendRegister when that object was registered. If a local identifer is present, it ranges in size from 1 to 8 bytes. The number of bytes is determined by the application program and is specified in a parameter passed to MIBConnect. This local identifiers field is passed back to the application program unchanged by CMIP services.