JavaScript TCP Client

The JavaScript TCP Client communication point is used to create a communications protocol through JavaScript. The JavaScript TCP Client communication point allows four scripts to be configured by the user to control the TCP connection. The connection itself is established and managed by the Rhapsody framework, however, the custom JavaScript is responsible for performing the reading and writing to the connection itself.

The four scripts are as follows:

init - runs when a new connection is established. This is to allow any initialization or login sequence to be performed.
send - this script is used to send a message over the connection.
receive - this script is used to read a message from the connection.
done - this script is used to indicate that a received message has been successfully stored by the communication point framework.

Refer to Global Variables for details on the global objects associated with these scripts.

Supported Operational Modes: All.

Input Mode Properties

Property	Description
Remote Host	The hostname/IP address of the remote system to which you want to connect.
Remote Port	The port number on the remote host to which you want to connect.
Local Address	The hostname/IP address of the local interface to which you want to bind the socket connection (all interfaces if blank).
Local Port	The port number to which you want to bind the local socket.
Use SSL	Whether to use SSL: Enabled - secure socket layer is used for this connection and all messages are encrypted. Disabled (default). It is recommended that SSL be enabled for JavaScript TCP Client communication points whenever it is supported by the remote server. Refer to TLS/SSL Support in Rhapsody for details.
SSL Protocol Mode	Refer to SSL Protocol Versions for details.
SSL Cipher Suites	Refer to SSL Cipher Suites for details.
Use SSL Client Mode	Whether to use SSL client mode: Enabled (default). Disabled. If this property is enabled, SSL client mode will be enabled. Note that this is NOT the same as TLS client authentication. TLS client authentication is supported by configuring one or more private keys in the Secure Keys configuration property.
Secure Keys	Identifies the private keys used for authenticating Rhapsody's end of the SSL connection. When configured with a private key, the SSL client supports SSL client authentication if requested by the SSL server. Refer to Client Authentication for details.
Trusted Certificates	Identifies the trusted certificates used at the non-Rhapsody end of the SSL connection. If it is not configured with the SSL server's certificate, then this SSL client operates in anonymous server authentication mode. It is highly recommended that the server's certificate always be provided here to allow server authentication to be performed. Refer to Server Authentication for details.
Initialise	The script called whenever the communication point is started. The initialization script is called as soon as a new connection is established by the communication point framework. Specifically, it is called in the getConnection() method of the communication point as soon as the TCP connection has been made. It enables you to perform any necessary initialization of the connection object. Additionally, any variables declared and initialized in this script are available to all other scripts for the same connection. The initialization object has only the 'log' and 'conn' objects placed in its scope. There is no return value from the initialization script.
Log Connections	Whether to log connections and disconnections: Enabled - details of when a connection to the communication point is established and dropped are logged to the log file specified in the Connection Log File property. Use of this logging facility slows the communication point down considerably. It is intended for debugging purposes and should not generally be used in production. Disabled (default).
Log Data	Whether to log data: Enabled - all data passed over the connections of the communication point is logged to the log file. This is potentially a large amount of data. Disabled (default).
Log Data As Hex	Whether to log data in hexadecimal form: Enabled - the hexadecimal representation of the data is logged to the log file. Disabled (default) - the data is logged exactly as it is as it passes over the communication point connection.
Connection Log File	The full file name (path and file name) of the file on the server to which to log the information.
Extra Information	Whether to include extra log information: `None`. `Log Time` (default) - the timestamps are logged with each event.
Receive	The Receive script is expected to read a message from the transport connection and populate the result message and return a `true` Boolean value. If no message can be received within a short time period (such as 5 seconds), the script should return a `false` value. The Receive script is used to read a message from the underlying connection. A writable message object is provided in the scope to receive the message data. The script has access to the log, conn, and result objects placed in its scope. The return value is a boolean indicating whether a message was received or not. If `true` (or no return value is provided) then the message is sent into Rhapsody for persisting. If `false` is returned, then the message is discarded. The Receive script can be written to operate in either a polling or blocking manner. However, if it is blocking, the script must be safely aborted if the communication point is shut down (as long as you have not put a spinning loop in the script). Note that each time the Receive script is executed; it is independent of previous executions of the same script (that is, runs in a new scope). This means that any variables needed across multiple script calls must be declared in the initialization script (for example, to build up a message received over multiple TCP packets where the Receive script may be called multiple times).
Done receive	The Done receive script is called once the message has been persisted into the Rhapsody database. The `success` global variable is set to `True` to indicate that Rhapsody has successfully stored the message and that the remote system may be informed that it has been received successfully. If the `success` global variable is `False` then the message was not received successfully and the remote system should be informed of this. The Done receive script is run after a message has been received and Rhapsody has committed it to its internal datastore. A boolean is provided as the parameter to indicate whether Rhapsody successfully persisted the message or not. This script has access to the `log`, `conn`, and `success` objects placed in its scope. There is no return value.

Output Mode Properties

Property	Description
Remote Host	The hostname/IP address of the remote system to which you want to connect.
Remote Port	The port number on the remote host to which you want to connect.
Local Address	The hostname/IP address of the local interface to which you want to bind the socket connection (all interfaces if blank).
Local Port	The port number to which you want to bind the local socket.
Use SSL	Whether to use SSL: Enabled - secure socket layer is used for this connection and all messages are encrypted. Disabled (default). It is recommended that SSL be enabled for JavaScript TCP Client communication points whenever it is supported by the remote server. Refer to TLS/SSL Support in Rhapsody for details.
SSL Protocol Mode	Refer to SSL Protocol Versions for details.
SSL Cipher Suites	Refer to SSL Cipher Suites for details.
Use SSL Client Mode	Whether to use SSL client mode: Enabled (default). Disabled. If this property is enabled, SSL client mode will be enabled. Note that this is NOT the same as TLS client authentication. TLS client authentication is supported by configuring one or more private keys in the Secure Keys configuration property.
Secure Keys	Identifies the private keys used for authenticating Rhapsody's end of the SSL connection. When configured with a private key, the SSL client supports SSL client authentication if requested by the SSL server. Refer to Client Authentication for details.
Trusted Certificates	Identifies the trusted certificates used at the non-Rhapsody end of the SSL connection. If it is not configured with the SSL server's certificate, then this SSL client operates in anonymous server authentication mode. It is highly recommended that the server's certificate always be provided here to allow server authentication to be performed. Refer to Server Authentication for details.
Initialise	The script called whenever the communication point is started. The initialization script is called as soon as a new connection is established by the communication point framework. Specifically, it is called in the `getConnection()` method of the communication point as soon as the TCP connection has been made. It enables you to perform any necessary initialization of the connection object. Additionally, any variables declared and initialized in this script are available to all the other scripts for the same connection. The initialization object has only the `log` and `conn` objects placed in its scope. There is no return value from the initialization script.
Log Connections	Whether to log connections and disconnections: Enabled - details of when a connection to the communication point is established and dropped are logged to the log file specified in the Connection Log File property. Use of this logging facility slows the communication point down considerably. It is intended for debugging purposes and should not generally be used in production. Disabled (default).
Log Data	Whether to log data: Enabled - all data passed over the connections of the communication point is logged to the log file. This is potentially a large amount of data. Disabled (default).
Log Data As Hex	Whether to log data in hexadecimal form: Enabled - the hexadecimal representation of the data is logged to the log file. Disabled (default) - the data is logged exactly as it is as it passes over the communication point connection.
Connection Log File	The full file name (path and file name) of the file on the server to which information will be logged.
Extra Information	Whether to include extra log information: `None`. `Log Time` (default) - the timestamps are logged with each event.
Send	The Send script is called whenever there is a message waiting to be sent via the communication point. The message to be sent is passed to the script in the global variable message. The Send script is used to send a message from Rhapsody using the JavaScript TCP communication point. A read-only message object is provided in the scope to allow access to the message data. The script then sends whatever is necessary over the wire to perform the message send. This script has access to the `log`, `conn`, and `message` objects placed in its scope. There is no return value from the send script.

Bidirectional, In->Out and Out->In Mode

The configuration properties for the JavaScript TCP Client communication point in Bidirectional, In->Out and Out->In modes is a combination of the properties described above.

Refer to Out->In and In->Out Properties for general details on a communication point's In->Out and Out->In modes.

Connection Monitoring

Refer to Connection Monitoring or details.

Additional Information

Refer to JavaScript Object Reference for details on JavaScript and the objects that Rhapsody exposes.
Refer to Shared JavaScript Libraries for details on how to manage shared JavaScript libraries.