DEFINE

DEFINE_COS adds a class of service definition or modifies a previously defined COS. The definition specifies TG “rows” and node “rows”, which associate a range of node and TG characteristics with weights used for route calculation. The lower the weight the more favorable the route.

VCB Structure

The DEFINE_COS verb contains a variable number of cos_tg_row and cos_node_row structures; the number of each is specified by the num_of_node_rows and num_of_tg_rows parameters. The TG rows are included at the end of the main DEFINE_COS structure, in ascending order of weight; they are followed by the node rows, again in ascending order of weight.

typedef struct define_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      cos_name[8];             /* class of service name      */
   unsigned char      description[32];         /* resource description       */
   unsigned char      reserv1[16];             /* reserved                   */
   unsigned char      transmission_priority;   /* transmission priority      */
   unsigned char      reserv3[9];              /* reserved                   */
   unsigned char      num_of_node_rows;        /* number of node rows        */
   unsigned char      num_of_tg_rows;          /* number of TG rows          */
} DEFINE_COS;

typedef struct cos_tg_row
{
   TG_DEFINED_CHARS   minimum;                 /* minimum                    */
   TG_DEFINED_CHARS   maximum;                 /* maximum                    */
   unsigned char      weight;                  /* weight                     */
   unsigned char      reserv1;                 /* reserved                   */
} COS_TG_ROW;

typedef struct tg_defined_chars
{
   unsigned char      effect_cap;              /* effective capacity         */
   unsigned char      reserve1[5];             /* reserved                   */
   unsigned char      connect_cost;            /* cost per connect time      */
   unsigned char      byte_cost;               /* cost per byte              */
   unsigned char      reserve2;                /* reserved                   */
   unsigned char      security;                /* security                   */
   unsigned char      prop_delay;              /* propagation delay          */
   unsigned char      modem_class;             /* reserved                   */
   unsigned char      user_def_parm_1;         /* user defined parameter 1   */
   unsigned char      user_def_parm_2;         /* user defined parameter 2   */
   unsigned char      user_def_parm_3;         /* user defined parameter 3   */
} TG_DEFINED_CHARS;

typedef struct cos_node_row
{
   COS_NODE_STATUS     minimum;                /* minimum                    */
   COS_NODE_STATUS     maximum;                /* maximum                    */
 
   unsigned char       weight;                 /* weight                     */
   unsigned char       reserv1;                /* reserved                   */
} COS_NODE_ROW;

typedef struct cos_node_status
{
   unsigned char       rar;                    /* route additional resistance*/
   unsigned char       status;                 /* node status                */
   unsigned char       reserv1[2];             /* reserved                   */
} COS_NODE_STATUS;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_DEFINE_COS

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.

description

A null-terminated text string (0-31 characters followed by a null character) describing the COS. This string is for information only; it is stored in the node's configuration file and returned on the QUERY_COS verb, but SNAplus2 does not make any other use of it.

transmission_priority

Transmission priority. Possible values are:

AP_LOW

AP_MEDIUM

AP_HIGH

AP_NETWORK

num_of_node_rows

Number of node rows which follow the DEFINE_COS VCB (after the TG rows). The maximum is 8.

num_of_tg_rows

Number of TG rows which follow the DEFINE_COS VCB. The maximum is 8.

Each TG row contains a set of minimum TG characteristics, a set of maximum TG characteristics, and a weight. When computing the weights for a TG, its characteristics are checked against the minimum and maximum characteristics defined for each TG row. The TG is then assigned the weight of the first TG row which bounds all the TG's characteristics within the limits specified. If the TG characteristics do not satisfy any of the listed TG rows, the TG is considered unsuitable for this COS, and is assigned an infinite weight. The TG rows must be concatenated in ascending order of weight.

cos_tg_row.minimum.effect_cap

Minimum limit for actual bits per second rate (line speed). The value is encoded as a 1-byte floating point number, represented by the formula 0.1 mmm * 2 ^eeeee where the bit representation of the byte is b'eeeeemmm'. Each unit of effective capacity is equal to 300 bits per second.

cos_tg_row.minimum.connect_cost

Minimum limit for cost per connect time. Valid values are integer values in the range 0-255, where 0 is the lowest cost per connect time and 255 is the highest.

cos_tg_row.minimum.byte_cost

Minimum limit for cost per byte. Valid values are integer values in the range 0-255, where 0 is the lowest cost per byte and 255 is the highest.

cos_tg_row.minimum.security

Minimum level of security. Possible values are:

AP_SEC_NONSECURE: No security.
AP_SEC_PUBLIC_SWITCHED_NETWORK: Data is transmitted over a public switched network.
AP_SEC_UNDERGROUND_CABLE: Data is transmitted over secure underground cable.
AP_SEC_SECURE_CONDUIT: Data is transmitted over a line in a secure conduit that is not guarded.
AP_SEC_GUARDED_CONDUIT: Data is transmitted over a line in a conduit that is protected against physical tapping.
AP_SEC_ENCRYPTED: Data is encrypted before transmission over the line.
AP_SEC_GUARDED_RADIATION: Data is transmitted over a line that is protected against physical and radiation tapping.

cos_tg_row.minimum.prop_delay

Minimum limits for propagation delay: the time that a signal takes to travel the length of the link. Specify one of the following values, according to the type of link:

AP_PROP_DELAY_MINIMUM: Minimum propagation delay.
AP_PROP_DELAY_LAN: Delay is less than 480 microseconds (typical for a LAN).
AP_PROP_DELAY_TELEPHONE: Delay is in the range 480-49,512 microseconds (typical for a telephone network).
AP_PROP_DELAY_PKT_SWITCHED_NET: Delay is in the range 49,512-245,760 microseconds (typical for a packet-switched network).
AP_PROP_DELAY_SATELLITE: Delay is greater than 245,760 microseconds (typical for a satellite link).
AP_PROP_DELAY_MAXIMUM: Maximum propagation delay.

cos_tg_row.minimum.user_def_parm_1 through cos_tg_row.user_def_parm_3

Minimum values for user-defined parameters, which you can use to include other TG characteristics not covered by the above parameters. Each of these parameters must be set to a value in the range 0-255.

cos_tg_row.maximum.effect_cap

Maximum limit for actual bits per second rate (line speed). The value is encoded as a 1-byte floating point number, represented by the formula 0.1 mmm * 2 ^eeeee where the bit representation of the byte is b'eeeeemmm'. Each unit of effective capacity is equal to 300 bits per second.

cos_tg_row.maximum.connect_cost

Maximum limit for cost per connect time. Valid values are integer values in the range 0-255, where 0 is the lowest cost per connect time and 255 is the highest.

cos_tg_row.maximum.byte_cost

Maximum limit for cost per byte. Valid values are integer values in the range 0-255, where 0 is the lowest cost per byte and 255 is the highest.

cos_tg_row.maximum.security

Maximum level of security. Possible values are:

AP_SEC_NONSECURE: No security.
AP_SEC_PUBLIC_SWITCHED_NETWORK: Data is transmitted over a public switched network.
AP_SEC_UNDERGROUND_CABLE: Data is transmitted over secure underground cable.
AP_SEC_SECURE_CONDUIT: Data is transmitted over a line in a secure conduit that is not guarded.
AP_SEC_GUARDED_CONDUIT: Data is transmitted over a line in a conduit that is protected against physical tapping.
AP_SEC_ENCRYPTED: Data is encrypted before transmission over the line.
AP_SEC_GUARDED_RADIATION: Data is transmitted over a line that is protected against physical and radiation tapping.

cos_tg_row.maximum.prop_delay

Maximum limits for propagation delay: the time that a signal takes to travel the length of the link. Specify one of the following values, according to the type of link:

AP_PROP_DELAY_MINIMUM: Minimum propagation delay.
AP_PROP_DELAY_LAN: Delay is less than 480 microseconds (typical for a LAN).
AP_PROP_DELAY_TELEPHONE: Delay is in the range 480-49,512 microseconds (typical for a telephone network).
AP_PROP_DELAY_PKT_SWITCHED_NET: Delay is in the range 49,512-245,760 microseconds (typical for a packet-switched network).
AP_PROP_DELAY_SATELLITE: Delay is greater than 245,760 microseconds (typical for a satellite link).
AP_PROP_DELAY_MAXIMUM: Maximum propagation delay.

cos_tg_row.maximum.user_def_parm_1 through cos_tg_row.maximum.user_def_parm_3

Maximum values for user-defined parameters, which you can use to include other TG characteristics not covered by the above parameters. Each of these parameters must be set to a value in the range 0-255.

cos_tg_row.weight

Weight associated with this TG row.

Each node row contains a set of minimum node characteristics, a set of maximum node characteristics, and a weight. When computing the weights for a node, its characteristics are checked against the minimum and maximum characteristics defined for each node row. The node is then assigned the weight of the first node row which bounds all the node's characteristics within the limits specified. If the node characteristics do not satisfy any of the listed node rows, the node is considered unsuitable for this COS, and is assigned an infinite weight. The node rows must be listed in ascending order of weight.

cos_node_row.minimum.rar

Route additional resistance minimum. Values must be in the range 0-255.

cos_node_row.minimum.status

Specifies the minimum congestion status of the node. Possible values are:

AP_UNCONGESTED: The number of ISR sessions is below the isr_sessions_upper_threshold value in the node's configuration.
AP_CONGESTED: The number of ISR sessions exceeds the threshold value.

cos_node_row.maximum.rar

Route additional resistance maximum. Values must be in the range 0-255.

cos_node_row.maximum.status

Specifies the maximum congestion status of the node. Possible values are:

AP_UNCONGESTED: The number of ISR sessions is below the isr_sessions_upper_threshold value in the node's configuration.
AP_CONGESTED: The number of ISR sessions exceeds the threshold value.

cos_node_row.weight

Weight associated with this node row.

Returned Parameters: Successful Execution

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

primary_rc: AP_OK

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 cos_name parameter contained a character that was not valid.
AP_INVALID_NUMBER_OF_NODE_ROWS: The num_of_node_rows parameter was not in the valid range.
AP_INVALID_NUMBER_OF_TG_ROWS: The num_of_tg_rows parameter was not in the valid range.
AP_NODE_ROW_WGT_LESS_THAN_LAST: The node rows were not listed in ascending order of weight.
AP_TG_ROW_WGT_LESS_THAN_LAST: The TG rows were not listed in ascending order of weight.

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

Returned Parameters: State Check

If the verb does not execute because of a state error, SNAplus2 returns the following parameters.

primary_rc

AP_STATE_CHECK

secondary_rc

AP_COS_TABLE_FULL: You cannot define a new COS because this would exceed the maximum number of COS definitions permitted for the node (specified by the cos_cache_size parameter on DEFINE_NODE).

Appendix A “Common Return Codes” lists further secondary return codes associated with AP_STATE_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.

DEFINE_COS

Technical documentation

» Table of Contents