DEFINE_COS

DEFINE_COS adds a class-of-service definition. The DEFINE_COS verb can also be used to modify any fields in a previously defined COS.

The definition provides node and TG rows. These rows associate a range of node and TG characteristics with weights that are 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 overlays. The cos_tg_row structures are concatenated onto the end of DEFINE_COS (and ordered in ascending weight) and are followed by the cos_node_row structures (also ordered in ascending weight).
typedef struct define_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   cos_name[8];      /* class-of-service name       */
        unsigned char   description[RD_LEN];
                                          /* resource description        */
        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_node_row
{
        COS_NODE_STATUS minimum;          /* minimum                     */
        COS_NODE_STATUS maximum;          /* max                         */
        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;
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;      /* modem class                 */
        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;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_DEFINE_COS
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
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.
description
Resource description (returned on QUERY_COS). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
transmission_priority
Transmission priority. This is set to one of the following values:

AP_LOW
AP_MEDIUM
AP_HIGH
AP_NETWORK

num_of_node_rows
Number of node row overlays that follow the DEFINE_COS VCB. The maximum is 8. 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 confines 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. Note that the node rows must be concatenated in ascending order of weight.
num_of_tg_rows
Number of TG row overlays that follow the node row overlays. 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 confines 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. Note that the TG rows must be concatenated 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. This can be one of the following values:
AP_UNCONGESTED
The node is not congested.
AP_CONGESTED
The number of ISR sessions is greater than the isr_sessions_upper_threshold.
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. This can be one of the following values:
AP_UNCONGESTED
The node is not congested.
AP_CONGESTED
The number of ISR sessions is greater than the isr_sessions_upper_threshold.
cos_node_row.weight
Weight associated with this node row. Values must be in the range 0–255.
cos_tg_row.minimum.effect_cap
Minimum limit for actual units of effective capacity. The value is encoded as a 1-byte floating-point number, represented by the formula 0.1mmm * 2 eeeee, where the bit representation of the byte is 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 limits for security values as described in the list below:
AP_SEC_NONSECURE
No security exists.
AP_SEC_PUBLIC_SWITCHED_NETWORK
Data transmitted over this connection network will flow over a public switched network.
AP_SEC_UNDERGROUND_CABLE
Data transmitted over secure underground cable.
AP_SEC_SECURE_CONDUIT
The line is a secure conduit that is not guarded.
AP_SEC_GUARDED_CONDUIT
Conduit is protected against physical tapping.
AP_SEC_ENCRYPTED
Encryption over the line.
AP_SEC_GUARDED_RADIATION
Line is protected against physical and radiation tapping.
cos_tg_row.minimum.prop_delay
Minimum limits for propagation delay representing the time it takes for a signal to travel the length of the link, in microseconds. The value is encoded as a 1-byte floating-point number, represented by the formula 0.1mmm * 2 eeeee, where the bit representation of the byte is eeeeemmm. Default values are listed below:
AP_PROP_DELAY_MINIMUM
No propagation delay.
AP_PROP_DELAY_LAN
Less than 480 microseconds delay.
AP_PROP_DELAY_TELEPHONE
Between 480 and 49␠512 microseconds delay.
AP_PROP_DELAY_PKT_SWITCHED_NET
Between 49␠512 and 245␠760 microseconds delay.
AP_PROP_DELAY_SATELLITE
Longer than 245␠760 microseconds delay.
AP_PROP_DELAY_MAXIMUM
Maximum propagation delay.
cos_tg_row.minimum.modem_class
Reserved. This field should always be set to zero.
cos_tg_row.minimum.user_def_parm_1
Minimum limit for user-defined parameter in the range 0–255.
cos_tg_row.minimum.user_def_parm_2
Minimum limit for user-defined parameter in the range 0–255.
cos_tg_row.minimum.user_def_parm_3
Minimum limit for user-defined parameter in the range 0–255.
cos_tg_row.maximum.effect_cap
Maximum limit for actual units of effective capacity. The value is encoded as a 1-byte floating-point number, represented by the formula 0.1mmm * 2 eeeee, where the bit representation of the byte is 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 limits for security values as described in the list below:
AP_SEC_NONSECURE
No security exists.
AP_SEC_PUBLIC_SWITCHED_NETWORK
Data transmitted over this connection network will flow over a public switched network.
AP_SEC_UNDERGROUND_CABLE
Data transmitted over secure underground cable.
AP_SEC_SECURE_CONDUIT
The line is a secure conduit that is not guarded.
AP_SEC_GUARDED_CONDUIT
Conduit that is protected against physical tapping.
AP_SEC_ENCRYPTED
Encryption over the line.
AP_SEC_GUARDED_RADIATION
Line is protected against physical and radiation tapping.
cos_tg_row.maximum.prop_delay
Maximum limits for propagation delay representing the time it takes for a signal to travel the length of the link, in microseconds. The value is encoded as a 1-byte floating-point number, represented by the formula 0.1mmm * 2 eeeee, where the bit representation of the byte is eeeeemmm. Default values are listed below:
AP_PROP_DELAY_MINIMUM
No propagation delay.
AP_PROP_DELAY_LAN
Less than 480 microseconds delay.
AP_PROP_DELAY_TELEPHONE
Between 480 and 49␠512 microseconds delay.
AP_PROP_DELAY_PKT_SWITCHED_NET
Between 49␠512 and 245␠760 microseconds delay.
AP_PROP_DELAY_SATELLITE
Longer than 245␠760 microseconds delay.
AP_PROP_DELAY_MAXIMUM
Maximum propagation delay.
cos_tg_row.maximum.modem_class
Reserved. This field should always be set to zero.
cos_tg_row.maximum.user_def_parm_1
Maximum limit for user-defined parameter in the range 0–255.
cos_tg_row.maximum.user_def_parm_2
Maximum limit for user-defined parameter in the range 0–255.
cos_tg_row.maximum.user_def_parm_3
Maximum limit for user-defined parameter in the range 0–255.
cos_tg_row.weight
Weight associated with this TG row.

Returned Parameters

If the verb executes successfully, the Program returns the following parameter:
primary_rc
AP_OK
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_NUMBER_OF_NODE_ROWS
AP_INVALID_NUMBER_OF_TG_ROWS
AP_NODE_ROW_WGT_LESS_THAN_LAST
AP_TG_ROW_WGT_LESS_THAN_LAST

If the verb does not execute because of a state error, the Program returns the following parameters:
primary_rc
AP_STATE_CHECK
secondary_rc
AP_COS_TABLE_FULL
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 the node is stopping, the Program returns the following parameter:
primary_rc
AP_NODE_STOPPING
If the verb does not execute because of a system error, the Program returns the following parameter:
primary_rc
AP_UNEXPECTED_SYSTEM_ERROR