TCPSocket

Syntax

createSubJob(ip, port, handler, [config])

Details The method creates a TCP connection to a specified IP and port, and a background task to receive TCP data. It returns a STRING scalar as the task identifier.

Note: Jobs created by createSubJob do not automatically terminate when the session closes. They must be manually ended using cancelSubJob.

Parameters

• ip: A STRING scalar indicating the IP address of the server.

• port: An INT scalar indicating the port of the server.

• handler: A unary function object used to parse data received from the TCP connection. The handler function should have the following signature:

  •   def hdndler(data){
      }

    
    The input data is a table with the following columns:
    
    - bytes: A BLOB column containing the received TCP data. The maximum length is 10240 bytes.
    - isHead: A BOOL column indicating whether the TCP data in this row is continuous with the previous row. The first row's *isHead* is set to true.

• config (optional): A dictionary with STRING keys and ANY values for configuring specific parameters. The currently supported key is:

  • maxRows: An INT scalar indicating the maximum number of rows. The default is 128 and the minimum value is 1.

Syntax

getSubJobStat()

Details

The function retrieves information on all TCP background tasks, including those canceled via cancelSubJob.

The function returns a table with the following columns:

• tag: STRING type, indicating the TCP task identifier.
• startTime: NANOTIMESTAMP type, indicating the task creation time.
• endTime: NANOTIMESTAMP type, indicating the end time of the task.
• firstMsgTime: NANOTIMESTAMP type, indicating the receive time of the first data message.
• lastMsgTime: NANOTIMESTAMP type, indicating the receive time of the last message.
• processedMsgCount: LONG type, indicating the number of successfully processed message rows.
• failedMsgCount: LONG type, indicating the number of failed message rows.
• lastErrMsg: STRING type, indicating the error message from the last processing failure (TCP connection failures, disconnections, data read errors, etc.).
• lastFailedTimestamp: NANOTIMESTAMP type, indicating the time of the last processing failure (TCP connection failures, disconnections, data read errors, etc.).

Syntax

cancelSubJob(tag)

Details

The function cancels a TCP background task.

Parameters

• tag: A STRING scalar indicating the TCP task identifier. This identifier can be obtained by getSubJobStat() or returned by createSubJob.

Syntax

connect(ip, port)

Details

The function creates a blocking TCP connection and returns a TCP socket resource that can be used in read and close methods.

Note: Upon the closure of the current session, the plugin automatically invokes close to terminate the connection.

Parameters

• ip: A STRING scalar indicating the IP address of the server.
• port: An INT scalar indicating the port number of the server.

Syntax

read(socket, [size])

Details

The method reads data from the TCP Socket and returns a BLOB scalar.

Parameters

• socket: The socket connection created by connect.
• size (optional): An INT scalar indicating the maximum number of bytes to read. The default is 10,240 bytes and must be greater than 0.

Syntax

write(socket, data)

Details

The method writes data to a TCP Socket and returns true if the write operation is successful; otherwise, an exception is thrown.

Parameters

• socket: The socket connection created by connect.
• data: A BLOB or STRING scalar indicating the data to be written to the socket.

Syntax

close(socket)

Details

The method closes a TCP socket connection and returns true.

Parameters

• socket: The socket connection created by connect.

Examples

def handler(mutable table1, data){
	table1.append!(data)
}
share table(1:0, `bytes`isHead, [BLOB, BOOL]) as t
config = dict(STRING, ANY)
config[`maxRows] = 8192
	
TCPSocket::createSubJob("192.168.1.38", 20002, handler{t}, config)

If the following exceptions are thrown after executing a plugin method, or if messages are displayed in the log: "[PLUGIN::TCPSocket]: failed to XXX with IO error type $", refer to the table below to identify the specific cause.