solidDB Help : solidDB reference : solidDB Server Control (SSC) API : SSC API reference : SSCSetNotifier
  
SSCSetNotifier
The SSCSetNotifier function sets the callback functions that a linked library access server calls when it is started or stopped. The function does not have a corresponding ADMIN COMMAND.
You can use the SSCSetNotifier function to verify that the solidDB server calls a specified user-defined function whenever a special event occurs. The function detects the following events:
▪ Server shutdown
▪ Bonsai merge from the index to the storage tree
▪ Bonsai merge interval maximum
▪ Backup or checkpoint request
▪ Idle server state
▪ Netcopy request received from the primary server
▪ Completion of a netcopy request, which occurs when the server is started with the new database received through netcopy
SscRetT SSC_CALL SSCSetNotifier(SscServerT h, SscNotFunT what,
    notify_fun handler, void* userdata
)
Parameters
The following table describes the parameters:
 
Parameters
Usage type
Description
h
in
Handle to the server
what
in
Specifies the event for notification.
The options are:
▪ SSC_NOTIFY_EMERGENCY_EXIT
This function is called if a server shuts down abnormally after it has been activated with SSCStartServer(). The notifier call SSCSetNotifier() must be run before SSCStartServer()
 
 
▪ SSC_NOTIFY_SHUTDOWN
Function is called at shutdown.
 
 
▪ SSC_NOTIFY_SHUTDOWN_REQUEST
Function is called when the server receives the shutdown request and might shut down if the user-defined function accepts the request. You can refuse the shutdown by returning SSC_ABORT from the notified function, or proceed with the request by returning SSC_SUCCESS.
 
 
▪ SSC_NOTIFY_ROWSTOMERGE
Function is called when there is data in the Bonsai index tree that needs to be merged to the storage server.
 
 
▪ SSC_NOTIFY_MERGE_REQUEST
Function is called when the General.MergeInterval parameter setting in the solid.ini configuration file is exceeded and the merge has to start.
 
 
▪ SSC_NOTIFY_BACKUP_REQUEST
Function is called when a backup is requested. You can refuse the backup by returning SSC_ABORT from the notified function.
 
 
▪ SSC_NOTIFY_CHECKPOINT_REQUEST
Function is called when a checkpoint is requested. You can refuse the checkpoint by returning SSC_ABORT from the notified function.
 
 
▪ SSC_NOTIFY_IDLE
Function is called when the server switches to the idle state.
 
 
▪ SSC_NOTIFY_NETCOPY_REQUEST
This callback function applies to the HotStandby component only. The function is called when a netcopy request is received from the primary server.
 
 
▪ SSC_NOTIFY_NETCOPY_FINISHED
This callback function applies to the HotStandby component only. The function is called when a netcopy request is finished. When finished, the server is started with the new database received through the network copy (netcopy). SSC_NOTIFY_NETCOPY_FINISHED is called to inform the application that the server is again available.
notify_fun_handler
in, hold
User function to call.
userdata
in, hold
User data to be passed to the notify function.
Note Check the warning on releasing parameters of usage type hold in section Parameters.
Return value
▪ SSC_SUCCESS - Request from the server accepted.
HotStandby only:
If SSC_NOTIFY_NETCOPY_FINISHED returns SSC_SUCCESS, all other application connections are terminated and the server is set to netcopy listening mode. The server accepts the connection from the primary server and the only possible operation for the secondary server is to receive the data from the HotStandby netcopy command.
▪ SSC_ABORT - Request from the server denied.
HotStandby only:
If the SSC_NOTIFY_NETCOPY_REQUEST returns SSC_ABORT, the netcopy is not started and the error SRV_ERR_OPERATIONREFUSED is returned to the primary server.
▪ SSC_INNETCOPYMODE - The server is in netcopy mode (HotStandby only).
SSC_SERVER_NOTRUNNING - The server is not running.
Comments
This function has no corresponding solidDB SQL extension ADMIN COMMAND.
The user-defined notifier functions cannot call any SA, SSC, or ODBC functions.
When creating a user-defined notifier function, you must conform to the following prototype:
int SSC_CALL mynotifyfun(SscServerT h, SscNotFunT what ,void* userdata);
After you have used SSC_CALL to explicitly define the convention for your user function, use the SSCSetNotifier function to register the function so that it is called during the specified event. For example:
SscRetT SSCSetNotifier(h, SSC_NOTIFY_IDLE, mynotifyfun, NULL);
Example: Calling a function upon shutdown
Assume that a user creates the function user_own_shutdownrequest, which is called every time a shutdown is requested:
int SSC_CALL user_own_shutdownrequest(SscServerT h, SscNotFunT what, void
*userdata);
{
  if (shutdown not needed) {
    return SSC_ABORT;
  }
  return SSC_SUCCESS; /*Proceed with shutdown*/
}
The SSCSetNotifier function can then be called as follows to specify that user_own_shutdownrequest gets called before the server is shut down.
SSCSetNotifier(handle, SSC_NOTIFY_SHUTDOWN, user_own_shutdownrequest, NULL);
Note If function user_own_shutdownrequest returns SSC_ABORT, the shutdown is not allowed. If the function returns SSC_SUCCESS, the shutdown can proceed.
Go up to
SSC API reference