QUERY_ADJACENT_NODE

QUERY_ADJACENT_NODE returns information about adjacent nodes configured on DEFINE_ADJACENT_NODE.

Information is returned in an ordered list. Each entry in the list consists of an ADJACENT_NODE_DATA overlay containing information about the adjacent CP, followed by an ADJACENT_NODE_LU_DATA overlay for each LU associated with the adjacent CP.

Entries are ordered by cp_name, then by fqlu_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_adjacent_node
{
        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   cp_name[17];       /* CP name of adjacent node   */
} QUERY_ADJACENT_NODE;
typedef struct adjacent_node_data
{
        unsigned short  overlay_size;      /* size of this entry         */
        unsigned short  sub_overlay_size;  /* size of this stub entry    */
        unsigned char   cp_name[17];       /* CP name                    */
        DESCRIPTION     description;       /* resource description       */
        unsigned char   reserv3[19];       /* reserved                   */
        unsigned short  num_of_lus;        /* number of LUs              */
} ADJACENT_NODE_DATA;
typedef struct adjacent_node_lu_data
{
        unsigned short  overlay_size;      /* effective capacity         */
        unsigned char   reserve2[2];       /* reserved                   */
        ADJACENT_NODE_LU adj_lu_def_data;  /* Adjacent LU defined data   */
} ADJACENT_NODE_LU_DATA;
typedef struct adjacent_node_lu
{
        unsigned char   wildcard_lu;       /* Is this LU a wildcard?     */
        unsigned char   fqlu_name[17];     /* Fully-Qualified LU name    */
        unsigned char   reserve1[6];       /* reserved                   */
        ADJACENT_NODE_LU adj_lu_def_data;  /* Adjacent LU defined data   */
} ADJACENT_NODE_LU;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_QUERY_ADJACENT_NODE
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 cp_name specified (see the following parameter, cp_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 adjacent node in the directory maintained by the Program.
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.
cp_name
Fully qualified name of the adjacent node. 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.)

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.
adjacent_node_data.overlay_size
The number of bytes in this entry, including any ADJACENT_NODE_LU_DATA structures, and hence the offset to the next entry returned (if any).
adjacent_node_data.sub_overlay_size
The number of bytes in the node part of the entry, not including any ADJACENT_NODE_LU_DATA structures; this is the offset to the first ADJACENT_NODE_LU_DATA field in the entry.
adjacent_node_data.cp_name
Fully qualified name of the adjacent node. 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.)
adjacent_node_data.description
Resource description (as specified on DEFINE_ADJACENT_NODE). The length of this field should be a multiple of four bytes, and nonzero.
adjacent_node_data.num_of_lus
The number of LUs defined for this adjacent node. An ADJACENT_NODE_LU_DATA structure for each LU follows.
adjacent_node_lu_data.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
adjacent_node_lu.wildcard_lu
Indicates whether the LU name is defined as a wildcard.
adjacent_node_lu.fqlu_name
Fully qualified name of the adjacent node. The name is 17 bytes long and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) 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.)
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_CP_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