Refer to the Application Building Guide for general information about building DB2 applications. Specifically, refer to the information that applies to building applications for Windows 32-bit operating systems. In addition, you should familiarize yourself with the information that applies to using the DB2 C/C++ APIs. The APIs that are used for synchronizing are provided in C only.
Each DB2 SDK includes sample programs that call DB2 APIs. The sample programs for Windows 32-bit operating systems are in the %DB2PATH%\samples\cli directory. You can build these sample programs for the Microsoft Visual C++ and IBM VisualAge C++ for Windows compilers using the DB2 API build files that are supplied with the DB2 SDK. You can also use the makefiles that are supplied. Both the makefiles and the build files show you the compiler options that you can use. These options are defined for each platform's supported compilers. You may need to modify the options for your environment. Refer to the Application Building Guide for information.
After you build the sample programs, you can use them as templates for creating your own applications.
The following sections describe the satellite APIs that you can use to set up and test the satellite environment, and to synchronize a satellite. For the full list of available APIs, refer to the Administrative API Reference.
Before a satellite can synchronize with its DB2 control server, two attributes of the satellite's environment must be configured: the unique satellite ID, and the application version. You do not use an API to set the satellite ID. Instead, you use the db2set command to set the value of the DB2SATELLITEID registry variable, or you use the logon ID of the satellite user as the satellite ID. See Setting the DB2SATELLITEID Registry Variable for information on setting the satellite ID.
You can use the db2SetSyncSession API to set the value of the application version on the satellite:
SQL_API_RC SQL_API_FN /* Set sync session for a satellite */
db2SetSyncSession (
db2Uint32 versionNumber, /* Database version number */
void * pParmStruct, /* Input parameters */
struct sqlca * pSqlca); /* SQLCA */
| Note: | The application version is case sensitive. |
The maximum length of an application version is:
#define SQL_SYNCSESSIONID_SZ 18
When you set the application version for a satellite, use the following structure for the pParmStruct to define the string:
typedef struct db2SetSyncSessionStruct
{
char *piSyncSessionID; /* ID for sync session */
} db2SetSyncSessionStruct;
If you supply an empty string for piSyncSessionID, you will reset the satellite's application version to NULL.
When setting the application version, the most common return codes are:
You can use the db2GetSyncSession API to query the value of the application version on the satellite:
SQL_API_RC SQL_API_FN /* Get sync session ID for a */
/* satellite */
db2GetSyncSession (
db2Uint32 versionNumber, /* Database version number */
void * pParmStruct, /* Output parameters */
struct sqlca * pSqlca); /* SQLCA */
When you retrieve the current application version for a satellite, supply the following structure for the pParmStruct to retrieve the value:
typedef struct db2GetSyncSessionStruct
{
char *poSyncSessionID; /* ID for sync session */
} db2GetSyncSessionStruct;
You must supply a buffer at least as large as SQL_SYNCSESSIONID_SZ (+1 for the NULL terminator) to receive the application version.
When retrieving the application version, the most common return codes are:
You can test the ability of a satellite to synchronize with its DB2 control server by executing the db2SyncSatelliteTest API on the satellite:
SQL_API_RC SQL_API_FN /* Test Satellite's ability to */
/* synchronize */
db2SyncSatelliteTest (
db2Uint32 versionNumber, /* Database version number */
void * pParmStruct, /* Input/Output parameters */
struct sqlca * pSqlca); /* SQLCA */
Because the satellite ID and application version are retrieved from the satellite environment, no parameter structure (pParmStruct) is required.
This API validates the following required configuration elements, which are necessary for synchronization to occur:
When testing the satellite environment, the most common return codes are:
Figure 6 shows the events that can occur when a satellite is synchronized, including the APIs that can be called from the synchronizing application. Specifically:
Figure 6. Synchronization Time Line
|
The sections that follow described the APIs that you can use to cause these events. For additional information about these APIs, and other satellite-related APIs that are not described in this book, refer to the Administrative API Reference.
To initiate the synchronization session, use the db2SyncSatellite API:
SQL_API_RC SQL_API_FN /* Synchronize Satellite */
db2SyncSatellite (
db2Uint32 versionNumber, /* Database version number */
void * pParmStruct, /* Input/Output parameters */
struct sqlca * pSqlca); /* SQLCA */
You must invoke the db2SyncSatellite API from the context of the satellite's instance (the same as a synchronization test). This API does not return until the synchronization session ends, successfully or otherwise.
Only one synchronization session can be active on the satellite at a time. If this API is invoked and a synchronization session is currently active on the satellite, the following SQLCODE is issued:
SQL3950N A synchronization session is active. At most one synchronization session can be active.
When this API ends successfully, the following SQLCODE is issued:
SQL3910I Synchronization session completed successfully.
Use the db2QuerySatelliteProgress API to return information about the progress of an active synchronization session:
SQL_API_RC SQL_API_FN /* Query Satellite Progress */
db2QuerySatelliteProgress (
db2Uint32 versionNumber, /* Database version number */
void * pParmStruct, /* Output parameters */
struct sqlca * pSqlca); /* SQLCA */
If the db2QuerySatelliteProgress API successfully returns the progress information, the following SQLCODE is issued:
SQL3918I Synchronization progress information was obtained successfully.
If a synchronization session is not active when the API is invoked, the following SQLCODE is issued:
SQL3936W No progress information is available.
You must supply the following output parameters for the pParmStruct parameter structure:
typedef struct db2QuerySatelliteProgressStruct
{
db2int32 oStep; /* current step of synchronization */
db2int32 oSubstep; /* substep of the current step */
db2int32 oNumSubsteps; /* total number of substeps */
db2int32 oScriptStep; /* step of current script substep */
db2int32 oNumScriptSteps; /* total number of script steps */
char *poDescription; /* description of step */
char *poError; /* error text, if available */
char *poProgressLog; /* contents of progress log */
} db2QuerySatelliteProgressStruct;
Where:
You can use the db2SyncSatelliteStop API to interrupt an active synchronization session:
SQL_API_RC SQL_API_FN /* Stop Satellite's Synchronization */
/* Session */
db2SyncSatelliteStop (
db2Uint32 versionNumber, /* Database version number */
void * pParmStruct, /* Input/Output parameters */
struct sqlca * pSqlca); /* SQLCA */
The db2SyncSatelliteStop API issues an asynchronous STOP request to the synchronization session. That is, the API returns immediately after it issues the STOP request, and not after the synchronization session stops. If a synchronization session is active and the STOP request is issued successfully, the following SQLCODE is issued:
SQL3912I STOP completed successfully.
If no synchronization session is active when the API is invoked, the following SQLCODE is issued:
SQL3913I STOP issued, but no synchronization session is currently active.
The db2SyncSatellite API only returns as a result of the interrupt when it has reached an appropriately safe point in the session. That is, a STOP request is not necessarily executed as soon as it is received. Instead, the db2SyncSatellite API finishes executing the current step in the synchronization process before exiting. For example, if the db2SyncSatelliteStop API is issued while the db2SyncSatellite API is executing a script, the db2SyncSatellite API completes executing the script before stopping. As another example, if the db2SyncSatellite API is interrupted before the satellite can upload the results of the synchronization session to the DB2 control server, the API issues the following SQLCODE:
SQL3917I A STOP request was received before the results were uploaded to the satellite control server. The results will be uploaded during the next synchronization session.
The next time db2SyncSatellite is invoked, the synchronization session resumes where it stopped.
Because the db2SyncSatellite API does not return until the synchronization session completes, and the db2SyncSatelliteStop is asynchronous, you must execute these two APIs on different threads or processes.
[ Top of Page ]