QUERY_CN_PORT

QUERY_CN_PORT returns information about ports defined on adjacent connection networks. The information is returned as a formatted list. To obtain information about a specific port, or to obtain the list information in several chunks, the port_name field should be set. Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field will be ignored. Note that the fqcn_name field must always be set to the name of a valid connection network.

See Querying the Node for background on how the list formats are used.

VCB Structure

typedef struct query_cn_port
{
        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   *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 */
        unsigned char   port_name[8];      /* port name                  */
} QUERY_CN_PORT;

typedef struct cn_port_data
{
        unsigned short  overlay_size;       /* size of this 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

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 combination of fqcn_name and port_name specified (see the following parameters, fqcn_name and port_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 must always be set.

port_name

8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. 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_port_data.overlay_size: The number of bytes in this entry, and hence the offset to the next entry returned (if any).
cn_port_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_port_data.port_name: Port name in an 8-byte, locally displayable character set. All 8 bytes are significant.
cn_port_data.tg_num: Transmission group number for specified port.

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_PORT_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