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
- 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
- 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.
- primary_rc
- AP_PARAMETER_CHECK
- secondary_rc
- AP_INVALID_CN_NAME
AP_INVALID_LIST_OPTION
- primary_rc
- AP_NODE_NOT_STARTED
- primary_rc
- AP_UNEXPECTED_SYSTEM_ERROR