QUERY_DOWNSTREAM_PU


The Communications Server icon lets you know that there is a change in the way things operate.
This verb applies only to Communications Server.
QUERY_DOWNSTREAM_PU returns information about downstream PUs (defined using a DEFINE_LS verb).

The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific local PU or to obtain the list information in several chunks, the dspu_name field should be set. Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field is ignored.

The list of PUs can be filtered by the type of service the local node provides for the downstream PU. To do this, the dspu_services field should be set to AP_PU_CONCENTRATION or AP_DLUR.

VCB Structure

typedef struct query_downstream_pu
{
        unsigned short  opcode;            /* verb operation code           */
        unsigned char   attributes;        /* Verb attributes               */
        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   dspu_name[8];      /* Downstream PU name            */
        unsigned char   dspu_services;     /* filter on DSPU services type  */
} QUERY_DOWNSTREAM_PU;
typedef struct downstream_pu_data
{
        unsigned short  overlay_size;      /* size of this entry            */
        unsigned char   dspu_name[8];      /* PU name                       */
        unsigned char   description[RD_LEN];
                                           /* resource description          */
        unsigned char   ls_name[8];        /* Link name                     */
        unsigned char   pu_sscp_sess_active;
                                           /* Is PU-SSCP session active     */
        unsigned char   dspu_services;     /* DSPU service type             */
        SESSION _STATS  pu_sscp_stats;     /* SSCP-PU session stats         */
        unsigned char   reserva[20];       /* reserved                      */
} DOWNSTREAM_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 win size      */
        unsigned short  cur_send_pac_win;  /* current send pacing win size  */
        unsigned short  max_rcv_pac_win;   /* max receive pacing win 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 recvd  */
        unsigned long   rcv_data_bytes;    /* number of data bytes received */
        unsigned char   sidh;              /* session ID high byte          */
        unsigned char   sidl;              /* session ID low byte           */
        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_DOWNSTREAM_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:
AP_SUMMARY
Returns summary information only.
AP_DETAIL
Returns detailed information.

The dslu_name specified (see the following parameter, dslu_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.
dspu_name
Name of the downstream PU that is 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.
dspu_services
DSPU services filter. If set to AP_PU_CONCENTRATION, only downstream LUs served by PU concentration are returned. If set to AP_DLUR, only DLUR-supported LUs are returned. Otherwise, if set to AP_NONE, information on all downstream LUs is 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.
downstream_pu_data.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
downstream_pu_data.dspu_name
Name of the downstream PU. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
downstream_pu_data.description
Resource description (as specified on DEFINE_LS).
downstream_pu_data.ls_name
Name of link station. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
downstream_pu_data.pu_sscp_sess_active
Indicates whether the PU_SSCP session to the downstream PU is active. Set to either AP_YES or AP_NO.
downstream_pu_data.dspu_services
Specifies the services that the local node provides to the downstream PU across the link. This is set to one of the following values:
AP_PU_CONCENTRATION
Local node that provides PU concentration for the downstream LU.
AP_DLUR
Local node that provides DLUR support for the downstream LU.
downstream_pu_data.pu_sscp_stats.rcv_ru_size
Maximum receive RU size. If downstream_lu_detail.det_data.dspu_services is set to AP_PU_CONCENTRATION, then this field is reserved.
downstream_pu_data.pu_sscp_stats.send_ru_size
Maximum send RU size. If downstream_lu_detail.det_data.dspu_services is set to AP_PU_CONCENTRATION, then this field is reserved.
downstream_pu_data.pu_sscp_stats.max_send_btu_size
Maximum BTU size that can be sent.
downstream_pu_data.pu_sscp_stats.max_rcv_btu_size
Maximum BTU size that can be received.
downstream_pu_data.pu_sscp_stats.max_send_pac_win
This field will always be set to zero.
downstream_pu_data.pu_sscp_stats.cur_send_pac_win
This field will always be set to zero.
downstream_pu_data.pu_sscp_stats.max_rcv_pac_win
This field will always be set to zero.
downstream_pu_data.pu_sscp_stats.cur_rcv_pac_win
This field will always be set to zero.
downstream_pu_data.pu_sscp_stats.send_data_frames
Number of normal flow data frames sent.
downstream_pu_data.pu_sscp_stats.send_fmd_data_frames
Number of normal flow FMD data frames sent.
downstream_pu_data.pu_sscp_stats.send_data_bytes
Number of normal flow data bytes sent.
downstream_pu_data.pu_sscp_stats.rcv_data_frames
Number of normal flow data frames received.
downstream_pu_data.pu_sscp_stats.rcv_fmd_data_frames
Number of normal flow FMD data frames received.
downstream_pu_data.pu_sscp_stats.rcv_data_bytes
Number of normal flow data bytes received.
downstream_pu_data.pu_sscp_stats.sidh
Session ID high byte.
downstream_pu_data.pu_sscp_stats.sidl
Session ID low byte.
downstream_pu_data.pu_sscp_stats.odai
Origin Destination Address Indicator. When bringing up a session, the sender of the BIND sets this field to zero if the local node contains the primary link station, and sets it to 1 if the BIND sender is the node containing the secondary link station.
downstream_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.
downstream_pu_data.pu_sscp_stats.pacing_type
Receive pacing type in use on the upstream PU-SSCP session. This will take the value 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