COM Library

This chapter describes how to use each API defined in the COM library. The COM library’s prototypes are defined in the comhead.h header file.

1. Overview

The COM library is a library provided by Tmax that enables a remote node to communicate with Tmax SVCGW through TCP/IP. The remote node must use the COM library to communicate with SVCGW. Users on the remote node can request services to Tmax or receive service requests from Tmax through TCP/IP by using the COM library. The communications between the users on the remote node and Tmax are handled by the COM library which enables easy access to Tmax services.

When communicating from the remote node to Tmax through TCP/IP, Tmax is always in the server mode and the remote node is in the client mode.

The following table describes the API provided by the COM library.

API Description

ComOpen

Makes a connection to SVCGW through TCP/IP communication and registers the remote node to SVCGW.

ComDetach

Unregisters from Tmax SVCGW.

ComClose

Unregisters and disconnects from Tmax SVCGW.

ComSend

Sends data from the remote node to Tmax SVCGW.

ComRecv

Receives data from Tmax SVCGW.

2. ComOpen

This function is used to make a connection to Tmax SVCGW through TCP/IP and registers the remote node to SVCGW. This function can be used to register a service name that is not configured in the Service Name item of the SVCGW environment file. If the service name is not registered, a service can be requested from the remote node to Tmax, but it cannot be requested from Tmax to the remote node. This function must be called first to connect to Tmax SVCGW before any other functions.

  • Prototype

    int ComOpen(int type, char *id, char *port)

  • Parameter

    Parameter Description

    type

    Protocol (TCPIP/SERIAL) used to communicate with Tmax.

    Each protocol is declared in the comhead.h file.

    id

    ID of the remote node. This ID is related to the previous SVCGW environment file. A remote node can be identified by defining the service name or this ID in the environment file. The ID must be a service name configured in the SERVICE section of the Tmax environment file.

    port

    Server address and port number used when connecting to Tmax’s SVCGW. Specify both the SVCGW server address and the port set using the [-P] option in the SVCGW CLOPT.

    (e.g., "1.1.1.1:8090")

  • Return Value

    Return Value Description

    0

    When a function call is successful.

    -1

    When a function call has failed.

3. ComDetach

This function is used to unregister from Tmax SVCGW. The function only unregisters and doesn’t actually disconnect from SVCGW. After executing this function, data can no longer be transmitted to Tmax SVCGW.

  • Prototype

    int ComDetach(void)

  • Return Value

    Return Value Description

    0

    When a function call is successful.

    -1

    When a function call has failed.

4. ComClose

This function is used to unregister and disconnect from Tmax SVCGW. This function is used to end communication with Tmax SVCGW.

  • Prototype

    int ComClose(void)

  • Return Value

    Return Value Description

    0

    When a function call is successful.

    -1

    When a function call has failed.

5. ComSend

This function is used to transmit data from a remote node to Tmax SVCGW. This function can be used to request services or send replies to Tmax. A new Tmax service name must be specified when sending a response to a Tmax service request.

  • Prototype

    int ComSend(char *svc, int msgtype, char *data, long len, long flags)

  • Parameter

    Parameter Description

    svc

    Service name to request to Tmax.

    msgtype

    Data type to send to Tmax SVCGW. For message types, refer to the commhead.h file.

    data

    Buffer pointer where the data to send to Tmax SVCGW is stored.

    len

    Length of the data to transmit.

    flags

    Specifies how SVCGW processes a service request.

    • COMMDELAY: SVCGW stores the data in RQ for deferred processing.

    • COMMNOREPLY: SVCGW only sends the service request without receiving a response.

    Currently, two options are available for flags. For more details, refer to the commhead.h file.

  • Return Value

    Return Value Description

    0

    When a function call is successful.

    -1

    When a function call has failed.

6. ComRecv

This function is used to receive data from Tmax SVCGW. The data can be a service request or response data..

  • Prototype

    int ComRecv(char *svc, int *msgtype, char *data, long *len, long flags)

  • Parameter

    Parameter Description

    svc

    Service name requested to Tmax.

    msgtype

    Data type sent from Tmax SVCGW. For message types, refer to the commhead.h file.

    data

    Buffer pointer where the data from Tmax SVCGW is stored. The buffer size must be equal to the size of the largest data among received data.

    len

    Length of the data to receive.

    flags

    Not used.

  • Return Value

    Return Value Description

    0

    When a function call is successful.

    -1

    When a function call has failed.