QUERY_PU

QUERY_PU returns a list of local PUs and the links associated with them.

The information is returned as a list. 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.

The verb specifies whether local PUs are attached directly to the host system or attached via DLUR. The host_attachment field can be used as a filter so that only information about the specified attachment type is returned.

VCB Structure

typedef struct query_pu
{
   unsigned short  opcode;            /* verb operation code           */
   unsigned char   attributes;        /* Verb attributes               */
   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];        /* PU name                       */
   unsigned char   host_attachment;   /* Host Attachment               */
} QUERY_PU;
typedef struct pu_data
{
   unsigned short  overlay_size;      /* size of this entry            */
   unsigned char   pu_name[8];        /* PU name                       */
   unsigned char   description[RD_LEN];
                                      /* resource description          */
   unsigned char   ls_name[8];        /* LS name                       */
   unsigned char   pu_sscp_sess_active;
                                      /* Is PU-SSCP session active     */
   unsigned char   host_attachment;   /* Host attachment               */
   SESSION_STATS   pu_sscp_stats;     /* PU-SSCP session statistics    */
   unsigned char   sscp_id[6];        /* SSCP ID                       */
   unsigned char   conventional_lu_compression;
                                      /* Data compression requested    */
                                      /* for conventional LU sessions  */
   unsigned char   conventional_lu_cryptography;
                                      /* Cryptography required for     */
                                      /* conventional LU sessions      */
   unsigned char   reserva[12];       /* reserved                      */
} PU_DATA;
typedef struct session_stats
{
   unsigned short  rcv_ru_size;       /* session receive RU size       */
   unsigned short  send_ru_size;      /* session send RU size          */
   unsigned short  max_send_btu_size; /* max send BTU size             */
   unsigned short  max_rcv_btu_size;  /* max rcv BTU size              */
   unsigned short  max_send_pac_win;  /* max send pacing window size   */
   unsigned short  cur_send_pac_win;  /* curr send pacing window size  */
   unsigned short  max_rcv_pac_win;   /* max recv pacing window size   */
   unsigned short  cur_rcv_pac_win;   /* current receive pacing        */
                                      /* window size                   */
   unsigned long   send_data_frames;  /* number of data frames sent    */
   unsigned long   send_fmd_data_frames;
                                      /* num of FMD data frames sent   */
   unsigned long   send_data_bytes;   /* number of data bytes sent     */
   unsigned long   rcv_data_frames;   /* num data frames received      */
   unsigned long   rcv_fmd_data_frames;
                                      /* num of FMD data frames rcvd   */
   unsigned long   rcv_data_bytes;    /* number of data bytes received */
   unsigned char   sidh;              /* session ID high byte          */
                                      /* (from LFSID)                  */
   unsigned char   sidl;              /* session ID low byte           */
                                      /* (from LFSID)                  */
   unsigned char   odai;              /* ODAI bit set                  */
   unsigned char   ls_name[8];        /* Link station name             */
   unsigned char   pacing_type;       /* type of pacing in use         */
} SESSION_STATS;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_QUERY_PU
attributes
The attributes of the verb. This field is a bit field. The first bit contains the visibility of the resource to be defined and corresponds to one of the following:

AP_EXTERNALLY_VISIBLE
AP_INTERNALLY_VISIBLE

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.
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 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 the first PU to be listed. 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.
host_attachment
Filter for host attachment:
AP_NONE
Return information about all local PUs.
AP_DLUR_ATTACHED
Return information about all local PUs that are supported by DLUR.
AP_DIRECT_ATTACHED
Return information about only those PUs that are directly attached to the host system.

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.
pu_data.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
pu_data.pu_name
PU name. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
pu_data.description
Resource description (as specified on DEFINE_LS or DEFINE_INTERNAL_PU). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
pu_data.ls_name
Name of the link station associated with this PU. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
pu_data.pu_sscp_sess_active
Specifies whether the PU-SSCP session is active (AP_YES or AP_NO).
pu_data.host_attachment
Local PU host attachment type:
AP_DLUR_ATTACHED
PU is attached to host system using DLUR.
AP_DIRECT_ATTACHED
PU is directly attached to host system.
pu_data.pu_sscp_stats.rcv_ru_size
This field is always reserved.
pu_data.pu_sscp_stats.send_ru_size
This field is always reserved.
pu_data.pu_sscp_stats.max_send_btu_size
Maximum BTU size that can be sent.
pu_data.pu_sscp_stats.max_rcv_btu_size
Maximum BTU size that can be received.
pu_data.pu_sscp_stats.max_send_pac_win
This field will always be set to zero.
pu_data.pu_sscp_stats.cur_send_pac_win
This field will always be set to zero.
pu_data.pu_sscp_stats.max_rcv_pac_win
This field will always be set to zero.
pu_data.pu_sscp_stats.cur_rcv_pac_win
This field will always be set to zero.
pu_data.pu_sscp_stats.send_data_frames
Number of normal flow data frames sent.
pu_data.pu_sscp_stats.send_fmd_data_frames
Number of normal flow FMD data frames sent.
pu_data.pu_sscp_stats.send_data_bytes
Number of normal flow data bytes sent.
pu_data.pu_sscp_stats.rcv_data_frames
Number of normal flow data frames received.
pu_data.pu_sscp_stats.rcv_fmd_data_frames
Number of normal flow FMD data frames received.
pu_data.pu_sscp_stats.rcv_data_bytes
Number of normal flow data bytes received.
pu_data.pu_sscp_stats.sidh
Session ID high byte.
pu_data.pu_sscp_stats.sidl
Session ID low byte.
pu_data.pu_sscp_stats.odai
Origin destination address indicator. When bringing up a session, the sender of the ACTPU sets this field to zero if the local node contains the primary link station, and sets it to one if the ACTPU sender is the node containing the secondary link station.
pu_data.pu_sscp_stats.ls_name
Link station name associated with statistics. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
pu_data.pu_sscp_stats.pacing_type
Receiving pacing type in use on the PU-SSCP session. This will take the value AP_NONE.
pu_data.sscp_id
This is a 6–byte field containing the SSCP ID received in the ACTPU for the PU.

If pu_sscp_sess_active is not AP_YES, then this field will be zeroed.

pu_data.conventional_lu_compression
Specifies whether data compression is requested for sessions using this PU.
AP_NO
The local node should not be compressing or decompressing data flowing on sessions using this PU.
AP_YES
Data compression should be enabled for sessions dependent on this PU if the host requests compression.
pu_data.conventional_lu_cryptography
Specifies whether session level encryption is required for conventional LU sessions dependent on this PU.
AP_NONE
Session level encryption is not performed by the Program.
AP_MANDATORY
Mandatory session level encryption is performed by the Program if an import key is available to the LU. Otherwise, it must be performed by the application that uses the LU (if this is PU Concentration, then it is performed by a downstream LU).
AP_OPTIONAL
This value allows the cryptography used to be driven by the host application on a per session basis. If the host requests cryptography for a session dependent on this PU, then the behaviour of the Program is as for AP_MANDATORY. If the host does not request cryptography, then the behaviour is the same as AP_NONE.
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_PU_NAME

AP_INVALID_PU_TYPE
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