QUERY_DIRECTORY_LU

QUERY_DIRECTORY_LU returns a list of LUs from the directory database. The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific LU, or to obtain the list information in several chunks, the lu_name field should be set. Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field will be ignored. See Querying the Node for background on how the list formats are used.

This list is ordered by the lu_name. Ordering is by name length first, and then by ASCII lexicographical ordering for names of the same length (in accordance with IBM's 6611 APPN® 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 that DLUS-served LUs present in the directory are also returned by this query.

VCB Structure

typedef struct query_directory_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[17];         /* network qualified LU name   */
} QUERY_DIRECTORY_LU;
typedef struct directory_lu_summary
{
        unsigned short  overlay_size;        /* size of this entry          */
        unsigned char   lu_name[17];         /* network qualified LU name   */
        unsigned char   description[RD_LEN]; /* resource description        */
} DIRECTORY_LU_SUMMARY;
typedef struct directory_lu_detail
{
        unsigned short  overlay_size;        /* size of this entry          */
        unsigned char   lu_name[17];         /* network qualified LU name   */
        unsigned char   description[RD_LEN]; /* resource description        */
        unsigned char   server_name[17];     /* network qualified           */
                                             /* server name                 */
        unsigned char   lu_owner_name[17];   /* network qualified           */
                                             /* LU owner name               */
        unsigned char   location;            /* Resource location           */
        unsigned char   entry_type;          /* Type of the directory entry */
        unsigned char   wild_card;           /* type of wildcard entry      */
        unsigned char   apparent_lu_owner_name[17];
                                             /* apparent LU owner name      */
        unsigned char   reserva[3];          /* reserved                    */
} DIRECTORY_LU_DETAIL;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_QUERY_DIRECTORY_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 lu_name specified (see the following parameter, lu_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.
lu_name
Network qualified LU name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.) 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 directory entries returned.
total_num_entries
Total number of entries that could have been returned. This can be higher than num_entries.
directory_lu_summary.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
directory_lu_summary.lu_name
Network qualified LU name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
directory_lu_summary.description
Resource description (as specified on DEFINE_LOCAL_LU, or DEFINE_ADJACENT_NODE). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
directory_lu_detail.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
directory_lu_detail.lu_name
Network qualified LU name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
directory_lu_detail.description
Resource description (as specified on DEFINE_LOCAL_LU, or DEFINE_ADJACENT_NODE). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
directory_lu_detail.server_name
Network qualified name of the node serving the LU. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
directory_lu_detail.lu_owner_name
Network qualified name of the node owning the LU. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
directory_lu_detail.location
Specifies the location of the resource, which can be one of the following values:
AP_LOCAL
The resource is at the local node.
AP_DOMAIN
The resource belongs to an attached end node.
AP_CROSS_DOMAIN
The resource is not within the domain of the local node.
directory_lu_detail.entry_type
Specifies the type of the directory entry. This can be one of the following values:
AP_HOME
Local resource.
AP_CACHE
Cached entry.
AP_REGISTER
Registered resource (NN only).
directory_lu_detail.wild_card
Specifies the type of wildcard the LU will match.
AP_OTHER
Unknown type of LU entry.
AP_EXPLICIT
The full lu_name will be used for locating this LU.
AP_PARTIAL_WILDCARD
Only the nonspace portions of lu_name will be used for locating this LU.
AP_FULL_WILDCARD
All lu_names will be directed to this LU.
directory_lu_detail.apprent_lu_owner_name
NN and BrNN only: Fully qualified apparent LU owner CP name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.)

If the apparent LU owner is the real LU owner, this field is set to binary zeroes.

If the apparent LU owner is not the real owner, then this field is set to the name of the apparent LU owner.

The real LU owner is not the apparent LU owner in the directory of the NNS of a BrNN if the resource is owned by an EN in the domain of the BrNN. In this case, the real LU owner is the EN, but the apparent owner is the BrNN.

Other node types: This field is set to binary zeroes.

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