Home
LNK APIs
The LNK programming interface includes language-specific methods and objects that provide common functionality across multiple environments.
C API
The C API enables applications to invoke maps and to develop adapters to use with HCL Link.
Custom adapters
The custom adapters interface makes it possible for users to develop adapters with as much functionality as those provided with the product.
Methods provided by adapter
C API return codes
There are three types of C API return codes: success, warning, or error.

LNK APIs
The LNK programming interface includes language-specific methods and objects that provide common functionality across multiple environments.
- Link programming interface overview
  The Link programming interface is an object-oriented approach that enables applications to invoke HCL Link maps, thus removing reliance on command lines.
- C API
  The C API enables applications to invoke maps and to develop adapters to use with HCL Link.
  - C API interface methods overview
    The map, card, and adapter object properties define the properties that can be set for each object. Use the C API interface methods to GET or SET the adapter object properties.
  - Object methods
  - Loading, running, and controlling maps
    There are various methods you can use to load, run, and control maps when you use APIs with HCL Link.
  - Custom adapters
    The custom adapters interface makes it possible for users to develop adapters with as much functionality as those provided with the product.
    - Developing custom adapters
      The custom adapters interface makes it possible for users to develop adapters with as much functionality as those provided with the product.
    - Adapter registration and the library virtual table
      The first step required to develop an adapter is to add the adapter to the adapters.xml registration file.
    - Initializing the adapter
      InitializeLibrary provides an entry point by which any global structures, critical sections, or lists that are required by the adapter can be initialized.
    - Point to adapter methods
      After your adapter is loaded, you call the virtual table (vtable) structure to obtain pointers to the methods.
    - Adapter registration file
      The adapters.xml registration file contains a single tag for each adapter, including a number of attributes to provide information about the adapter.
    - Vtable adapter library
    - Methods provided by adapter
      - Methods provided by an adapter
        Various methods must be provided by an adapter.
      - Adapter methods used post-instance creation
        After you create an instance of the adapter and connection objects, the map can use these objects to get data, put data, or to listen for events. The adapter virtual table, MPI_ADAPTER_VTABLE, points to a number of methods that are provided by the adapter.
      - Adapter instance overview
        When a map executes, there are a number of objects created (for example, map and card). Each card has an associated adapter instance. The adapter instance contains a number of properties that determine the behavior of the adapter. The number and type of these properties are defined through the mpiObjectNewPropColl method.
      - Connection instance overview
        Instances of connection objects are created in the same way as adapter instances. When a new connection is required, a connection instance is created.
      - Connection interface
        The connection interface methods are called to connect to a resource and to control connection pooling.
      - Library initialization and termination methods
        The InitializeLibrary and DestroyLibrary custom adapter methods are called to perform one-time initialization tasks and to clean up from these tasks.
      - Listener interface
        The Listener interface uses the Listen, CombinedListen, and CompareWatches methods to listen for single or multiple events from the resource.
      - Method invocation
        The method invocation examples demonstrate the sequence of calls made to an adapter.
      - Source and target interface
        Source and target interface methods are called to get data from a resource, to put data to a resource, and to control a transaction while developing custom adapters.
      - Property interface
        The ValidateProperties custom adapter method is called to validate the adapter’s properties.
      - C API return codes
        There are three types of C API return codes: success, warning, or error.
    - Additional adapter methods
      There are a number of additional methods that are part of the HIP Programming Interface library that are of particular relevance to adapter developers.
    - Passing data to and from maps
      Data is passed between adapters and the engine through stream objects. From the adapter perspective, there is no need to create these stream objects; they are already created when either the Get or Put method is called.
    - Threads, connections, and transactions overview
      It is important to understand how threads, connections, and transactions interact.
- Python API
  Use the Python API to create, edit, and run maps and schemas from a Python program. For details, see the documentation installed in install_dir/python/api/hip/docs/html/index.html. Examples of the Python API are installed in install_dir/python/api/examples. Documentation for the Python API examples is available in install_dir/python/api/docs/html/examples.html.
- Java API
  The Java API interfaces enable you to create, edit, and run maps and schemas from a Java™ program.
- Java Tools
  The Java™ Tools provide objects and JNI utilities that you can use to get information about your map instances.

C API return codes

There are three types of C API return codes: success, warning, or error.

Success: The call succeeded. The only success code is MPIRC_SUCCESS.
Warning: The call succeeded, but some condition arose that might be of concern. For example, MPIRC_W_NO_DATA.
Error: The call failed.

The following return codes, which are defined in the dtxpi.h header file along with many others, should be used by an adapter.


Return code	Description
MPIRC_SUCCESS	This operation was successful.
MPIRC_W_NO_DATA	The adapter has no data to return from a Get.
MPIRC_W_END_OF_DATA	All data has been retrieved from the input.
MPIRC_E_BAD_CONNECTION	The connection became unusable.

In addition to predefined codes, an adapter might provide its own return codes. Error and warning codes returned should be defined using the following macros:

MAKEUSERWARNING(code) - sets the code as a warning code
MAKEUSERERROR(code) - sets the code as an error code

Example

#define MY_E_CONNECT_FAILED 
MAKEUSERERROR(1)

#define MY_E_BAD_PARMS 
MAKEUSERERROR(2)

#define MY_E_NO_MEMORY 
MAKEUSERERROR(3)

#define MY_W_NO_MSG_AVAIL 
MAKEUSERWARNING(1)

#define MY_W_TIMED_OUT 
MAKEUSERWARNING(2)

Zero (0) should not be used as the parameter of MAKEUSERERROR or MAKEUSERWARNING.

These codes must then be returned as properties of the object.

Example

mpiPropertySetInteger(hAdapter,
MPIP_OBJECT_ERROR_CODE, 0, rc);

Return codes from the resource to which the adapter connects might also be returned, (for example, a SQL State or code from an R/3 API) by settingthe MPIP_ADAPTER_PROVIDER_CODE property. The return code from the adapter methods determines program flow. If an error occurs in an adapter method, an error code must be returned in the return code. The MPIP_OBJECT_ERROR_CODE property does not determine flow, but is used to maintain error information related to various objects. This information can then be displayed in the trace and audit logs.