 |
» |
|
|
|
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). This verb can be used to obtain information about a specific
connection network, or about multiple connection networks, depending
on the options used. It can be issued only at an end node; it is
not valid at a LEN node. VCB
Structure | |
typedef struct query_cn
{
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 *buf_ptr; /* pointer to buffer */
AP_UINT32 buf_size; /* buffer size */
AP_UINT32 total_buf_size; /* total buffer size required */
AP_UINT16 num_entries; /* number of entries */
AP_UINT16 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
{
AP_UINT16 overlay_size; /* size of returned 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
{
AP_UINT16 num_act_ports; /* number of active ports */
unsigned char reserva[20]; /* reserved */
} CN_DET_DATA;
|
typedef struct cn_def_data
{
unsigned char description[32]; /* resource description */
unsigned char reserve0[16]; /* reserved */
unsigned char num_ports; /* number of ports on CN */
unsigned char reserve1[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; /* 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;
|
Supplied
Parameters | |
The application supplies the following parameters: - opcode
AP_QUERY_CN - overlay_size
For compatability with future releases of SNAplus2, your
application must use this field to determine the exact length of
the overlay structure returned, and should not rely on the use of
the sizeof()function. - buf_ptr
A pointer to a data buffer that SNAplus2 will use
to return the requested information. - buf_size
Size of the supplied data buffer. - num_entries
Maximum number of CNs for which data should be returned.
To request data for a specific CN rather than a range, specify the
value 1. To return as many entries as possible,
specify zero; in this case, SNAplus2 will return the maximum number
of entries that can be accommodated in the supplied data buffer. - list_options
The position in the list of CNs from which SNAplus2 should
begin to return data. Possible values are: - AP_FIRST_IN_LIST
Start at the first entry in the list. - AP_LIST_INCLUSIVE
Start at the entry specified by the fqcn_name parameter. - AP_LIST_FROM_NEXT
Start at the entry immediately following the entry
specified by the fqcn_name parameter.
For more information about how the list is ordered and how
the application can obtain specific entries from it, see “List
Options For QUERY_* Verbs”. - fqcn_name
Fully qualified name of the CN for which information
is required, or the name to be used as an index into the list of
CNs. This value is ignored if list_options is set to AP_FIRST_IN_LIST. The name is a 17-byte EBCDIC string, right-padded with EBCDIC
spaces. It consists of a network ID of up to 8 A-string characters,
an EBCDIC dot (period) character, and a network name of up to 8
A-string characters.
Returned
Parameters: Successful Execution | |
If the verb executes successfully, SNAplus2 returns the following parameters: - primary_rc
AP_OK - buf_size
Length of the information returned in the supplied buffer. - total_buf_size
Returned value indicating the size of buffer that
would have been required to return all the list information requested.
A value greater than buf_size indicates that not all the available entries were returned. - num_entries
Number of entries returned in the data buffer. - total_num_entries
Total number of entries available. A value greater
than num_entries indicates that not all the available entries were returned. Each entry in the data buffer consists of the following parameters: - cn_data.overlay_size
The size of the returned cn_data structure, and therefore the offset to the start of the
next entry in the data buffer. - cn_data.fqcn_name
Fully qualified name of the CN. The name is a 17-byte EBCDIC
string, padded on the right with EBCDIC spaces. It consists of a
network ID of 1-8 A-string characters, an EBCDIC dot (period) character,
and a network name of 1-8 A-string characters. - cn_data.det_data.num_act_ports
The number of active ports on the connection network. - cn_data.def_data.description
A null-terminated text string describing the CN,
as specified in the definition of the CN. - cn_data.def_data.num_ports
The total number of ports on the connection network. - cn_data.def_data.tg_chars.effect_cap
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 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. Values are integers in the range 0-255, where
zero is the lowest cost per byte and 255 is
the highest. - cn_data.def_data.tg_chars.security
Security level of the network. 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. - AP_SEC_MAXIMUM
Maximum security.
- cn_data.def_data.tg_chars.prop_delay
Propagation delay: the time that a signal takes
to travel the length of the link. Possible values are: - 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.
- cn_data.def_data.tg_chars.user_def_parm_1 through def_data.tg_chars.user_def_parm_3
User-defined parameters, which include other TG characteristics
not covered by the above parameters. Each of these parameters is
set to a value in the range 0-255.
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_CN_NAME
The list_options parameter was set to AP_LIST_INCLUSIVE,
to list all entries starting from the supplied name, but the fqcn_name parameter was not valid. - AP_INVALID_LIST_OPTION
The list_options parameter was not set to a valid value.
Appendix A “Common
Return Codes” lists further
secondary return codes associated with AP_PARAMETER_CHECK,
which are common to all NOF verbs. Returned
Parameters: Function Not Supported | |
If the verb does not execute successfully because the local
node is a LEN node, SNAplus2 returns the following parameters: - primary_rc
- AP_FUNCTION_NOT_SUPPORTED
The local node is a LEN node. This verb is valid
only at an end node.
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. |
Printable version
