Home
Runtimes
Descriptions of Link runtime services.
SDK
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
Connection interface
The connection interface methods are called to connect to a resource and to control connection pooling.
CompareConnection
The CompareConnection method is called by the Resource Manager to determine whether a connection can be reused.

Runtimes
Descriptions of Link runtime services.
- REST API
  The REST Runtme provides a REST API used to run maps and flows that have been deployed.
- Flow Command Server
  Deploy a flow from the HCL Link to the local filesystem using Execution flow server definition.
- Map Command Server
  To use the Map Command Server to execute a map, you will prepare the maps for execution.
- SDK
  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.
        Connect
        The Connect method is called to connect to the resource specified by the adapter object. Context information returned from the connection, such as handles, cursors or other contextual information, is returned by setting properties of the connection object.
        Disconnect
        The Disconnect method disconnects from the resource referenced by the connection object. The connection context is obtained by getting the properties of the connection object that were set in the Connect call.
        CompareConnection
        The CompareConnection method is called by the Resource Manager to determine whether a connection can be reused.
        ValidateConnection
        The ValidateConnection method is called by the Resource Manager on an idle connection to determine whether a connection is still valid. It is invoked when the period specified in the configuration file expires. The method should ping the connection to determine whether it is still valid, using whatever mechanism the resource supports to do this.
        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 HCL Link 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.

CompareConnection interface method

The CompareConnection method is called by the Resource Manager to determine whether a connection can be reused.

It is called in two cases:

To determine whether multiple adapter references within the same map can share a connection.
To determine whether a connection that is currently inactive can be used by a map.

This method can be logically equivalent to CompareWatches.

MPIRC CompareConnection (HMPIADAPT  hAdapter, HMPICONNECT  hConnection,
												MPICOMP *peComp)

Inputs

hAdapter: Adapter handle for the potentially new connection.
hConnection: Connection handle for the existing connection.

Outputs

peComp

MPI_CMP_EQUAL: Connection corresponds.
MPI_CMP_DIFFER: Connection does not correspond.
MPI_CMP_LESS: Connection is less than adapter.
MPI_CMP_GREATER: Connection is greater than adapter.

Returns

Success status

The adapter consults the properties for the adapter object and the connection object and determines whether the properties correspond such that the connection might be reused for the adapter object. The MPIP_CONNECTION_INUSE property determines whether the connection object is currently being used in a map. If this property is FALSE, the connection is currently idle.

Besides adapter-specific properties, other properties might be important in determining whether a connection can be reused. For example, MPIP_ADAPTER_ON_FAILURE determines whether to rollback or commit at the end of the transaction. If this is set to MPI_ACTION_COMMIT for one adapter object, but MPI_ACTION_ROLLBACK for another, it is most unlikely that the connection should be shared if the connection is active.

If the sense of ordering in comparisons can be made, the number of comparisons can be reduced because every existing connection does not have to be compared when searching for a valid connection to use.

In the following code example, a resource is identified by QueueManager.

mpiPropertyGetText(hAdapter, MYPROP_Q_MGR, 0, &pAdaptQMgr, &iLen);
mpiPropertyGetText(hConnection, MYPROP_Q_MGR, 0, &pConnQMgr, &iLen);
rc = strcmp(pAdaptQMgr, pConnQMgr);
if (rc == 0)
return MPI_CMP_EQUAL;
else if (rc < 0)
return MPI_CMP_LESS;
else 
return MPI_CMP_GREATER;