Description and example of the API header

The API header is built for the application program when the application program calls API functions that send messages to CMIP services. It is returned to the application program when the message is sent from CMIP services to the application program.

The API header begins in the first byte of the message. The length of the header varies according to the size of the local identifier. If the message contains data in addition to the API header, the data begins immediately following the API header.

The C language definition of the API header follows. Note that actual local identifiers vary in size from one to eight bytes in length and can be of any data type. It is declared as an eight-character array for simplicity.

Note: To facilitate reading on any host terminal and printing on any host printer, trigraph sequences have been used for square brackets. These sequences are "??(" for left square bracket and "??)" for right square bracket.

typedef struct APIhdr_tag
{
  unsigned char msg_type;
  unsigned char api_version;
  unsigned char origin;
  unsigned char RESERVED1;          /* Application programs must not
                                       use or depend on the value of
                                       this field in any way.        */
  unsigned int invokeId;
  unsigned int connectId;
  unsigned int numLocalIds;
  time_t timestamp;
  unsigned short resultCode;
  unsigned char RESERVED2??(2??);   /* Application programs must not
                                       use or depend on the value of
                                       this field in any way.        */
  unsigned int  RESERVED3;          /* Application programs must not
                                       use or depend on the value of
                                       this field in any way.        */
  unsigned char localIds??(8??);
} APIhdr;

The actual size of the API header associated with a particular message received from CMIP services is determined by the size of the fixed part (all fields up to but not including the localIDs field) plus the number of attached local identifiers times the size of each local identifier. For this release, the number of attached local identifiers is always one.

The actual size is a useful quantity because the string portions of the message start immediately after the API header.

To make it easier to calculate the actual size, the APIhdrSize macro is provided in the language header file, ACYAPHDH. Given the name of an APIhdr and the size of the application's local identifiers, it returns the actual size of an API header. The following example shows the APIhdrSize macro:

#define MY_LOCAL_ID_SIZE 7
 
APIhdr *APIhdr1;
APIhdr APIhdr2;
size_t Size1, Size2;
 
Size1 = APIhdrSize(*APIhdr1,MY_LOCAL_ID_SIZE);
Size2 = APIhdrSize( APIhdr2,MY_LOCAL_ID_SIZE);