5. CheckServer API

Overview of the CheckServer API

The CheckServer API of Altibase is an application programming interface for creating applications that use function calls to monitor whether the Altibase server has terminated abnormally. The CheckServer API provides the same functionality as the CheckServer utility. For more information about the CheckServer utility, please refer to the Utilities Manual.

The following table summarizes the CheckServer API functions.

Function Name	Description
altibase_check_server_init	This function allocates a CheckServer handle
altibase_check_server_final	This function frees a handle and all associated resources
altibase_check_server	This function monitors whether an Altibase server has terminated abnormally.
altibase_check_server_cancel	This function is used to terminate the execution of CheckServer

Restrictions

• The CheckServer API does not support multi-threaded programs.
• An application that uses the CheckServer API can only be used to monitor an Altibase database server on the local host, i.e. on the same machine as the application.
• Running two or more applications that use the CheckServer API at the same time will cause application errors.

Using the CheckServer API

Head File

This is a header file that should be included in the application.

$ALTIBASE_HOME/include/chksvr.h

The CheckServer Libraries

The library files that are required in order for applications to use the CheckServer API reside in the $ALTIBASE_HOME/lib directory. Ensure that applications are always linked with the following libraries:

• UNIX libchksvr.a, libaltiutil.a

Samples

Sample applications that use the CheckServer API can be found in the $ALTIBASE_HOME/sample/CHECKSERVER directory.

CheckServer API Data Structure

This section describes the C type that is made available to applications that use the CheckServer API.

The CheckServer Handle

The CheckServer handle is an opaque data structure that is defined in the CheckServer API library. It is used to store information pertaining to the behavior of applications that use the CheckServer API.

• ALTIBASE_CHECKSERVER_HANDLE
  This is the CheckServer handle. The CheckServer handle is primarily used when monitoring an Altibase server. The CheckServer handle is allocated with altibase_check_server_init() and freed with altibase_check_server_final().

CheckServer API

This section describes each of the functions in the CheckServer API.

The following information is provided for each function.

• The name and purpose of the function
• The function syntax
• A list of arguments for the function
• The function's return values
• Diagnostics for the function
• Notes related to use of the function
• A list of related functions
• An example of use of the function in code

altibase_check_server

This function checks whether the Altibase process is running.

Syntax

int altibase_check_server (
ALTIBASE_CHECK_SERVER_HANDLE handle );

Argument

Argument	In/Output	Description
handle	Input	The CheckServer handle

Return Values

ALTIBASE_CS_SERVER_STOPPED, ALTIBASE_CS_ERROR, or ALTIBASE_CS_INVALID_HANDLE

If the Altibase server terminates abnormally, this function returns ALTIBASE_CS_SERVER_STOPPED

Description

When CheckServer is started or this function is called, a file named checkserver.pid is created in the $ALTIBASE_HOME/trc directory. The presence of the checkserver.pid file prevents another instance of the CheckServer API application from being started while the current instance is running. Calling altibase_check_server_final() removes this file.

If this function is called while the Altibase server is running, the application that called this function will be nonresponsive until an error occurs, until it is detected that the Altibase server is shutting down, or until altibase_check_server_cancel() is called.

Related Function

• altibase_check_server_init
• altibase_check_server_final
• altibase_check_server_cancel

Example

int main()
{
    ALTIBASE_CHECK_SERVER_HANDLE handle = ALTIBASE_CHECK_SERVER_NULL_HANDLE;
    char *homeDir = NULL;
    int rc;

    rc = altibase_check_server_init( &handle, homeDir );

    if ( rc != ALTIBASE_CS_SUCCESS )
    {
        printf( "altibase_check_server_init() failed: %d\n", rc );
    }

    rc = altibase_check_server(handle);

    if ( rc == ALTIBASE_CS_SERVER_STOPED )
    {
        printf( "Server stopped.\n" );
    }
    else
    {
        printf( "An error has occured: %d\n", rc );
    }

    if ( handle != ALTIBASE_CHECK_SERVER_NULL_HANDLE )
    {
        altibase_check_server_final(&handle);
    }

    return 0;
}

altibase_check_server_final

This function frees a handle and all associated resources.

Syntax

int altibase_check_server_final (
ALTIBASE_CHECK_SERVER_HANDLE * handle );

Argument

Argument	In/Output	Description
handle	Input	This is the pointer to the CheckServer handle to be freed.

ReturnValues

ALTIBASE_CS_SUCCESS, ALTIBASE_CS_ERROR, or ALTIBASE_CS_INVALID_HANDLE

Description

altibase_check_server_final() frees all resources associated with the specified CheckServer handle.

In addition, this function removes the checkserver.pid file, which was created when altibase_check_server() was called. If the application using the CheckServer API is terminated abnormally using a command such as kill, the checkserver.pid file may be left in the file system. In this case, it will be necessary to manually delete the file before it will be possible to run the CheckServer utility or for the application that uses the CheckServer API to call altibase_check_server().

Related Function

altibase_check_server_init

Example

Refer to altibase_check_server.

altibase_check_server_init

This function allocates a CheckServer handle.

Syntax

int altibase_check_server_init (
ALTIBASE_CHECK_SERVER_HANDLE * handle,
char * home_dir );

Arguments

Argument	In/Output	Description
handle	Output	This is a pointer to a buffer in which the handle to the newly allocated data structure is returned.
home_dir	Input	This must be set to the $ALTIBASE_HOME directory.

Return Values

ALTIBASE_CS_SUCCESS or ALTIBASE_CS_ERROR

Description

This function allocates memory for information related to CheckServer, and passes a pointer to this memory back in *handle.

Only one Altibase server can be monitored by one application that uses the CheckServer API. The location of this server is specified using the home_dir argument. If home_dir is set to NULL, the value of the ALTIBASE_HOME environment variable is used.

Only one CheckServer handle can be used within one application. Additionally, a CheckServer handle cannot be shared by more than one thread at the same time.

Related Function

altibase_check_server

Example

Refer to altibase_check_server.

altibase_check_server_cancel

This function cancels the processing of the altibase_check_server()function associated with the specified handle.

Syntax

int altibase_check_server_cancel (
    ALTIBASE_CHECK_SERVER_HANDLE handle);

Arguments

Argument	In/Output	Description
handle	Input	This is the CheckServer handle to be canceled.

Result Value

ALTIBASE_CS_SUCCESS, ALTIBASE_CS_ERROR or ALTIBASE_CS_INVALID_HANDLE

Description

In a multithreaded application, one thread can call altibase_check_server_cancel() to cancel the altibase_check_server() function that is running on another thread. If the call to altibase_check_server_cancel() is successful, altibase_check_server() is stopped, and the value ALTIBASE_CS_ABORTED_BY_USER is returned.

It might take some time from the time that altibase_check_server_cancel() is called until the execution of altibase_check_server() is terminated.

Once altibase_check_server_cancel() has been called, if it is called again before altibase_check_server() returns a result, there is no guarantee that either call to altibase_check_server_cancel() will execute correctly.

Related Function

altibase_check_server

Example

Refer to altibase_check_server.