QUERY_COS

QUERY_COS returns route calculation information for a specific class of service (COS).

This verb can be used to obtain information about a specific COS or about multiple COSs, depending on the options used.

VCB Structure

typedef struct query_cos
{
   AP_UINT16        opcode;                 /* verb operation code           */
   unsigned char    reserv2;                /* reserved                      */
   unsigned char    format;                 /* reserved                      */
   AP_UINT16        primary_rc;             /* primary return code           */
   AP_UINT32        secondary_rc;           /* secondary return code         */
   unsigned char    *buf_ptr;               /* pointer to buffer             */
   AP_UINT32        buf_size;               /* buffer size                   */
   AP_UINT32        total_buf_size;         /* total buffer size required    */
   AP_UINT16        num_entries;            /* number of entries             */
   AP_UINT16        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
{
   AP_UINT16        overlay_size;           /* size of returned entry        */
   unsigned char    cos_name[8];            /* cos name                      */
   unsigned char    description[32];        /* resource description          */
   unsigned char    reserv1[16];            /* reserved                      */
   unsigned char    transmission_priority;  /* transmission priority         */
   AP_UINT16        num_of_node_rows;       /* number of node rows           */
   AP_UINT16        num_of_tg_rows;         /* number of tg rows             */
   AP_UINT32        trees;                  /* number of tree caches for COS */
   AP_UINT32        calcs;                  /* number of route calculations  */
                                            /*  for this COS                 */
   AP_UINT32        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

overlay_size

For compatability with future releases of SNAplus2, your application must use this field to determine the exact length of the overlay structure returned, and should not rely on the use of the sizeof() function.

buf_ptr

A pointer to a data buffer that SNAplus2 will use to return the requested information.

buf_size

Size of the supplied data buffer.

num_entries

Maximum number of COSs for which data should be returned. To request data for a specific COS rather than a range, specify the value 1. To return as many entries as possible, specify zero; in this case, SNAplus2 will return the maximum number of entries that can be accommodated in the supplied data buffer.

list_options

The position in the list of COSs from which SNAplus2 should begin to return data. Possible values are:

AP_FIRST_IN_LIST: Start at the first entry in the list.
AP_LIST_INCLUSIVE: Start at the entry specified by the cos_name parameter.
AP_LIST_FROM_NEXT: Start at the entry immediately following the entry specified by the cos_name parameter.

For more information about how the list is ordered and how the application can obtain specific entries from it, see “List Options For QUERY_* Verbs”.

cos_name

Class of service name for which data is required, or the name to be used as an index into the list. This value is ignored if list_options is set to AP_FIRST_IN_LIST. The name is an 8-byte type-A EBCDIC string (starting with a letter), padded on the right with EBCDIC spaces if the name is shorter than 8 characters.

Returned Parameters: Successful Execution

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

primary_rc

AP_OK

buf_size

Length of the information returned in the supplied buffer.

total_buf_size

Returned value indicating the size of buffer that would have been required to return all the list information requested. A value greater than buf_size indicates that not all the available entries were returned.

num_entries

Number of entries returned in the data buffer.

total_num_entries

Total number of entries available. A value greater than num_entries indicates that not all the available entries were returned.

Each entry in the data buffer consists of the following parameters:

cos_data.overlay_size

The size of the returned cos_data structure, and therefore the offset to the start of the next entry in the data buffer.

cos_data.cos_name

Class of service name. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded on the right with EBCDIC spaces.

cos_data.description

A null-terminated text string describing the COS, as specified in the definition of the COS.

cos_data.transmission_priority

Transmission priority. Possible values are:

AP_LOW

AP_MEDIUM

AP_HIGH

AP_NETWORK (the highest priority)

cos_data.num_of_node_rows

Number of node rows defined for this COS.

cos_data.num_of_tg_rows

Number of TG rows defined 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 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.

Returned Parameters: Parameter Check

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

primary_rc

AP_PARAMETER_CHECK

secondary_rc

Possible values are:

AP_INVALID_COS_NAME: The list_options parameter was set to AP_LIST_INCLUSIVE, to list all entries starting from the supplied name, but the cos_name parameter was not valid.
AP_INVALID_LIST_OPTION: The list_options parameter was not set to a valid value.

Appendix A “Common Return Codes” lists further secondary return codes associated with AP_PARAMETER_CHECK, which are common to all NOF verbs.

Returned Parameters: Other Conditions

Appendix A “Common Return Codes” lists further combinations of primary and secondary return codes that are common to all NOF verbs.

QUERY_COS

Technical documentation

» Table of Contents

» Index

VCB Structure

Supplied Parameters

Returned Parameters: Successful Execution

Returned Parameters: Parameter Check

Returned Parameters: Other Conditions