J Socket Protocol

>> << 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

Command | Sent by | Type | Data | Description
CMDDO | client | 0 | string | JE executes sentence
CMDDOZ | JE | error | none | JE finished with sentence
CMDIN | JE | 0 | prompt | J requests keyboard input
CMDINZ | client | 0 | input | JE resumes execution
CMDWD | JE | x | array | client runs 11!:x request
CMDWDZ | client | WDZ | data | JE resumes execution
CMDOUT | JE | OUT | string | output for display
CMDBRK | client | 0 | none | JE interrupts execution
CMDGET | client | 0 | name | JE replies with CMDGETZ
CMDGETZ | JE | error | array | value in 3!:1 format
CMDSETN | client | 0 | name | sets name for CMDSET
CMDSET | client | 0 | array | sets name with 3!:1 value
CMDSETZ | JE | error | none | result of set
CMDEXIT | JE | code | none | 2!: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