QUERY_PARTNER_LU_DEFINITION

QUERY_PARTNER_LU_DEFINITION returns information that had previously been passed in on a DEFINE_PARTNER_LU verb.

The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific partner LU, or to obtain the list information in several chunks, the plu_alias field (or the fqplu_name if the plu_alias is set to all zeros) should be set. If the plu_alias field is nonzero it will be used to determine the index and the fqplu_name is ignored. If the plu_alias field is set to all zeros, the fqplu_name will be used to determine the index. If the list_options field is set to AP_FIRST_IN_LIST then both of these fields will be ignored. (In this case the returned list will be ordered by plu_alias if the AP_LIST_BY_ALIAS list_options is set, otherwise it will be ordered by fqplu_name). See Querying the Node for background on how the list formats are used.

This list is ordered on either plu_alias or fqplu_name according to the options specified. 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 returned list starts from the next entry according to the defined ordering (whether the specified entry exists or not).

Note this verb returns definition information only. The QUERY_PARTNER_LU verb returns information that is determined when at least one session is established with the partner LU.

VCB Structure

typedef struct query_partner_lu_definition
{
   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   plu_alias[8];        /* partner LU alias              */
   unsigned char   fqplu_name[17];      /* fully qualified partner       */
                                        /* LU name                       */
} QUERY_PARTNER_LU_DEFINITION;
typedef struct partner_lu_def_summary
{
   unsigned short  overlay_size;        /* size of this entry            */
   unsigned char   plu_alias[8];        /* partner LU alias              */
   unsigned char   fqplu_name[17];      /* fully qualified partner       */
                                        /* LU name                       */
   unsigned char   description[RD_LEN];
                                        /* resource description          */
} PARTNER_LU_DEF_SUMMARY;
typedef struct partner_lu_def_detail
{
   unsigned short  overlay_size;        /* size of this entry            */
   unsigned char   plu_alias[8];        /* partner LU alias              */
   unsigned char   fqplu_name[17];      /* fully qualified partner       */
                                        /* LU name                       */
   unsigned char   reserv1;             /* reserved                      */
   PLU_CHARS       plu_chars;           /* partner LU characteristics    */
} PARTNER_LU_DEF_DETAIL;
typedef struct plu_chars
{
   unsigned char   fqplu_name[17];      /* fully qualified partner       */
                                        /* LU name                       */
   unsigned char   plu_alias[8];        /* partner LU alias              */
   unsigned char   description[RD_LEN]; /* resource description          */
   unsigned char   plu_un_name[8];      /* partner LU uninterpreted name */
   unsigned char   preference;          /* routing preference            */
   unsigned short  max_mc_ll_send_size;
                                        /* max MC send LL size           */
   unsigned char   conv_security_ver;   /* already_verified accepted     */
   unsigned char   parallel_sess_supp;  /* parallel sessions supported?  */
   unsigned char   reserv2[8];          /* reserved                      */
} PLU_CHARS;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_QUERY_PARTNER_LU_DEFINITION
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:
AP_SUMMARY
Returns summary information only.
AP_DETAIL
Returns detailed information.

The plu_alias (or the fqplu_name if the plu_alias is set to all zeros) specified (see the following parameter, plu_alias) 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.
AP_LIST_BY_ALIAS
The returned list is ordered by plu_alias. This option is only valid when AP_FIRST_IN_LIST is specified. If AP_LIST_FROM_NEXT or AP_LIST_INCLUSIVE is specified, the list ordering will depend on whether the plu_alias or fqplu_name has been supplied as a starting point.
plu_alias
Partner LU alias. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. If this field is set to all zeros, the fqplu_name field is used to specify the required partner LU. This field is ignored if list_options is set to AP_FIRST_IN_LIST.
fqplu_name
17-byte fully qualified network name for the partner LU. 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 only significant if the plu_alias field is set to all zeros. 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
partner_lu_def_summary.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
partner_lu_def_summary.plu_alias
Partner LU alias. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
partner_lu_def_summary.fqplu_name
17-byte fully qualified network name for the partner LU. 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.)
partner_lu_def_summary.description
Resource description (as specified on DEFINE_PARTNER_LU). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
partner_lu_def_detail.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
partner_lu_def_detail.plu_alias
Partner LU alias. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
partner_lu_def_detail.fqplu_name
17-byte fully qualified network name for the partner LU. 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.)
partner_lu_def_detail.plu_chars.fqplu_name
17-byte fully qualified network name for the partner LU. 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.)
partner_lu_def_detail.plu_chars.plu_alias
Partner LU alias.
partner_lu_def_detail.plu_chars.description
Resource description (as specified on DEFINE_PARTNER_LU). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
partner_lu_def_detail.plu_chars.plu_un_name
Uninterpreted name of the partner LU. This is an 8-byte type-A EBCDIC character string.
partner_lu_def_detail.plu_chars.preference
The set of routing protocols to be preferred for session activation to this partner LU. This field can take the following values:
AP_NATIVE
Use native (APPN) routing protocols only.
AP_NONNATIVE
Use nonnative (AnyNet) routing protocols only.
AP_NATIVE_THEN_NONNATIVE
Try native (APPN) protocols, and if the partner LU cannot be located then retry session activation using nonnative (AnyNet) protocols.
AP_NONNATIVE_THEN_NATIVE
Try nonnative (AnyNet) protocols, and if the partner LU cannot be located then retry session activation using native (APPN) protocols.
AP_USE_DEFAULT_PREFERENCE
Use the default preference defined when the node was started.
Note: Nonnative routing is only meaningful when an AnyNet® DLC is available to the Node Operator Facility, and there is an AnyNet link station defined.
partner_lu_def_detail.plu_chars.max_mc_ll_send_size
Maximum size of logical length (LL) record that can be sent to the partner LU. Data records that are larger than this are broken down into several LL records before being sent to the partner LU. The maximum value max_mc_ll_send_size can take is 32␠767.
partner_lu_def_detail.plu_chars.conv_security_ver
Specifies whether the partner LU is authorized to validate user_ids on behalf of local LUs, that is whether the partner LU can set the already verified indicator in an Attach request.

AP_YES
AP_NO

partner_lu_def_detail.plu_chars.parallel_sess_supp
Specifies whether parallel sessions are supported (AP_YES or AP_NO).
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_PLU_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