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

# J 5.02 Release Highlights and Overview

For installation info see Windows or Unix.
J has a console interface called Jconsole and a GUI interface called Jwd. Use Jwd for an easier, user-friendly introduction to both standard and new features. In Windows, start Jwd with the blue J icon created in program group J by the install. In Unix, start Jwd by running jw in the J directory (for example, ~/j502a/jw).
The system includes 3 online books that are introductions: J Primer by Eric Iverson, Learning J by Roger Stokes, and J for C Programmers by Henry Rich. They vary in approach and you can probably benefit from reading all three. Hopefully you will find one which matches your requirements and outlook.
Whether you are new to J or an old hand, it is a good idea to start by exploring the Jwd menu.

# Menu

Help Browse the help to get an idea of what is there and how to navigate.
Studio Demos are example applications. Run them to get an idea of what J can do. The code is all there, so later on you can look to see exactly how it is done. Run the plot demo. Labs can teach you all kinds of things. Labs are a series of steps where the computer gives you the next piece of information, shows you examples, and then lets you experiment before proceeding.
Tools Execute IDE extensions (customized with Edit|Configure).
Run Load definitions from files and run services such as Project Manager and Debug.
Edit Find and replace; customize your system; etc.
File Commands for working with scripts and other files.

# J User License

You must have a J User License (JUL) to program in J.
J can be installed on any number of platforms and systems for free. All J installations are complete and there are no 'crippled' versions. End user applications (runtime apps) built with J that don't provide a J programming interface can be used without a JUL.

# System Overview

J is a high-level, general purpose programming language. The J system provides: an engine for executing J; various front ends that provide user interfaces to the J engine; a library, written in J, that provides an IDE (interactive development environment), numerous tools, utililties, demos, tutorials; and online documention.

# J Engine (JE)

The JE executes J sentences and maintains state information such as the definitions of verbs, the values of nouns, and the execution stack. The JE acts as a server to a J Front End that provides a user interface. All other JE interfaces with the world outside its own execution and state are through a few 'foreign conjunctions' that enable the JE to work with files, call routines in external libraries (DLLs), and access host services.
See Release Notes for details on J Engine changes in this, and earlier releases.

# J Front End (JFE)

A JFE provides a user interface to the JE. Typically a JFE takes user input from the keyboard, gives it to the JE, and then displays the formatted result that the JE returns on the screen. Jconsole is a command line JFE and Jwd is a GUI based JFE that implements wd.

# wd (window driver)

wd is a command processor implemented in a JFE that executes commands that create and manage forms, controls, events, etc. The JE passes wd arguments to the JFE for execution and the JFE returns command results as well as calls the JE with event information for user actions such as button presses and menu command selection. wd extends J so that the J programmer can create GUI interfaces to J programs. wd is portable and provides the same capabilities in Windows and Unix.

# Jwd

Jwd is a JFE that implements wd. Jwdp, the portable Jwd, is implemented in Java and runs in Unix and Windows. Jwdw, the Windows specific Jwd, is implemented in C++ with the Win32 API and supports the standard wd commands as well as additional Windows specific features..
In Windows, start Jwdw with the blue J icon. If you want to run Jwdp in Windows see section red J icon.
In Unix, start Jwd by running jw in the J directory (e.g., ~/j502a/jw). This can be made easier by creating an icon, copying jw to a directory in the path, creating a link, etc.

# Jconsole

Jconsole is a command line interface to the JE. It does not implement wd. Jconsole is very similar in Windows and Unix and can be run from a host console and can be used like any other console command. The jconsole binary in Windows is called jconsole.exe and in Unix it is called jconsole.
In Windows, start Jconsole by running jconsole.exe. For example, if J is installed in directory c:\j502a: click Start taskbar button, select Run, and type c:\j502a\jconsole. Or you can type that line in any DOS console window. If you use Jconsole a lot you may want to create a bat file (perhaps called jc.bat) in a directory in PATH.
In Unix, start Jconsole by running jc in the J directory (e.g., ~/j502a/jc). This can be made easier by creating an icon, copying jc to a directory in PATH, creating a link, etc. Hash bang (#!) scripts can use Jconsole. Jconsole uses readline and identifies itself as 'jconsole'. The input history from previous sessions is loaded from file ~/.jhistory (if it exists) when Jconsole starts and the new input lines are added to the file on exit. Create an empty ~/.jhistory file to make use of this feature. See the Unix man or info pages on readline.

# Script Library

J definitions are stored in ASCII plain text files called scripts. J scripts usually have a filename suffix of ijs. The system includes an extensive script library and related files that include an IDE, tutorials, demos, tools, and utilities.

# profile

When a JFE starts it loads profile.ijs from the library to initialize the system. The Jwd profile uses wd to create a complete IDE.

# Interactive Development Environement

The same Jwd IDE is available in Windows and Unix. The IDE is written in J/wd and is implemented in library scripts. It is open and available for study and modification.

# Portability

J is portable across platforms. An application written for Jconsole or Jwd is as close as you can get to 'write once, run anywhere'. The JE is as identical as possible and wd, except for a few Windows specific features, is portable.
A Jwd application developed in Unix will run in Windows on either Jwdw or Jwdp.
A Jwd application developed in Windows in either Jwdp or Jwdw will run in Unix as long as the Windows specific features of Jwdw are not used.
For information on Jwdp in Windows see red J icon.

# J Engine Protocol

The J Engine 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. See J Engine Protocol for documentation.
The 502 release has important changes to the JE Protocol that significantly improve performance by simplifying message transactions. The JCMDFL message is killed off. This message was used to send form locale for use with a possible wd'pc ...'. The form locale is now sent as a string after the wd array argument in the wd message. JCMDED message is killed off. The event data is now sent with the JCMDINZ or JCMDDO message. If there is event data the message type is 1 and the event data is after the null terminated input data.

# Context sensitive help

Ctrl+F1 in an ijx or ijs window displays the Dictionary page for the primitive at the caret.
Ctrl+F1 with the caret in the last line of a script error report opens the script and highlights the error. An example of a script error report is:
load 'c:\j502a\user\test.ijs'
|domain error: script
| 'a' +2
|[-5] c:\j502a\temp\2.ijs

# Index

If you don't find what you want in the index for the online help books, try Edit|Find In Files for a general and powerful search of html help.

# PDF Books for Hardcopy

www.jsoftware.com has downloadable PDF versions of all the J books that are included in online html format with the release. The PDF format is particulary useful for printing hardcopy pages, chapters, or even entire books. There are additional publications available at the web site.

# ctrl+Break, Break, and ctrl+C

You can interrupt J execution. In Jwdw you signal with ctrl+Break (key labeled as Pause/Break); in Jwdp you signal with Break, and in Jconsole you signal with ctrl+C.
One signal interrupts at the start of a sentence with an attention interrupt or a request for input (for example, 1!:![1) with an input interrupt. Input interrupt is not currently supported in Jconsole in Unix.
Two or more signals breaks execution in the middle of a sentence with a break
It is much preferred to use a single signal to get an attention interrupt as the state of execution at the start of a line is clear. In a break it is not clear what has been executed and there is some chance of crash as it is difficult to ensure a clean state in all cases. Signals should be made carefully and you should wait many seconds before making additional signals.

# Form Editor

The Form Editor in 502 is much improved over the version in 501.

# Path names

You can configure the assignment of names to paths. These names simplify access to frequently used folders and make it easy to make systematic changes.
SYSTEMFOLDERS_j_ is defined in the profile, and USERFOLDERS_j_ in the user configuration. Menu Edit|Configure|Folders manages the USERFOLDERS_j_ table.
Verb jpath references tables SYSTEMFOLDERS_j_ and USERFOLDERS_j_.
jpath with an argument with a leading ~ looks up the name in the folder tables. For example:
jpath '~system\main\dates.ijs'
c:\j502\system\main\dates.ijs
Verbs load and require use jpath. See Directory Paths for complete information.
J501 defined verbs jaddonspath, jconfigpath, jsystempath, jtemppath, and juserpath. These have been decomitted and are replaced by jpath. Load system\extras\migrate\paths.ijs if you need the old definitions.

# ijs/ijx title bar

The ijs/ijx title bar has a * if it is modified and shows the line number with the caret. If the caret is in an explicit definition it also shows the definition line number.
You can change the form of the ijs/ijx title bar with Edit|Configure|Startup Window Title Style. If the style contains [...] it is updated as [nn cc] where nn is the line number with the caret and cc is the line number in an explicit definition. If the style has a * in front of the [...] then the modified state is indicated.
The explicit definition line number is determined simplisitically and won't be correct in all cases. It searches preceeding lines looking for a line with only a : or for a line that contains one of the patterns '... :0...' or '... : 0...' or '... define...'
The * and [...] features are not supported in Jwdp.

# Jwdp performance

Jwdp (Java based Jwd) performance is improved in 502 over 501. Jwdp uses the JE Protocol and transaction rates of dozens per second have been increased to thousands per second. This makes the Jwdp more lively.
Output to the ijx window (smoutput, 1!:1[2, echo, et.al.) is now displayed immediately. This was always the case with Jwdw.

# Directory Match

Edit|Directory Match compares directories. You can use an external file comparison tool (e.g., ExamDiff, either the paid or free version, from http://www.prestosoft.com) with Directory Match.

# Labs

Lab commentary text (from the start of a section up to the closing right paren) is no longer 'code colored'.
There are 2 new labs on circuit theory by John Wilson in the General Interest category. From the lab:
This presentation of elementary DC circuit theory is unusual. It differs from conventional treatments in the mathematical model used for a circuit.
In the conventional treatment a physical circuit is modeled as a directed linear graph together with a function that describes the voltage-current relation in each of its branches, together with Kirchhoff's laws. This is an internal view of circuits rather than an external view.
The model presented here is the voltage-current relation at the terminals of the circuit; in other words, its external behaviour. For simplicity I take this relation to be a function from voltage to current. This function is a mapping in n-space having two simple properties related to Kirchhoff's laws.

# Trace (13!:16) decommitted

The 13!:16 implementation required unwarranted complications in the interpreter. A similar trace facility is provided by a script that also provides a model of the J parser whose internal workings can be examined and experimented with. One thing that the script does not do that 13!:16 did, is to recurse down explicit function calls. However, explicit function calls generated output too voluminous for ready comprehension.
load '~system\packages\misc\trace.ijs'
NB. x trace y - trace expression y to x levels of function calls
NB. trace y - same as _ trace y
trace '3+i.4'

# gl2 changes - wd 2d graphics

isigraph is now always drawn double-buffered in both Jwdw and Jwdp.
glshow now correctly does an immediate repaint in Jwdp.
load'gl2' loads into the jgl2 locale. This keeps the many gl2 definitions from cluttering up the z locale. Production users of gl2 can either use the full name (e.g. glline_jgl2_) or can add the jgl2 locale to their locale path. Requiring _jgl2_ on all names for casual use is a nuisance and you can use coinsert to add jgl2 to your current path. For example: coinsert'jgl2' will allow you to use gllines in base without having to add the _jgl2_.
gl2 mapping has 3 standard mapping modes:
glmap MM_DEFAULT - x right, y up, scales glwindowext to fit
glmap MM_RAW - x right, y down, units are pixels
glmap MM_RIGHTDOWN - x right, y down, scales glwindowext to fit
Command 11!:2999 takes a list of multiple gl commands. Each command starts with an integer count followed by the command and data. For example:
11!:2999 [ 4 2013 500 500 4 2013 900 100 2 2036 NB. glline, glline, glshow
11!:2999 [ 4 2056 500 200 5 2038 65 66 67 2 2036 NB. gltextxy, gltext, glshow
This can be used to move the overhead in the J Engine Protocol of passing thousands of individual small commands over the socket interface by one large 2999 command.
Commands for working with pixels:
glpixels x y w h pixeldata
pixeldata is an integer per pixel with RGB values
pixeldata =: glqpixels x y w h
See gl2 Command Reference for documentation.

# jserver and jtelnet classes

The jserver class allows you to create and manage a separate J task as a server. jserver.ijs (open 'jserver') defines a jserver class that uses the J Engine Protocol to create and manage a J Engine server. This class works in both Jconsole and Jwd. It starts a new J task, either on the local machine or a remote machine, and controls that task with the J Engine Protocol.You can take advantage of multiple processors on the same host, remote hosts, and build applications where the interactive GUI runs in one JE and the data processing is done in others as appropriate. For example:
require'jserver'
js=: conew'jserver' NB. create new jserver object
local__js'' NB. create J server task
run__js'abc=: i.2 3 4' NB. run sentence in server task
d=: get__js'abc' NB. get value from J server task
destroy__js'' NB. destroy object and free resources
The jserver class also supports J server tasks running on on other machines.
It uses jtelent to start the J server on the remote machine. If you had J installed on another machine that was accessible to you from telnet you could start and use a J server on that remote machine. For example, if your other machine is called Frodo and you have a user id of
Bilbo and a password of Baggins, you could try the following:
require'jserver'
js=.conew'jserver'
NB. start J server on remote machine
remote__js'Frodo Bilbo Baggins 0'
NB. run sentence on remote server
run__js'abc=:i.2 3 4'
destroy__js''
You could use Frodo's IP address (e.g. 192.168.1.5) instead of the name.
The remote jserver uses jtelnet, a simple and naive implementation of the
telnet protocol. For example:
require'jtelnet'
tn=: conew'jtelnet' NB. create jtelnet object
logon__tn'Frodo Bilbo Baggins 0'
run__tn'ls'
destroy__tn''
Open and study the scripts for more information and ideas on their use.

# Command line parameters

With -jprofile, -jijx, and -js command line parameters you can start J in various ways. When J starts the JFE puts all the command line parameters into noun ARGV_z_.
In the following J is j.exe or jconsole.exe or jw or jc. FN is the name of a script. ARGS is 0 or more additional command line parameters.
J - JFE loads profile
J FN - JFE loads profile; profile loads FN
J FN ARGS - JFE loads profile; profile loads FN; ARGS available in ARGV
J -jprofile - no profile (default ijx window if Jwd)
J -jprofile FN - JFE loads FN (alternate profile)
J -jprofile FN ARGS - JFE loads FN
J -jijx FN - JFE loads profile; profile does not create ijx and loads FN
J -jijx FN ARGS - JFE loads profile; profile does not create ijx and loads FN
J -js ARGS - creates verb ARGVERB_z_ from ARGS and runs it
Examples with -js:
jconsole.exe -js a=.23 b=.3 "echo a*b"
jconsole.exe -js a=.23 b=.3 "echo a*b" exit
An end user application (runtime app) can be started with -jijx if it needs the standard profile, or with -jprofile FN if it doesn't require profile.
Jwd tests at the end of the execution of every sentence. If there is an error and no ijx window, then a message is displayed and the session is terminated after the message is closed. If there are no forms, then the sesssion is terminated.

# Unix J #! script

A #! J script (hash bang J script) is an executable text file with a first line that gives the full path the jconsole binary.Try the following:
create file sumsquares with 3 lines of text:
#!/usr/local/bin/jconsole
echo +/*:0".>,.2}.ARGV
exit''
make it executable ( chmod +x ) and run it
./sumsquares 1 2 3 4 5
Use NB. to comment out the exit'' to stay in J.
The following loads profile, which loads the #! script, which echos the result on the console and leaves J running.
#!/bin/jconsole
load'strings'
echo 'abcXXXdef' rplc 'XXX';' insert '
The following is the same, except it exits J at the end.
#!/bin/jconsole
load'strings'
echo 'abcXXXdef' rplc 'XXX';' insert '
exit''
The following doesn't load profile and just loads the script.
#!jconsole -jprofile
...
Profile loads jconsole with the following definitions that are useful in #! J scripts:
ARGV - boxed list of jconsole, script name, and arguments
echo - format and display output
getenv - get value of environment variable
stdin - read from standard input
stdout - write to standard output
stderr - write to standard error
exit - exit J (arg is return code)
stdin is defined with stdout as its obverse (see the :. conjunction). When used with &. (under conjunction), as in foo&.stdin '' stdin is first called, reading all of standard input. That input is the argument to foo, and the result is passed to the inverse of stdin, which is stdout. A verb which transforms a character list can be combined with the stdin verb with under to apply the transformation as a Unix filter. As an example we will create a Unix filter which reverses all the characters in a file. Rather than just using |. we'll use (|.@}: , {:) which reverses all but the last character, and appends the last character to it. For files which end in a newline, this reverses the file keeping that newline at the end. Define the #! J script reverse as follows:

    #!/usr/local/bin/jconsole
    rev=. |.@}: , {:
    rev&.stdin ''
    exit''

If you wanted to do a complete reverse of a file which does not end in a newline you could do the following:
rev=. |.`(|.@}: , {:)@.(LF&=@{:)
echo uses 1!:2 to write to J output (file number 2) and formats and writes any J array. stdout and stderr , however, must be given character lists, and writes them unaltered. In particular, echo 'a line' will write a trailing newline character whereas stdout 'a line' does not.

# Unix - jconsole - stdin and stdout

The verb defined below calls a program, writes to its standard input, and reads its output.

    run=: 4 : 0
    'p o i'=. 2!:2 x.   NB. Run command, save Process, Output, Input
    y. fwrite i         NB. Write to its input
    fclose i            NB. Close its input
    2!:3 p              NB. Wait for process to terminate
    z=.fread o          NB. Read its output
    fclose o            NB. Close its output
    z                   NB. Result
    )

# Starting J - tech details

In Windows, 1!:45 returns profile.ijs in the path of the J Front End (j.exe or jconsole.exe). For example: c:\j502a\profile.ijs.
In Unix, 1!:45 uses environment variables and the J version to determine the default profile. The version is the text in 9!:14'' up to the first /. If 9!:14'' returned j502a/2003-05-01/16:45, then the version is j502a. If HOME/version/profile.ijs exists, then it is the default profile. For example, if HOME was /home/eric, then /home/eric/j502a/profile.ijs would be the default profile if it existed. If that file doesn't exist, environment variable JPATHversion (for example, JPATHj502a), if it is defined, is the default profile.
Normally J is initialized by the JFE with:
(3 : '0!:0 y.')<1!:45''[ARGV_z_=:...
The JFE command line is given to the JE by setting ARGV_z_. The 1!:45'' returns the full path to the default profile. The profile is loaded by an explicit verb and it must use =: for global assignments.
The default profile defines PROFILE_z_ (if not already defined) as 1!:45''. This makes it easy for a stub profile to redirect to another profile.
-jprofile as the first parameter with additional parameters initializes J with:
(3 : '0!:0 y.')2{ARGV_z_=:...
That is, the parameter after -jnoprofile is loaded instead of the standard profile.

# Previous Release Highlights

See Old Windows Release Notes for documentation from previous releases that has not yet been merged into the standard documentation, or perhaps just stands out more clearly.

# Windows install

J is installed on your windows system with program j502X.exe (where X indicates a bug release level). You can download this program from www.jsoftware.com. Run this program and follow the instructions to install J. Start J with the blue J icon the install creates in program group J.

# Windows Jwdp red J icon

You should normally run Jwdw (blue J icon) as it has the following advantages over Jwdp:
1. supports OCX and OLE automation (not available in Jwdp)
2. starts quickly (Java is slow to start)
3. don't need to install/maintain Java Runtime Environment
4. is more stable (Jwdp is new and more likely to have bugs)
5. Java is a bit flakey compared to Win32
6. will run applications developed in Jwdp
7. develop apps for Jwdp by simply avoiding Windows only features
You may want to run Jwdp to see more closely how your application will look in Unix, or to check more carefully that it really is portable, or just because you are curious.
To run Jwdp you need to have the Java Runtime Environment or the Java SDK installed (version 1.4 or later, available at the Sun web site).
The easiest way to create a Jwdp icon is to make a copy of the blue J icon and then edit the properties as follows:
1. edit shortcut target to end in j.jar rather than j.exe
2. Change Icon to select the jr.ico in the J directory
One reason for this icon to fail is that the file assocation between jar and java is broken. You can fix the association, or try a shortcut target like:
c:\Program Files\Java\j2re1.4.0\bin\javaw.exe -jar c:\j502a\j.jar

# Unix install

J is installed on your Unix system with file j502X_Y.tar.gz (where X indicates a bug release level and Y is the uname in lowercase). Example unames are linux and darwin (for Mac OS X). You can download this file from www.jsoftware.com.
The first step is to unpack the file to create a directory tree rooted at j502X. The file is a gzipped tar file and unpacking it varies on different systems. On Linux do the unpack with:
tar -xzf j502X_linux.tar.gz
The simplest install is to do the unpack in your home directory. If you do, you are ready to run J after the unpack.
Start Jwd with command ~/j502X/jw and start Jconsole with ~/j502X/jc. A common jw failure is that java isn't on your path and you can edit jw to give the full path.
Customize your installation by edits to jw and jc; copy them to bin directories; create links and icons.
There is a minimal man page for jconsole at system/extras/help/man/jconsole.1 and you can make this available to man by copying the file to /usr/local/man/man1 or other suitable directory.
You don't have to install in the j502X directory in your home directory, but installing in a different location requires extra steps. When you run J it needs to find its library files and it looks first in ~/j502X. If you install J in another directory you must set an environment variable so that it can find the library files. The variable has the name JPATHj502X. For example, if you installed j502a to ~/programs, then you could edit the jw and jc files as follows:
#!/bin/sh
export JPATHj502a=~/programs/j502a
java -jar ~/programs/j502a/j.jar $*
#!/bin/sh
export JPATHj502a=~/programs/j502a
~/programs/j502a/jconsole $*
More complicated installations, for example installation in a shared, read-only directory, for use by multiple users are possible, and require both system admin and J programming knowledge. The profile.ijs has to be modified so that standard J user directories such as user and temp are properly set. For example, the following changes to profile.ijs would give each user their own temp and user directories in their ~/J directory:
USER_j_=: (2!:5'HOME'),'/J'
TEMP_j_=: USER_j_

# Incompatible changes introduced in 501

The 501 release is a major release (4 to 5). In minor releases (4.05 to 4.06) we do our best to minimize changes which will break existing applications. In a major release we are more cavalier and introduce incompatible changes if we feel there is sufficient long term benefit.
We have concluded that the tridents (except for fork) and some of the bidents complicate the system out of proportion to their utility and they are decommited. See "J 5.01 Non-compatible Changes" in Release Notes for details.
There are also incompatible changes in foreigns, wd, and gl2.

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