jCML Communication Protocol

The jBASE Remote Connectivity Layer defines a communication protocol, which the client library uses to send requests to and receive replies from the remote server process. The protocol is based on Extensible Mark-up Language (XML) and will be named JCML (jBASE Communication Mark-up Language). The structure of JCML is discussed further in this section and is based on the following assumptions:

  1. The underlying networking protocol used for transmission of JCML is connection-oriented, reliable, error-correcting and stream-capable. Protocols falling into this category are TCP, SPX, UNIX domain sockets, stream pipes, and FIFOs. The implementation of JCML will be discussed in the context of TCP/IP, but this specification does not preclude implementation of JCML on other fundamental network protocols.
  2. All data link security is handled in the underlying network protocol. The security strategy may include access restriction techniques, such as firewalling, or transparent data encryption (PPTP, IPSec, SSL, or SSH tunnelling). JCML does not incorporate any security features and in its unmodified form is suitable for LANs and VPNs.
  3. JCML messages are synchronous and atomic and assume that requests are paired with replies from the server and that not more than one outstanding request is pending for the server at any given instant. This implicitly assumes that requests from multiple client threads are serialized prior to being communicated to the server.


Overall Structure of JCML

JCML mark-up incorporates several tags, defining the structure of the message. The tags are listed in the following table:

Tag Optional Attributes Description





Root tag of JCML markup. The "src" attribute defines the origination point - client or server. The type attribute specifies the message type:


req - client request

reply - server reply

termout - server terminal output message

prompt - server request for terminal input

termin - client reply with terminal input

<obj>   Proxy object handle. This is the handle referencing the target object on the server. The connection object always has handle 0. Other object handles - such as file objects - created by the server are communicated back to the client.
<cmd>   Function to be executed by the target object.
<data> enc="esc|base64" Function parameters or return values. The "enc" attribute defines how parameter data is encoded, either by escaping XML non-printables (esc), or by base64-encoding the data (base64).
<stat> id=<numeric value> Function return status. The "id" attribute determines the return code. The content of the tag is the error message. If this tag indicates failure upon return from the host, an exception is thrown by the C++ library.

The valid message formats in JCML are defined below.

The Request for Service Message

Request for service is the message sent by the client library to the remote server to initiate a service request (remote function call). The format of the message is as follows: 

  1. A <jcml> tag with src="client" and type="req".

  2. A <obj> tag with handle of the target object.

  3. A <cmd> tag with name of the function to be invoked on the object.

  4. Zero or more optional <data> tags with encoded function parameters.


<?xml version="1.0" encoding="UTF-16"?>

<jcml src="client" type="req">



<data enc="esc">Test</data>

<data enc="esc">MCU</data>


The XML fragment above calls the function oconv in object 0 (connection object) and passing it string "Test" as the first parameter and string "MCU" as the second parameter.


Service Reply

The service reply message is sent by the remote server after the processing of the client‟s request is completed. The message is formatted as follows:

  1. A <jcml> tag with src="server" and type="reply".

  2. A <stat> tag with id set to the return code and containing the error message.

  3. Zero or more <data> tags containing return values.


<?xml version="1.0" encoding="UTF-16"?>

<jcml src="server" type="reply">

<stat id="0"></stat>

<data enc="esc">TEST</data>


This example illustrates a possible server reply to the sample request constructed in previous section. It instructs the client that the server function has completed with status code of 0, no error messages, and the return value is "TEST".


Terminal Output

This message may be sent by the server to the client while the request for service is being executed. It indicates that the server has generated terminal output during the course of its processing and is supplying the output to the client. This message requires neither acknowledgement nor a reply. The structure of the message is as follows:

  1. A <jcml> tag with src="server" and type="termout".

  2. A <data> tag supplying the terminal output. Due to the fact that terminal output may contain non-printable characters and escape codes, this parameter is typically base64-encoded.


<?xml version="1.0" encoding="UTF-16"?>

<jcml src="server" type="termout">

<data enc="base64">VGVzdCBvdXRwdXQK</data>


This example illustrates a terminal output message from the remote server supplying a base64-encoded string "Test output" to the client.


Request for Input

A request for input is sent to the client when the server encounters a command requiring terminal input while processing the client request. This message requires the client to send back a terminal input message with input characters for the server process. The request for input is typically formatted as follows:

  1. A <jcml> tag with src="server" and type="prompt".

  2. An optional <data> tag with a parameter defining the maximum length of input requested. If this parameter is omitted, the amount of input the client can supply is unlimited.


<?xml version="1.0" encoding="UTF-16"?>

<jcml src="server" type="prompt">

<data enc="esc">100</data>


This example illustrates the server request for at most 100 characters to be returned from the client.


Terminal Input

The terminal input message is sent by the client in response to the server‟s request for input. This message has the following format:

  1. A <jcml> tag with src="client" and type="termin".

  2. A <data> tag with terminal input characters supplied to the server. The input is typically base64-encoded because it may include binary data. The data itself is not converted to UTF-16, but is base64-encoded and passed verbatim to the server.


<?xml version="1.0" encoding="UTF-16"?>

<jcml src="client" type="termin">

<data enc="base64">VGVzdCBpbnB1dAo=</data>


This example illustrates a terminal input message sent to the server with base64-encoded string "Test input" as input.


jBASE Remote Connectivity Service