Programming interfaces for providing classification data to be used in differentiated services policies

Applications and users of TCP/IP networks might have different requirements for the service they receive from those networks. A network that treats all traffic as best effort might not meet the needs of such users. Service differentiation is a mechanism to provide different service levels to different traffic types based on their requirements and importance in an enterprise network. For example, it might be critical to provide Enterprise Resource Planning (ERP) traffic better service during peak hours than that of FTP or web traffic. The overall service provided to applications or users, in terms of elements such as throughput and delay, is termed Quality of Service (QoS).

One aspect of QoS is Differentiated Services (DS), which provides QoS to broad classes of traffic or users, for example all outbound web traffic accessed by a particular subnet. z/OS® provides support for DS by allowing network administrators to define policies that describe how different z/OS TCP/IP workload traffic should be treated. Administrators can define service policy rules that identify desired workloads and map them to service policy actions that dictate the DS attributes assigned to these workloads. For more information on QoS and DS, see z/OS Communications Server: IP Configuration Guide.

Service policy rules can specify generic attributes to identify a given workload, such as the server's well-known port or jobname. However, there are cases where a more granular level of classification for a server's outgoing TCP/IP traffic is desired. For example, a server application might provide services for several different types of requests using a single well-known port. A network administrator might want to be able to specify unique DS attributes for each service type the application supports. One way of accomplishing this is by allowing applications to provide additional information that can be used by an administrator to define more granular service policy rules and actions. The programming interfaces described in this topic provide this capability.

Application defined policy classification data can be specified using extensions to the sendmsg() socket API. The sendmsg() API is similar to other socket APIs, such as send() and write() that allow an application to send data, but also provides the capability of specifying ancillary data. Ancillary data allows applications to pass additional option data to the TCP/IP protocol stack along with the normal data that is sent to the TCP/IP network. This ancillary data can be used by the application to define the attributes of the outgoing traffic for a particular TCP connection or for the specific data being sent in that sendmsg() invocation. These extensions to the sendmsg() API are only available to applications using the TCP protocol and the following socket API libraries:

z/OS IBM® C/C++ sockets with the z/OS Language Environment®. For more information about these APIs, see z/OS XL C/C++ Runtime Library Reference.
z/OS UNIX System Services Assembler Callable services socket APIs. For more information about these APIs, see z/OS UNIX System Services Programming: Assembler Callable Services Reference.

The policy classification data is defined by the application and contains one (or both) of the following two formats:

Application defined token: This token is a free format character string that can represent any application defined resource (for example, as transaction identifier, user ID, URL, and so on). When an application passes this token in sendmsg(), TCP/IP will invoke the policy classification function passing it the application-defined token in addition to any of the existing classification attributes (local/remote IP address and port, job name, and so on). The application defined token maps to the ApplicationData attribute of a DS policy rule.
Application priority levels: An application specified priority that maps to one of five predefined QoS service levels: Expedited, High, Medium, Low and Best Effort. Applications using this format of application classification data need to map their outgoing data types to one of these priority levels. For example, the application might already have a concept of transaction priority that it can use to map to one of these priority levels. It is important to note that the priority specified by the application does not automatically translate to a QoS service level. The actual service level assigned is derived by the contents of the service policy. Application priority rules are mapped to the ApplicationPriority attribute of a DS policy rule.

Applications might decide to pass classification data of either format or for both formats. The latter option allows applications to specify the same application defined token yet associate it with different priorities depending on the type of request being processed. For example, an application can pass an application token of ORDER and a HIGH priority for one user and a token of ORDER with a LOW priority for another user. The policy administrator would then be able to distinguish the service level assigned to these two different classes of users. When passing classification data on the sendmsg() API, applications also need to determine the scope of the classification:

Connection-Level: The DS policy action assigned will be used for all traffic on this TCP connection until another sendmsg() with different classification data is specified.
Message-Level: The DS policy action assigned will be used only for the outgoing data passed on this sendmsg() invocation. Any future data sent on this connection without the specification of any classification data will use the original DS policy action that was assigned to this TCP connection.