Standard C API

Overview

Use the Standard API functions to connect to a Connect:Direct® node, execute Connect:Direct commands, manage command response data, and retrieve error information.

The C API is implemented using the C++ Classes. This interface is used by C programmers.

Handles

Handles simplify object and memory management by referencing a particular object. Pass a handle to an API to uniquely identify an object. The Connect:Direct C API uses the following types of object handles to return node, Process, statistics, message, and trace information:

  • Node Handles—Represent the Connect:Direct node that is the target of the operation. It is a virtual connection to a Connect:Direct node. The node handle is a special type of object handle; it holds information about the node but does not return data from the node.

    A node handle is created by calling the CdConnect() function and passing it the node name, user ID, password, and protocol within a NODE_STRUCT structure. After you finish with a node handle, you call the CdCloseHandle() to close it. Closing the handle releases the virtual connection and any internal resources associated with it. The node handle is no longer valid on subsequent operations.

    Note: You are responsible for closing the node handle and for releasing any resources that you allocate.
  • Process Handles—Handles returned from a submit command or from a Process object, which is created when a select process, change process, or delete process command is executed. The following example demonstrates the select process command returning a Process:
    if (CdExecuteCommand (hNode, “SELECT PROCESS”, &hProc))
    {
         if (CdGetProcRec(hProc, &Proc))
         {
         printf("%d %s/n", Proc.ProcessNumber, Proc.ProcessName);
         }
    }
  • Statistic Handles—Statistics objects that are returned after a select statistics command is executed.
  • Message Handles—Message objects that are returned when a select message command is executed.
  • Trace Handles—Trace objects that are returned when a traceon or traceoff command is executed.

Block the Calling Thread

CdWaitOnProcess()—Use this function to serialize Connect:Direct Process execution. This function blocks the calling thread until the specified Process is no longer in the TCQ. It takes a Process handle that contains references to the target Process object. Any Process object handle can enable you to specify Processes to wait on. Use this method to wait on a Process returned from a submit command and any Process returned by the select process command.

Retrieve Error Text

  • CdGetErrorText()—Call this function to translate return code values into messages that explain the error. This helps the user understand the error message and provides a method for logging meaningful trace messages within an application.
  • CdGetDetailedError()—Use this function to retrieve messages one at a time until CD_ENDOFDATA is returned. This call fills in the MESSAGE_STRUCT structure with a detailed error message for node, parser, and connection errors. The messages are erased upon entry to any other API to prepare for other potential errors.

Blocking

The C Application Programming Interface is synchronous; when an API that performs a complex function (such as the CdConnect() or CdExecuteCmd() functions) is called, the caller's thread is blocked until the request is completed or until a failure occurs. The caller's thread blocks while waiting for other threads to finish the request.

If the CdConnect() function is called from a Microsoft Windows application, it should not be called from the primary user interface (UI) thread. Calling the function from the UI thread causes the user interface of the program to run slowly.