Porting APL*PLUS/PC to APL.68000 
Author Message
 Porting APL*PLUS/PC to APL.68000

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



Wed, 09 Apr 1997 02:12:28 GMT  
 
 [ 1 post ] 

 Relevant Pages 

1. Porting Mainframe APL to APL*PLUS/PC

2. I-APL, Vanguard APL, and APL.68000

3. APL for 68000; MAC APL

4. Converting Dyalog APL Multiple Assignments to APL*PLUS

5. Translating COMPLEX.AWS from STSC APL-PLUS to generic APL

6. Dyalog APL vs APL*PLUS UNX

7. XP and APL font for APL-PLUS II?

8. Paradox and APL*PLUS II (Or APL+WIN) and Memo Fields

9. US-SFL APL/2, APL*Plus Analyst/Developer

10. US-SFL APL/2, APL Plus Analyst/Developer

11. APL*PLUS III vs Dyalog APL/W

12. VS APL and APL*PLUS III

 

 
Powered by phpBB® Forum Software