APL*PLUS/PC TO APL.68000 SOFTWARE CONVERSION GUIDE
Doug White, MIT Lincoln Lab, 10/12/94
This is a comparison of the differences between STSC's APL*PLUS/PC for IBM
personal computers and APL.68000 for the Macintosh. It is primarily based
on my own experiences in porting several magabytes of code to APL.68000.
It includes some info copied from APL.68000 documentation, along with some
corrections and amplifications graciously provided by David Eastwood of
MicroAPL Ltd. All APL code has been transliterated using Jim Weigang's
APL2ASCII workspace.
The technique I used for the transfering the workspaces was Source Level
Transfer (SLT), using the APL.68000 STSCSLT and PLUSFNS workspaces.
Workspaces transfered using the SLT system will frequently not execute
without some modification, or in some instances, they may execute, but
produce completely bogus results. The SLT software from Micro-APL is
fairly good about flagging incompatibilities, and replaces the '#' in
front of unsupported system functions with a '{delta}'. The PLUSFNS
workspace contains '{delta}' functions to try to emmulate the APL*PLUS
system functions. Unfortunately, many are not 100% equivalent, and others
are not supported at all. In many cases, simple changes to the code can
eliminate the need for additional '{delta}' functions altogether.
The STSCSLT and PLUSFNS workspaces are issued free of charge by MicroAPL
and are unsupported code. Users of APL.68000 Level II might prefer to use
)IN and )OUT to move workspaces to and from other APL interpreters that
support the Transfer Format (currently APL2 and APL*PLUS II and III). The
slight advantage to the STSCSLT route is that warnings are generated where
APL*PLUS code might not run under APL.68000 and also functions that cannot
be fixed in APL.68000 are kept in character form in the workspace.
----------------------------------------------------------------------------
The section below is a composite of information copied out of both the
APL.68000 SLT translation workspace 'STSCSLT' and the substitute function
workspace 'PLUSFNS'. It also contains some additions and corrections of my
own. It is the most complete breakdown available of what happens to all of
the various system functions and variables during the conversion process.
The text in CAPS is copied from the APL.68000 documentation.
THE 'PLUSFNS' WORKSPACE CONTAINS APL.68000 FUNCTIONS DESIGNED TO SUBSTITUTE
FOR APL*PLUS/PC QUAD-SYSTEM FUNCTIONS AND VARIABLES WHEN PORTING APL*PLUS
APPLICATIONS TO APL.68000.
EACH QUAD-FUNCTION OR VARIABLE IS EMULATED BY AN APL.68000 {delta}-FUNCTION.
SYSTEM FUNCTIONS WHICH ARE SPECIFIC TO THE IBM PC ENVIRONMENT, OR WHICH
CANNOT BE EMULATED WITHOUT CHANGES TO THE APL.68000 INTERPRETER HAVE NOT
BEEN EMULATED, BUT APL.68000 COVER-FUNCTIONS ARE INCLUDED, WHICH PRESERVE
THE SYNTAX, BUT RETURN NONCE ERROR UPON EXECUTION.
LIST OF IMPLEMENTED QUAD-FUNCTIONS AND VARIABLES:
------------------------------------------------------------------------
1. THE FOLLOWING APL.68000 FUNCTIONS WORK EXACTLY LIKE THE APL*PLUS
#-FUCTIONS OR VARIABLES WHICH THEY REPLACE:
{delta}CRL, {delta}CRLPC, {delta}ERASE, {delta}FI, {delta}IDLIST,
{delta}INKEY, {delta}LOAD, {delta}QLOAD, {delta}SI, {delta}SS,
{delta}SYSID, {delta}TC---, {delta}VI, {delta}VR, {delta}WSID
2. THESE APL.68000 FUNCTIONS DIFFER SLIGHTLY IN ACTION FROM THE APL*PLUS
#-FUNCTIONS WHICH THEY REPLACE:
#AI - REPLACED BY {delta}AI - {delta}AI[3,4] ARE ALWAYS 0
#AV - CHARACTERS IN APL.68000 #AV ARE IN DIFFERENT LOCATIONS:
REPLACE WITH {delta}AV WHERE NECESSARY
#COPY - CANNOT RETURN ALL POSSIBLE ERROR CODES; NOT FOUND MESSAGES
APPEAR.
#CRLPC - {delta}CRLPC IS UNABLE TO SHOW COMMENTS
WITHIN LOCKED FUNCTIONS
#CRT - {delta}CRT ALWAYS RETURNS THE SAME RESULT.
#CURSOR - REPLACED BY FUNCTIONS {delta}CURSOR1 AND {delta}CURSOR2.
#DEF - HANDLES MISMATCHED QUOTES WITHOUT ERROR, BUT DOESN'T REPORT
WS FULL OR OTHER SUCH EXCEPTIONS IN THE EXPLICIT RESULT
#DEFL - SAME PROBLEMS AS #DEF
#DM - USES #ERM, BUT THIS WILL ONLY WORK IN ERROR-TRAP ENVIRONMENT
#DR - {delta}DR CODES ARE DIFFERENT: 11 FOR BOOLEAN, 323 FOR INTEGER
#F--- - SEE 'HELP' IN 'PLUSFNS' WORKSPACE FOR DESCRIPTION OF THE
FILING PRIMITIVES IMPLEMENTATION
#FMT - APL.68000 #FMT SYNTAX DIFFERS FROM THAT OF APL*PLUS:
CHANGES MAY BE NECESSARY
#LIB - {delta}LIB DISPLAYS )LIB LISTING BUT DOES NOT RETURN IT
AS AN EXPLICIT RESULT.
#LOCK - {delta}LOCK CANNOT RETURN THE CORRECT ERROR CODES
#PCOPY - CANNOT RETURN ALL POSSIBLE ERROR CODES; NOT FOUND MESSAGES
APPEAR.
#SIZE - REPLACED BY {delta}SIZE WHICH ONLY WORKS FOR VARIABLES.
#SOUND - REPLACED BY {delta}SOUND, WHICH MERELY OUTPUTS <BEL>
TO THE TERMINAL.
#SYMB - {delta}SYMB DISPLAYS THE )SYMB LISTING, BUT DOES NOT
RETURN IT AS AN EXPLICIT RESULT.
#WSLIB - {delta}WSLIB DISPLAYS THE )LIB LISTING, BUT DOES NOT
RETURN IT AS AN EXPLICIT RESULT.
#WSOWNER - {delta}WSOWNER RETURNS #AI[1].
3. THESE SYSTEM FNS AND VARS ARE THE SAME IN BOTH APL VERSIONS:
#CT, #DL, #EX, #FX, #IO, #LC, #LX, #NC, #NL, #PW, #RL, #TS, #UL, #WA
#STOP, #TRACE. (#PP DIFFERS IN MAX. PRECISION: 15 IN APL.68000, 17 IN
APL*PLUS)
4. THE FOLLOWING SYSTEM FUNCTIONS AND VARIABLES COULD NOT BE IMPLEMENTED FULLY
WITHOUT CHANGE TO THE APL.68000 INTERPRETER OR RECOURSE TO AUXILIARY
PROCESSORS:
#ALX, #CALL, #CAP, #ELX, #IDLOC, #FMT, #LIB, #SA, #SINL, #STPTR, #SYMB
#WSLIB, #WSOWNER, #WSSIZE, #WSTS, #XLOAD
5. THE FOLLOWING ARE SYSTEM-DEPENDENT FUNCTIONS, AND HAVE NOT BEEN EMULATED:
#ARBIN, #CMD, #CRT, #EDIT, #G---- (GRAPHICS), #HELP, #INBUF, #INT, #IN,
#IOSTATE, #KEYW, #LIBS, #N----- (NATIVE FILES), #OUT, #PEEK, #PFKEY,
#POKE, #SEG, #SOUND, #WGET, #WIN, #WINDOW, #WKEY, #WPUT
----------------------------------------------------------------------------
Below is list of of the incompatibilities I have encountered so far, and
suggestions about dealing with them.
NOTE: In many instances I have also included comments about how the Mainframe
APL works as well. This is partly for completeness, partly for the curious,
and partly for those who are trying to fix Mainframe code that only passed
through APL*PLUS/PC during the file transfer process. For a complete rundown
on the differences between the PC and the Mainframe, see my 'MAINFRAME TO
APL*PLUS/PC SOFTWARE CONVERSION GUIDE'.
1) GRAPHICS: Anything involving graphics is going to cause problems.
STSC's APL PLUS/PC graphics are completely incompatible with the
APL.68000 graphics on the Macintosh, which use the Apple Quickdraw
graphics subsystem via a series of APL cover functions.. The PC has
two types of graphics, VDI graphics, and '#G' graphics. The '#G'
graphics is an older, less powerful set of graphic commands that
support only a limited range of display devices. The VDI graphics is
considerably more sophisticated, and uses a standard graphics
language interface to talk to a large variety of device drivers.
2) ORDER OF EXECUTION: There are a number of functions where the order of
execution of an APL expression on the Mainframe and on the PC differed.
This does not appear to be a problem between the PC and The Mac. All
of the code I've tested from the PC works fine, and a few simple test
cases produce the same results on the Mac that they do on the PC.
3) TERMINAL CONTROL CODES: In APL*PLUS/PC, there are several ways to
generate terminal control codes. There are seperate system variables
for some, a 3 element vector, '#TC', consisting of terminal control
codes, and one can also use elements of the atomic vector #AV. The
same system variables do not exist in the Mac, but there are
equivalents, including the system variable '#C'. #C is a vector of
the 32 control characters in the order they are found in the ASCII
character set. Translation from STSC APL*PLUS control variables
to APL.68000 is as follows (#IO{is}1):
ON PC ON MAC
#TC[1] = #TCBS = #AV[9] #B = #C[9] = #AV[9] (Backspace)
#TC[2] = #TCNL = #AV[14] #R = #C[14] = #AV[14] (New Line)
#TC[3] = #TCBEL = #AV[8] #C[8] = #AV[136] (Bell)
#TCHT = #AV[10] #T = #C[10] (Horizontal Tab)
4) NEGATIVE ODD ROOTS: Evaluation of negative odd roots produces a
DOMAIN ERROR on the PC and the Mac. For example, {neg}1*{reciprocal}3
(cube root of negative one) results in an error on both the Mac and the
PC, but not on the mainframe. This is a quirk of the original Mainframe
APL, and has nothing to do with later APL2 implementation of complex
number support. This should not cause a problem with any code that
worked on the PC.
5) PROMPTS WITH QUOTE QUAD: There are significant differences between
the way the Mac, the PC and the Mainframe handle prompts with
'{quotequad}'. The Mainframe places N spaces in the result, where N is
the length of the prompt string. The Mac and APL*PLUS/PC echo the
prompt string along with the result. In APL*PLUS, the prompt string
may be eliminated using '#ARBOUT {iota}0' (see PC example below), but
APL.68000 doesn't support this. Fortunately, there is another approach
that is completely compatible across all 3 systems (see Mac example).
MAINFRAME: [0] TEST
TEST
ENTER NUMBER: 2
15 <- Length of result
2 <- String result with spaces
2 <- Numeric result from format
As written, this bombs on the PC because the
result contains the prompt string and can't be
formatted as a number.
ON PC: [0] TEST
TEST
ENTER NUMBER: 2
1 <- Length of result
2 <- String result (no prompt)
2 <- Numeric result from format
NOTE: Without '#ARBOUT {iota}0', the result 'Y' would
have been the string: 'ENTER NUMBER: 2'
ON MAC: [0] TEST
input
strip off prompt
TEST
ENTER NUMBER: 2
1 <- Length of result
2 <- String result (no prompt)
2 <- Numeric result from format
NOTE: The advantage of this approach is that it
will work on all 3 systems!
6) DYADIC FORMAT: The output of functions that make use of the dyadic
format '{format}' may have to be adjusted for the added length of the
result. Unlike the Mainframe, the Mac and the PC use 4 digits for
the exponent of floating point numbers, regardless of the value of
the exponent. This can either just make a mess out of displays that
expected a smaller result, or it can result in a DOMAIN ERROR if the
new result is too wide for the field specified. The Mac and the
Mainframe allow the field to fill the field completely, where as the
PC always leaves room for a space. For example:
ON MAINFRAME: 10 {neg}3 {format} 1E{neg}3 produces 1.00E{neg}03
10 {neg}4 {format} 1E{neg}3 produces 1.000E{neg}03
10 {neg}5 {format} 1E{neg}3 produces 1.0000E{neg}03
10 {neg}6 {format} 1E{neg}3 produces DOMAIN ERROR
ON PC: 10 {neg}3 {format} 1E{neg}3 produces 1.00E{neg}003
10 {neg}4 {format} 1E{neg}3 produces DOMAIN ERROR
ON MAC: 10 {neg}3 {format} 1E{neg}3 produces 1.00E{neg}003
10 {neg}4 {format} 1E{neg}3 produces 1.000E{neg}003
10 {neg}5 {format} 1E{neg}3 produces DOMAIN ERROR
7) FLOATING POINT NUMBERS: There are only some very minor differences
in the floating point number systems between the Mac and the PC. In
the thousands of computations done by several test workspaces,
only ONE resulted in an answer that differed from the PC, and that
was in the 15th decimal place. The PC supports two more digits of
printing precision (#PP) than both the Mac and the mainframe. Both
the Mac and the PC can deal with floating point exponents between
plus and minus 308, as compared to 'only' 99 on the mainframe.
8) INTEGER NUMBERS: David Eastwood pointed out the APL.68000 uses a four
byte representation for integers, whereas APL*PLUS uses only 2 bytes.
This never caused a problem in going from APL*PLUS to APL.68000, but
might produce problems going the other way.
9) GROUPS: APL.68000 supports groups, but APL*PLUS/PC doesn't. Groups
are used to move related collections of functions and variables
around from workspace to workspace. If you used '#COPY', '#ERASE',
and '#PCOPY' to do this on the PC using character matrices of names,
you may have to use groups on the Mac. None of these system
functions exist in APL.68000, although you can use '#EX' instead of
'#ERASE'. The good news is that there is another way of doing this
(and probably a lot more) on the Mac. APL.68000 allows the use of
some ')FN' operations inside functions using the execute '{execute}'
operator:
ON THE PC: [1] #PCOPY LIBNO WSNAME
ON THE MAC: [1] {execute}')PCOPY LIBNO WSNAME'
Users of APL.68000 Level II can use the indirect copy syntax (similar
to mainframe APL) which allows a variable to be used in the )COPY
command line.
10) #AI: The exact response of #AI (Account Information) between APL*PLUS
and APL.68000 differ in several respects. The original IBM Mainframe
APL #AI only had four elements. APL.68000 duplicates these four, and
adds three of its own. APL*PLUS/PC's #AI contains only four elements,
but they aren't quite the same as the 1st four of APL.68000. In
general, any code that worked on the Mainframe will work without
modification on the Mac. Code originating on or modified for APL*PLUS
will need some work. The differences are as follows (#IO=1):
IN APL*PLUS/PC:
#AI[1] = User Number
#AI[2] = Number of seconds since start of APL session
(with 10 millisecond resolution)
#AI[3] = Number of characters of input
#AI[4] = Number of characters of output
IN APL.68000:
#AI[1] = User Number
#AI[2] = CPU time in milliseconds
#AI[3] = Connect time in milliseconds
#AI[4] = Keyboard Unlock time in milliseconds
The most common use of #AI is in timing applications, using #AI[2].
If you need absolute time, you can always use #TS, or substitute
(#AI[3]{divide}1000) for APL*PLUS/PC's #AI[2].
Porting APL*PLUS/PC to APL.68000