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.

Note: The environment variable NDMAPICFG must be set to the pathname of the client configuration file. Refer to Starting the CLIfor instructions on setting the environment variable.

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();
};