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