2 Writing MS Applications

Function Call

        void ms (
                 AP_UINT32  target_handle,
                 void *     msvcb
                 );

Supplied Parameters

An application supplies the following parameters when it uses the ms entry point:

target_handle

For the UNREGISTER_MS_APPLICATION, UNREGISTER_NMVT_APPLICATION, and DISCONNECT_MS_NODE verbs, the application supplies the value that was returned on the CONNECT_MS_NODE verb. This parameter is used to identify the target SNAP-IX node.

For all other verbs, this parameter is not used; set it to 0 (zero).

msvcb

Pointer to a Verb Control Block (VCB) that contains the parameters for the verb being issued. The VCB structure for each verb is described in Management Services Verbs. These structures are defined in the MS API /usr/include/sna/ms_c.h.

Note

The MS VCBs contain many parameters marked as reserved; some of these are used internally by the SNAP-IX software, and others are not used in this version but may be used in future versions. Your application must not attempt to access any of these reserved parameters; instead, it must set the entire contents of the VCB to zero to ensure that all of these parameters are zero, before it sets other parameters that are used by the verb. This ensures that SNAP-IX will not misinterpret any of its internally-used parameters, and also that your application will continue to work with future SNAP-IX versions in which these parameters may be used to provide new functions.

To set the VCB contents to zero, use memset:

memset(vcb, 0, sizeof(vcb));

Returned Values

The ms entry point does not have a return value. When the call returns, the application should examine the return code in the VCB to determine whether the verb completed successfully and to determine parameters it needs for further verbs. In particular, when the CONNECT_MS_NODE verb completes successfully, the VCB contains the target_handle that the application should use when the application issues subsequent verbs.

Using the Synchronous Entry Point

Only one synchronous verb can be outstanding at any time for each target handle. A synchronous verb fails with the primary return code AP_STATE_CHECK and secondary return code AP_SYNC_PENDING if another synchronous verb for the same target handle is in progress.

Function Call

 unsigned short ms_async(
                         AP_UINT32     target_handle,
                         void *        msvcb,
                         VMV_CALLBACK  comp_proc,
                         AP_CORR       corr
                        );

 typedef void (*VMV_CALLBACK) (
                               AP_UINT32   target_handle,
                               void *      msvcb,
                               AP_CORR     corr
                              );

  typedef union ap_corr  {
                          void *          corr_p;
                          AP_UINT32       corr_l;
                          AP_INT32        corr_i;
                         } AP_CORR;

For more information about the parameters in the VMV_CALLBACK structure, see The Callback Routine Specified on the ms_async Entry Point.

Supplied Parameters

An application supplies the following parameters when it uses the ms_async entry point:

target_handle

Identifier for the target SNAP-IX node. For the REGISTER_*, UNREGISTER_*, and DISCONNECT_MS_NODE verbs, the application supplies the value that was returned on the CONNECT_MS_NODE verb.

For all other verbs, this parameter is not used; set it to 0 (zero).

msvcb

Pointer to a Verb Control Block (VCB) that contains the parameters for the verb being issued. The VCB structure for each verb is described in Management Services Verbs. These structures are defined in the MS API header file /usr/include/sna/ms_c.h.

Note

The MS VCBs contain many parameters marked as reserved; some of these are used internally by the SNAP-IX software, and others are not used in this version but may be used in future versions. Your application must not attempt to access any of these reserved parameters; instead, it must set the entire contents of the VCB to zero to ensure that all of these parameters are zero, before it sets other parameters that are used by the verb. This ensures that SNAP-IX will not misinterpret any of its internally-used parameters, and also that your application will continue to work with future SNAP-IX versions in which these parameters may be used to provide new functions.

To set the VCB contents to zero, use memset:

memset(vcb, 0, sizeof(vcb));

comp_proc

The callback routine that SNAP-IX will call when the verb completes. For more information about the requirements for a callback routine, see The Callback Routine Specified on the ms_async Entry Point.

corr

An optional correlator for use by the application. This parameter is defined as a C union so that the application can specify any of three different parameter types: pointer, unsigned long, or integer.

SNAP-IX does not use this value, but passes it as a parameter to the callback routine when the verb completes. This value enables the application to correlate the returned information with its other processing.

Returned Values

The asynchronous entry point returns one of the following values:

AP_COMPLETED

The verb has already completed. The application can examine the parameters in the VCB to determine whether the verb completed successfully. SNAP-IX does not call the supplied callback routine for this verb.

AP_IN_PROGRESS

The verb has not yet completed. The application can continue with other processing, including issuing other MS verbs, provided that they do not depend on the completion of the current verb. However, the application should not attempt to examine or modify the parameters in the VCB supplied to this verb.

SNAP-IX calls the supplied callback routine to indicate when the verb processing completes. The application can then examine the VCB parameters.

Using the Asynchronous Entry Point

When using the asynchronous entry point, note the following:

• If an application specifies a null pointer in the comp_proc parameter, the verb will complete synchronously (as though the application issued the verb using the synchronous entry point).

• If the call to ms_async is made from within an application callback, specifying a null pointer in the comp_proc parameter is not permitted. In such cases, SNAP-IX rejects the verb with primary return code value AP_PARAMETER_CHECK and secondary return code value AP_SYNC_NOT_ALLOWED .

• The application must not attempt to use or modify any parameters in the VCB until the callback routine has been called.

• Multiple verbs do not necessarily complete in the order in which they were issued. In particular, if an application issues an asynchronous verb followed by a synchronous verb, the completion of the synchronous verb does not guarantee that the asynchronous verb has already completed.

Callback Function

 typedef void (*VMV_CALLBACK) (
                               AP_UINT32   target_handle,
                               void *      msvcb,
                               AP_CORR     corr
                              );

  typedef union ap_corr  {
                          void *          corr_p;
                          AP_UINT32       corr_l;
                          AP_INT32        corr_i;
                         } AP_CORR;

Supplied Parameters

SNAP-IX calls the callback routine with the following parameters:

target_handle

For MS data and status indications, SNAP-IX passes the target handle that was supplied with the REGISTER_MS_APPLICATION or REGISTER_NMVT_APPLICATION verb. For completion of verbs, this parameter is undefined.

msvcb

One of the following:

• For MS data and status indications, a pointer to a VCB supplied by SNAP-IX.

• For completion of verbs, a pointer to the VCB supplied by the application. The VCB now includes the returned parameters set by SNAP-IX.

corr

The correlator value supplied by the application. This value enables the application to correlate the returned information with its other processing.

The callback routine need not use all of these parameters (except as described in Using the Callback Routine for Indications). The callback routine can perform all the necessary processing on the returned parameters, or it can simply set a variable to inform the MS application that the verb has completed.

Returned Values

The callback function does not return any values.

Using the Callback Routine for Indications

The callback routine supplied with the REGISTER_MS_APPLICATION VCB can receive the following indications:

• FP_NOTIFICATION (if the application requested this information when registering)

• MDS_MU_RECEIVED

• MS_STATUS

The callback routine supplied with the REGISTER_NMVT_APPLICATION VCB can receive the following indications:

• NMVT_RECEIVED (if the application did not request conversion from NMVT-level data to MDS-level data)

• MDS_MU_RECEIVED (if the application requested conversion from NMVT-level data to MDS-level data)

• MS_STATUS

Although the application allocates the VCBs for MS verbs, SNAP-IX allocates the VCBs for indications. Therefore, the application has access to the VCB information only from within the callback routine; the VCB pointer that SNAP-IX supplies to the callback routine is not valid outside the callback routine. The application must either complete all the required processing from within the callback routine, or it must make a copy of any VCB data that it needs to use outside this routine.

In the event that the MS application needs to make a copy of the data supplied on the callback routine and the MS application is using the signal-based scheduling mode, an operating system limitation may prohibit memory allocation. In this case, some memory must be preallocated before the REGISTER_MS_APPLICATION or REGISTER_NMVT_APPLICATION verb is issued.

Processing of indications in the callback routine must fulfill the following additional requirements:

• If an NMVT-level application uses REGISTER_NMVT_APPLICATION to receive incoming NMVTs, it must be capable of receiving a data length of 512 bytes (the maximum NMVT size).

• If an MDS-level application uses REGISTER_NMVT_APPLICATION to receive incoming NMVTs after conversion to MDS_MUs, it must be capable of receiving a data length of 700 bytes, which allows for the maximum NMVT size together with the MDS_MU header information. (This requirement does not apply to an application using REGISTER_MS_APPLICATION to receive MDS_MUs, because the application can specify the maximum data length it can accept, and SNAP-IX segments the data if necessary.)

• If an MDS-level application uses REGISTER_MS_APPLICATION to receive incoming MDS_MUs, it must be capable of receiving data of length up to the value specified for the max_rcv_size parameter on the REGISTER_MS_APPLICATION verb.