>>  <<  Ndx  Usr  Pri  Phr  Dic  Rel  Voc  !:  wd  Help  User

J Engine Protocol

Jconsole in both Windows and Unix provides a console interface to the J Engine (JE). Jconsole can also be started with a command line parameter so that it instead provides a socket interface to the JE that uses the J Engine Protocol. The client side of this interface to the JE server is a J Front End (JFE).

JFE starts JE with a command line requesting it to connect to a socket. JFE can start JE on the same machine, in which case it needs to provide a port number. Or it can start JE on another machine, in which case it also nees to provide the host name or address. For example:

jconsole -jconnect 1234
jconsole -jconnect frodo:2002
jconsole -jconnect 192.168.1.3:4321

The J Socket Protocol allows any client with sockets to have full use of a JE. This provides facilities that are similar to J OLE Automation in Windows, but does so in a portable, open, more efficient, and much simpler manner.

Jsoftware provides a JFE written in Java that runs in both Windows and Unix. This JFE supports the J wd interface that provides GUI facilities to the J programmer and provides a standard, portable, cross-platform IDE (Interactive Development Environment).

Jsoftware also provides a script (open'jserver') that lets J act as a JFE to another JE. Studying and playing with this script is a good way to learn about the J Socket Protocol. See the jserver script for details like the values for names (e.g. CMDDO) used in this document.

Messages

The JFE client and the JE server exchange messages over the socket. Some messages require a reply and others don't.

All messages have the following format:

Command - 1 byte
reserved - 3 bytes
Type - 4 byte integer (NBO) with extra command info
Len - 4 byte integer count (NBO) of bytes in data
Data - Len bytes of data

In NBO (network byte order or standard byte order) the bytes 0 0 0 1 are the integer 1. In RBO (reverse byte order) the bytes 1 0 0 0 are the integer 1. In HBO (host byte order) the byte order is NBO or RBO depending on the host. Intel x86 and related machines are RBO and most others are NBO.

Len can be 0, in which case there are 0 Data bytes. Data bytes are not null terminated and can have any value.

Command Summary

CommandSent byTypeDataDescription
CMDDOclient0stringJE executes sentence
CMDDOZJEerrornoneJE finished with sentence
CMDINJE0promptJ requests keyboard input
CMDINZclient0inputJE resumes execution
CMDWDJExarrayclient runs 11!:x request
CMDWDZclientWDZdataJE resumes execution
CMDOUTJEOUTstringoutput for display
CMDBRKclient0noneJE interrupts execution
CMDGETclient0nameJE replies with CMDGETZ
CMDGETZJEerrorarrayvalue in 3!:1 format
CMDSETNclient0namesets name for CMDSET
CMDSETclient0arraysets name with 3!:1 value
CMDSETZJEerrornoneresult of set
CMDEXITJEcodenone2!:55 code


Type in CMDWDZ describes the Data format:
WDZSTR - string
WDZINT - list of integers in JE HBO
WDZMTM - Len is 0 and the J result is an emtpy matrix
WDZERR - Len is 0 and Type is 1000+error (e.g. 1003 is domain error)

Type in CMDOUT describes the output:
OUTFR - formatted result array (just before CMDDOZ)
OUTERR - error output
OUTLOG - output from loading script
OUTSYS - system assertion failure
OUTFILE - 1!:2[2

error Type is 0 for no error or a J error (e.g. 3 is domain error).

Data array is the 3!:1 binary representation of a J array.

Event data for wd'q' is sent as a string after the null terminated input string with a CMDDO or CMDINZ message with Type 1.

CMDWD includes the current locale as a string after the array argument.

Command Transactions

Some messages require a response.

DO/DOZ - client sends a sentence and JE replies when finished
WD/WDZ - JE sends a wd command and the client replies when finished
GET/GETZ - client sends a name and JE replies with its 3!:0 value
SETN/SET/SETZ - client sends name, then 3!:0 value, and JE replies when finished


DO/DOZ is the main transaction. IN/INZ/WD/WDZ/OUT/BRK messages occur only only within a DO/DOZ transaction.

DO, GET, SETN, and SET commands can only be sent when J is ready (i.e., not already working on a message).

Command Sequences

sentence with no output:
client DO a=.5
server DOZ

sentence with output:
client DO i.5
server OUT OUTFR 0 1 2 3 4
server DOZ

1!:2[2 (smoutput) output
client DO i.5[smoutput 'test'
server OUT OUTFILE test
server OUT OUTFR 0 1 2 3 4
server DOZ

error:
client DO 'a'+1
server OUT OUTERR domain error
server DOZ

1!:1[1 request for input (or a debug suspension):
client DO ...
server IN prompt
client INZ input
server OUT OUTFR formatted result
server DOZ

break:
client DO 6!:3[100 NB. long running sentence
client BRK
server OUT OUTERR interrupt
server DOZ

wd command:
client DO wd'pc abc;cc b button;pshow'  
server WD 'pc abc;cc b button;pshow' + 'base'
client WDZ WDZMTM
server OUT OUTFR formatted result
server DOZ

wd event:
client DO wdhandler_formlocale_'' + event data
... server DOZ


Array Data

Array data is the 3!:1 representation of a J array. Numerics are in the JE HBO except for SET which can be either NBO or RBO.

The array format is: type, flag, count, rank, shape, data

The type, flag, count, rank, shape are 4 byte integers. The type is defined as in 3!:0. The flag must be 0. Boxed arrays are nested with values as offsets to the array.

You can experiment in J to see the bytes in the data array. Try the following sentences.

   hex=: 3!:3 NB. hex display of 3!:1 - host byte order
   hex 'abc'
   hex 'abcd'
   hex 2 2$'abcd'
   hex 23+i.3
Character arrays have a trailing null that is padded with nulls to a 4 byte boundary. This format of J array data will not change over releases with the possible exception of the nulls after character data. Do not depend on the character trailing nulls!
>>  <<  Ndx  Usr  Pri  Phr  Dic  Rel  Voc  !:  wd  Help  User