QUERY_LS_EXCEPTION

QUERY_LS_EXCEPTION returns a list of information about the link stations defined at the node. This information is structured as determined data (data gathered dynamically during execution) and defined data (the data supplied by the application on DEFINE_LS).

The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific LS, or to obtain the list information in several chunks, the ls_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 ls_name. Ordering is according to 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).

The list of link stations returned can be filtered by the name of the port that they belong to. In this case, the port_name field should be set (otherwise this field should be set to all zeros).

VCB Structure

typedef struct query_ls_exception
{
        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 long   exception_index;    /* index of LS exception entry    */
        unsigned char   ls_name;            /* name of link station           */
} QUERY_LS_EXCEPTION;
typedef struct LS_EXCEPTION
{
        unsigned short  overlay_size;       /* size of this entry             */
        unsigned long   exception_indes;    /* index of this entry            */
        unsigned_DATE_TIME
                        time;               /* date and time                  */
        unsigned char   ls_name[8];         /* link station name              */
        unsigned char   adj_cp_name[17];
                                            /* adjacent CP name               */
        unsigned char   adj_node_id[4];
                                            /* adjacent node id               */
        unsigned short  tg_number;          /* TG number                      */
        unsigned long   general_sense;      /* general sense data             */
        unsigned char   retry;              /* wil retry request              */
        unsigned long   end_sense;          /* termination sense data         */
        unsigned long   xid_local_sense;    /* XID local sense data           */
        unsigned long   xid_remote_sense;   /* XID remote sense data          */
        unsigned short  xid_error_byte;     /* offset of byte in error        */
        unsigned short  xid_error_bit;      /* offset of bit in error         */
        unsigned char   dlc_type;           /* DLC type                       */
        LINK_ADDRESS    local_addr;         /* local address                  */
        LINK_ADDRESS    destination_addr;   /* destination address            */
        unsigned char   reserved[20];       /* reserved                       */
} LS_EXCEPTION;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_QUERY_LS_EXCEPTION
format
Identifies the format of the VCB. Set this field to one to specify the format 1 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 index specified in the following parameter 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 ignore and the returned list starts from the first entry in the list.
AP_LIST_FROM_NEXT
The returned lists 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.
exception_index
Index of the LS exception entry. This field is ignored if list_options is set to AP_FIRST_IN_LIST.
ls_name
Name of the link station that returned entries relate. This is an 8–byte string in a locally displayable character set. All 8 bytes are significant. If this field is set to null, then entries that relate to any or all links stations are returned.

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.
ls_exception.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
ls_exception.exception_index
The index assigned for this LS exception entry. The value of the index begins at zero and increases incrementally up to a maximum value of 2**31–1 (2,147,483,647) before wrapping.
ls_exception.time
Time and date that the LS exception entry was generated.
ls_exception.ls_name
Name of link station. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
ls_exception.adj_cp_name
Fully qualified, 17-byte, adjacent CP name. It 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.) The value of this field is determined as follows:

If an adjacent CP name was received on XID, it is returned.

If an adjacent CP name was received on XID, but a locally-defined value is available, it is returned.

Otherwise, null is returned.

ls_exception.node_id
Node ID received from adjacent node during XID exchange (or null if none is received). This is a 4–byte hexadecimal string.
ls_exception.tg_number
Number associated with the TG to this link station. Range 0 through 256. A value of 256 indicates that the TG number was unknown at the time of the failure.
ls_exception.general_sense
The error sense data associated with the start sequence of activation of a link up to the beginning of the XID sequence. This is generated by the node.
ls_exception.retry
Indicates whether the node will retry the start request to activate the link.
AP_NO
The node will not retry the start request.
AP_YES
The node will retry the start request.
ls_exception.end_sense
Sense data associated with the termination of the activation attempt. This is generated by the DLC layer.
ls_exception.xid_local_sense
Locally generated sense data sent in XID.
ls_exception.xid.remote_sense
Remotely generated sense data received in XID.
ls_exception.xid_error_byte
Offset of error bit in error byte in XID (range 0 through 65535). The value 65535 indicates that this field has no meaning.
ls_exception.xid_error_bit
Offset of error bit in error byte in XID (range 0 through 7). The value 8 indicates that this field has no meaning.
ls_exception.dlc_type
Type of DLC. The Program supports the following types:

AP_SDLC
AP_X25
AP_TR

Additional DLC types can be defined by specifying the new type on the DEFINE_DLC verb. See DEFINE_DLC for more information.
ls_exception.local_addr.length
The length of local link station's address.
ls_exception.local_addr.address
The local link station's address.
ls_exception.destination_addr.length
The length of destination link station's address on adjacent node.
ls_exception.destination_addr.address
Destination link station's address on adjacent node.
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_EXCEPTION_INDEX

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