QUERY_CN

QUERY_CN returns information about adjacent Connection Networks. This information is structured as determined data (data gathered dynamically during execution) and defined data (the data supplied by the application on DEFINE_CN).

The information is returned as a formatted list. To obtain information about a specific CN, or to obtain the list information in several chunks, the fqcn_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 fqcn_name. Ordering is by name length first, and then by ASCII lexicographical ordering for names of the same length (in accordance with normal MIB ordering).

If AP_LIST_FROM_NEXT is selected, the list will start from the next entry according to the defined ordering (whether the specified entry exists or not).

VCB Structure

typedef struct query_cn
{
        unsigned short  opcode;            /* Verb operation code        */
        unsigned char   attributes;        /* verb attributes            */
        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   fqcn_name[17];     /* Name of connection network */
} QUERY_CN;
typedef struct cn_data
{
        unsigned short  overlay_size;      /* size of this entry         */
        unsigned char   fqcn_name[17];     /* Name of connection network */
        unsigned char   reserv1;           /* reserved                   */
        CN_DET_DATA     det_data;          /* Determined data            */
        CN_DEF_DATA     def_data;          /* Defined data               */
} CN_DATA;
typedef struct cn_det_data
{
        unsigned short  num_act_ports;     /* number of active ports     */
        unsigned char   reserva[20];       /* reserved                   */
} CN_DET_DATA;
typedef struct cn_def_data
{
        unsigned char   description[RD_LEN];
                                           /* resource description       */
        unsigned char   num_ports;         /* number of ports on CN      */
        unsigned char   reserv1[16];       /* reserved                   */
        TG_DEFINED_CHARS tg_chars;         /* TG characteristics         */
} CN_DEF_DATA;
typedef struct tg_defined_chars
{
        unsigned char   effect_cap;        /* effective capacity         */
        unsigned char   reserve1[5];       /* reserved                   */
        unsigned char   connect_cost;      /* connection cost            */
        unsigned char   byte_cost;         /* byte cost                  */
        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_QUERY_CN
attributes
The attributes of the verb. This field is a bit field. The first bit contains the visibility of the resource to be defined and corresponds to one of the following:

AP_EXTERNALLY_VISIBLE
AP_INTERNALLY_VISIBLE

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 fqcn_name specified (see the following parameter, fqcn_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.
fqcn_name
Fully qualified, 17-byte, connection network name. This name is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded 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.
cn_data.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
cn_data.fqcn_name
Fully qualified, 17-byte, connection network name. This name is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
cn_data.det_data.num_act_ports
Dynamic value giving number of active ports on the connection network.
cn_data.def_data.description
Resource description (as specified on DEFINE_CN). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
cn_data.def_data.num_ports
Number of ports on the connection network.
cn_data.def_data.tg_chars.effect_cap
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.
cn_data.def_data.tg_chars.connect_cost
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.
cn_data.def_data.tg_chars.byte_cost
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.
cn_data.def_data.tg_chars.security
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 is 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.
cn_data.def_data.tg_chars.prop_delay
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.
cn_data.def_data.tg_chars.modem_class
Reserved. This field should always be set to zero.
cn_data.def_data.tg_chars.user_def_parm_1
User defined parameter in the range 0–255.
cn_data.def_data.tg_chars.user_def_parm_2
User defined parameter in the range 0–255.
cn_data.def_data.tg_chars.user_def_parm_3
User defined parameter in the range 0–255.
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_CN_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