Trailing-Edge
-
PDP-10 Archives
-
aplsfv2
-
aplcnv.doc
There are 2 other files named aplcnv.doc in the archive. Click here to see a list.
APLCNV.DOC -- V1(3)
September 1979
COPYRIGHT (C) 1979 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
TRANSFERRED.
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.
APLCNV.DOC Page 2
APLCNV.DOC -- V1(3)
September 1979
1.0 SUMMARY
The APL Workspace Interchange Standard (WSIS) is a source-level
interchange format for APL workspaces, agreed to by implementors of
APL and documented in the article "Workspace Interchange Convention",
APL Quote-Quad, volume 9 number 3 of March, 1979.
This convention defines a tape interface that enables transfer of
workspaces between vendors regardless of their internal APL formats or
size and content of their .BXAV's. The contents of the workspace is
encoded using .BXCR for functions and an equivalent for variables. A
tape (whose characteristics are agreed to by both the sender and the
receiver) is written beginning with a "standard" representation of the
sender's .BXAV, followed by the workspaces in the sender's .BXAV
codes. Other components of a workspace, such as groups, the SI stack
or APLSF files, are NOT transferable with WSIS. Certain system
variables ARE transferred by DEC's implementation of WSIS.
The DEC implementation of WSIS consists of two APL workspaces and a
MACRO program: workspace WSOUT is used to create disk files of all
workspaces to be transferred; program APLTAP on the -20 and TENTAP on
the -10 output these disk files to a mag tape in the "standard" format
to be read by the receiver and can read a sender's "standard" format
tape; workspace WSIN reads a disk file created from the sender's tape
and produces workspaces useable by APLSF.
Because of the use of the APLSF file system, the Workspace Interchange
Standard is only available from APLSF on the DECsystem-10 or the
DECSYSTEM-20, but not from APL-BASIC (-10 nor -20).
Version 1 of WSIS runs under version 2 of APLSF under release 6.03A or
later of the TOPS-10 monitor and 3A or later of the TOPS-20 monitor.
2.0 OPERATING INSTRUCTIONS
1. When generating a tape in the WSIS format from a set of
workspaces, the first step is to create a disk file for each
workspace to be converted. The .ZQ.ZQWSOUT function in the
workspace WSOUT does this. The following sequence of
commands implements this step:
run APLSF
TERMINAL..TTY
)LOAD <workspace1>
)COPY WSOUT
APLCNV.DOC Page 3
.ZQ.ZQWSOUT '<filename1>'
)LOAD <workspace2>
)COPY WSOUT
.ZQ.ZQWSOUT '<filename2>'
.
.
.
In the above example, "<workspace1>" is the name of the
workspace to be transferred; "<filename1>" is the name of
the disk file to be created. The default extension for
"<filename>" is ".ABI". This procedure is done for each
workspace to be written on the tape.
WSOUT does not copy any variables or functions whose names
begin with .ZQ.ZQ since those names are used internally by
WSOUT.
2. The next step is to write the disk files onto a tape in the
WSIS format.
The characteristics of the magnetic tape, such as density,
parity, record length, format, presence of labels and label
type, are outside WSIS. These tape parameters must be agreed
to by both the sender and the receiver in order for
successful transfer to occur.
1. The procedure to write the tape under TOPS-20 is:
@RUN APLTAP
APLTAP!? one of the following:
EXIT INITIALIZE READ TERMINATE WRITE
APLTAP!INITIALIZE (TAPE) <tape>:
APLTAP!WRITE (FILE) <filename1>
APLTAP!WRITE (FILE) <filename2>
.
.
.
APLTAP!TERMINATE (WRITING ON THE TAPE)
APLTAP!EXIT (TO MONITOR)
@
APLTAP uses the COMND JSYS on the -20 so <ESC> ($)
recognition and completion and ? (HELP) are available.
2. The TOPS-10 procedure is:
.RUN TENTAP
APLTAP!?
ONE OF THE FOLLOWING
R READ A TAPE
I INITIALIZE A TAPE FOR WRITING
W WRITE A WORKSPACE DUMP ONTO TAPE
T TERMINATE WRITING A TAPE
E EXIT
APLCNV.DOC Page 4
APLTAP!INITALIZE (TAPE) <tape>:
APLTAP!WRITE (WORKSPACE DUMP) <filename1>
APLTAP!WRITE (WORKSPACE DUMP) <filename2>
.
.
.
APLTAP!TERMINATE THE TAPE
APLTAP!EXIT (TO MONITOR)
.
TENTAP accepts single letter commands and then prompts
for the rest of the command line automatically.
"<tape>:" is a magnetic tape device, loaded with a
write-enabled tape. "<filename1>", "<filename2>", etc. are
the disk files produced by .ZQ.ZQWSOUT.
The tape is unlabelled with one file. The tape is written
with a fixed blocksize of 1892 8-bit bytes. The last block
is padded with spaces. If several workspaces are dumped to
the same tape, the "WSIS" and "TRANSLATE" pseudo-variables
are not rewritten and an "END" pseudo-variable is only
written after the last workspace.
3. To transfer a tape written in WSIS format, the first step is
to convert the tape into a disk file.
1. The TOPS-20 procedure is:
@RUN APLTAP
APLTAP!READ (FROM TAPE) <tape>: (COMMANDFILE) <cmdfile>
APLTAP!EXIT (TO MONITOR)
@
2. The TOPS-10 procedure is:
.RUN TENTAP
APLTAP!READ FROM (TAPE) <tape>: <crlf>
WRITING (COMMANDFILE) <cmdfile>
APLTAP!EXIT (TO MONITOR)
.
Note that a carriage return-linefeed is necessary after
specifying "<tape>:" in the R (read) command. TENTAP
will then prompt for the "<cmdfile>".
This procedure creates a disk file named "Wnnn.ABI" where
"nnn" is a 3-digit decimal number (starting from "000")
making the filename unique. This name is embedded into the
command file created for the next step.
The <cmdfile> will be overwritten if it exists.
APLCNV.DOC Page 5
A tape block may not exceed 4096 8-bit bytes in length. The
tape may not be a multi-reel volume. If the tape is a
multi-file volume, each file is treated as an independent
file that must be in the WSIS format.
4. The next step is to convert the disk file to workspaces. The
command file generated by APLTAP or TENTAP contains all APL
commands necessary. NOte that APLTAP and TENTAP assume that
WSIN is on SYS:.
run APLSF
TERMINAL..TTY
)INPUT <cmdfile>
This procedure creates workspaces with the name from the WSIS
tape and an extension of ".APL" in your connected directory
on the -20 and in your default path on the -10. If a file by
that name already exists, WSIN creates an extension of ".Wnn"
where "nn" is a 2-digit decimal number (starting with "00")
making the filename unique.
WSIN lists the function and variable names on the terminal as
it transfers them from the input file to the workspace. If
you invoke WSIN using the above ")INPUT" command, each
function name will be listed twice, once by WSIN and once by
the .BXFX function that WSIN executes. This is a "feature"
of APLSF: when a function is defined from a )INPUT stream,
either through the .DL syntax or .BXFX, the function name is
listed on the terminal.
3.0 ERROR MESSAGES FROM THE WSIS SOFTWARE
1. The WSOUT workspace will output the following messages:
1. UNABLE TO ASSIGN THE OUTPUT FILE
WSOUT uses channel 1 for the output file.
2. APLTAP and TENTAP output the following messages:
1. YOU ARE IN THE PROCESS OF WRITING A TAPE. TERMINATE TO
CLOSE.
A second "I" command was typed before a "T" to terminate
the first "I".
2. INITIALIZE THE TAPE FIRST.
"W" was typed before an "I" command.
APLCNV.DOC Page 6
3. YOU HAVE NOT INITIALIZED A TAPE.
"T" was typed before an "I" command.
4. COMMAND ERROR
APLTAP outputs this message when the command is illegal
or an input file does not exist.
5. ILLEGAL COMMAND CODE
TENTAP outputs this message when the command is illeagl.
6. JSYS ERROR: PA2040 DETECTED..ERROR NUMBER IS: n
TENTAP outputs this message when
1. (n=-1) input file not found
2. (n=600060) unexpected character in input, eg $ (ESC)
or extraneous spaces.
3. WSIN generates the following messages:
1. TRANSLATE TABLE NOT FOUND OR IN WRONG FORMAT
2. INPUT FILE file NOT FOUND
3. FILE IN INCORRECT FORMAT
4. UNKNOWN PSEUDOVARIABLE name IGNORED
RANK: r SHAPE: s
VALUE: v
5. UNEXPECTED END OF FILE
6. WS FULL. YOU MUST START OVER.
7. UNEXPECTED ERROR NUMBER n
4.0 SAMPLE SESSION
Lower case text in the following sample session note important points.
@APLSF
TERMINAL..TTY
APL-20 DECSYSTEM-20 APLSF 1B(301)
TTY217) 12:58:37 WEDNESDAY 11-APR-79 ANKER [4,33]
CLEAR WS
APLCNV.DOC Page 7
)LOAD TEST
SAVED 9:55:52 14-NOV-78 7P
)COPY SYS:WSOUT
SAVED 8:06:54 7-JUL-78 9P
.ZQ.ZQWSOUT 'TEST' create test.abi
DONE
)LOAD TEST1
SAVED 9:55:45 14-NOV-78 7P
)COPY SYS:WSOUT
SAVED 8:06:54 7-JUL-78 9P
.ZQ.ZQWSOUT 'TEST1'
DONE
)OFF HOLD
TTY217) 12:58:51 11-APR-79
CONNECTED 0:00:14 CPU TIME 0:00:02
476 STATEMENTS 1830 OPERATIONS
EXIT
@
@RUN APLTAP
APLTAP!INITIALIZE (TAPE) MTA1:
APLTAP!WRITE (FILE) TEST.ABI
APLTAP!WRITE (FILE) TEST1.ABI
APLTAP!TERMINATE (WRITING ON THE TAPE)
APLTAP!EXIT (TO MONITOR)
@
@RUN APLTAP
APLTAP!READ (FROM TAPE) MTA1: (COMMANDFILE) CONV.AAS
APLTAP!EXIT (TO MONITOR)
@
@APLSF
TERMINAL..TTY
APL-20 DECSYSTEM-20 APLSF 1B(301)
TTY217) 12:59:03 WEDNESDAY 11-APR-79 ANKER [4,33]
CLEAR WS
)INPUT CONV
CLEAR WS
SAVED 10:33:36 14-NOV-78 8P
READING FROM W000 disk file created by APLTAP
OLD WSID WAS TEST
NEW WSID IS TEST new ws to be produced
FN function names
FN appear twice if )INPUT
FN1
FN1
.BXCT system variables transferred
.BXIO
.BXPP
.BXPW
.BXRL
.BXSF
.BXAUS
.BXLX
BATM ws variables
BEMPTY
APLCNV.DOC Page 8
BMAT
BVEC
CATM
CEMPTY
CMAT
CVEC
IATM
IEMPTY
IMAT
IVEC
RATM
REMPTY
RMAT
RVEC
WORKSPACE TEST SAVED first workspace completed
OLD WSID WAS TEST1
NEW WSID IS TEST1
.BXCT
.BXIO
.BXPP
.BXPW
.BXRL
.BXSF
.BXAUS
.BXLX
FN
FN
FN1
FN1
BATM
BEMPTY
BMAT
BVEC
CATM
CEMPTY
CMAT
CVEC
IATM
IEMPTY
IMAT
IVEC
RATM
REMPTY
RMAT
RVEC
WORKSPACE TEST1 SAVED second workspace transferred
DONE WITH INPUT FILE W000 done with file from APLTAP
12:59:21 11-APR-79
WORKSPACE TEST SAVED ws resaved to remove WSIN
12:59:22 11-APR-79 3 PGS TEST <007> [4,33]
WORKSPACE TEST1 SAVED
12:59:23 11-APR-79 3 PGS TEST1 <007> [4,33]
12:59:24 11-APR-79
APLCNV.DOC Page 9
)OFF HOLD conversion complete
TTY217) 12:59:26 11-APR-79
CONNECTED 0:00:23 CPU TIME 0:00:06
1531 STATEMENTS 6157 OPERATIONS
EXIT
@
@TYPE CONV.AAS
)CLEAR
)COPY SYS:WSIN APLTAP thinks WSIN is on SYS:
.ZQ.ZQWSIN 'W000'
'CONVERSION COMPLETED'
@
[End of APLCNV.RND]