Writing Custom C Programs

If you write a custom program using the C API calls, you must include the header file ndmapi.h and link it with ndmapi.a. A sample program called apicheck.c is provided.

For Java programming, you can call the C API functions by using the JNI and the libndmapi shared objects: libndmapi.sl for HP and libndmapi.so for the other supported platforms. Although the JNI is supported, the IBM® Connect:Direct® Java Application Interface is recommended for Java programs that invoke the services of IBM Connect:Direct.

Note: The environment variable NDMAPICFG must be set to the pathname of the client configuration file. Refer to Controlling and Monitoring Processes for instructions on setting the environment variable.

Use the following IBM Connect:Direct API functions for C and C++ programs:

C++ Function C Function Description
ndmapi_connect() ndmapi_connect_c() Establishes a connection with the server. Specify the node to connect to in the ndm_nodespec pointer or in the CLI/API Configuration Information file. If the call is successful, NDM_NO_ERROR is returned. Control returns to the application when the connection is established and is ready for the first API request.
ndmapi_sendcmd() ndmapi_sendcmd_c() Sends commands to IBM Connect:Direct. You must provide the command text. The resp_moreflag is a pointer to the flag indicating that more responses are pending for the executed command. Invoke ndmapi_recvresp_c() for C programs or ndmapi_recvresp() for C++ programs to retrieve the extra responses. Only the select process and select statistics commands require the use of ndmapi_recvresp_c() for use with C and ndmapi_recvresp() for use with C++.
ndmapi_recvresp() ndmapi_recvresp_c() Receives responses to commands sent to IBM Connect:Direct. The contents of the response buffer are returned.
ndmapi_disconnect() ndmapi_disconnect_c() Terminates the API connection.

Three types of IBM Connect:Direct command responses are returned by these functions.

  • Informational responses return information about the submitted command.
  • Data responses, stored in the resp_buffer, contain data records.
  • Error responses return ERROR_H, a pointer to a linked list of all errors found. The ID field values are fixed for use when debugging. The msgid, feedback, and rc fields are specified by IBM Connect:Direct and are referred to in message text. The subst field points to a string that contains substitution variable information to be inserted appropriately in the message text. The error control structure keeps track of the current and total number of errors. You can move through the errors by using the next pointer in error entry blocks.

The following code defines the ERROR_H structure:

#define NDM_ERR_ENT_T struct NDM_ERR_ENT_S
#define NDM_ERR_CTL_T struct NDM_ERR_CTL_S
#define ERROR_H       NDM_ERR_CTL_T *
struct NDM_ERR_ENT_S
		int32				id;
		char				msgid[MSGIDLEN];
		int32				feedback;
		int32				rc;
		char				*subst;
		NDM_ERR_ENT_H				 next; 
struct NDM_ERR_CTL_S
		int32				id;
		int32				cur_entry;
		int32				num_entries;
		NDM_ERR_ENT_H				 next;