QAPI Developer's Guide

Overview

The Application Programming Interface (QAPI) is a Software Development Kit designed to provide programmatic interface for users to perform various operations that can be run using command line utilities or the CommCell Console. QAPI exposes C style APIs which allows users develop customized client applications, using either C or C++, for UNIX and Windows operating systems.

The following sections explain how to use QAPI to develop customized applications.

Download QAPI Programmers Library

Click here to download the header file (QAPI.h).

API Interface

QAPIs are designed in such a way that any user who is well versed with command line utilities can use the QAPIs intuitively as each command line utility is mapped one to one with QAPIs. Each QAPI takes a text string input which exactly matches the command line parameters to their corresponding command line accepts.

All QAPIs take an argument to configure the way output is displayed. Depending on the output display mode set through the output parameter, the output can be:

Displayed on the console.
Returned through a user-supplied call back function

If a user supplies a call back function, the QAPIs call the function along with a data pointer and blocks the function until it returns.

Caution

The users of these APIs are considered advanced users who are familiar with the command line parameters passed to each qcommand. Error checking and validation of command line parameters will be very limited and will not exceed what the command line framework already provides.

All qcommands can be executed as QAPIs using appropriate parameters. See the examples provided below for usage information on the following APIs:

QAPI_Init

This API takes configuration parameters needed by QAPIs. User must call this API before invoking any other API.

Syntax	API_Status QAPI_Init(QAPI_InitParameters initParams);
Parameters	initParams [in] Configuration parameters
Returns	Command return code, 0 – Success and Non-zero – Failure, along with error description.

QAPI_Login

This API is functionally equivalent to the 'qlogin' command. It accepts the command line parameters passed to 'qlogin' and starts a new login session with the specified CommServe. This API must be called before running any other QAPIs.

Syntax	QAPI_Status QAPI_Login(const char * commandString, QAPI_Output * output);
Parameters	commandString [in] Commandline parameters of 'qlogin' command output [in,out] Output parameters
Returns	Command return code, 0 – Success and Non-zero – Failure, along with error description.

QAPI_Operation

This API is functionally equivalent to the 'qoperation' command. It accepts the command line parameters passed to 'qoperation', barring a subcommand type e.g., 'backup' or 'restore'. The subcommand type is passed through the first parameter 'subcommandType'.

Syntax	QAPI_Status QAPI_Operation(QAPI_OperationSubType subcommandType, const char * commandString, QAPI_Output * output);
Parameters	subcommandType [in] Operation subcommand type commandString [in] Commandline parameters of 'qoperation' command output [in,out] Output parameters
Returns	Command return code, 0 – Success and Non-zero – Failure, along with error description.

QAPI_Logout

This API is functionally equivalent to the 'qlogout' command. It accepts the command line parameters passed to 'qlogout' and terminates the login session created by the 'qlogin' command. Once this API is called, the user will have to call QAPI_Login in order to run more commands.

Syntax	QAPI_Status QAPI_Logout(const char * commandString, QAPI_Output * output);
Parameters	commandString [in] Commandline parameters of 'qlogout' command output [in,out] Output parameters
Returns	Command return code, 0 – Success and Non-zero – Failure, along with error description.

QAPI_Exit

This API must be the last API to call and user must invoke QAPI_Init again in order to invoke more QAPIs.

Syntax	QAPI_Status QAPI_Exit();
Parameters	None
Returns	Command return code, 0 – Success and Non-zero – Failure, along with error description.

Sample Client program

The following sample client program performs the following operations:

Log on to a CommServe
Fetches a list of configured clients
Displays the output on the CommCell Console

Note that this sample program is for Windows computers.

// command_line_arguments.cpp
// compile with: /EHsc
#include <windows.h>
using namespace std;
#include "QAPI.h"
int main(int argc, char ** argv)
{
    //
    // Load QAPI library
    //
    HINSTANCE hinstLib = NULL;
    hinstLib = LoadLibrary(TEXT("QAPI.dll"));
    if (hinstLib == NULL)
    {
        printf("ERROR: Unable to load QAPI library ");
        return 1;
    }
    //
    // Get function pointers for all QAPIs
    //
    QAPI_Init_Type initFunc;
    QAPI_Login_Type loginFunc;
    QAPI_Operation_Type operationFunc;
    QAPI_Logout_Type logoutFunc;
    QAPI_Exit_Type exitFunc;
    QAPI_List_Type clientlistFunc;
    initFunc = (QAPI_Init_Type)GetProcAddress(hinstLib, "QAPI_Init");
    loginFunc = (QAPI_Login_Type)GetProcAddress(hinstLib, "QAPI_Login");
    operationFunc = (QAPI_Operation_Type)GetProcAddress(hinstLib, "QAPI_Operation");
    clientlistFunc = (QAPI_List_Type)GetProcAddress(hinstLib, "QAPI_List");
    logoutFunc = (QAPI_Logout_Type)GetProcAddress(hinstLib, "QAPI_Logout");
    exitFunc = (QAPI_Exit_Type)GetProcAddress(hinstLib, "QAPI_Exit");
    if (!initFunc || !loginFunc || !operationFunc || !logoutFunc || !exitFunc)
    {
        printf("ERROR: Unable to load QAPI functions");
        FreeLibrary(hinstLib);
        return 1;
    }
    //
    // Initialize QAPI
    //
    QAPI_InitParameters initParams;
    QAPI_Status qapiStatus;
    initParams.version = QAPI_VERSION;
    qapiStatus = initFunc(initParams);
    if (qapiStatus.code)
    {
        printf("ERROR: QAPI_Init failed with error code %d and message %s", qapiStatus.code, qapiStatus.description);
        FreeLibrary(hinstLib);
        return qapiStatus.code;
    }
    //
    // Login to the CommServe
    //
    const char * loginCommand = " - cs commserver –u user –p password";
    QAPI_Output output;
    output.outputMode = QAPI_OUTPUTMODE_CONSOLE;
    output.outDataReader = NULL;
    qapiStatus = loginFunc(loginCommand, &output, NULL);
    if (qapiStatus.code)
    {
        printf("ERROR: QAPI_Login failed with error code %d and message %s",
            qapiStatus.code, qapiStatus.description);
        FreeLibrary(hinstLib);
        return qapiStatus.code;
    }
    //
    // Fetch list of Configured CommCell Clients
    //
    const char * listCommand = " - cs commserver";
    output.outputMode = QAPI_OUTPUTMODE_CONSOLE;
    output.outDataReader = NULL;
    qapiStatus = clientlistFunc(QAPI_LIST_CLIENT, listCommand, &output, NULL);
    if (qapiStatus.code)
    {
        printf("ERROR: QAPI_List failed with error code %d and message %s",
            qapiStatus.code, qapiStatus.description);
        FreeLibrary(hinstLib);
        return qapiStatus.code;
    }
    //
    // Logout from the CommServe
    //
    const char * logoutCommand = " - cs commserver";
    output.outputMode = QAPI_OUTPUTMODE_CONSOLE;
    output.outDataReader = NULL;
    qapiStatus = logoutFunc(logoutCommand, &output, NULL);
    if (qapiStatus.code)
    {
        printf("ERROR: QAPI_Logout failed with error code %d and message %s",
            qapiStatus.code, qapiStatus.description);
        FreeLibrary(hinstLib);
        return qapiStatus.code;
    }
    //
    // Terminate QAPIs
    //
    qapiStatus = exitFunc();
    if (qapiStatus.code)
    {
        printf("ERROR: QAPI_Exit failed with error code %d and message %s",
            qapiStatus.code, qapiStatus.description);
        FreeLibrary(hinstLib);
        return qapiStatus.code;
    }
    FreeLibrary(hinstLib);
    return 0;
}