QUERY_PARTNER_LU

QUERY_PARTNER_LU returns information about partner LUs that have been used by a local LU.

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 should be set (or the fqplu_name if the plu_alias is set to all zeros). If the list_options field is set to AP_FIRST_IN_LIST, both of these fields will be ignored. The lu_name or lu_alias field must always be set. The lu_name, if nonzero, will be used in preference to the lu_alias. See Querying the Node for background on how the list formats are used.

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

If plu_alias is set to all zeros, the fqplu_name value will be used; otherwise, the plu_alias is always used and the fqplu_name is ignored.

The list of partner LUs returned can be filtered according to whether they currently have any active sessions. If filtering is desired, the active_sessions field should be set to AP_YES (otherwise this field should be set to AP_NO).

This verb returns information that is determined when at least one session is established with the partner LU.

The QUERY_PARTNER_LU_DEFINITION verb returns definition information only.

VCB Structure

typedef struct query_partner_lu
{
   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    lu_name[8];         /* LU name                         */
   unsigned char    lu_alias[8];        /* LU alias                        */
   unsigned char    plu_alias[8];       /* partner LU alias                */
   unsigned char    fqplu_name[17];     /* fully qualified partner         */
                                        /* LU name                         */
   unsigned char   active_sessions;     /* active sessions only filter     */
} QUERY_PARTNER_LU;
typedef struct plu_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   reserv1;             /* reserved                        */
   unsigned char   description[RD_LEN];
                                        /* resource description            */
   unsigned short  act_sess_count;      /* curr active sessions count      */
   unsigned char   partner_cp_name[17]; /* partner LU CP name              */
   unsigned char   partner_lu_located;  /* CP name resolved?               */
} PLU_SUMMARY;
typedef struct plu_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                        */
   unsigned char   description[RD_LEN];
                                        /* resource description            */
   unsigned short  act_sess_count;      /* curr active sessions count      */
   unsigned char   partner_cp_name[17]; /* partner LU CP name              */
   unsigned char   partner_lu_located;  /* CP name resolved?               */
   unsigned char   plu_un_name[8];      /* partner LU uninterpreted name   */
   unsigned char   parallel_sess_supp;  /* parallel sessions supported?    */
   unsigned char   conv_security;       /* conversation security           */
   unsigned short  max_mc_ll_send_size; /* max send LL size for mapped     */
                                        /* conversations                   */
   unsigned char   implicit;            /* implicit or explicit entry      */
   unsigned char   security_details;    /* conversation security detail    */
   unsigned char   duplex_support;      /* full-duplex support             */
   unsigned char   preference;          /* routing preference              */
   unsigned char   reserva[16];         /* reserved                        */
} PLU_DETAIL;
The application supplies the following parameters:

Supplied Parameters

opcode
AP_QUERY_PARTNER_LU
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 combination of the lu_name (or lu_alias if the lu_name is set to all zeros) and plu_alias (or fqplu_name if the plu_alias is set to all zeros) specified (see the following parameter, lu_name and 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 plu_alias and fqplu_name fields are 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.
lu_name
LU name. This name is an 8-byte type-A EBCDIC character string. If this field is set to all zeros, the lu_alias field will be used for determining the index.
lu_alias
Locally defined LU alias. This is an 8-byte string in a locally displayable character set. This field is only significant if the lu_name field is set to all zeros, in which case all 8 bytes are significant and must be set. If both the lu_name and the lu_alias are set to all zeros then the LU associated with the control point (the default LU) is used.
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 will be used as the index value.
fqplu_name
17-byte fully qualified network name for the partner LU. This name is 17 bytes long and 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.)
active_sessions
Active session filter. Specifies whether the returned partner LUs should be filtered according to whether they currently have any active sessions (AP_YES or AP_NO).

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.
plu_summary.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
plu_summary.plu_alias
Partner LU alias. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
plu_summary.fqplu_name
17-byte fully qualified network name for the partner LU. This name is 17 bytes long and 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.)
plu_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.
plu_summary.act_sess_count
Total number of active sessions between the local LU and the partner LU. If the active_sessions filter has been set to AP_YES, then this field will always be greater than zero.
plu_summary.partner_cp_name
17-byte fully qualified network name for the control point of 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.)
plu_summary.partner_lu_located
Specifies whether the control point name for the partner LU has been resolved (AP_YES or AP_NO).
plu_detail.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
plu_detail.plu_alias
Partner LU alias. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
plu_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.)
plu_detail.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.
plu_detail.act_sess_count
Total number of active sessions between the local LU and the partner LU. If the active_sessions filter has been set to AP_YES, then this field will always be greater than zero.
plu_detail.partner_cp_name
17-byte fully qualified network name for the control point of 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.)
plu_detail.partner_lu_located
Specifies whether the control point name for the partner LU has been resolved (AP_YES or AP_NO).
plu_detail.plu_un_name
Uninterpreted name of the partner LU. This is an 8-byte type-A EBCDIC character string.
plu_detail.parallel_sess_supp
Specifies whether parallel sessions are supported (AP_YES or AP_NO).
plu_detail.conv_security
Specifies whether conversation security information can be sent to this partner LU (AP_YES or AP_NO). If it is set to AP_NO, then any security information supplied by a transaction program is not sent to the partner LU. If there are currently no active sessions to this partner LU, this is set to AP_UNKNOWN.
plu_detail.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.
plu_detail.implict
Specifies whether the entry is the result of an implicit (AP_YES) or explicit (AP_NO) definition.
plu_detail.security_details
Returns the conversation security support as negotiated on the BIND. This can be one or more of the following values:
AP_CONVERSATION_LEVEL_SECURITY
Conversation security information will be accepted on requests to or from the partner LU to allocate a conversation. The specific types of conversation security support are described by the following values.
AP_ALREADY_VERIFIED
Both local and partner LU agree to accept already verified requests to allocate a conversation. An already verified request need carry only a user ID, and not a password.
AP_PERSISTENT_VERIFICATION
Persistent verification is supported on the session between the local and partner LUs. This means that, once the initial request (carrying a user ID and, typically, a password) for a conversation has been verified, subsequent requests for a conversation need only carry the user ID.
AP_PASSWORD_SUBSTITUTION
The local and partner LU support password substitution conversation security. When a request to allocate a conversation is issued, the request carries an encrypted form of the password. If password substitution is not supported, the password is carried in clear text (nonencrypted) format.
Note:
If the session does not support password substitution, then an ALLOCATE or SEND_CONVERSATION with security type of AP_PGM_STRONG will fail.
AP_UNKNOWN
There are currently no active sessions to this partner LU.
plu_detail.duplex_support
Returns the conversation duplex support as negotiated on the BIND. This is one of the following values:
AP_HALF_DUPLEX
Only half-duplex conversations are supported.
AP_FULL_DUPLEX
Full-duplex as well as half-duplex conversations are supported.
AP_UNKNOWN
The conversation duplex support is not known because there are no active sessions to the partner LU.
plu_detail.preference
Returns the routing protocols preference as specified in the DEFINE_PARTNER_LU verb.
AP_NATIVE
Use native (APPN) routing protocols only.
AP_NONNATIVE
Use nonnative (AnyNet) protocols, and if the partner LU cannot be located, then retry session activation using nonnative (AnyNet) protocols.
AP_NATIVE_THEN_NONNATIVE
Try native (APPN) 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. (This is set on START_NODE and can be recalled by QUERY_NODE.)

Note that nonnative routing is only meaningful when an AnyNet DLC is available to the Program, and there is an AnyNet Link Station defined. See DEFINE_LS for more information.

If the field anynet_supported supplied on START_NODE was set to AP_NO this field must take the value AP_NATIVE or AP_USE_DEFAULT_PREFERENCE.

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_LU_NAME
AP_INVALID_LU_ALIAS
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