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