Command Line Interface - QAPI Developers Guide

Topics | QCommands | Save As Script | XML Scripts | QScripts | QAPI Developers Guide  | How To | Troubleshoot | Support | Related Topics

Overview

Download QAPI Programmers Library

API Interface

Sample Client Program

Overview

QAPI is an SDK (Software Development Kit) designed to provide programmatic interface for users to perform various operations that can be run using command line utilities or CommCell Console. This SDK exposes C style APIs using which users can develop customized client applications, using either C or C++, which can run on UNIX and Windows.

The following documentation explains how to use the QAPI to develop customized applications.

Download QAPI Programmers Library

The header file (QAPI.h) is available for download.
  • Click Download Now to download this file.

 

Download Size: 128KB

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. Moreover each QAPI takes input in the form of a text string which exactly matches the command line parameters its corresponding command line accepts.

All QAPIs accept an argument to configure the way output is displayed. Currently two modes of display are supported – either output is redirected to console or a user supplied call back routine is called. If a user supplies call back routine, then QAPIs call that function along with data pointer and blocks until that function returns.

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 the Qcommands can be executed as QAPIs using appropriate parameters. Given below are few examples for usage:

QAPI_Init

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

Syntax QAPI_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 'qlogin' command. It accepts the command line parameters passed to 'qlogin' command and starts a new login session to the specified CommServe. This API must be called before running any other QAPIs. Output of the API is either returned through callback function set through output parameter or displayed on the console, depending on output mode set through output parameter.

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 'qoperation' command. It accepts the command line parameters passed to 'qoperation' command, barring subcommand type, say 'backup', 'restore', etc. Subcommand type is passed through first parameter 'subcommandType'. Output of the API is either returned through callback function set through output parameter or displayed on the console, depending on output mode set through output parameter.

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 'qlogout' command. It accepts the command line parameters passed to 'qlogout' command and terminates the login session created by 'qlogin' command. Once this API is called, user will have to call QAPI_Login API in order to run more commands. Output of the API is either returned through callback function set through output parameter or displayed on the console, depending on output mode set through output parameter.

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();
Returns Command return code, 0 – Success and Non-zero – Failure, along with error description.

Sample Client program

Sample client program which does a login to a CommServe and fetches list of clients configured and displays the output on CommCell Console. Note that this sample program is written to work on just Windows.

#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;
initFunc = (QAPI_Init_Type)GetProcAddress(hinstLib, "QAPI_Init");
loginFunc = (QAPI_Login_Type)GetProcAddress(hinstLib, "QAPI_Login");
operationFunc = (QAPI_Operation_Type)GetProcAddress(hinstLib, "QAPI_Operation");
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_Status qapiStatus;
initParams.version = QAPI_VERSION;
qapiStatus = QAPI_Init(initParams);
if(qapiStatus)
{
printf(“ERROR: QAPI_Init failed with error code %d and message %s”,
qapiStatus.code, qapiStatus.description);
FreeLibrary(hinstLib);
return qapiStatus.code;
}

//
// Perform Commserver login
//
const char * loginCommand = “-cs commserver –u user –p password”;
QAPI_Output output;
output.outputMode = QAPI_OUTPUTMODE_CONSOLE;
output.outDataReader = NULL;
qapiStatus = QAPI_Login(loginCommand,
output);
if(qapiStatus)
{
printf(“ERROR: QAPI_Login failed with error code %d and message %s”,
qapiStatus.code, qapiStatus.description);
FreeLibrary(hinstLib);
return qapiStatus.code;
}

//
// Fetch list of Commclients configured
//
const char * listCommand = “-cs commserver”;
output.outputMode = QAPI_OUTPUTMODE_CONSOLE;
output.outDataReader = NULL;
qapiStatus = QAPI_List(QAPI_QLIST_CLIENT,
listCommand,
output);
if(qapiStatus)
{
printf(“ERROR: QAPI_List failed with error code %d and message %s”,
qapiStatus.code, qapiStatus.description);
FreeLibrary(hinstLib);
return qapiStatus.code;
}

//
// Logout from Commserver
//
const char * logoutCommand = “-cs commserver”;
output.outputMode = QAPI_OUTPUTMODE_CONSOLE;
output.outDataReader = NULL;
qapiStatus = QAPI_Logout(logoutCommand,
output);
if(qapiStatus)
{
printf(“ERROR: QAPI_Logout failed with error code %d and message %s”,
qapiStatus.code, qapiStatus.description);
FreeLibrary(hinstLib);
return qapiStatus.code;
}

//
// Terminate QAPIs
//
qapiStatus = QAPI_Exit();
if(qapiStatus)
{
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;
}

Back to Top