DEFINE_FOCAL_POINT

Personal Communications or Communications Server can have a number of types of relationships with different focal points. The DEFINE_FOCAL_POINT verb defines a focal point with which Personal Communications or Communications Server has an implicit relationship (which can be of type primary or backup). These relationships, and the ways in which they can be established, are described below. Relationships between a management services focal point (FP) and a management services entry point (EP) for a given category are established when they exchange Management Services Capabilities messages. The following types of FP-EP relationships can be established.
  • Explicit
    • This relationship is established by an operator at the focal point assigning the entry point to its sphere of control. The focal point initiates exchange of Management Services Capabilities.
  • Implicit (primary)
    • The relationship is established when an operator at an entry point assigns the entry point to a specified focal point (for example, when the operator issues a DEFINE_FOCAL_POINT verb). The entry point initiates the Management Services Capabilities exchange.
  • Implicit (backup)
    • This relationship is established when an entry point loses either an explicit or implicit primary focal point. The entry point initiates Management Services Capabilities exchange. The identity of the backup focal point can be defined (using the DEFINE_FOCAL_POINT verb) or can be acquired via Management Services Capabilities exchange.
  • Default
    • This relationship is established when an FP acquires an EP without operator intervention. The FP initiates the MS Capabilities exchange. This relationship only applies to EPs that are NNs.
  • Domain
    • This relationship is established when a serving network node (NN) informs the end node entry point of the identity of the focal point. Domain relationships are only valid in end nodes.
  • Host
    • This relationship does not involve Management Services Capabilities exchange and is established by the configuration of an SSCP-PU session from the entry point node to a host. It is the lowest precedence focal point relationship.
Each DEFINE_FOCAL_POINT verb can only be used to define an implicit focal point (which can be of type primary or backup). Each DEFINE_FOCAL_POINT verb is issued for a specific management services category. Within this category the DEFINE_FOCAL_POINT verb can be used to do the following:
  • Define a focal point
  • Replace a focal point (or backup focal point)
  • Revoke the currently active focal point

The fields on a DEFINE_FOCAL_POINT verb are used as follows.

The ms_category must always be filled in. The combination of the fp_fqcp_name and ms_appl_name fields specify the focal point (or backup focal point if the backup field is set to AP_YES) for the specified category.

If the verb is being issued to revoke the currently active focal point without providing a new one, the fp_fqcp_name and ms_appl_name fields should be set to all zeros. When a DEFINE_FOCAL_POINT verb defining or replacing a focal point is received, Personal Communications or Communications Server attempts to establish an implicit primary focal point relationship with the specified focal point by sending a Management Services Capabilities request. When Personal Communications or Communications Server receives a DEFINE_FOCAL_POINT verb revoking the currently active focal point, it sends a Management Services Capabilities revoke message to the focal point. It is recommended that the DELETE_FOCAL_POINT verb (specifying AP_ACTIVE) be used to revoke the currently active focal point.

VCB Structure

typedef struct define_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   reserved;         /* reserved                     */
        unsigned char   ms_category[8];   /* management services category */
        unsigned char   fp_fqcp_name[17]; /* Fully qualified focal        */
                                          /* point CP name                */
        unsigned char   ms_appl_name[8];  /* Focal point application name */
        unsigned char   description[RD_LEN];
                                          /* resource description         */
        unsigned char   backup;           /* is focal point a backup      */
        unsigned char   reserv3[16];      /* reserved                     */
} DEFINE_FOCAL_POINT;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_DEFINE_FOCAL_POINT
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
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_fqcp_name
Focal point's fully qualified control point name. This should be set to all zeros or 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.) If the focal point is being revoked, this field should be set to all zeros.
ms_appl_name
Focal point application name. 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 focal point is being revoked, this field should be set to all zeros.
description
Resource description (returned on QUERY_FOCAL_POINT). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
backup
Specifies whether a backup focal point is being defined (AP_YES or AP_NO). This field is reserved if the currently active focal point is being revoked. It is recommended that the DELETE_FOCAL_POINT verb (specifying AP_ACTIVE) be used to revoke the currently active focal point.

Returned Parameters

If the verb executes successfully, the Program returns the following parameter:
primary_rc
AP_OK
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_FP_NAME

AP_INVALID_CATEGORY_NAME

If the verb does not execute successfully, the Program returns the following parameters:
primary_rc
AP_REPLACED

AP_UNSUCCESSFUL

secondary_rc
AP_IMPLICIT_REQUEST_REJECTED

AP_IMPLICIT_REQUEST_FAILED

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 the node is stopping, the Program returns the following parameter:
primary_rc
AP_NODE_STOPPING
The Program returns the following parameter if the verb does not execute because of a system error or because the Program failed to contact the focal point successfully:
primary_rc
AP_UNEXPECTED_SYSTEM_ERROR