QUERY_DLUR_PU
QUERY_DLUR_PU returns a list of information about DLUR-supported PUs.
The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific PU, or to obtain the list information in several chunks, the pu_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 pu_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).
The list of PUs returned can be filtered either by dlus_name or by whether the PU is local or downstream or by both. If filtering by DLUS is desired, the dlus_name field should be set (otherwise this field should be set to all zeros). If filtering by PU location is desired, the filter field should be set to AP_INTERNAL or AP_DOWNSTREAM (otherwise, if no filtering is required, this field should be set to AP_NONE).
VCB Structure
typedef struct query_dlur_pu
{
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 pu_name[8]; /* name of PU */
unsigned char dlus_name[17]; /* fully qualified DLUS name */
unsigned char filter; /* local/downstream filter */
} QUERY_DLUR_PU;typedef struct dlur_pu_summary
{
unsigned short overlay_size; /* size of this entry */
unsigned char pu_name[8]; /* name of PU */
unsigned char description[RD_LEN];
/* resource description */
} DLUR_PU_SUMMARY;typedef struct dlur_pu_detail
{
unsigned short overlay_size; /* size of this entry */
unsigned char pu_name[8]; /* name of PU */
unsigned char description[RD_LEN];
/* resource description */
unsigned char defined_dlus_name[17];
/* defined DLUS name */
unsigned char bkup_dlus_name[17]; /* backup DLUS name */
unsigned char pu_id[4]; /* PU identifier */
unsigned char pu_location; /* downstream or local PU */
unsigned char active_dlus_name[17];
/* active DLUS name */
unsigned char ans_support; /* Auto-Network shutdown support */
unsigned char pu_status; /* status of the PU */
unsigned char dlus_session_status; /* status of the DLUS pipe */
unsigned char reserv3; /* reserved */
FQPCID fqpcid; /* FQPCID used on pipe */
unsigned short dlus_retry_timeout; /* DLUS retry timeout */
unsigned short dlus_retry_limit; /* DLUS retry limit */
} DLUR_PU_DETAIL;typedef struct fqpcid
{
unsigned char pcid[8]; /* proc correlator identifier */
unsigned char fqcp_name[17]; /* originator's network */
/* qualified CP name */
unsigned char reserve3[3]; /* reserved */
} FQPCID;Supplied Parameters
- opcode
- AP_QUERY_DLUR_PU
- 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 pu_name specified (see the following parameter, pu_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.
- pu_name
- Name of PU being queried. This is an 8-byte alphanumeric type A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces. This field is ignored if list_options is set to AP_FIRST_IN_LIST.
- dlus_name
- DLUS filter. This should be set to all zeros or to a 17-byte string composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. If this field is set then only PUs associated with an SSCP-PU session to the specified DLUS node are returned. This field is ignored if it is set to all zeros.
- filter
- This field should be set to AP_NONE.
Returned 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.
- dlur_pu_summary.overlay_size
- The number of bytes in this entry, and hence the offset to the next entry returned (if any).
- dlur_pu_summary.pu_name
- Name of PU. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
- dlur_pu_summary.description
- Resource description (as specified on DEFINE_INTERNAL_PU). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
- dlur_pu_detail.overlay_size
- The number of bytes in this entry, and hence the offset to the next entry returned (if any).
- dlur_pu_detail.pu_name
- Name of PU. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
- dlur_pu_detail.description
- Resource description (as specified on DEFINE_INTERNAL_PU). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
- dlur_pu_detail.defined_dlus_name
- Name of the DLUS node defined by either a DEFINE_INTERNAL_PU verb or DEFINE_LS verb (with dspu_services set to AP_DLUR). This is a 17-byte string 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.)
- dlur_pu_detail.bkup_dlus_name
- Name of backup DLUS node defined by either a DEFINE_INTERNAL_PU verb or DEFINE_LS verb (with dspu_services set to AP_DLUR). This is a 17-byte string 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.)
- dlur_pu_detail.pu_id
- PU identifier defined in a DEFINE_INTERNAL_PU verb or obtained in an XID from a downstream PU. This a 4-byte hexadecimal string. Bits 0–11 are set to the Block number and bits 12–31 are set to the ID number that uniquely identifies the PU.
- dlur_pu_detail.pu_location
- Location of PU. The only value returned is:
AP_INTERNAL
AP_DOWNSTREAM - dlur_pu_detail.active_dlus_name
- Name of the DLUS node that the PU is currently using. This is a 17-byte string composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, which is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) If the SSCP-PU session is not active, this field will be set to all zeros.
- dlur_pu_detail.ans_support
- Auto Network Shutdown support. This field is reserved if the
SSCP-LU session is inactive. The support setting is sent to DLUR from
the DLUS at SSCP-PU activation. It specifies whether link-level contact
should be continued if the subarea node initiates an auto network
shutdown procedure for the SSCP controlling the PU. This can be one
of the following values:
AP_CONT
AP_STOP - dlur_pu_detail.pu_status
- Status of the PU (as seen by DLUR). This can be set to one of
the following values:
- AP_RESET
- The PU is in reset state.
- AP_PEND_ACTPU
- The PU is waiting for an ACTPU from the host.
- AP_PEND_ACTPU_RSP
- Having forwarded an ACTPU to the PU, DLUR is now waiting for the PU to respond to it.
- AP_ACTIVE
- The PU is active.
- AP_PEND_DACTPU_RSP
- Having forwarded a DACTPU to the PU, DLUR is waiting for the PU to respond to it.
- AP_PEND_INOP
- DLUR is waiting for all necessary events to complete before it deactivates the PU.
- dlur_pu_detail.dlus_session_status
- Status of the DLUS pipe currently being used by the PU. This
can be one of the following values:
AP_PENDING_ACTIVE
AP_ACTIVE
AP_PENDING_INACTIVE
AP_INACTIVE - dlur_pu_detail.fqpcid.pcid
- Procedure correlator ID used on the pipe. This is an 8-byte hexadecimal string. If the SSCP-PU session is not active this field will be set to zeros.
- dlur_pu_detail.fqpcid.fqcp_name
- Fully qualified Control Point name used on the pipe. 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 SSCP-PU session is not active this field will be set to zeros.
- dlur_pu_detail.dlus_retry_timeout
- Interval in seconds between second and subsequent attempts to contact the DLUS specified in the dlus_name and bkup_dlus_name fields. The interval between the initial attempt and the first retry is always one second. If zero is specified, the default value configured through DEFINE_DLUR_DEFAULTS is used.
- def_data.dlus_retry_limit
- Maximum number of retries after an initial failure to contact the DLUS specified in the dlus_name and bkup_dlus_name fields. If zero is specified, the default value configured through DEFINE_DLUR_DEFAULTS is used. If X'FFFF' is specified, the Program retrys indefinitely.
- primary_rc
- AP_PARAMETER_CHECK
- secondary_rc
- AP_INVALID_PU_NAME
AP_INVALID_FILTER_OPTION
AP_INVALID_LIST_OPTION
- primary_rc
- AP_NODE_NOT_STARTED
- primary_rc
- AP_UNEXPECTED_SYSTEM_ERROR