Writing Custom Programs
The IBM Connect:Direct Application Programming Interface (API) allows you to write custom programs in either C or C++ to use with IBM® Connect:Direct®. With the C functions or the C++ classes, you can create programs to perform the following tasks:
- Establish a connection to the IBM Connect:Direct server
- Disconnect from the server
- Receive command responses from the server
- Send commands to the server
This topic describes the format of the IBM Connect:Direct API functions and classes and provides samples of their use. Sample programs are provided that use the IBM Connect:Direct API functions and classes to issue commands and receive responses from the IBM Connect:Direct server.
Compiling Custom Programs
After you write a custom program, you must compile it, using a C or C++ compiler. Refer to the following information to determine what minimum C++ compiler version to use for each platform:
Platform | C++ Compiler |
---|---|
AIX | IBM XL C/C++ for AIX, V11.1 |
Linux x86 | g++ (GCC) 6.3.1 |
Linux S390 | g++ (GCC) 4.4.7 |
Linux ppc64le | g++ 4.8.5 |
Use the commands defined in the following table to compile a custom C++ program using the C++ API calls:
Platform | C++ Compile Command |
---|---|
AIX | |
64-bit | /usr/vacpp/bin/xlC -q64 -qinline -I../include -+ -o sdksample sdksample.C ../lib/ndmapi64.a -lbsd -ldl -lsrc -lpthreads |
Linux x86 | |
64-bit |
g++ -I/usr/include/tirpc -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi64.a -ldl -lstdc++ -ltirpc Note: The
libtirpc-devel package is required for compiling. |
LinuxS390 | |
64-bit |
g++ -I/usr/include/tirpc -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi64.a -ldl -lstdc++ -ltirpc Note: The
libtirpc-devel package is required for compiling. |
Linux ppc64le | |
64-bit |
g++ -I/usr/include/tirpc -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi64.a -ldl -lstdc++ -ltirpc Note: The
libtirpc-devel package is required for compiling. |
To build a C++ program using the C API calls, such as the apicheck.C sample program, replace the sdksample.C parameter with the name of the C++ program and rename the output file parameter, -o sdksample, to the name of the output file you want to create such as apicheck.
Use the commands defined in the following table to compile a C program:
Platform | C Compile Command |
---|---|
AIX | |
64-bit | /usr/vacpp/bin/xlc -q64 -I../include -+ -o apicheck apicheck.c ../lib/ndmapi64.a -lbsd -ldl -lsrc -lC -lpthreads |
Linux x86 | |
64-bit |
gcc -I/usr/include/tirpc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lstdc++ -ltirpc Note: The
libtirpc-devel package is required for compiling. |
LinuxS390 | |
64-bit |
gcc -I/usr/include/tirpc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lstdc++ -ltirpc Note: The
libtirpc-devel package is required for compiling. |
Linux ppc64le | |
64-bit |
gcc -I/usr/include/tirpc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lstdc++ -ltirpc Note: The
libtirpc-devel package is required for compiling. |
Writing Custom C++ Programs
If you write a custom program using C++ API calls, you must include the class called ConnectDirectSession. The calling program must instantiate ConnectDirectSession and call the send and receive functions. A sample program called sdksample.C is provided. To write a custom C++ program, create a ConnectDirectSession class. The class contains the ConnectDirectSession interface and a constructor and destructor call to allocate and release the storage associated with the class. This class is the interface to the IBM Connect:Direct methods and provides connection, command, data retrieval, and error services. Each method returns either CD_SUCCESS or CD_FAILURE.
To use the ConnectDirectSession class, your application must include the cdunxsdk.h header file provided in the installation and must link with the ndmapi.a file. Following is a sample ConnectDirectSession class program:
#include "cdunxsdk.h"
#include <iostream.h>
#include <string.h>
void getError(ConnectDirectSession& cdSess);
main()
{
ConnectDirectSession cdSess;
char processText[16384];
if (cdSess.SessionINF->Connect() == CD_SUCCESS)
{
strcpy(processText,"submit maxdelay=unlimited sdksample process snode=SNODENAME ");
strcat(processText,"copy00 copy from (file=sample.txt pnode)");
strcat(processText," to (file=sample.000 snode disp=rpl) ;");
if (cdSess.SessionINF->SendCommand(processText) == CD_SUCCESS)
{
printf("%s completed, pnumber = %ld.\n",
cdSess.SessionINF->GetCommandName(),
cdSess.SessionINF->GetProcessNumber());
sprintf(processText, "SELECT STATISTICS PNUMBER=%ld DETAIL=YES ;", cdSess.SessionINF-
>GetProcessNumber());
(cdSess.SessionINF->SendCommand(processText) == CD_SUCCESS)
{
}
else
{
getError(cdSess);
}
}
else
{
getError(cdSess);
}
cdSess.SessionINF->DisConnect();
}
else
{
getError(cdSess);
}
}
void getError(ConnectDirectSession& cdSess)
{
if (cdSess.SessionINF->GetFirstError())
{
printf("\nError Message: %s", cdSess.SessionINF->GetMsgID());
printf("\nError Feedback: %d", cdSess.SessionINF->GetFeedBackCode());
printf("\nError RC: %d", cdSess.SessionINF->GetReturnCode());
printf("\nError SUBST: %s\n", cdSess.SessionINF->GetSubstitute()); }
while(cdSess.SessionINF->GetNextError())
{
printf("\nError Message: %s", cdSess.SessionINF->GetMsgID());
printf("\nError Feedback: %d", cdSess.SessionINF->GetFeedBackCode());
printf("\nError RC: %d", cdSess.SessionINF->GetReturnCode());
printf("\nError SUBST: %s\n", cdSess.SessionINF->GetSubstitute());
}
}
The ConnectDirectSession class methods are described in the following table:
Method | Description | Parameter | Return Values |
---|---|---|---|
Connect | Provides a connection to the IBM Connect:Direct server. Connect() with a void parameter connects to the hostname and port specified in the client configuration file. |
void or a pointer to an IP address and port. | CD_SUCCESS or CD_FAILURE |
DisConnect | Disconnects the current session. | void | CD_SUCCESS or CD_FAILURE |
SendCommand | Sends a IBM Connect:Direct command to the server for processing. | Pointer to a command text buffer. | CD_SUCCESS or CD_FAILURE |
ReceiveResponse | Receives the response from a previously issued command, such as the select statistics command. | void | CD_SUCCESS or CD_FAILURE |
GetResponse | Retrieves the response from the ReceiveResponse call. | void | Pointer to a response buffer. |
GetResponseLength | Returns the length of the previously received response buffer. | void | Length of the response buffer from the previously issued call. |
MoreData | Returns a value indicating if outstanding data from the previously issued send command call is available. If the return value is TRUE, call ReceiveResponse again to retrieve more data. | void | TRUE—If more data is outstanding. FALSE—If no data is outstanding. |
GetCommandName | Returns the command name of the previously issued send command, such as the submit command. | void | Pointer to a command name buffer. |
GetProcessNumber | Returns the Process number of a previously issued submit command. | void | Process number of a submit command. -1—If no submit command can be found. |
GetProcessCount | Returns the number of Processes affected by the last send command that issued a delete, change, or flush process. | void | Process number of a submit command that issued a delete, change or flush process. -1—If no submit command can be found. |
GetCurrentError | Moves the error data pointer to the current error in the list. | void | TRUE—If successful FALSE—If no current error exists. |
GetNextError | Moves the error data pointer to the next error in the list. | void | TRUE—If successful FALSE—If no more errors are found. |
GetPreviousError | Moves the error data pointer to the previous error in the list. | void | TRUE—If successful FALSE—If no previous error exists. |
GetFirstError | Moves the error data pointer to the first error in the list. | void | TRUE—If successful FALSE—If no error is found. |
GetLastError | Moves the error data pointer to the last error in the list. | void | TRUE—If successful, otherwise FALSE. |
GetMsgID | Retrieves the message of the current error data block. You must call one of the GetXXXXError methods before calling this method in order to retrieve the proper results. |
void | Return Value: Pointer to a message ID if data block is value. |
GetFeedBackCode | Returns the feedback code of the current error data block. | void | Feedback code. |
GetReturnCode | Returns the IBM Connect:Direct return code. | void | One of the valid IBM Connect:Direct return code: 1,4,8,16. |
GetStatus | Returns the status. | void | IBM Connect:Direct status code. |
GetSubstitute | Returns the current substitution buffer associated with the error. | void | Pointer to a substitution buffer. |
DisplayError | Displays the current error chain to an output location. | Parameters: Pointer to a file I/O structure. | Return Value: Returns the highest error found in the error chain or -1 on error. |
Following is the ConnectDirectSession class header:
#include <stdio.h>
// Error enumeration.
typedef enum CDErrorCode
{
CD_SUCCESS = 0,
CD_FAILURE = -1
} CDErrorCode;
// <<Interface>>
class CDSession
{
public:
// Communication methods...
virtual CDErrorCode Connect(void) = 0;
virtual CDErrorCode Connect(char *IpAddress, char *IpPort) = 0;
virtual CDErrorCode DisConnect(void) = 0;
virtual CDErrorCode SendCommand(char *CmdText) = 0;
virtual CDErrorCode ReceiveResponse(void) = 0;
// Methods for retrieving ReceiveResponse data...
virtual const char *GetResponse(void) = 0;
virtual int GetResponseLength(void) = 0;
virtual bool MoreData(void) = 0;
// Methods for retrieving SendCommand return data...
virtual const char *GetCommandName(void) = 0;
virtual long GetProcessNumber(void) = 0;
virtual long GetProcessCount(void) = 0;
// Methods to iterate over error collection ...
virtual bool GetCurrentError(void) = 0;
virtual bool GetNextError(void) = 0;
virtual bool GetPreviousError(void) = 0;
virtual bool GetFirstError(void) = 0;
virtual bool GetLastError(void) = 0;
// Methods to retrieve error data...
virtual const char *GetMsgID(void) = 0;
virtual int GetFeedBackCode(void) = 0;
virtual int GetReturnCode(void) = 0;
virtual int GetStatus(void) = 0;
virtual const char *GetSubstitute(void) = 0;
// Method to display error collection...
virtual int DisplayError(FILE *Output) = 0;
};
class ConnectDirectSession
{
public:
// Interface classes
CDSession *SessionINF;
ConnectDirectSession();
~ConnectDirectSession();
};