Novell Documentation: Storage Architecture Components (incl. Media Manager & NWPA)

CDM_Callback

The CDM's entry point for being notified of the completion of a non-blocking HACB request.

Thread Context:Non-Blocking

Syntax

    LONG CDM_Callback (
       struct SuperHACBStruct *superHACB,
       LONG                    npaCompletionCode
       );

Parameters

superHACB: (IN) NWPA passes the value of this parameter, which is a pointer to the SuperHACBStruct encapsulating theHACBStruct that contains the data of the request just completed.

npaCompletionCode

(IN) NWPA generates and passes the value of this parameter, which is a completion code for an internal NWPA process.

If the value of this parameter is zero, it means that the value in the HACB's hacbCompletion field is valid; therefore, normal callback processing should be performed.

If the value of this parameter is nonzero, it means that an internal messaging error has occurred. In this case, CDM_Callback should simply complete the request by calling CDI_Complete_Message passing it the value of npaCompletionCode as the API's npaCompletionCode input parameter. For a list of these codes, refer to Completion Codes.

Return Values

The following table lists return values and descriptions.

zero	Successful
nonzero	Unsuccessful

Remarks

CDM_Callback is the CDM's entry point for being notified of HACB completion. Within the context of CDM_Callback, the CDM can check a HACB's completion status (provided npaCompletionCode = 0) and determine a course of action. Depending on a HACB's completion status, contained in the HACB's hacbCompletion field, the CDM can do one of the following:

Option	Description
Option 1:	If the HACB completion status is successful (hacbCompletion=0x0000), complete the HACB by calling CDI_Complete_Message with a value of zero in the nwpaCompletionCode input parameter.
Option 2:	If the HACB completion status indicates an error (hacbCompletion=0x0001 to 0x0008), translate the error into an appropriate NWPA error code, and complete the HACB by calling CDI_Complete_Message with the NWPA error code as the value in the nwpaCompletionCode input parameter.
Option 3:	If the HACB completion status indicates an error, spawn a blocking, error handling thread to try and remedy the error. In this situation, the CDM must provide some error handling functions. If the error handling function can remedy the error, within its context it should complete the HACB as described in option 1. If the error could not be remedied, the error handling function should complete the HACB as described in option 2.

Option

Description

Option 1:

If the HACB completion status is successful (hacbCompletion=0x0000), complete the HACB by calling CDI_Complete_Message with a value of zero in the nwpaCompletionCode input parameter.

Option 2:

If the HACB completion status indicates an error (hacbCompletion=0x0001 to 0x0008), translate the error into an appropriate NWPA error code, and complete the HACB by calling CDI_Complete_Message with the NWPA error code as the value in the nwpaCompletionCode input parameter.

Option 3:

If the HACB completion status indicates an error, spawn a blocking, error handling thread to try and remedy the error. In this situation, the CDM must provide some error handling functions.

If the error handling function can remedy the error, within its context it should complete the HACB as described in option 1.

If the error could not be remedied, the error handling function should complete the HACB as described in option 2.

CDM_Callback becomes visible to NWPA when the CDM executes a HACB request by calling CDI_Execute_HACB. Along with a pointer to the HACB to be executed, the CDM supplies the address of the CDM_Callback as an input parameter to CDI_Execute_HACB. The CDM must supply these parameters for each HACB request it executes. NWPA associates the specified HACB request with the specified callback function, and makes the callback after the HACB request completes. Since a callback function is specified for each call to CDI_Execute_HACB, the CDM can provide either one all-inclusive callback function or a set of callback functions where each provides specific functionality specially designed for a certain type of HACB request. In this manual, however, the term CDM_Callback is used generically to refer to either case.

IMPORTANT:CDM_Callback should not hold the current thread for any lengthy amount of time, and it must not make any calls to blocking processes. If blocking threads such as error handling threads are necessary, then CDM_Callback should spawn them using NPA_Spawn_Thread, and then relinquish control by returning to the calling process.