Dyalog APL Workspace Transfer Guide
Dyalog APL Workspace Transfer Guide
Dyalog APL Workspace Transfer Guide
Workspace Transfer
Version 13.2
Dyalog Limited
South Barn
Minchens Court
Minchens Lane
Bramley
Hampshire
RG26 5BH
United Kingdom
Tel: +44 (0)1256 830030
Fax: +44 (0)1256 830031
email: [email protected]
http://www.dyalog.com
Dyalog is a trademark of Dyalog Limited
Copyright 1982-2011
No part of this publication may be reproduced in any form by any means without the
prior written permission of Dyalog Limited, South Barn, Minchens Court, Minchens
Lane, Bramley, Hampshire, RG26 5BH, United Kingdom..
Dyalog Limited makes no representations or warranties with respect to the contents
hereof and specifically disclaims any implied warranties of merchantability or
fitness for any particular purpose. Dyalog Limited reserves the right to revise this
publication without notification.
TRADEMARKS:
Intel, 386 and 486 are registered trademarks of Intel Corporation.
IBM is a registered trademark of International Business Machines Corporation.
Microsoft, MS and MS-DOS are registered trademarks of Microsoft Corporation.
POSTSCRIPT is a registered trademark of Adobe Systems, Inc.
SQAPL is copyright of Insight Systems ApS.
The Dyalog APL True Type font is the copyright of Adrian Smith.
TrueType is a registered trademark of Apple Computer, Inc.
UNIX is a trademark of X/Open Ltd.
Windows, Windows NT, Visual Basic and Excel are trademarks of Microsoft Corporation.
All other trademarks and copyrights are acknowledged.
Contents
iii
Contents
Contents ......................................................................................................................... iii
Workspace Transfer........................................................................................................ 1
Introduction ...................................................................................................................... 1
General Techniques .......................................................................................................... 2
Methods used .................................................................................................................... 2
Exporting ......................................................................................................................... 5
The DWSOUT Workspace ............................................................................................... 5
Using the user command ]OUT ....................................................................................... 7
The XFRCODE workspace .............................................................................................. 8
Using the user command ]OUTX ................................................................................... 9
Importing ....................................................................................................................... 10
The DWSIN Workspace ................................................................................................. 10
The ATFIN Workspace .................................................................................................. 11
Using the user command ]IN ......................................................................................... 12
The XFRCODE workspace ............................................................................................ 14
Using the user command ]INX ...................................................................................... 15
Problems Transferring Workspaces and files ................................................................. 15
Workspace Transfer
Introduction
It is often necessary to either transfer Dyalog APL workspaces from one machine to
another, or to transfer workspaces created by another version of APL to Dyalog APL.
Since the internal structure of an APL workspace is dependent upon the architecture of
the machine on which it was created, and the version of APL that was used to create it,
it is not always possible to transfer a workspace directly. It must first be transformed
into a format that is common to both source and target environments. This can then be
transferred, and used to create a workspace on the target machine.
The following sections describe the steps that are involved in moving workspaces
between machines and different versions of any APL. APL component files are
transferred in a similar way to workspaces; each component is read into an APL
variable which is then transferred.
The subsequent sections describe specific examples of this process. The basic
technique is the same in most cases. Doubtless better techniques can be used, but the
following examples are useful as a basis from which to work.
The problems of conversion from one version of APL to Dyalog APL are not discussed
in this section. Nor are the procedures for transferring from Dyalog APL to other
APLs. However, using the techniques discussed in this section, it is a simple (if
tedious) matter to produce software that will transfer in the opposite sections.
Where possible, the tools required to transfer to Dyalog APL are supplied with the
product; where this is impractical, listings of the appropriate software is given or the
location where they can be found.
General Techniques
Create a Export File and Read it back
If we can produce a text file on the source machine that contains all of the statements
necessary to recreate the workspace, we could execute each line of this file on the
target machine using Dyalog APL, thereby recreating the workspace in the correct
format. The process of creating the file is called EXPORT and the process of reading it
is called IMPORT.
How do we transform a workspace into a text format? Functions are easy as we can
just produce a listing of them. Variables are more difficult; we must produce lines of
text that when executed, recreate the variables with the correct contents, type, shape
and depth.
Any APL programmer should be capable of writing the simple APL system required to
perform both of these tasks; however, Dyalog provides methods to do this on the
Dyalog side.
Methods used
Dyalog provides methods to export a workspace by creating a file from looking at it
and other methods to import a workspace from reading the same kind of file. There are
several ways to do this. One of these methods is built on an 80 column punched card
format that APL2 came up with in the 1980s. Because one of the designs created a file
with an ATF extension (for APL Transfer File) this format is sometimes known as the
ATF format. There are in fact at least 2 variants to this format and one of them comes
in a flavour that uses a DXF extension instead of ATF.
Technicalities
Dyalog supplies 2 workspaces to deal with the DXF files (1 in and 1 out), 1 to deal
with the ATF files (in only) and 1 workspace to deal with the extended format.
It also supplies 2 sets of user commands (both in and out) for the DXF/ATF files and
the extended format.
All will be discussed here.
Exporting
There are essentially two ways to export code: using a workspace or using a user
command. The user commands are basically a cover for the workspaces. In each case
there are also two alternatives: one dealing with older (pre-namespaces) version of
Dyalog APL and one dealing with newer version. All four are described here.
Other APL vendors have different methods of exporting workspaces. Some vendors of
APL provide a workspace named DWSOUT or a system function to do the work or, as
in APL+s case, a user command.
Exporting a Workspace
The function DWSOUT is used to transfer entire workspaces, or named objects
from a workspace. The full syntax of the function call is:
{names} DWSOUT wsname
wsname is a simple character vector containing the name under which the workspace
is to be )SAVEd on the target system. names, if present, is a character matrix
containing the names of the objects to be transferred. The default is the entire
workspace.
A file called wsname, followed b .DXF1 is created, and listings of the requested
objects, system variables and constants, and some control statements are appended to
the file.
Restrictions
The following restrictions apply to all versions of DWSOUT:
The state indicator must be empty.
The names of objects to be transferred may not begin with .
Locked functions cannot be transferred.
Class 9 objects like Namespaces are not transferred
[]NULLS and composed functions will not be transferred
Characters not in []AV cannot be dealt with
Example
Create a text file called NEWWS.DXF containing a complete representation of a
workspace called MYWS.
)LOAD MYWS
saved ...
)FNS
FOO GOO HOO
A B C
)VARS
)COPY DWSOUT
saved ...
DWSOUT 'NEWWS'
Functions ...
FOO, GOO, HOO,
Variables ...
A, B, C,
System Variables ...
Finished
Example
Create a text file called PJB.DXF containing a complete listing of a component file
called PJB.
)LOAD DWSOUT
saved ...
DCFOUT 'PJB'
Components ...
1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Finished
filename obj=a,b,c
Exporting a Workspace
Under Dyalog APL the function to call is
xfr.xfrto3 '\tohost\filename
[switches]'
The argument is a string specifying the name of the file to produce followed optionally
by some switches:
-q
-obj=
Example:
)xload YOURWS
)copy XFRCODE
xfr.xfrto '\tmp\dbutil'
* XFR version 3.08
17 objects transferred
Under other APLs the workspace name is XFRPC and the function xfrto resides in
the workspace as there are no namespaces in those APLs. The syntax is the same but
the switches start with a / instead of a and the filename extension varies from one
APL to another. See HTTP://www.milinta.com/xfrpc.htm for details.
transfer components n1 to n2
file lock to use for reading the file, if any
Example:
)copy XFRCODE
xfr.xfrto '\tohost\DOSfilename file=MyFile'
\path\to\file
[switches]
If the export is done for a workspace the filenames extension will be xdw. If it is done
for a file the extension will be xdf.
Example:
Export objects A, BC and Def in the current workspace to file \tmp\myws.xdw:
]outx
\tmp\myws
-obj=A BC Def
The command is smart enough to export :included namespaces and :Based classes first
in order to be able to recreate them properly when reading back the file.
If you use obj to specify the objects to export make sure you list all the objects
needed in the proper order otherwise recreating them may not be possible.
Example:
Export quietly cpts 10 to 20 of APL file MyFile to native file \temp\MF.xdf :
]outx
\temp\MF
-q
-range=10 20
-file=MyFile
10
Importing
There are essentially two ways to import code: using a workspace or using a user
command. The user commands are basically a cover for the workspaces. In each case
there are also two alternatives: one dealing with older (pre-namespaces) version of
Dyalog APL and one dealing with newer version. All four are described here.
Importing a Workspace
DWSIN contains function DWSIN that can process files produced by the
DWSOUT workspaces of different APLs.
DWSIN is used to read the files produced by DWSOUT and DCFOUT. The
file is read to recreate the workspace or component file. The full syntax of the function
call is:
{source} DWSIN filename
filename is a simple character vector containing the name of the file to be
processed. This file must have been produced by a previous call of DWSOUT. Note
that the suffix ".DXF" is appended to the given filename so you should rename
your file if the extension is different.
source, if present, is a simple text vector containing the name of the source APL,
taken from the set 'DYALOG', 'APLPLUS', 'STSCMF' or 'VSAPL'. If source
is omitted, the default is 'DYALOG'.
DWSIN reads the file, applying the relevant translation from the source APL to
Dyalog APL, to recreate the objects.
If an object cannot be recreated because of badly formed lines in the file, then that
object is ignored and a warning message printed. The names of such objects are held in
a variable WontFix.
Example
Create a Dyalog APL workspace from the file NEWWS.DXF, which was created by
Dyalog APL possibly on another machine.
)LOAD DWSIN
saved ...
DWSIN 'NEWWS'
Processing script ...
Functions & Operators ...
FOO, GOO, HOO,
Variables ...
System variables ...
*****************************
**** Workspace name is NEWWS
**** REMEMBER TO )SAVE IT !!!
*****************************
Example
Create a Dyalog APL component file from the file PJB.DXF, which was created by
APL*PLUS/PC.
)LOAD DWSIN
saved ...
'APLPLUS' DWSIN 'PJB'
Processing script ...
1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Finished.
Importing a Workspace
ATFIN contains function atfin that can process files produced by different APLs.
The full syntax of the function call is:
11
12
atfin filename
filename is a simple character vector containing the name of the file to be
processed. Note that the extension ATF must be appended to the given file name as it is
not automatically supplied.
atfin reads the file, applying the relevant translation from the source APL to
Dyalog APL, to recreate the objects.
If an object cannot be recreated because of badly formed lines in the file, then that
object is ignored and a warning message printed. The names of such objects are held in
variable _problems.
Example
Create a Dyalog APL workspace from the file \tmp\dbutil, which was created by
APL+
)LOAD ATFIN
saved ...
atfin '\tmp\dbutil.atf
...Processing script
Variable : a
Fn/Op
: cut
Cannot form variable PR
Variable : LX
... Finished
To remove APL2IN and associated objects, execute the
following line
EX _names
quadthings
to see the systems variables reset
_problems contains unfixed objects
At this point you should save your workspace if satisfied.
filename fliplu
-apl=
13
You can specify which APL version the file came from. There are 8 acceptable cases:
APL2PC, APLX, APLC, APL2MF, DYALOG, APLPLUS, VSAPL and STSCMF. If
you do not specify which APL vendor this file came from the command will try to
guess and will be right most of the time but there is no guarantee this will work.
Because some APL vendors use a different convention for upper and lower case
alphabets you might have to use the fliblu switch to reverse the cases. This is often
the case for APLX and APL+ for example.
Example
Import a workspace from the file \tmp\dbutil.atf, which was created by APL+.
)CLEAR
]IN \tmp\dbutil
...Processing script
Variable :
Fn/Op
:
Variable : PP
Variable : IO
Variable : CT
...
Cannot form variable PR
Variable : LX
... Finished
)save \tmp\dbutil.atf
*** PROBLEMS contains unfixed objects
Because APL+ uses a different convention for upper and lowercase the variable names
are mangled (APL+ does not have variable names like ). If you see this happen use
the fliplu switch to solve it.
Example
Import a workspace from the file \tmp\abc.def, which was created by APLX. Flip
the lower/upper alphabet cases.
)CLEAR
]IN \tmp\abc.def -fliplu
...Processing script
Variable : bar
Fn/Op
: foo
Fn/Op
: xyz
Variable : PP
Variable : IO
Variable : CT
Variable : LX
... Finished
)save \mypath\abc.def
-apl=APLX
14
[switches]'
The switches are (these do not apply when importing a NARS2000 workspace):
-q
-apl=
Example
Import a workspace from the file \tmp\dbutil.xsw, which was created by APL+.
)load xfrcode
Saved
xfr.xfrfrom'\tmp\util.xsw'
* XFR version 3.43
A2K3.08 20090824 224036; WS=C:\APLWIN50\XUTIL
* "#.lx:C" not redefined
* "#.pw:N" not redefined
* "#.io:N" not redefined
* "#.ct:N" not redefined
13 objects defined
filename
[switches]
It accepts the same switches as xfr.xfrfrom and performs the same function.
Example
Import a workspace from the file \tmp\dbutil.xuw, which was created by Sharp
APL under Unix:
)CLEAR
]inx \tmp\dbutil.xuw -replace
* XFR version 3.43
SAX3.08 20090714 123016; WS=/home/db/dbutil
17 objects defined
INX will also import NARS2000 workspaces if the file name ends with .nars but in
that case none of the switches apply.
however there is no guarantee the code will run as the new version may contain features that do not
exist in the older one
15
16
17
Example
a)
On APL2/PC:
)LOAD MYWS
saved ...
)OUT c:\tmp\apl2.atf
c:\tmp\apl2.atf
18
)SAVE newname
NOTES:
1.
APL2 may allow to use ANY filename with )OUT. Depending on the APL2 system you use
(mainframe or PC) you may have to use quotes around the name and/or to specify the
extension. ]IN supposes the file has an ATF extension. To avoid ambiguities you should
always specify the full pathname.
Example
a)
In APLX:
)LOAD MYWS
saved ...
)OUT myaplxfile.atf
19
)SAVE newname
NOTES:
1. APLX allows to use ANY filename with )OUT. ]IN supposes the file has an ATF extension. To
avoid ambiguities you should always specify the full pathname
2.
APLX alphabet mapping is the reverse of Dyalog. You may have to use the fliplu switch to
flip the alphabet casing if unusual names are being defined instead of proper names.
Example
a)
In APL+:
)LOAD MYWS
saved ...
]OUT myapl+file.atf
20
NOTES:
1.
APL+ allows to use ANY filename with )OUT. ]IN supposes the file has an ATF
extension. To avoid ambiguities you should always specify the full pathname
2.
APL+ alphabet mapping is the reverse of Dyalog. You may have to use the fliplu switch
to flip the alphabet casing if unusual names are being defined instead of proper names.