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 provided by Tmax to enable a remote node to communicate with Tmax SRLGW through RS232. The remote node must use the COM library to communicate with SRLGW. Users on the remote node can request services to Tmax or receive service requests from Tmax through serial communication 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.

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

API Description

ComOpen

Connects to Tmax SRLGW through serial communication and registers the remote node to SRLGW.

ComDetach

Unregisters from Tmax SRLGW.

ComClose

Unregisters and disconnects from Tmax SRLGW.

ComSend

Sends data from the remote node to Tmax SRLGW.

ComRecv

Receives data from Tmax SRLGW.

2. ComOpen

This function is used to establish a connection to Tmax SRLGW through serial communication and registers the remote node to SRLGW.

This function can be used to register a service name that is not configured in the Service Name item of the SRLGW environment file. If the service name is not registered, then 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 SRLGW 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 SRLGW 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

    Port used to connect to Tmax SRLGW. For serial communication, each of the configured environment settings described above must be specified.

    Multiple ports can be specified using a string. (Example: "COM1:9600:8:ODD:1")

  • Return Value

    Return Value Description

    0

    Indicates the function call was successful.

    -1

    Indicates the function call failed.

3. ComDetach

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

  • Prototype

    int ComDetach(void)

  • Return Value

    Return Value Description

    0

    Indicates the function call was successful.

    -1

    Indicates the function call failed.

4. ComClose

This function unregisters from and disconnects from Tmax SRLGW. To terminate communication with Tmax SRLGW, this function must be called. Especially in serial communication, This function must be called to disconnect from SRLGW since SRLGW cannot discern whether the user program on the remote node has been terminated.

  • Prototype

    int ComClose(void)

  • Return Value

    Return Value Description

    0

    Indicates the function call was successful.

    -1

    Indicates the function call failed.

5. ComSend

This function is used to transmit data from a remote node to Tmax SRLGW. It 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 SRLGW. For message types, refer to the commhead.h file.

    data

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

    len

    Length of the data to transmit.

    flags

    Indicates how SRLGW processes a service request.

    If set to COMMDELAY, SRLGW stores the data in RQ for deferred processing. If set to COMMNOREPLY, SRLGW only sends the service request without receiving a response.

    Currently, there are 2 available options for flags. Refer to the commhead.h file.

  • Return Value

    Return Value Description

    0

    Indicates the function call was successful.

    -1

    Indicates the function call failed.

6. ComRecv

This function is used to receive data from Tmax SRLGW. 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 SRLGW. For message types, refer to the commhead.h file.

    data

    Buffer pointer where the data from Tmax SRLGW 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

    Indicates the function call was successful.

    -1

    Indicates the function call failed.