WSINOUT - Workspace Transfer
Manual
Version 2.0
14 July 1997
Contents
Section 1 - Abstract
Section 2 - How to Transfer APL Objects
Section 3 - wsout - Arguments
Section 4 - wsout - Messages
Section 5 - wsout - Common Difficulties
Section 6 - wsin - Arguments
Section 7 - wsin - Messages
Section 8 - wsin - Common Difficulties
Section 9 - How are Characters Translated?
Section 10 - Handling Character Translation
Difficulties
Section 11 - How Are Name Conflicts Handled?
Section 12 - Problem Resolution
Section 13 - Supported APL Systems
Section 14 - Special Comments
Section 15 - Background
Section 16 - Contact
The WSINOUT workspaces provide a facility for transferring functions and
variables between APL systems.
WSINOUT is provided for the following systems:
WSINOUT.AWS APL-Plus PC
WSINOUT.WS APL-Plus II
WSINOUT.APL APL2
WSINOUT.DWS Dyalog APL
WSINOUT-.SAW Sharp APL
WSINOUT.ATF APL2 Transfer Format
Each workspace contains two functions: wsout and wsin. The "out"
function writes APL objects to a standard interchange file; the "in"
function reads the objects from the file. Using two workspaces, one for
each system, you have a facility for transferring APL objects between
different APL systems.
The functions, wsin and wsout, are easy to use and flexible, with
detailed reports. Reliability is paramount: arguments are thoroughly
checked, and run-time errors are caught, precisely reported, and where
possible "fix-up" action is taken.
Note these restrictions: (1) The functions transfer only the functions
and simple variables of ISO Standard APL. Nested arrays, boxed arrays,
packages, etc. are not supported. (2) "Semantic" transformations, that
is, "conversions" of APL code, are NOT done.
WSINOUT is "freeware": it may be copied and used without permission or
restriction. There is no formal software support.
Section 2. How
to Transfer APL Objects
The functions <wsout> and <wsin> are in every WSINOUT
workspace.
To transfer objects from System A to System B:
1. use wsout on System A: names wsout filename
2. use wsin on System B: wsin filename
e.g. To transfer from APL-PLUS PC to APL2:
1. Start APL-PLUS PC.
2. Load the workspace containing the objects to be transferred
)load mywork
3. Copy wsout from wsinout.aws (version for APL-PLUS PC)
)copy wsinout wsout
4. Execute wsout (writes the objects to a transfer file)
'fun1 fun2' wsout '\apldata\myfile'
5. If APL2 is on another computer, move file by diskette, modem, etc.
6. Start APL2
7. Copy wsin from wsinout.apl (version for APL2)
)copy wsinout wsin
8. Execute wsin (reads and fixes the objects from the file)
wsin '\apldata\myfile'
This procedure may be modified: <wsin> and <wsout> may be
executed at
any time. They are completely self-contained, and <wsout> makes no
changes to the workspace.
The arguments to <wsin> and <wsout> have additional
functionality. See
Section 3: wsout - Arguments, and Section 6: wsin - Arguments.
Note: A WSINOUT workspace must be installed in a directory accessible to
the corresponding APL system e.g. wsinout.aws must be accessible to APL-
PLUS PC, wsinout.apl must be accessible to APL2, etc.
Section 3. wsout
- Arguments
Syntax: x wsout y
x
- (optional)
- Character vector or matrix - Names of functions and variables
- If left out, all names (except "ws" names) are transferred.
y
- character vector specifying 2 parameters
- format: 'filename filesize'
filename
- Name of DOS file
- An existing file is deleted, then a file is created.
- If directory parth is specified, it has to exist.
filesize
- (optional)
- Integer specifying maximum transfer file size
- wsout stops before the file reaches <filesize> bytes
- If left out, file has unlimited size.
Examples:
wsout 'wsfile'
- Write all fns/vars in workspace to 'wsfile' (current directory)
'fun1 fun2 matrix2 vector3 fun4' wsout 'myfile'
- Write specified objects to 'myfile'
'fun1 fun2 matrix2 vector3 fun4' wsout '\apldata\myfile'
- Write specified objects to '\apldata\myfile'
- Directory \apldata must exist
wsout 'myfile 50000'
- Write all fns/vars to 'myfile'
- wsout will exit before file reaches 50000 bytes
Section 4. wsout
- Messages
(1) Cannot write to file
Since wsout creates a file when required, the usual problems are
invalid name, mis-spelled directory name, or non-existent
directory. Correct directory name (or write file in home
directory).
(2) Warning - Locked function
Names are noted in trace report, but functions are not
transferred.
(3) Warning - object not transferred
Non-ISO-standard objects (e.g. packages, nested arrays, boxed
arrays) are not handled. You can change data to functions or
simple arrays, then transfer. Note that quadnames (system
variables) on some APLs will not be transferred by name.
(4) Warning - name starts with <ws>
This is a warning only. See Section 11 - Name Conflicts.
Section 5: wsout
- Common Difficulties
(1) Workspace Full (or other System Limit situation):
<wsout> puts all objects in one variable before writing to file.
Usual problem is this variable gets too big.
- Use filesize parameter; this limits size of variable written to
file. (See Section 3: wsout - Arguments)
- Try a smaller name list; e.g. ('abcd' quadnl 2 3) returns matrix
of names of fns/vars starting with a, b, c, or d.
- Remove some objects from workspace.
- Execute <wsout> several times to create several smaller files.
Section 6: wsin
- Arguments
Syntax: wsin y
y
- Character vector specifying 3 parameters
- Format: 'filename reverse-case-flag underscore-replacement'
filename
- Character vector - name of transfer file
reverse-case-flag
- (optional) character
- Specifies to reverse case of letters after translation
- y = Reverse case of names and data
("data" means function text and character data)
- d = Reverse case of data only
(names are not reversed)
Useful for text variables entered with "unified" keyboard
- n = (default) do not reverse case
Needed when specifying parameter 3
underscore-replacement
- (optional) character
- Character ("delta", a-z, A-Z)
- Replaces underscore (_) in all names and function text
- If unspecified, underscore is not replaced
Examples:
wsin '\apldata\myfile'
- Read 'myfile' in directory 'apldata'
wsin '\apldata\myfile y'
- Read '\apldata\myfile'
- Reverse case of letters in names, functions, and character data
wsin '\apldata\myfile d'
- Read '\apldata\myfile'
- Reverse case of letters in functions and character data
- (Do not reverse case of object names.)
- This would be useful if the text variables were workspace
documentation written as standard text (upper and lower case).
wsin 'testfile n X'
- Read 'testfile'
- Take default for parameter 2
- Replace underscore (_) with X in names and text of functions
Section 7: wsin
- Messages
(1) Cannot read file
Usual problem - mis-spelled file name or incorrect directory.
(2) Cannot fix function
Functions typically cannot be fixed for the following reasons:
(1) System cannot define a function containing squish-quad.
(2) System cannot define a function with duplicate or non-ISO-
standard names or syntax in header line. <wsin> assigns data to
variable with original name. (The quadfx return code is the line
number where problem occurred.) Data can be edited afterwards to
resolve the difficulty.
(3) Warning - name starts with <ws>
See Section 11 - How Are Name Conflicts Handled?
(4) Warning - name is in use
An object with this name is already in the workspace. The current
object is erased and the name redefined with the new object.
Section 8. wsin
- Common Difficulties
(1) Workspace Full (when wsin begins)
wsin reads the entire file at the beginning. Translating all the
data can cause "workspace full" at this point. Try one or more of
the following:
- Increase workspace size.
- On origin APL system, run wsout several times to create several
small files.
- If origin system not available, consider splitting file using
text editor. Files are partly ascii-readable.
(2) Workspace Full (partway thru wsin)
Save ws, erase defined objects, restart <wsin> at suspended line.
(3) Unexpected or Undesirable Character Translation
For discussion on dealing with undesirable or unexpected character
translation, see Section 9 - How are Characters Translated? and
Section 10 - Handling Character Translation Difficulties.
(4) Underscore Character in Names Being Transferred to Sharp APL
Sharp APL does not allow well-formed names to contain the
underscore character. When the target system is Sharp APL,
however, the <wsin> default is to replace the underscore only when
an ill-formed name is detected. To over-ride this default, use the
<wsin> parameter, underscore-replacement. (See Section 6: wsin -
Arguments)
Section 9. How
are Characters Translated?
wsin and wsout use built-in translate tables.
(1) Translate tables
The translate tables accommodate all APL language symbols in Sharp
APL, which is a superset of the ISO APL character set.
- includes all APL ISO-standard characters
- includes backspace (BS), line feed (LF), carriage return (CR)
- includes special characters such as "epsilon underbar"
- characters not in Sharp APL (e.g. "zilde", underscore
characters) become squish-quad
(2) The Normative Case
In APL the "normative case" appears when typing the letters in the
unshifted position. This is the case usually used for variable
names, etc. The "distinguished" case is another case used for
special purposes, such as special variable names. In the past, on
the mainframe, the "normative case" was the set of "upper case"
(majuscule) letters, and the "distinguished case" was the set of
"underscored" upper case letters.
On the personal computer, APL2, APL-PLUS, and Dyalog APL often use
upper case for the normative case, and lower case for the
distinguished case. (This is the "traditional" situation.)
Conversely, Sharp APL uses lower case for the normative case, and
upper case for the distinguished case.
Normative Distinguished
Sharp APL lower upper
APL2
APL-PLUS upper lower
Dyalog APL
When transferring from one APL system to another, the <wsin>
function defaults to translating the normative alphabet (object
names AND values) of one system to the normative alphabet of the
other, using the assumptions in the table above.
To use a different translation assumption, set the wsin parameter,
reverse-case-flag, to "y" or "d". (See Section 6 - wsin -
Arguments.) You will typically need to do this if (1) APL2, APL-
PLUS, or Dyalog APL was configured to use the "unified" keyboard;
(2) only certain character data was typed using the "unified"
keyboard typically because it was documentation. The results will
be obvious if you don't choose the correct translation assumption
the first time.
Section 10.
Handling Character Translation Difficulties
Character translation difficulties are common between APL systems.
(1) Characters Not Supported By Translate Tables:
To transfer a character not supported in the target system:
(a) In the origin system replace the character by a cover name.
(b) In the target system define a function with the cover name.
To transfer a character not supported in the translate tables, but
supported in the origin and target systems:
(a) In the origin system replace the character by a cover name.
(b) In the target system replace the cover name by the character.
(a) and (b) may be simplified by using text replacement functions.
(2) Alphabet is Reverse to What You Want:
The usual reason is that the origin system did not use the
expected keyboard, e.g. the unified keyboard was used in APL2,
APL-PLUS, etc. Re-run wsin with the reverse-case-flag set to "y"
or "d". (See Section 6 - wsin - Arguments)
To help correct "reversal" problems outside the transfer process,
WSINOUT contains the following three utility functions:
(1) ncase y (translate letters to normative case in array y )
(2) rcase y (reverse case of letters in array y )
(3) rcomments y (reverse case of comments in canonical matrix y )
This is useful if comments in functions were typed using the
"unified" system.
For more details, refer to the functions.
Section 11. How
Are Name Conflicts Handled?
During the transfer process it is possible (though unlikely) that local
names in wsin or wsout will "shadow" names of user-defined objects, and
therefore the objects will not be defined correctly.
All local names in <wsin> and <wsout> begin with "ws". Objects
with
names starting with "ws" MAY therefore be the same as <wsin> or
<wsout>
internal names. What to do? For simplicity, <wsout> and <wsin> give
warning whenever ANY suspect object name (starting with "ws") is
encountered; then the function transfers the object with its current
value. This method is usually adequate; if necessary use a different
name before transferring.
No other names encounter a conflict situation.
Section 12.
Problem Resolution
If there are problems with the transfer process (e.g. unexpected
character translation, procedural difficulties, etc.), the following
"trouble-shooting" procedure may be helpful.
(1) Load WSINOUT.
(2) Display and inspect the following 2 variables:
printchars
- Character vector
- This is a list of all printable characters in Sharp APL
- (This is a superset of the ISO APL character set.)
nonprintchars
- Character vector
- Sample text containing the standard non-printing characters:
- backspace BS, line feed LF, carriage return CR
(3) Transfer these variables to the other system. Test the different
parameters. For example, consider from APLIWIN to APL-PLUS II:
- APLIWIN
'printchars nonprintchars' wsout '\apldata\testfile'
- APL-PLUS II
wsin '\apldata\testfile'
wsin '\apldata\testfile d' --- use parameter 2
(4) Display variables on APL PLUS II and compare.
(5) Transfer back to APLIWIN and compare again.
Section 13.
Supported APL Systems
There is a wsinout workspace for each supported system. See the table
below. (WSINOUT has been tested with the version level indicated.)
wsinout.dws - DYALOG APL (Version 6.3 Release 1)
wsinout.aws - APL-PLUS PC (Version 6.3)
wsinout.ws - APL-PLUS II (Version 5.1.09)
wsinout.apl - APL2/PC (Version 1.02)
wsinout-.saw - APLIWIN (Version 5.0)
- APLI386 (Version 4.0)
For convenience the package also includes the following format:
wsinout.atf - APL2 transfer format
wsinout.atf is for APL2 users (such as APL2/PC 32-bit Version), and
other systems that can access this format.
Section 14.
Special Comments
(1) The Dyalog APL version blank-fills an existing file before re-using
it. This is not a problem, but is not the preferable method. (Erasing
the file through DOS causes my system to "suspend".)
(2) The APL2 version allows transfer of system variables (quadio,
quadpw, etc.) as these are considered in class 2 (variables). This
situation is not a known problem, but transferring quadio may cause wsin
to fail.
(3) "Workspace Full" is common when transferring large numbers of
functions and variables at one time from a "large" system to one
restricted to small workspace size.
(4) "Mixed arrays" ("heterogenous arrays") are not caught. They will be
transferred incorrectly and may cause wsin or wsout to fail.
(5) "Nested arrays" and "boxed arrays" are not valid arguments for wsin
or wsout. They are not trapped, and usually cause the functions to fail.
Section 15.
Background
Version 1.0 appeared in 1993 supporting three APL systems, including
APLIWIN (Sharp APL Version 20 adapted for the PC by Iverson Software).
WSINOUT Version 2.0 supports more APL systems, and has been re-written,
enhanced, and extensively re-documented.
The main goal of WSINOUT is to provide a consistent tool for moving data
and functions between dissimilar APL systems, or from older to newer
systems. Therefore, at this time, only ISO-standard APL objects
(functions and simple variables) are supported. For transfer of APL2
objects between APL2-based systems, users can usually use vendor-
provided software, often based on ATF format (APL Transfer Format), a
format for APL workspaces developed by IBM.
The WSINOUT transfer format follows the standards and guidelines in the
APL Workspace Interchange Standard, Version 0 (WSIS0). The WSIS0
'translate' pseudo-variable is not supported.
Thanks to all who made suggestions. Special note to Eric Iverson for
advice and encouragement during the initial development.
Section 16.
Contact
The author of WSINOUT is Richard Levine. There is no formal support, but
suggestions, comments, questions, "bug" reports, etc. are welcome. Contact the
author by e-mail at rlevine@rlevine.ca