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

# J 5.01 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, ~/j501a/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

Starting with release 5.01 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. Debug, performance, and other features that previously required a software license fee for each installation are now available on all J installations.
End user applications (runtime apps) built with J that don't provide a J programming interface can be used without a JUL.

# Incompatible changes

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 that are covered in later sections.

# 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., ~/j501a/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:\j501a: click Start taskbar button, select Run, and type c:\j501a\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., ~/j501a/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'. 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. The IDE in previous versions was closed and was implemented in C++.
In previous Windows versions the IDE was based on MDI (multi-document interface) and the edit and execution windows existed within a single application frame. The MDI model is dropped in this release and edit and execution windows are independent top-level windows. Some users who have grown up with MDI will miss it, but we believe there are benefits to the new approach. It is simpler, does away with the requirement for MDI support, and is more inline with current IDE's in other languages.

# 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:\j501a\user\test.ijs'
|domain error: script
| 'a' +2
|[-5] c:\j501a\temp\2.ijs

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

# Index

The index for the online help books has been stripped down to a minimum. Previously it indexed everything and was so large that it was slow enough to be a nuisance. Use 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 diffictult to ensure a clean state in all cases. Signals should be made carefully and you should wait many seconds before making additional signals.

# wd changes

There are numerous wd changes. See Window Driver Command Reference Overview for documentation.

# gl2 changes - wd 2d graphics

load'gl2' now 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 been changed and simplified. There are 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
New gl 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.
Decommitted: glmapraw, glmark, and glmarkc.
New 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.

# Foreigns

Decommitted:
1!:40 1!:41 1!:42
2!:4 2!:6
9!:30 9!:31
New:
1!:43 returns current working directory (getcwd posix)
1!:44 sets current directory (chdir posix)
1!:45 returns default profile (for example: c:\j501a\profile.ijjs)

# Java version

Jwdp (Java based Jwd) has has been developed and tested with Java version 1.4.0.

# Linux

fvvm2 is NOT supported. You must run Gnome, KDE, or other X window managers.

# 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:\j501a\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 j501a/2002-07-05/17:50, then the version is j501a. If HOME/version/profile.ijs exists, then it is the default profile. For example, if HOME was /home/eric, then /home/eric/j501a/profile.ijs would be the default profile if it existed. If that file doesn't exist, environment variable JPATHversion (for example, JPATHj501a), 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 j501X.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:\j501a\j.jar

# Unix install

J is installed on your Unix system with file j501X_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 j501X. The file is a gzipped tar file and unpacking it varies on different systems. On Linux do the unpack with:
tar -xzf j501X_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 ~/j501X/jw and start Jconsole with ~/j501X/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 j501X 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 ~/j501X. 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 JPATHj501X. For example, if you installed j501a to ~/programs, then you could edit the jw and jc files as follows:
#!/bin/sh
export JPATHj501a=~/programs/j501a
java -jar ~/programs/j501a/j.jar $*
#!/bin/sh
export JPATHj501a=~/programs/j501a
~/programs/j501a/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_

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