A key difference in the sendmsg() API versus the more common send() API is that most parameters are passed in a message header input parameter. The mapping for the message header is defined in socket.h for C/C++ and in the BPXYMSGH macro for users of the UNIX System Services Assembler Callable services. For simplicity, only the C/C++ version of the data structures is shown in this topic:

struct msghdr {                                                 
    void               *msg_name;              /* optional address           */   
    size_t             msg_namelen;            /* size of address            */ 
    struct             iovec *msg_iov;         /* scatter/gather array       */  
    int                msg_iovlen;             /* # elements in msg_iov      */  
    void               *msg_control;           /* ancillary data             */  
    size_t             msg_controllen;         /* ancillary data length      */  
    int                msg_flags;              /* flags on received msg      */  
};            
                                                 

The following list shows some key points regarding the usage of sendmsg() for the purpose of passing application defined classification data:

• Because application policy classification data is supported only for TCP sockets, the msg_name and msg_namelen parameters are not applicable.
• Data to be sent using sendmsg() needs to be described in the msg_iov structure.
• The address of the ancillary data is passed in the msg_control field.
• msg_controllen contains the length of the ancillary data passed.
  Note: If multiple ancillary data sections are passed, this length should reflect the total length of ancillary data sections.
• msg_flags is not applicable for sendmsg()

The ancillary data (in this case the application classification data) is pointed to by the msg_control parameter. This msg_control pointer points to the following structure (C/C++ example shown below) that describes the ancillary data (also defined in socket.h and BPXYMSGH respectively):

 struct cmsghdr  {                                               
    size_t   cmsg_len;       /* data byte count includes hdr */ 
    int      cmsg_level;     /* originating protocol         */ 
    int      cmsg_type;      /* protocol-specific type       */ 
   /* followed by u_char    cmsg_data[]; */
 };            

• The cmsg_len should be set to the length of the cmsghdr plus the length of all application classification data that follows immediately after the cmsghdr. This is represented by the commented out cmsg_data field.
• The cmsg_level must be set to the constant IPPROTO_IP for AF_INET sockets and IPPROTO_IPV6 for AF_INET6 sockets. IPPROTO_IP and IPPROTO_IPV6 are defined in in.h and BPXYSOCK.
• The cmsg_type must be set to the constant IP_QOS_CLASSIFICATION_DATA (defined in header file ezaqosdc.h for C/C++ users and in macro EZAQOSDA for assembler users). The header file and macro are both included in the SEZANMAC data set. This data set must be available in the concatenation when compiling or assembling a part that makes use of these definitions.

The data that follows the cmsghdr structure is described by the following structure:

struct ip_qos_classification_data {   
  int            ip_qos_version;              /* Version of structure       */
  int            ip_qos_classification_scope; /* Classification Scope       */
  int            ip_qos_classification_type;  /* Type of QoS classification */
  u_char    ip_qos_reserved[12];              /* Reserved for IBM use       */
  int            ip_qos_appl_token_len;       /* Length of application data */
 /*  u_char  ip_qos_appl_token[128];     /* Application Classification Token*/
}

The ip_qos_classification_data structure should be filled in as follows:

• ip_qos_version: This field indicates version of the structure. This must be filled in using the constant IP_QOS_CURRENT_VERSION.
• ip_qos_classification_scope: Specify a connection level scope (use constant IP_QOS_CONNECTION_LEVEL) or a message level scope (constant IP_QOS_MESSAGE_LEVEL).

  Connection level scope indicates that the DS policy action assigned by the way of classification of this message will remain in effect for all subsequent messages sent until a sendmsg() with new classification data is issued. Message level scope indicates that the DS policy action assigned will be used only for the message data included in this sendmsg() invocation. Future data sent without classification data will inherit the previous connection level DS policy action assignment (from last Connection Level classification by the way of sendmsg() or from the original TCP connection classification during connection establishment).

• ip_qos_classification_type: This specification indicates the type of classification data being passed. An application can choose to pass an application defined token, an application specified priority, or both a token and a priority. If the latter option is selected the two selected classification types should be logically ORed together. The following types can be specified:
  • Application defined token classification. A single type should be specified. If more than one type is specified the results are unpredictable.
    • IP_SET_QOSLEVEL_W_APPL_TOKEN_ASCII: This indicates that the classification data is a character string in ASCII format. When this option is specified the application token needs to be passed in the ip_qos_appl_token field.
      Note: If the application needs to pass numerical values for the classification data it should first convert them to printable ASCII format. Also note that the string specified can be in mixed case and will be used in the exact format specified for comparison purposes.
    • IP_SET_QOSLEVEL_W_APPL_TOKEN_EBCDIC: Same as above except that the string is in EBCDIC format.
      Note: The IP_SET_QOSLEVEL_W_APPL_TOKEN_ASCII does perform slightly better than this option as the application data specified in the policy is saved in ASCII format inside of the TCP/IP stack, thereby eliminating the need to translate the application defined token on every sendmsg() request.
  • Application defined priority classification. A single type should be specified. If multiple priority types are specified the results are unpredictable.
    • IP_SET_QOSLEVEL_EXPEDITED: Indicates that Expedited priority is requested.
    • IP_SET_QOSLEVEL_HIGH: Indicates that High priority is requested.
    • IP_SET_QOSLEVEL_MEDIUM: Indicates that Medium priority is requested.
    • IP_SET_QOSLEVEL_LOW: Indicates that Low priority is requested.
    • IP_SET_QOSLEVEL_BEST_EFFORT: Indicates that Best Effort priority is requested.
  • ip_qos_appl_token_len: The length of the ip_qos_appl_token specified. This length should not include any null terminating characters.
  • ip_qos_appl_token: This virtual field immediately follows the ip_qos_classification_len field and contains the application classification token string in either ASCII or EBCDIC format depending on which flavor of IP_SET_QOSLEVEL_W_APPL_TOKEN_xxxx was specified for the classification type. This field is referenced only when an application defined token type is specified. Note that this string should not exceed 128 bytes. If a larger size is specified, only the first 128 bytes will be used.