QUERY_COS

QUERY_COS returns route calculation information for a specific class of service. The information is returned as a formatted list. To obtain information about a specific COS, or to obtain the list information in several chunks, the cos_name field should be set.

Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field will be ignored. See Querying the Node for background on how the list formats are used. This list is ordered on the cos_name. Ordering is by name length first, and then by ASCII lexicographical ordering for names of the same length (in accordance with IBM's 6611 APPN MIB ordering). If AP_LIST_FROM_NEXT is selected the returned list starts from the next entry according to the defined ordering (whether the specified entry exists or not).

VCB Structure

typedef struct query_cos
{
        unsigned short  opcode;            /* verb operation code           */
        unsigned char   reserv2;           /* reserved                      */
        unsigned char   format;            /* format                        */
        unsigned short  primary_rc;        /* primary return code           */
        unsigned long   secondary_rc;      /* secondary return code         */
        unsigned char   *buf_ptr;          /* pointer to buffer             */
        unsigned long   buf_size;          /* buffer size                   */
        unsigned long   total_buf_size;    /* total buffer size required    */
        unsigned short  num_entries;       /* number of entries             */
        unsigned short  total_num_entries; /* total number of entries       */
        unsigned char   list_options;      /* listing options               */
        unsigned char   reserv3;           /* reserved                      */
        unsigned char   cos_name[8];       /* COS name                      */
} QUERY_COS;

typedef struct cos_data
{
        unsigned short  overlay_size;      /* size of this entry            */
        unsigned char   cos_name[8];       /* COS name                      */
        unsigned char   description[RD_LEN];
                                           /* resource description          */
        unsigned char   transmission_priority;
                                           /* transmission priority         */
        unsigned char   reserv1;           /* reserved                      */
        unsigned short  num_of_node_rows;  /* number of node rows           */
        unsigned short  num_of_tg_rows;    /* number of TG rows             */
        unsigned long   trees;             /* number of tree caches for COS */
        unsigned long   calcs;             /* number of route calculations  */
                                           /* for this COS                  */
        unsigned long   rejs;              /* number of route rejects       */
                                           /* for COS                       */
        unsigned char   reserva[20];       /* reserved                      */
} COS_DATA;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_COS

format

Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.

buf_ptr

Pointer to a buffer into which list information can be written. The application can append data to the end of the VCB, in which case buf_ptr must be set to NULL.

buf_size

Size of buffer supplied. The data returned will not exceed this size.

num_entries

Maximum number of entries to return. The number of entries will not exceed this value. A value of zero means no limit.

list_options

This indicates what should be returned in the list information: The cos_name specified (see the following parameter, cos_name) represents an index value that is used to specify the starting point of the actual information to be returned.

AP_FIRST_IN_LIST: The index value is ignored, and the returned list starts from the first entry in the list.
AP_LIST_FROM_NEXT: The returned list starts from the next entry in the list after the one specified by the supplied index value.
AP_LIST_INCLUSIVE: The returned list starts from the entry specified by the index value.

cos_name

Class-of-service name. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces. This field is ignored if list_options is set to AP_FIRST_IN_LIST.

Returned Parameters

If the verb executes successfully, the Program returns the following parameters:

primary_rc: AP_OK
buf_size: Length of the information returned in the buffer.
total_buf_size: Returned value indicating the size of buffer that would have been required to return all the list information requested. This can be higher than buf_size.
num_entries: Number of entries actually returned.
total_num_entries: Total number of entries that could have been returned. This can be higher than num_entries.
cos_data.overlay_size: The number of bytes in this entry, and hence the offset to the next entry returned (if any).
cos_data.cos_name: Class-of-service name. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
cos_data.description: Resource description (as specified on DEFINE_COS). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
cos_data.transmission_priority: Transmission priority. This is set to one of the following values:
AP_LOW
AP_MEDIUM
AP_HIGH
AP_NETWORK
cos_data.num_of_node_rows: Number of node rows for this COS.
cos_data.num_of_tg_rows: Number of TG rows for this COS.
cos_data.trees: Number of route tree caches built for this COS since the last initialization.
cos_data.calcs: Number of session activation requests (and therefore route calculations) specifying this class of service.
cos_data.rejs: Number of session activation requests that failed because there was no acceptable (using the specified class of service) route from this node to the named destination through the network. A route is only acceptable if it is made up entirely of active TGs and nodes that can provide the specified class of service.

If the verb does not execute because of a parameter error, the Program returns the following parameters:

primary_rc: AP_PARAMETER_CHECK
secondary_rc: AP_INVALID_COS_NAME
AP_INVALID_LIST_OPTION

If the verb does not execute because the node has not yet been started, the Program returns the following parameter:

primary_rc: AP_NODE_NOT_STARTED

If the verb does not execute because of a system error, the Program returns the following parameter:

primary_rc: AP_UNEXPECTED_SYSTEM_ERROR