QUERY_CN

QUERY_CN_PORT returns information about ports defined on an adjacent Connection Network.

This verb can be used to obtain information about a specific port, or about multiple ports, 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_port
{
     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   */
     unsigned char      port_name[8];        /* port name                    */
} QUERY_CN_PORT;

typedef struct cn_port_data
{
     AP_UINT16          overlay_size;        /* size of returned entry       */
     unsigned char      fqcn_name[17];       /* Name of Connection Network   */
     unsigned char      port_name[8];        /* name of port                 */
     unsigned char      tg_num;              /* transmission group number    */
     unsigned char      reserva[20];         /* reserved                     */
} CN_PORT_DATA;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_CN_PORT

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 ports for which data should be returned. To request data for a specific port 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 ports 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 port_name parameter.
AP_LIST_FROM_NEXT: Start at the entry immediately following the entry specified by the port_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 on which the required port is defined, or the CN for which a list of ports is required.

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.

port_name

Name of the port for which information is required, or the name to be used as an index into the list of ports. This is an 8-byte ASCII string, padded on the right with spaces if the name is shorter than 8 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_port_data.overlay_size: The size of the returned cn_port_data structure, and therefore the offset to the start of the next entry in the data buffer.
cn_port_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_port_data.port_name: Name of the port. This is an 8-byte ASCII string, padded on the right with spaces if the name is shorter than 8 characters.
cn_port_data.tg_num: Transmission group number for the specified port.

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_PORT_NAME: The list_options parameter was set to AP_LIST_INCLUSIVE, to list all entries starting from the supplied name, but the port_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.

QUERY_CN_PORT

Technical documentation

» Table of Contents