QUERY_FOCAL_POINT

QUERY_FOCAL_POINT returns information about focal points that Personal Communications or Communications Server knows about.

This information is returned as a list. To obtain information about a specific focal point category or to obtain the list information in several chunks, the ms_category 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.

Note:
If no focal point is found, then one FP_DATA structure will be returned with fp_data.fp_type set to AP_NO_FP. See the following structure.

VCB Structure

typedef struct query_focal_point
{
        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   ms_category[8];    /* name of MS category          */
} QUERY_FOCAL_POINT;
typedef struct fp_data
{
        unsigned short  overlay_size;      /* size of this entry           */
        unsigned char   ms_appl_name[8];   /* focal point application name */
        unsigned char   ms_category[8];    /* focal point category         */
        unsigned char   description[RD_LEN];
                                           /* resource description         */
        unsigned char   fp_fqcp_name[17];  /* focal pt fully qual CP name  */
        unsigned char   bkup_appl_name[8]; /* backup focal pt appl name    */
        unsigned char   bkup_fp_fqcp_name[17];
                                           /* backup FP fully qualified    */
                                           /* CP name                      */
        unsigned char   implicit_appl_name[8];
                                           /* implicit FP appl name        */
        unsigned char   implicit_fp_fqcp_name[17];
                                           /* implicit FP fully            */
                                           /* qualified CP name            */
        unsigned char   fp_type;           /* focal point type             */
        unsigned char   fp_status;         /* focal point status           */
        unsigned char   fp_routing;        /* type of MDS routing to use   */
        unsigned char   reserva[20];       /* reserved                     */
        unsigned short  number_of_appls;   /* number of applications       */
} FP_DATA;
Each fp_data is followed by number_of_appls application names. Each application name has the following format:
typedef struct application_id
{
        unsigned char    appl_name[8];     /* application name             */
} APPLICATION_ID;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_QUERY_FOCAL_POINT
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: The ms_category specified (see the following parameter, ms_category) 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.
ms_category
Management services category. This can either be one of the 4-byte architecturally defined values (right-padded with EBCDIC spaces) for management services categories as described in SNA management services, or an 8-byte type 1134 EBCDIC installation defined name. 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
The number of entries actually returned.
total_num_entries
Total number of entries that could have been returned. This can be higher than num_entries.
fp_data.overlay_size
The number of bytes in this entry (including any application names, and hence the offset to the next entry returned (if any)).
fp_data.ms_appl_name
Name of the currently active focal point application. This can either be one of the 4-byte architecturally defined values (right-padded with EBCDIC spaces) for management services applications as described in SNA management services, or an 8-byte type 1134 EBCDIC installation defined name.
fp_data.ms_category
Management services category. This can either be one of the 4-byte architecturally defined values (right-padded with EBCDIC spaces) for management services categories as described in SNA management services, or an 8-byte type 1134 EBCDIC installation defined name.
fp_data.description
Resource description (as specified on DEFINE_FOCAL_POINT). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
fp_data.fp_fqcp_name
Currently active focal point's fully qualified control point 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.)
fp_data.bkup_appl_name
Name of backup focal point application. This can either be one of the 4-byte architecturally defined values (right-padded with EBCDIC spaces) for management services applications as described in SNA management services, or an 8-byte type 1134 EBCDIC installation defined name.
fp_data.bkup_fp_fqcp_name
Backup focal point's fully qualified control point 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.)
fp_data.implicit_appl_name
Name of implicit focal point application (specified using the DEFINE_FOCAL_POINT verb). This can either be one of the four byte architecturally defined values (right-padded with EBCDIC spaces) for management services applications as described in SNA management services, or an 8-byte type 1134 EBCDIC installation defined name. This field will be the same as the ms_appl_name if the implicit focal point is the currently active focal point.
fp_data.implicit_fp_fqcp_name
Implicit focal point's fully qualified control point name (as specified using the DEFINE_FOCAL_POINT verb). 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 will be the same as the fp_fqcp_name if the implicit focal point is the currently active focal point.
fp_data.fp_type
Type of focal point. Refer to SNA Management Services for further detail. This will be one of the following values:

AP_EXPLICIT_PRIMARY_FP
AP_BACKUP_FP
AP_DEFAULT_PRIMARY_FP
AP_IMPLICIT_PRIMARY_FP
AP_DOMAIN_FP
AP_HOST_FP
AP_NO_FP

fp_data.fp_status
Status of the focal point. This can be one of the following values:
AP_NOT_ACTIVE
The focal point is currently not active.
AP_ACTIVE
The focal point is currently active.
AP_PENDING
The focal point is pending active. This occurs after an implicit request has been sent to the focal point and before the response has been received.
AP_NEVER_ACTIVE
No focal point information is available for the specified category although application registrations for the category have been accepted.
fp_data.fp_routing
Type of routing that applications should specify when using MDS transport to send data to the focal point.
AP_DEFAULT
Default routing is used to deliver the MDS_MU to the focal point.
AP_DIRECT
The MDS_MU will be routed on a session directly to the focal point.
fp_data.number_of_appls
Number of applications registered for this focal point category. Following this field will be number_of_appls application_id entries, one for each application registered for the focal point category.
application_id.appl_name
Name of application registered for focal point category. This can either be one of the 4-byte architecturally defined values (right-padded with EBCDIC spaces) for management services applications as described in SNA management services, or an 8-byte type 1134 EBCDIC installation defined name.
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_MS_CATEGORY

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