Transfer functions documentation

Cross APL Transfer functions

Introduction

The transfer functions in workspace 'xfrpc' allow transferring objects, workspaces and files between major APLs. The following text applies to version 3.0 rolled out April 2003.

This can come in handy when porting code from one APL to another or to go back to a previous version of the same APL.

Conventions

In the following text, italicized words have a special meaning. The character '^' represents the APL character delta, '%' represents the APL character delta underscored, the sequence '[]' represents the APL character quad and examples of lines of code are written in evenly spaced font like "Courier New".

Some acronyms are used: SAPL is SHARP APL, SAM is SAPL on the mainframe, SAX is SAPL under UNIX.

History

The code was originally written in 1984 to port functions and variables between APL PLUS/PC and SHARP APL when workspaces were of very small size and only simple types were available. It has then evolved and been rewritten to support some of the more popular APLs with their newer data types.

Syntax

They use a common syntax consisting of a list of arguments followed by some switches. The arguments are separated by spaces and the switches start with a forward slash (‘/’) as in

[arg0] Function 'arg1 arg2 /switchA /switchB'

The use of the switches is strict. Some switches take a value, some may and some don't. The order in which they are specified is unimportant. Only the minimum number of letters needed to describe uniquely a switch can be used.

For example, if both '/replace' and '/range' are possible switches, then '/re' is sufficient to mean '/replace'. '/r' isn't as it could also mean '/range'. If there is any conflict of any sort the parser will signal an error.

Method

The method used consists of writing out to a native file, without ANY translation, a representation of variables and functions in ravel order.

The variables' information includes total length of the representation, class, name length, name, rank, shapes and data. Functions and operators are first put in canonical representation then written to file in the same format as a variable.

Classes

At present the transfer functions will accept variables of type strictly character (C), strictly numeric (N), both or mixed (M), any element enclosed (E), undefined ('?'), packages, namespaces or overlays (P), operators, functions and dynamic functions (F).

[]AV mapping

Upon reading back the native file the stream is first translated to account for the source APL's []AV positions. Characters that do not exist in one APL have been attributed another character in all other APL in order for the mapping to work. Some of these attributions are arbitrary.

Code translation

As functions are read back some code modifications can be performed, if this was specified on the command line, and an attempt is made at redefining it. If this fails the function's definition is stored in a variable of the same name as the desired function, preceded by a ‘delta underscored’ (%). For example, a failure to produce function <FOO> would produce variable '%FOO' which can be inspected later.

Usage

There are basically two functions to perform the transfer, one to write out the objects to file and one to read them back. They both will write and read a subset of a file or workspace.

These functions exist for the following APLs:

[nl] ^xfrto 'target'

This function takes a string argument describing the name of native file to write to, including any path where access is granted to write, and some switches to modify its behavior. These switches are

/file

the source will be an APL file of the same name as the native file

/file=xy

/lock=

the source will be an APL file named <xy>

the file lock to use, if any

/range=n

the APL file component to transfer is 'n'

/range=n1,n2

the APL file components to transfer range from 'n1' to 'n2'

/q

quiet, do not display version number message

If /file is not specified the contents of the current workspace is used. If the left argument describing the names to transfer is not specified (for workspaces only) then all objects in the workspace, including []io, []ct, []lx and []pw, are used. This namelist can be specified as a space-delimited string or as a table (matrix) of names.

The function will always try to write the access matrix of a file.

The function will return a string indicating the number of objects put on file.

^xfrfrom 'source'

This function takes a string argument describing the name of native file to read from, including any path where access is granted to read, and some switches to modify its behavior. These switches are

/apl=

the source APL. Valid values are SAM, SAX, DYW (Dyalog APL), APX (AplX) and A2K (APL2000 family). If not specified, the file extension is used to determine the source (see Technicalities, below). Case insensitive.

/list

show what would be changed only. Do not make any changes.

/objs=

for workspaces only: the object classes to define. The value can be any of 'pmencfo' (Packages, Mixed, Enclosed, Numeric, Character, Function and Operator). Case insensitive.

/file

the target will be an APL file of the same name as the native file (without the extension)

/file=xzy

the target will be an APL file named <xyz>

/noam

the access matrix is NOT to be transferred

/range=n

the APL file component to transfer is 'n'

/range=n1,n2

the APL file components to transfer range from 'n1' to 'n2'

/replace

objects (variables or components) will be replaced if they already exist.

/trans

same as /trans=1

/trans=X

perform code translation. X=0 means do NOT translate. This is the same as not using the /trans switch. X=1 means perform translation and X=2 means perform translation, produce a '^AV' variable containing the source []AV and replace all occurrences of []AV by ^AV.

/q

quiet, do not display version number message

The function will return how many objects were defined.

NOTE: if a file containing a workspace was used (extension ends with 'w') then all the transfer code will be expunged automatically at the end of the function call to create a 'clean' workspace (except for SAM, see below) unless '/list' was specified in the argument or no objects were defined.

Examples

Export 3 objects under any APL:

'abc def zzzzz' ^xfrto 'my3objs'

Move an entire workspace under Windows (or DOS):

^xfrto 'c:\apl\temp\myws'

Transfer quietly components 12 to 99 of file <myfile> to (DOS) diskette using lock 314159:

^xfrto 'a:exportfile /q /range=12,99 /f=myfile /lock=314159'

Read back 3 objects produced under SAX and erase the transfer code:

^xfrfrom '\usr\home\danb\my3objs.xuw (note backward slash same as Windows/DOS)'

List what would defined if we were to replace:

^xfrfrom 'my3objs.xuw /rep /l'

Read back all functions in <myws> produced under APL+Win and erase the transfer code:

^xfrfrom 'c:\apl\temp\myws.xsw /obj=fns /rep'

Read back components 50 to 150 in backup.xmf (SAM) into APL file <dir>. Apply special translation 2. Do not bring back the access matrix. Do not show the version number:

^xfrfrom 'e:\danb\backup.xmf/ra=50 150/f=dir/tr=2/n/re/q'

 

Other functions

^all

returns a list of names excluding the transfer group's names but including some system variables like []lx

^forme

takes an object name and produces a representation for it

^create

takes a representation and produces an object from it

^xfr

calls ^forme for each of the names given as argument and returns them all together

Restrictions and notes

Locked functions cannot be transferred. They go out as {locked del}.

Dyalog APL’s dynamic fns, inline functions (ex: sum {is} +/) and []or of fns will be recreated but function reassignment (fn1 {is} fn2) will not. []OR of windows objects are written out as variables containing the string ‘GUI object’. They will create problems in any APL.

System variables in namespaces are NOT written out.

All the code specific to an interpreter cannot be automatically translated (ex: Windows' calls).

System variables will crash (often with a syntax error) the redefining code if they are not supported in the target environment.

Under SAM (SHARP APL for the mainframe) the automatic expunge of the translation code will miss the <^xfrfrom> function because '[]ex' doesn’t work on fns on the stack in that APL. A message reminding you of this fact appears after the function call.

Some representations cannot be honored. For example, in SHARP APL a variable containing an enclosed simple scalar like <42 will end up as the scalar 42 under any APL using strand notation (like APL+Win). Also, the vector (9 'dsa') under APL+Win will end up as (<9),<'dsa' under SAM. Complex numbers will also crash the code in non SAM.

This version does not make any difference between a function and an operator. Both are classified as 'F'.

This version does not allow to specify a path in Unix with '/' as it conflicts with the switches' leading '/'. Instead you must use '\' as in DOS/Windows.

This version uses []CR to represent functions. This usually means more space is required but it is supported by all APLs

Technicalities

To minimize name clashing all functions start with a delta. Where relevant, the source code has been modified to remove labels and change locals to follow a naming convention. The resulting generated code is quite unreadable at this point.

The code has been tested under all supported APLs (SAM, SAX, Dyalog APL, AplX and APL+Win) using code coverage where possible and a suite of tests to validate the above claims.

Under SHARP APL for the mainframe (SAM) two options for transferring the code out exist: write the code to a PC if a proper terminal emulator or session manager allows it (like PC328 or RC108) or use TSIO to produce a file on the mainframe which can then copied elsewhere. All workspaces contain code to write character strings out of APL.

The name of the native file produced will have a 3-letter extension describing its contents:

.xuw       is a file containing a Unix (SAX) Workspace

.xmw      is a file containing a Mainframe (SAM) Workspace

.xdw       is a file containing a Dyalog APL Workspace

.xsw       is a file containing a APL+Win Workspace (former STSC)

.xpw      is a file containing a AplX Workspace

.xuf        is a file containing a Unix (SAX) File

.xmf       is a file containing a Mainframe (SAM) File

.xdf        is a file containing a Dyalog APL File

.xsf         is a file containing a APL+Win File (former STSC)

.xpf        is a file containing a AplX APL File

This extension is used to determine the source APL and the translation to apply. If this extension is wrong or non-existent you can specify the source APL with the /apl= switch.

NOTE: there is little checking done throughout the code. If wrong arguments are provided (for ex: bad object name or file) the code will fail ungracefully.

Code Translation

The code translation method consists in listing expressions to be replaced by another. There is a variable in the workspace, '^equivalence', which describes what these expressions are. Its format is a series of sections of this format:

:APLCODE

text1%replace1

test2%replace2

etc.

The first line describes the APL (SAM, SAX, DYW or A2K) it applies to. The other lines are one-to-one non-overlapping replacements. For example, '[]DEF', under APL+Win would become '3 []fd' under SAPL (SAM or SAX). This variable can be edited to suit better your needs. Sometimes the translation produces a statement that will interpret properly but cause problems further down the code. For example, APL+Win's '[]elx' will be translated into SAPL's '[]trap'. This will allow functions to be fixed if it appears in the header but won't make error trapping work later in the code.

Disclaimer

Although this code has been widely used and a lot of testing done on it there is no warranty of any sort that it will perform as described. Read this for details.