------------------------------- Page    i -------------------------------

                          Tube Control Language

                              User's Guide




                                                 February 16, 1981

------------------------------- Page   ii -------------------------------

                            TABLE OF CONTENTS


1.    Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .   1

2.    Interfaces  . . . . . . . . . . . . . . . . . . . . . . . . . .   1

3.    The Pre-Processor . . . . . . . . . . . . . . . . . . . . . . .   1

3.1      Usage  . . . . . . . . . . . . . . . . . . . . . . . . . . .   2
3.2      Statements . . . . . . . . . . . . . . . . . . . . . . . . .   2

3.2.1       Open Statement  . . . . . . . . . . . . . . . . . . . . .   2
3.2.2       Input Statement . . . . . . . . . . . . . . . . . . . . .   2
3.2.3       Interact Statement  . . . . . . . . . . . . . . . . . . .   3

3.3      Macros and Externals . . . . . . . . . . . . . . . . . . . .   3

3.3.1       Screen Macro  . . . . . . . . . . . . . . . . . . . . . .   3
3.3.2       Rc Macro  . . . . . . . . . . . . . . . . . . . . . . . .   4
3.3.3       Row and Col Macros  . . . . . . . . . . . . . . . . . . .   4
3.3.4       Cursaddr  . . . . . . . . . . . . . . . . . . . . . . . .   4
3.3.5       Iscan and Oscan . . . . . . . . . . . . . . . . . . . . .   4
3.3.6       Inbuf and Outbuf  . . . . . . . . . . . . . . . . . . . .   4
3.3.7       Escaid  . . . . . . . . . . . . . . . . . . . . . . . . .   5
3.3.8       An Example  . . . . . . . . . . . . . . . . . . . . . . .   5

4.    The Library . . . . . . . . . . . . . . . . . . . . . . . . . .   5

4.1      Getoutput  . . . . . . . . . . . . . . . . . . . . . . . . .   5
4.2      Putoutput  . . . . . . . . . . . . . . . . . . . . . . . . .   5
4.3      Getinput . . . . . . . . . . . . . . . . . . . . . . . . . .   6
4.4      Putinput . . . . . . . . . . . . . . . . . . . . . . . . . .   6
4.5      Stdiscan . . . . . . . . . . . . . . . . . . . . . . . . . .   6
4.6      Stdoscan . . . . . . . . . . . . . . . . . . . . . . . . . .   6
4.7      Fssystem . . . . . . . . . . . . . . . . . . . . . . . . . .   6
4.8      Outscreen  . . . . . . . . . . . . . . . . . . . . . . . . .   7
4.9      Rdscreen . . . . . . . . . . . . . . . . . . . . . . . . . .   7
4.10     Wrtscreen  . . . . . . . . . . . . . . . . . . . . . . . . .   7
4.11     Aidlook  . . . . . . . . . . . . . . . . . . . . . . . . . .   7

5.    Possible Future Enhancements  . . . . . . . . . . . . . . . . .   7

5.1      Support of Other Tubes . . . . . . . . . . . . . . . . . . .   7
5.2      Support of Multiple Tubes  . . . . . . . . . . . . . . . . .   8
5.3      Direct BSC Interface . . . . . . . . . . . . . . . . . . . .   8

------------------------------- Page  iii -------------------------------

                                                            Last Page   8

-------------------------------- Page  1 --------------------------------

1.    INTRODUCTION

The Tube Control Language (TCL) is a package that allows UTS programs  to
communicate with other systems (including other UTS systems) by  simulat-
ing 3270  terminals (tubes).   Currently, the  "language" consists  of  a
pre-processor to C, a  few header files,  and a library of run-time  rou-
tines.

It is expected that  users of TCL have  a good knowledge  of UTS, C,  and
3270s.




2.    INTERFACES

Each TCL program uses one  of two separate pass-through interfaces.   The
first is the  VM Logical  Device Support Facility,  which allows  virtual
machines to create virtual 3270 terminals called Logical Devices  (LDEVs)
that VM treats the same as real 3270s (with a few restrictions).  In UTS,
these LDEVs are accessed through the files /dev/ldev*.  The limit on  the
number of simultaneous LDEVs is  the number the driver has been  compiled
to support  (at most  255).  See  the VM  System Programmers'  Guide  for
further information on LDEVs.

The other pass-through interface is a VMCF connection to the PVM  virtual
machine.  This allows  a UTS  program to connect  to whatever systems  to
which the PVM machine is connected.  Unfortunately, because the PVM  VMCF
interface was designed for use  by CMS, only one UTS program may use  the
interface at a time.  The PVM interface is accessed through the UTS  file
/dev/pvm.

TCL also provides a rudimentary full-screen interface for 3270s  attached
to UTS.  It is not compatible with Quick-Screen.  Note that  TCL programs
do not have to use the full-screen  interface, which allows use by  users
at ASCII terminals or invocation from cron.




3.    THE PRE-PROCESSOR

The TCL pre-processor is named tclpp and is similar in usage to yacc.

-------------------------------- Page  2 --------------------------------

3.1      USAGE

The usage of tclpp is:

     tclpp xxx.tcl ...

Tclpp insists that  its input  files have a  suffix of  .tcl and  outputs
files of the  same base name with  a suffix of  .c.  The following  lines
will compile and load frog.tcl:

     tclpp frog.tcl
     cc frog.c -o frog -ltcl


3.2      STATEMENTS

All TCL statements begin with a '$' and end with a ';'.  The '$' must  be
the first non-space  character on  its line.  TCL  statements may  appear
anywhere a C compound (enclosed in braces) statement may appear.


3.2.1       OPEN STATEMENT

The are two forms of  open statements, one for  each of the  pass-through
interfaces. They are

     $open ldev;

and

     $open pvm [node];

The open statement must be executed before any other TCL statement.   The
node parameter is a PVM  node to which to be passed-through.  It must  be
either a  string enclosed  in  double quotes  ('"') or  a  C  expression,
enclosed in parentheses, that evaluates to a character pointer.


3.2.2       INPUT STATEMENT

The purpose of the input statement is to simulate input from a 3270  key-
board.  The input statement has the form

     $input [command ...] [aid];

Aid is a 3270 Attention  Identifier, one of  clear, testreq, enter,  pa1,
pa2, or pf1 through pf12.  Command is either a data entry command, a cur-
sor movement command, or a screen editing command.

-------------------------------- Page  3 --------------------------------

A data entry command is either a string enclosed in double quotes or a  C
expression enclosed in parentheses.  It inputs characters into the screen
starting at the current cursor position.  The cursor position is  updated
as the input proceeds and  stops if the end of the field is reached.   No
input occurs if the cursor was in a protected field.  A newline character
in the data is treated as a newline cursor movement command.

A cursor movement command is one of up, down, left, right, tab,  backtab,
or newline.  These commands behave exactly like the corresponding keys on
the 3270 keyboard.

A screen editing command is either eeof or einput.  These behave  exactly
like the "erase eof" and "erase input" keys on the 3270 keyboard.

Some example input commands are

 1.  $input enter;
 2.  $input "blah" tab (frog) pf3;

The first is simply hitting the enter  key.  The second places "blah"  at
the current cursor  position, skips  to the beginning  of the next  input
field, inputs whatever data frog points at, and then hits the pf3 key.


3.2.3       INTERACT STATEMENT

The form of the interact statement is

     $interact;

It connects the simulated 3270 with a  user's 3270 and thereby allow  the
user to interact with the system with which the TCL program is connected.
The interaction is  continued until  a scanning routine  signals that  it
should stop (see below).  The interact statement may only be  used if the
TCL program was invoked by a user at a 3270.


3.3      MACROS AND EXTERNALS

A number of macros and external variables are defined in files  automati-
cally included  in every  TCL program.   Many more are  defined than  are
important to describe here, so watch for conflicts.


3.3.1       SCREEN MACRO

The screen macro takes a screen position (0 through 1919) as an  argument
and returns  a pointer to  an ASCII  string representing what  is on  the
simulated 3270's screen at that position.

-------------------------------- Page  4 --------------------------------

3.3.2       RC MACRO

The rc macro takes  two arguments  representing a row  (1-24) and  column
(1-80) and returns a screen  position (0-1919).  It is often used as  the
argument to the screen macro.


3.3.3       ROW AND COL MACROS

The row and col  macros each take  a screen position  as an argument  and
return either the row or the column that that screen position represents.


3.3.4       CURSADDR

The current screen position of the simulated cursor is always kept in the
external integer cursaddr.


3.3.5       ISCAN AND OSCAN

The variables  Iscan and  Oscan are  pointers to  functions which  return
integers.  The function pointed to by Iscan (default stdiscan) is  called
to scan and act  on input received  from a user's  3270 (not a  simulated
3270).  The function pointed to by Oscan (default stdoscan) is  called to
scan and act on output being written to a simulated 3270 by the system to
which it is  connected.  These  functions must return  one of the  values
S_OK, S_NOTOK, or S_STOP.  S_OK is returned in the usual case; S_NOTOK is
returned if the scanning  routine did something  to upset the state of  a
user's 3270, or if the data being scanned  should not be passed to  wher-
ever it normally goes;  S_STOP is returned  if an interaction started  by
the interact statement (above) should be stopped.  The value returned  is
only significant when an interact statement is active.


3.3.6       INBUF AND OUTBUF

The structures inbuf and outbuf hold the current input and output  images
and are used by scanning routines.  Their structure is:

     struct {
             char op;
             char data[4095];
             int  len;
     };

The CCW opcode is in op; it is READMOD or READBUF for input and WRITE  or
EWRITE for output.  The 3270 data is in data; it  begins with the AID for
input and with the WCC for output.  Len gives the length of data.   Inbuf
is used for  input received from a  user's 3270 or  created by the  input

-------------------------------- Page  5 --------------------------------

statement and is sent to the  system being communicated with.  Outbuf  is
used for output received from the external system and possibly being sent
to the user's 3270.


3.3.7       ESCAID

The variable escaid is used by  the standard input scanner (stdiscan)  as
the AID to be used in escape sequences (see below).   The default is TES-
TREQ; other valid  values are  CLEAR, ENTER,  PA1, PA2,  and PF1  through
PF12.


3.3.8       AN EXAMPLE

The following can be used  to test if a VM  terminal is in the "CP  READ"
state:

      if(row(cursaddr) == 23 &&
         strncmp(screen(24,61), "CP READ", 7) == 0) ...




4.    THE LIBRARY

The TCL library is in /lib/libtcl.a and is included with the -ltcl loader
argument.  Again, more routines exist  in the library than will be  docu-
mented here, so watch for conflicts.


4.1      GETOUTPUT

The routine getoutput reads 3270  output data from the simulation  inter-
face.  It is used when  a TCL program wishes to wait for the next  output
from the  system to  which  it is  connected.  There  are  no  arguments.
Getoutput reads the  data, updates  the TCL screen  image, and calls  the
output scanner.


4.2      PUTOUTPUT

The routine putoutput writes data to the user's 3270, after the data  has
been obtained by getoutput or generated in some other way  (see outscreen
below).  It is seldom used in TCL programs.

-------------------------------- Page  6 --------------------------------

4.3      GETINPUT

Getinput reads  data from  a  user's 3270.   It  is used  mainly  by  the
interact statement.


4.4      PUTINPUT

Putinput writes input data to the simulation interface after it has  been
obtained by getinput or generated by the program (e.g., input statement).
It's direct use is not encouraged.


4.5      STDISCAN

The standard input scanning  routine is stdiscan.   This routine  watches
real 3270 input for  commands beginning with  '!' and ended with the  AID
escaid (default TESTREQ).  Four types of commands are recognized:

'!>fn'  copies the current contents of the screen to the file  specified.
        If fn is not given,  the screen is appended to a file  previously
        specified.

'!>>fn' is like '!>fn' but starts out appending.

'!<fn'  reads the contents  of a  file into  the screen  starting in  the
        field in which the  command is given  and continuing to the  last
        field on the screen.  The user must then hit enter (or some other
        AID) to send the input to the remote system.  Newline  characters
        encountered in the file  will be treated  as newline cursor  com-
        mands.  If  fn is  null, input  will continue  from a  previously
        specified file.

'!cmd'  invokes the specified UTS command.  The screen is cleared  before
        invoking the command, and restored when it completes.


4.6      STDOSCAN

The standard output scanning is stdoscan.  It does nothing.


4.7      FSSYSTEM

Fssystem is used by stdiscan to issue UTS commands and take care of leav-
ing and re-entering full-screen mode.   Its one argument is a pointer  to
the command to be invoked.  If the command is null, an interactive  shell
is invoked.

-------------------------------- Page  7 --------------------------------

4.8      OUTSCREEN

Outscreen copies the in-core screen image into the outbuf buffer so  that
the user's screen image may  be restored.  Normally, putoutput is  called
after outscreen.  Outscreen has no arguments.


4.9      RDSCREEN

Rdscreen is the routine used  by stdiscan to read data  from a file  into
the screen.  It is called  with two arguments: a beginning field  address
and a file name.  If  the file name is the  null string, input  continues
from the previously read file.


4.10     WRTSCREEN

Wrtscreen is used by stdiscan  to write the contents of  the screen to  a
file.  It has two  arguments, a flag for  appending and a pointer to  the
file name.  If the file name is not null, that file is opened either  for
writing or appending as determined by the append flag.  If  the file name
is the  null string,  then writing  continues in  a previously  specified
file.


4.11     AIDLOOK

Aidlook is just a handy way to map from the  name of an AID to the  value
of an AID. For example,

     escaid = aidlook(argv[1]);




5.    POSSIBLE FUTURE ENHANCEMENTS

The potential of TCL is enormous, but  some spiffy features will have  to
wait until  they are needed.   The rest  of this paper  suggests some  of
these features.


5.1      SUPPORT OF OTHER TUBES

Right now, TCL and associated drivers support only 3277-2 terminals.  The
LDEV and  PVM interfaces  also support  3278 terminals, so  TCL could  be
expanded to support them also.

-------------------------------- Page  8 --------------------------------

Note that it would  not be necessary  to have 3278  terminals to  support
them, since TCL could simulate the 3278 features on a 3277.


5.2      SUPPORT OF MULTIPLE TUBES

TCL could be extended to allow a  single program to simulate many  tubes.
This is not needed too badly since many TCL processes can be run at once,
but it would allow programs  which did things similar  to the VM  SESSION
command.


5.3      DIRECT BSC INTERFACE

Only one program may use the PVM interface, and it is the only  interface
to MVS.  If usage of TCL to get to MVS becomes popular, a higher capacity
link to MVS will be needed.  This could  be done by by-passing PVM  alto-
gether and implementing  a bi-synch  (BSC) driver to  talk to MVS.   This
would allow up to 32 simulated terminals per BSC line.

-------------------------------- The End --------------------------------
