solidDB Help : solidDB reference : solidDB Server Control (SSC) API : SSC API reference
  
SSC API reference
The SSC API reference describes each SSC API function in alphabetic order. Each description includes the purpose, synopsis, parameters, return value, and comments.
Function synopsis
Parameters
Return values
SSC API error codes and messages
Function synopsis
The declaration synopsis for the function is:
ReturnType SSC_CALL function(modifier parameter[,...]);
The ReturnType varies, but is usually a value that indicates success or failure of the call. Return values are described in more detail later in this section.
SSC_CALL is required for portability. SSC_CALL specifies the calling convention of the function. It is defined appropriately for each platform in the sscapi.h file.
Parameters are in italics.
Parameters
In each function description, parameters are described in a table format. The table includes the general usage type of the parameter, as well as the use of the parameter variable in the specific function.
Parameter usage type
The following table shows the possible usage type for SSC API parameters. Note that if a parameter is used as a pointer, it contains a second category of usage to specify the ownership of the parameter variable after the call.
 
Usage type
Meaning
in
Indicates the parameter is input.
output
Indicates the parameter is output.
in out
Indicates the parameter is input/output
use
Applies only to a pointer parameter. It means that the parameter is used during the function call. The caller can do whatever it wants with the parameter after the function call. use is the most common type of parameter passing.
take
Applies only to a pointer parameter. It means that the parameter value is taken by the function. The caller cannot reference the parameter after the function call. The function or an object created in the function is responsible for releasing the parameter when it is no longer needed.
hold
Applies only to a pointer parameter. It means that the function holds the parameter value even after the function call. The caller can continue to reference the parameter value after the function call and is responsible for releasing the parameter.
Note Because this parameter is shared by the user and the server, you must not release it until the server is finished with it. In general, you can free the held object after you free the object that is holding it. For example:
conn = SaConnect("", "dba", "dba");
/* Connection is held until cursor is freed */
scur = SaCursorCreate(conn, "mytable");
...
SaCursorFree(scur);
/* After we free the cursor, it is safe to free */
/* the connection (or, as in this case, call a */
/* server function that frees the connection). */
SaDisconnect(conn);
Return values
Each function description indicates if the function returns a value and the type of value that is returned.
SscTaskSetT
When functions return a value of type SscTaskSetT, this definition is used as a bit mask. SScTaskSetT is defined in sscapi.h with the following possible values:
SSC_TASK_NONE
SSC_TASK_CHECKPOINT
SSC_TASK_BACKUP
SSC_TASK_MERGE
SSC_TASK_LOCALUSERS
SSC_TASK_REMOTEUSERS
SSC_TASK_SYNC_HISTCLEAN
SSC_TASK_SYNC_MESSAGE
SSC_TASK_HOTSTANDBY
SSC_TASK_HOTSTANDBY_CATCHUP
SSC_TASK_ALL (all of the above tasks)
The HotStandby "netcopy" and HotStandby "copy" operations are performed by the task "SSC_TASK_BACKUP"; there is no separate task "SSC_TASK_NETCOPY".
SSC API error codes and messages
SSC API functions can return the error codes and messages listed in the following table.
These constants are defined in the sscapi.h file.
 
Error code/message
Description
SSC_SUCCESS
Operation is successful.
SSC_ERROR
Generic error.
SSC_ABORT
Operation cancelled.
SSC_FINISHED
SSCAdvanceTasks returns this message if all tasks are executed.
SSC_CONT
SSCAdvanceTasks returns this message if there are still more tasks to execute.
SSC_CONNECTIONS_EXIST
There are open connections.
SSC_UNFINISHED_TASKS
There are unfinished tasks.
SSC_INFO_SERVER_RUNNING
The server is already running.
SSC_INVALID_HANDLE
Invalid local server handle given. This server does not match the one started through SSCStartServer.
SSC_INVALID_LICENSE
No license or invalid license file found.
SSC_NODATABASEFILE
No database file found.
SSC_SERVER_NOTRUNNING
The server is not running.
SSC_SERVER_INNETCOPYMODE
The server is in netcopy mode (applies only with HotStandby).
See
SSCGetServerHandle
SSCGetStatusNum
SSCIsRunning
SSCIsThisLocalServer
SSCRegisterThread
SSCSetNotifier
SSCSetState
SSCStartDisklessServer
SSCStartServer
SSCStartSMADisklessServer
SSCStartSMAServer
SSCStopServer
SSCUnregisterThread
Retrieving task information
Obtaining solidDB status and server information
Go up to
solidDB Server Control (SSC) API