SNAP-IX NOF Programmer's Guide - 3.167 REGISTER_INDICATION

3.167 REGISTER_INDICATION_SINK

REGISTER_INDICATION_SINK registers the NOF application to receive indications of a particular type; for details of the SNAP-IX NOF indications, see NOF Indications. The application specifies the required type of indication by its opcode parameter; an application can register more than once to accept multiple indication types. Each time an event occurs for which the application has requested indications (for example a change in the configuration of the application's target node or a change in the status of a DLC), SNAP-IX sends the appropriate indication message to the application.

A NOF_STATUS_INDICATION, which indicates status changes for the target node or file, may be returned to an application that has registered for any type of indication. For more information, see NOF_STATUS_INDICATION.

This verb must always be issued using the asynchronous NOF API entry point, including a callback routine (for more information about the NOF API entry points, see Asynchronous Entry Point: nof_async ). SNAP-IX uses this callback routine to return the requested indications to the application.

This verb may be issued to different targets depending on the type of indications required, as follows:

To register for SNA network file indications, the target must be the sna.net file.
To register for server indications, no target is required; the application must specify a null target handle.
To register for configuration indications relating to domain resources, the target must be the domain configuration file.
To register for configuration indications relating to node resources, or to register for any other indications, the target may be either a running node or an inactive node on a computer where the SNAP-IX software is running.

3.167.1 VCB Structure

typedef struct register_indication_sink
{
   AP_UINT16        opcode;               /* verb operation code             */
   unsigned char    reserv2;              /* reserved                        */
   unsigned char    format;               /* reserved                        */
   AP_UINT16        primary_rc;           /* primary return code             */
   AP_UINT32        secondary_rc;         /* secondary return code           */
   AP_UINT32        proc_id;              /* reserved                        */
   AP_UINT16        queue_id;             /* reserved                        */
   AP_UINT16        indication_opcode;    /* opcode of indication to be sunk */
} REGISTER_INDICATION_SINK;

3.167.2 Supplied Parameters

The application supplies the following parameters:

opcode

AP_REGISTER_INDICATION_SINK

indication_opcode

The opcode parameter of the indication to be returned. SNAP-IX will send this indication to the application's callback routine every time the indication is generated.

To receive configuration indications, specify the value AP_CONFIG_INDICATION. If the target handle specified on the REGISTER_INDICATION_SINK verb identifies the domain configuration file, this value requests an indication each time the file is updated; if the target handle identifies a node, this value requests an indication each time the node's configuration is updated.

To receive SNA network file indications, issue the verb using a target handle that identifies the sna.net file, and specify the value AP_SNA_NET_INDICATION. This value requests an indication each time the file is updated.

For all other indications, specify the opcode value for the required indication. For more information, see the descriptions of individual indications in NOF Indications.

3.167.3 Returned Parameters: Successful Execution

If the verb executes successfully, SNAP-IX returns the following parameters:

primary_rc: AP_OK
secondary_rc: Not used.

3.167.4 Returned Parameters: Parameter Check

If the verb does not execute because of a parameter error, SNAP-IX returns the following parameters:

primary_rc

AP_PARAMETER_CHECK

secondary_rc

Possible values are:

AP_INVALID_OP_CODE

One of the following has occurred:

The indication_opcode parameter did not match the opcode of any of the SNAP-IX NOF API indications.
The indication_opcode parameter specified an indication type that does not apply to the specified target. If the target handle identifies the domain configuration file, only configuration indications are valid; if the target handle identifies the sna.net file, only SNA network file indications are valid; and if the target handle specifies a running node, all indications except SNA network file indications are valid.

AP_DYNAMIC_LOAD_ALREADY_REGD

The indication_opcode parameter was set to a reserved value.

AP_SYNC_NOT_ALLOWED

The application issued REGISTER_INDICATION_SINK using the synchronous NOF entry point. This verb must use the asynchronous entry point.

Common Return Codes lists further secondary return codes associated with AP_PARAMETER_CHECK, which are common to all NOF verbs.

3.167.5 Returned Parameters: Function Not Supported

If the verb does not execute successfully because the local node does not support the function associated with the specified indication, SNAP-IX returns the following parameters:

primary_rc

AP_FUNCTION_NOT_SUPPORTED: The local node does not support the specified indication. For details of the support required for each indication, see the description of each indication in NOF Indications.

3.167.6 Returned Parameters: Other Conditions

Common Return Codes lists further combinations of primary and secondary return codes that are common to all NOF verbs.