IBM 3270 PERSONAL COMPUTER ATTACHMENT ENHANCEMENTS
__________________________________________________
IBM 3270 PERSONAL COMPUTER ATTACHMENT ENHANCEMENTS

This README file may be printed with the PC command "copy readme
lpt1:".  It provides additional information on IBM 3270 Personal
Computer Attachment sample programs. The files are:


On the ENHANCEMENTS diskette
____________________________
On the ENHANCEMENTS diskette

DT3270B.BIN, DT3270B.OBJ: BASIC interfaces to the API.  See Appendix B
DT3270B.BIN, DT3270B.OBJ:
of the User's Guide for the description.

DT3270P.OBJ: a PASCAL interface to the API.  See Appendix C of the
DT3270P.OBJ:
User's Guide for a description.

XLATAPL.COM: keyboard translation support for PC/APL using the IBM
XLATAPL.COM:
3278/3279 EBCDIC Typewriter/APL keyboard.  If you have a different
keyboard, use the CONVERT option of the XLATKBD.EXE program to support
your keyboard.  See page 1.

VMOUT.APL, TSOOUT.APL: VSAPL support for PC/APL workspaces.  See page
VMOUT.APL, TSOOUT.APL:
1.

XLATKBD.EXE: a program to change keyboard translations.  See page 8.
XLATKBD.EXE:


On the CUSTOMIZATION diskette
_____________________________
On the CUSTOMIZATION diskette

SEND.COM, RECEIVE.COM: file transfer programs you may use if VM/CMS
SEND.COM, RECEIVE.COM:
file transfer program 5664-281 or TSO file transfer program 5665-311 is
installed on your host.  See chapter 13 of the IBM 3270 Personal
Computer Control Program User's Guide (1837434).



APL Support
___________
APL Support

The IBM 3270 Personal Computer Attachment provides support for file
transfers between a host (CMS or TSO) and an IBM Personal Computer.
This permits the exchange of APL workspaces between PC/APL and VSAPL
(an APL program product for CMS and TSO).

The IBM 3270 Personal Computer Attachment also provides support for use
of the 3278/3279 APL keyboard.  This permits an APL keyboard to be used
for both VSAPL in host computer mode and PC/APL in personal computer
mode.

The section Getting Started describes how you get the VSAPL functions
            Getting Started
from the ENHANCEMENTS diskette to your host system, and how you make
the 3278/3279 keyboard work correctly for the PC/APL program.

The section How to Transfer Your APL Workspaces describes the steps you
            How to Transfer Your APL Workspaces
take to send a copy of an APL workspace from a Personal Computer to a
host, and vice versa.

The section Notes on Workspaces gives some information on the compat-
            Notes on Workspaces
ibility between VSAPL and PC/APL workspaces

References and definitions are:

ž   IBM 3270 Personal Computer Attachment User's Guide (Version 1.1)

ž   PC/APL is the APL program product from the Madrid Scientific Center

                 ------------ 1 of 8 Pages -----------

ž   The PC/APL book (First Edition - May 1983)  -- 1502219

ž   VSAPL, Release 4 of the APL program product supported on VM/CMS and
    TSO

ž   VSAPL, CMS Terminal User's Guide  (SH20-9067)

ž   VSAPL, TSO Terminal User's Guide  (SH20-9180)



Notes on Differences in File Formats
Notes on Differences in File Formats

INTERNAL FORMATS: PC/APL and VSAPL internal workspace formats are not
INTERNAL FORMATS:
compatible. The encodings are also different.  The workspaces must be
transformed from one internal format to another for each APL interpret-
er program to process.

AIO FORMAT: The PC/APL program uses an intermediate format for trans-
AIO FORMAT:
ferring the files between the Personal Computer and a host.  This
transfer format is called AIO.

CONVERTING WORKSPACES: Two VSAPL workspaces are provided on the 3270
CONVERTING WORKSPACES:
Personal Computer Attachment Enhancements diskette, one for VM/CMS
(VMOUT.APL) and one for TSO (TSOOUT.APL).  The new XIN and XOUT func-
                                                   _ _     _  _
tions in these workspaces, do conversion between a VSAPL workspace and
a file in AIO format at the host.


What's Different from the PC/APL Description
What's Different from the PC/APL Description

3278/3279 KEYBOARD: IBM 3270 Personal Computer Attachment replaces the
3278/3279 KEYBOARD:
Personal Computer keyboard with a 3278/3279 APL keyboard.  The
3278/3279 APL keyboard is mapped to generate Personal Computer scan
codes in Personal Computer mode.  You do not have to relearn APL key
functions positions on a new keyboard or use the stickers supplied with
PC/APL.  The special PC/APL functions you will need to know are:

              ŚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄĖÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄø
              ³ PC/APL Function   ³ Keystroke         ³
              ĘÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ×ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
              ³ Switch to mono    ³ PA2 + PF1         ³
              ĘÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ×ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
              ³ Switch to 80 color³ PA2 + PF8         ³
              ĘÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ×ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
              ³ Switch to 40 color³ PA2 + PF4         ³
              ĘÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ×ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
              ³ lower case letters³ Alt + letter      ³
              ĘÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ×ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
              ³ END               ³ ERAse EOF         ³
              ĘÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ×ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
              ³ APL characters    ³ As engraved on    ³
              ³                   ³ keyboard          ³
              ÓÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄŹÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¼

The XLATAPL translation table that is provided on this diskette is for
the 87 Key EBCDIC Typewriter/APL keyboard. You may use the program
XLATKBD described on page 8 to review the keystroke mappings or convert
to a different keyboard.

ASYNCHRONOUS COMMUNICATIONS AUXILIARY PROCESSOR (AP232): Refer to the
ASYNCHRONOUS COMMUNICATIONS AUXILIARY PROCESSOR (AP232):
PC/APL book, pages 3-28 to 3-35.  This Auxiliary Processor provides an
interface for the communications between the Personal Computer and the

                 ------------ 2 of 8 Pages -----------

host using the Asynchronous Communications Adapter.  It is not required
                                                           not required
for communication with the host system or for File Transfer with the
IBM 3270 Personal Computer Attachment.

VM232 WORKSPACE ON PERSONAL COMPUTER: This workspace is provided as
VM232 WORKSPACE ON PERSONAL COMPUTER:
part of the PC/APL programming support for host communication via an
Asynchronous Communication Adapter.  Refer to the PC/APL book,  pages
2-23 through 2-42.  The VM232 workspace is not required when using the
                                           not required
IBM 3270 Personal Computer Attachment.

The communication support for the IBM 3270 Personal Computer Attachment
uses the attached 3278 or 3279 Display Station's host communication
link.  The file transfer application support in the Personal Computer
is provided as a sample application (HOST.EXE) on a diskette distrib-
uted as part of the IBM 3270 Personal Computer Attachment.

AUXILIARY FILES ON THE HOST: The PC/APL book section on "Auxiliary
AUXILIARY FILES ON THE HOST:
Files on the Host" list several VSAPL functions and EXECs for you to
type on your host APL system.  Refer to the PC/APL book, pages 2-43
through 2-56.  NONE of these is required for IBM 3270 Personal Computer
               NONE
Attachment.

You should use whatever APL EXEC you normally use on your host system
for starting VSAPL.

The VSAPL workspace OUT, described in the PC/APL book, is replaced with
another VSAPL workspace from the 3270 Personal Computer Attachment
Enhancements diskette -- (VMOUT.APL for VM/CMS or TSOOUT.APL for TSO).
This new VSAPL workspace contains two functions XIN and XOUT for
                                                _ _     _  _
converting AIO transfer format files to/from VSAPL workspaces.

The XIN function converts an AIO format file (transferred up FROM the
    _ _                                                      FROM
PC) into a VSAPL workspace.
    into

The XOUT function converts a VSAPL workspace into a CMS AIO format file
    _  _
or TSO AIO format data set that may be transferred TO the PC.
                                                   TO

The XIN and XOUT functions are associated with other functions and
    _ _     _  _
variables in GROUPs. The XIN function is in the TRANIN group.  The XOUT
                         _ _                                       _  _
function is in the TRANOUT group.


Getting Started
Getting Started

To use the PC/APL program on the IBM 3270 Personal Computer Attachment
you copy most of the files from the APL diskette onto a system disk
customized for the IBM 3270 Personal Computer Attachment and activate
an APL translate table before starting the PC/APL program.

To use the VSAPL workspace conversion functions you must transfer the
VSAPL workspace from the 3270 Personal Computer Attachment Enhancements
diskette to the host system.  (Note: This only needs to be done ONCE.)

Creating a PC/APL Application Disk
__________________________________
Creating a PC/APL Application Disk


 1.  Create an application disk according to the instructions in the
     section Customizing Your Application Disk in the IBM 3270 Personal
             Customizing Your Application Disk
     Computer Attachment User's Guide.  This will be the PC/APL Appli-
     cation Disk.

 2.  Put a WRITE protect tab on the APL diskette sent with the PC/APL
     book.

                 ------------ 3 of 8 Pages -----------

 3.  Copy all the files from the PC/APL diskette to the PC/APL Applica-
     tion Disk, except for:
                except for:

     a.  the Asynchronous Communications Auxiliary Processor
         (AP232.COM)

     b.  the VM232 workspaces (VM232___.AIO)

 4.  Copy the XLATAPL.COM file from the 3270 Personal Computer Attach-
     ment Enhancements diskette to the PC/APL Application Disk.  This
     file supports the use of the 87 key Typewriter/APL 3278/3279
     keyboard for PC/APL.

     If you do not have this particular 3278/3279 APL keyboard type,
     you may CREATE your own XLATAPL.COM file using the Keyboard
     Mapping Utility (XLATKBD).  You may get a list of the translation
     changes used in the supplied XLATAPL.COM file by running the
     XLATKBD mapping application program with the PRINT option.  It is
     easier to CONVERT the XLATAPL file to a file for your keyboard
     type.  You can then PRINT or REVIEW the mapping, and make any
     changes using UPDATE.

 5.  If you used the FIXED DISK transfer procedure in your APL book
     (FDTRANS), it created an APL.BAT file.  Change it according to the
     next step.

 6.  Create an APLX.BAT file containing the commands:

                   ŚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄø
                   ³ XLATAPL ON                        ³
                   ³ APL %1 %2 %3 %3 %4 %5 %6 %7 %8 %9 ³
                   ³ XLATAPL OFF                       ³
                   ÓÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¼

 7.  Run PC/APL by entering the command APLX.


Getting Workspace Conversion Functions to Host
______________________________________________
Getting Workspace Conversion Functions to Host


The OUT VSAPLWS on the 3270 Personal Computer Attachment Enhancements
diskette must be placed in your private VSAPL library or in a public
VSAPL library on the host system.  The VSAPLWS can be sent to your
private library using the IBM 3270 Personal Computer Attachment File
Transfer procedure or from another user's private library using a host
networking or spooling procedure.  The VSAPLWS can be sent by the APL
system support representative to the public APL library in either of
the ways given above.

TRANSFERRING THE VSAPLWS WORKSPACE TO VM/CMS:
TRANSFERRING THE VSAPLWS WORKSPACE TO VM/CMS:

 1.  In Personal Computer mode, enter the command HOST (from the
     CUSTOMIZATION diskette).

 2.  Enter the CMS command
     PCXFER VMOUT VSAPLWS FROM VMOUT.APL ( NOTRAN UNFM LRECL 80 RECFM F

     The BLKSIZE should be 800 for compatibility with VSAPL release 3
     and 4.  You may have a problem loading or copying the VMOUT work-
     space into VM if the BLKSIZE is not 800.  If the problem occurs,
                                               If the problem occurs,
     then refer to the IBM VM/SP: CMS User's Guide (SC19-6210) or ask
     your system liaison.

     ž   DEFINE a temporary disk with blocksize = 800.
                 ------------ 4 of 8 Pages -----------

     ž   Access the temporary disk (preferably as A).

     ž   File transfer the VMOUT VSAPLWS to the temporary disk

     ž   Start VSAPL and load the VMOUT workspace.

         If the workspace loads without error, then return to VM and
         copy VMOUT VSAPLWS from the temporary disk to your original
         A-disk.


TRANSFERRING THE VSAPLWS WORKSPACE TO TSO:
TRANSFERRING THE VSAPLWS WORKSPACE TO TSO:

 1.  In Personal Computer mode, enter the command HOST (from the
     CUSTOMIZATION diskette).

 2.  Enter the TSO command
     PCXFER DSN(@W.TSOOUT) FROM FILE(TSOOUT.APL) NOTRAN UNFM LRECL(80)
     RECFM(FB) BLKSIZE(800) DSORG(PS)

     The second level qualifier for TSO VSAPL workspaces may be "@W"
     (at symbol, W).  The third level qualifier for TSO is the work-
     space name.  If you have problems loading or copying VSAPL work-
     spaces, contact your APL liaison for your system's naming
     convention for workspaces.

     The BLKSIZE should be 800 for compatibility with VSAPL release 3
     and 4.

Contact your APL support group to have the transfer workspace put in
the  public library.


How to Transfer User's APL Workspaces
How to Transfer User's APL Workspaces

From the Personal Computer to the Host
______________________________________
From the Personal Computer to the Host


 1.  Start the PC/APL program.

 2.  Use the )OUT system command (see the PC/APL book) to save the
     workspace on a Personal Computer disk as a transfer format file.

     Example on default disk: )OUT PCAPLWS

     Example to B Disk: )OUT 2 PCAPLWS

     The file extension will be AIO for the transfer format file.  If
     the filename is less than eight characters, the end of the name is
     padded with underscore characters.  The PC_filespec for this exam-
     ple would be B:PCAPLWS_.AIO .  However, APL only accepts the name
     PCAPLWS, not PCAPLWS_.

 3.  Exit PC/APL with )OFF command.

 4.  From DOS, type HOST (to start the HOST.EXE program).

 5.  Run PCXFER (File Transfer)

     VM Example: PCXFER PCAPLWS AIO A FROM B:PCAPLWS_.AIO (UNFM TRAN
     LRECL 80 RECFM F

     TSO Example: PCXFER DSN(PCAPLWS.AIO) FROM FILE(B:PCAPLWS_.AIO)
     UNFM TRAN LRECL(80) RECFM(FB)
                 ------------ 5 of 8 Pages -----------

 6.  Enter the VSAPL environment

 7.  In a CLEAR workspace copy the TRANIN group of variables and func-
     tions from the VMOUT  or TSOOUT workspace.

     TSO Example: )COPY TSOOUT TRANIN

     VM Example: )COPY VMOUT TRANIN

 8.  Using the XIN function, load the entire PC/APL workspace.
               _ _
     Example: '' XIN 'PCAPLWS'
                 _ _

 9.  You can now use the PC/APL workspace as a VSAPL workspace on your
     host or save it using the )SAVE command.

10.  If you want to cleanup the workspace (to get rid of the XIN func-
                                                             _ _
     tions and its variables), then execute )ERASE TRANIN


To the Personal Computer from the Host
______________________________________
To the Personal Computer from the Host


 1.  Enter the VSAPL environment on your host as you would normally.

 2.  Load the active VSAPL workspace with the functions and variables
     to be transferred.

 3.  Copy the TRANOUT group of functions and variables from the VMOUT
     or TSOOUT workspace into the active workspace.  These are used to
     create the PC's AIO transfer format of the VSAPLWS.

     VM Example: )PCOPY VMOUT TRANOUT

     TSO Example: )PCOPY TSOOUT TRANOUT

 4.  Use the XOUT function to create the AIO transfer format file or
             _  _
     data set.  Example: '' XOUT 'MYAPLWS'
                            _  _

     This creates a file containing the VSAPL workspace in the AIO
     transfer format with the VM file_id of MYAPLWS AIO A or a data set
     with the TSO data_set_name of MYAPLWS.AIO .

 5.  Exit the VSAPL environment using the )OFF HOLD command or the
     )CONTINUE HOLD command.

 6.  Switch to Personal Computer mode.

 7.  Start the HOST.EXE program from DOS.

 8.  Run PCXFER (File Transfer)

     VM Example: PCXFER MYAPLWS AIO A TO B:MYAPLWS_.AIO (UNFM TRAN

     TSO Example: PCXFER DSN(MYAPLWS.AIO) TO FILE(B:MYAPLWS_.AIO) UNFM
     TRAN

     Remember the Personal Computer filename must be 8 characters long
     or PC/APL will not find it.

 9.  Switch to Personal Computer mode

10.  Terminate the HOST.EXE program, using the BREAK or ATTN key.

11.  Enter the PC/APL program.
                 ------------ 6 of 8 Pages -----------

12.  Load your transferred VSAPL workspace into your PC/APL workspace
     using the )IN system command.

     Example on default disk: )IN MYAPLWS

     Example from B Disk: )IN 2 MYAPLWS

     If AIO filename was less than 8 characters, then you will get
     message WS NOT FOUND.  If AIO filename had the UNDERSCORE Charac-
     ter(s) added to the end of the name, ONLY USE the name without the
     UNDERSCORE characters.  If you use )IN MYAPLWS_  , you get COMMAND
     ERROR. If you use )IN MYAPLWS it works, and you get message start-
     ing with SAVED .....



Notes on Workspaces
Notes on Workspaces

The AIO transfer format requires a great deal more storage space than
the VSAPL or PC/APL workspace format.

TSO Example with 14 functions:

     48160 bytes in canonical form on TSO sequential data set

     300800 bytes in AIO format from the XOUT function
                                         _  _

     68000 bytes in PC/APL after transferred by PCXFER and loaded by
     )IN.


AUXILIARY PROCESSORS (APS): The Auxiliary Processors of VSAPL and
AUXILIARY PROCESSORS (APS):
PC/APL generally differ in name and in syntax.  Workspace compatibility
will depend on the APL application design and interface to the auxilia-
ry processors.

If the auxiliary processors are in separate functions the workspaces
could be used just by replacing the VSAPL functions that deal with APs
with PC/APL functions of the same names.  The PC/APL AP set is not as
rich as the VM or TSO VSAPL AP set.

The VSAPL AP100 differs markedly from the PC/APL AP100 processor.  The
VSAPL workspaces using AP100 will have to be changed to run on the PC.

VSAPL workspaces that depend on the GDDM auxiliary processor AP126 to
produce color displays in 7 colors, or graphics images will not work.

VSAPL workspaces dependent on full screen manager AP124, will have to
be changed to take into account the function of the PC/APL AP205.
Sometimes where the functions coincide, the return codes differ.  Some
functions in AP124 are not available in AP205 (e.g. light pen).

VSAPL workspaces that require access to other than 'flat' system files
                                        other than
(e.g. CMS files, TSO sequential data sets) will not function without
modification.

LANGUAGE ADDITIONS TO PC/APL: The VSAPL language is compatible with
LANGUAGE ADDITIONS TO PC/APL:
PC/APL except for the following additions to the PC/APL language.

Dyadic Grade: The functions of Grade Up and Grade Down have been imple-
Dyadic Grade:
mented in the dyadic argument form. Both the grade functions will now
accept a collating sequence as a left argument. The collating sequence
determines the order in which the right argument values will be
indexed.
                 ------------ 7 of 8 Pages -----------

Picture Format: Allows the you to specify the decoration and formatting
Picture Format:
of numeric output data.

Ambivalent dyadic functions: All dyadic defined functions may be
Ambivalent dyadic functions:
executed monadically without generating a SYNTAX error.

Alternate Execute: This system function was available for VSAPL under
Alternate Execute:
VSPC and as a modification under VM. It should be assumed NOT to be
available under VSAPL in general.

When transferring PC/APL workspaces for execution in VSAPL, these
features should not be used.  These add on features of PC/APL are
however, available in APL2 and users of this version of APL will find a
higher degree of compatibility to PC/APL than users of VSAPL.

NOTE: The host functions XIN and XOUT were written for VSAPL only.
                         _ _     _  _
Users of APL2 should not expect them to work unmodified.

SYMBOLS NOT SUPPORTED IN PC/APL: PC/APL does not use the UNDERSCORE
SYMBOLS NOT SUPPORTED IN PC/APL:
UPPER CASE letter symbols available with VSAPL on the host. Instead
PC/APL uses lower case ASCII symbols. Generally this will not create
any problems since PC/APL will recognize function and variable names in
lower case ASCII.  If your VSAPL workspace contains lower case EBCDIC
symbols, the translation of these will be to various ASCII symbols,
which are not necessarily meaningful. This will require you to re-key
title and other text strings using lower case ASCII symbols.


The Keyboard Mapping Application Program (XLATKBD)
__________________________________________________
The Keyboard Mapping Application Program (XLATKBD)

The Keyboard Reference Cards in the IBM 3270 Personal Computer Attach-
ment User's Guide show the Personal Computer Keyboard functions mapped
to 3278/3279 Keyboard keys for Personal Computer Mode.  Part of the IBM
3270 Personal Computer Attachment Customization includes matching the
correct Personal Computer Mode keyboard translation table with your
3278/3279 Keyboard.  (Sixteen keyboard are supported.)

Some of the available Personal Computer application programs have
keyboard mappings that are not compatible with the standard trans-
lations (e.g. Personal Editor allows you to define unique key mappings
for the Personal Computer Keyboard).

This Keyboard Mapping Application Program (XLATKBD) lets you create
unique keyboard translate table changes for each Personal Computer
application.

To use the Keyboard Mapping Application Program, enter the command
XLATKBD, and follow the instructions.  You will find extensive informa-
tion to assist you.















                 ------------ 8 of 8 Pages -----------
