!TITLE EMAS-3 Command Language - ECL

(Preliminary version of User Note 81, 15 Mar 88)

Any comments to Tony Gibbons please.


!<General Remarks
Comments
--------

Comments (single lines only) may be interspersed with commands.  They are
delimited by
          /*  ........  */
or        /*  ..... to end of line

Literal strings
---------------
Literal strings are delimited by either single or double quotes:
          '"Where am I?"'
          "You're here!"

Redirection of input/output
---------------------------
All EMAS-3 commands may be executed so that output that would normally go to
the terminal is sent instead to a file. This is done by following the command
with
         > filename
for example
         Command:analyse a* > xa
produces an analysis of all files whose names begin with a in file xa.
Similarly, if a command normally reads data from the terminal, it can instead
be made to read it from a file.  To do this the command is followed by
         < filename
for example
         Command:edit a < com
applies the editing commands in file com to file a.  Both forms may be
combined, for example
         Command:edit a > xa < com
applies the commands in file com to the file a with output to file xa.

Use of ECL Statements
---------------------
The ECL statements described below may be used at the terminal, in an
obey file, in a batch job and within an ECL procedure. The sole
exception to this is that control statements, i.e. cycle ... repeat and
if ... else ... fi, cannot be used directly at the terminal.

Action after an Error
---------------------
If a command fails, that is, sets the return code non zero, the default
action is to print an error message and continue with the next command.
A different action can be specified by setting an ECL variable erroraction
to the command to be executed. For example
            erroraction = 'stop'
or          erroraction = 'files p*'
The default action is restored by setting erroraction to zero or a null
string.
!>
!<ECL Variables and Expressions
Variables can be assigned values and used in computations. These variables are
not declared: it is sufficient to assign a value. This is done with a statement
of the form 
          Command:variable = expression
for example

          Command:message = "I've gone for lunch"
          Command:count = 2*3*4
          Command:rate = 1.2
          Command:x = (a + b) * c

Variables can have values which are strings, integers or long reals and type
conversions take place when necessary. Specifically, a combination of an
integer and a long real produces a long real and anything combined with a
string produces a string. Thus
   count+rate         produces a long real 25.2
   count+" "+message  produces a string '24 I've gone for lunch'
Brackets and the operators + - * / may be used in arithmetic expressions.

In string expressions, + means concatenate, - means concatenate with one
space character between. * and / are undefined. Another kind of assignment
statement for strings is 'string resolution' which allows a string to be
searched from left to right for a specified substring of characters. If the
substring is found, then the characters to the left and right of the substring
are stored in two variables, if specified, to the left and right of the
substring in the command. If the substring is not found, a failure occurs.
Multiple resolutions can be specified in a single command. The basic form of
the command is:
         Command:variable -> variable (substring) variable
For example, if the variable date has the value 08/01/87 then the
following resolutions would succeed:
         Command:date -> day ('/') rest
         Command:date -> day ('/')
         Command:date -> day ('/') month ('/') year

The value of an expression is displayed with

          Command:say expression
(giving a simple calculator facility).  If you wish to send control characters
to the terminal (see function pos below) then saychs should be used.

The values of all variables are given with

          Command:monitor
!>
!<Global Variables
The sets of variables used at command level and within ECL procedures are
distinct and a procedure can neither read nor change the value of a variable
that is not declared within it. This is not always convenient and the global
statement allows a procedure to access variables used at command level, the
variables being created if necessary. For example:
            procedure weeklyjob
            global file, entries
            /* here follow statements to process file and compute entries
            end
could be used in the sequence
            file = 'week140388'
            weeklyjob
            say "Entries=" + entries + newline
!>
!<Built in Functions
Name              Type           Description

arccos(x)         longreal
arcsin(x)         longreal
arctan(x,y)       longreal
cos(x)            longreal
count             integer        the number of elements in a set
                                 See 'Operations on a Set' below
date              string         format dd/mm/yy
exp(x)            longreal
filetype(name)    integer        takes a file or group name as
                                 parameter and returns its type:
                                  < 0 invalid or does not exist
                                    0 a group
                                    1 object
                                    2 non-standard
                                    3 character
                                    4 data
                                    5 corrupt object
                                    6 pd file
                                    7 directory
                                    8 journal
hex(number)       string         gives the hex representation
hypcos(x)         longreal
hypsin(x)         longreal
intpt(x)          integer
length(x)         integer
log(x)            longreal
newline           string      
next              string         See 'Operations on a Set' below
pop               string         See 'The System Stack' below
pos(line, col)    string         saychs pos(0,10)+'Chapter 1' for example,
                                 places the text on line 0 at column 10
radius(x,y)       longreal
real(x)           longreal
sin(x)            longreal
sqrt(x)           longreal
substr(string, first, last)
                  string         substr(s,1,2) gives first 2 characters of s
tan(x)            longreal
time              string         format hh.mm.ss
typeof(variable)  integer
uinfi(integer)    integer        see User Guide
uinfs(integer)    string         see User Guide
vdus(integer)     string         gives various characteristics of
                                 your video terminal:
                                    0 terminal name
                                    1 clear screen sequence
                                    2 cursor home
                                    3 clear to end of line
!>
!<System Variables
The following may be read or written:
Type              Name           Description

returncode        integer        as set by EMAS3SETRETURNCODE
returntext        string         as set by EMAS3SETFNAME
result                           treated as an ECL variable, i.e. it may
                                 be integer, string or long real. It is
                                 used to return a 'result' to a caller.
!>
!<Control Statements
In the list below, B stands for a Boolean expression and [IF] means that the
statement may optionally be followed by
         if B
or
         unless B

         if B
         unless B
         else
         fi
         cycle
         repeat [IF]
         exit [IF]          exit from a cycle ... repeat loop
         continue [IF]      begin a new repetition of a cycle ... repeat loop
         stop [IF]          return to command level
         return [IF]        leave the ECL procedure
         for specifier      see 'Operations on a Set' below
         end                marks the end of the ECL procedure

If desired, 'ifnot' and 'finish' can be used instead of 'unless' and 'fi'.

The normal way to use if is:
            if B
               /* statements to be executed if B is true
            else
               /* statements to be executed if B is false
            fi
Very simple sequences can be written on one line:
            if B then statement

Arithmetic values can be compared using =, #, >, >=, < and <=.  String values
can only be compared using = and #. String comparisons are case independent.
String resolutions may be used in Boolean expressions.  For example, the
following would remove all multiple spaces from the variable line:
         cycle
            exit unless line -> left ('  ') right  /* 2 spaces in quotes
            line = left - right  /* concatenate with single space
         repeat
!>
!<Operations on a Set
The elements of a set are processed with a cycle of the form:
         for specifier
            ......
            variable = next
            ......
         repeat
The function next gives the 'next' element of the set on each call and
exits from the cycle when the set is exhausted. The set is defined by specifier.
The specifiers available are:
      a)   files(pattern, option, filetype)
           where the parameters are essentially the same as those in
           the files command. For example

              for 'files(a*,c,o)'
                 say next + newline
              repeat
           gives a list of cherished object files whose names begin
           with 'a'.

      b)   lines(file)
           This specifier provides a line of the (character) file at
           each call of next.

The function count gives the total number of elements in a set.
!>
!<Substitution
The values of ECL variables can be inserted into commands by the technique known
as substitution. Each variable to be substituted is enclosed in angle brackets
< and >. For example, if we have the assigmnents

          srce='s.util01'
          obj="y.util"
then
          imp <srce>,<obj>
is equivalent to
          imp s.util01,y.util
Substitution never fails. If the text inside the brackets is not the name of a
variable, no substitution is done. Thus, given the assignments above,
         imp <s>,<obj>
becomes
         imp <s>,y.util
The only restriction on the use of substitution is that the command names in
control statements cannot be substituted, specifically:
IF, UNLESS, ELSE, FI, CYCLE, REPEAT, EXIT, CONTINUE and FOR.
!>
!<Procedure Definitions
The first line of an ECL procedure (sometimes called a 'macro') has the form
          procedure procedurename
where procedurename is alphanumeric starting with a letter. The body of the
procedure follows and is terminated by end of file, by the start of another
procedure or by the end statement. The body of a procedure consists of the
commands to be executed.

To make the procedure (or procedures if there is more than one in the file)
known to the system, the file is inserted into a directory in the same way as
an object file. A procedure in the file can then be called by giving its
name. For example
          procedure conn
          parm nocheck,noarray
          imp conns,conny,connl
          xref connl,x
          list connl+x,.lp
          end
If the file containing this text is 'inserted' then
          Command:conn
results in the execution of the four statements comprising the procedure body.
!>
!<Procedure Parameters
Procedures become more useful when they are written to accept parameters.
Procedures acquire their parameters through the Parameter Acquisition Mechanism
(PAM) in a similar way to ordinary commands by making calls on emas3string etc.
Full details are available in the EMAS-3 User Guide. For example
          emas3string 'Source file', source
obtains a string value for the variable source. The previous example could
be rewritten to use a parameter:
         procedure com
         emas3string "File stem", stem
         parm nocheck,noarray
         imp <stem>s,<stem>y,<stem>l
         xref <stem>l,x
         list <stem>l+x,.lp
         end
and the call would have the form
         Command:com conn
The first parameter in emas3string is a PAM vector with fields
         prompt;qualifier;default;help
For example
         emas3string "Input;file;?;the file containing the data", inf
Values for integer and long real parameters are obtained with emas3integer and
emas3longreal respectively.
!>
!<Data for Commands
If a command in a procedure requires data, that data can simply follow the
command:
         edit file
         p10
         e
Alternatively, the data can be enclosed in 'brackets', ---- and ++++. This
has two advantages, first the end of the data is indicated so the command cannot
'consume' more than intended and second substitution can be done on the data.
For example:
         edit file
         ----
         (a.<word>.p1)*
         e
         ++++
Alternatively, a command may take the first part of its data, modified by
substitution, from the procedure definition and the remainder from the
interactive terminal, by replacing the '++++' by '....', for example:
         recall
         ----
         m-/**** LOG-ON/
         ....
!>
!<Screen Handling
The routines described here allow a number of 'windows' to be displayed on
the screen of a video terminal.  The windows may overlay each other and
the ordering (i.e. which one goes at the back etc.) may be changed
dynamically.  A window displays a number of lines of a character file and
can move up or down the file.  Additionally, a window can have a 'cursor' -
a pointer to one of its lines.  The cursor can be moved up and down within
its window and the line of text which it references retrieved.
!STOP
!<emas3 window

   %external %routine %spec emas3 window(%integer %name n,
          %string %name specifier,
          %integer %name firstline, lastline, firstcol, lastcol, cursor, flag)
                                              {irsririririririw}

This defines window n, 1 <= n <= 4, with dimensions given by firstline etc.
where
          0 <= firstline < lastline <= 23
and       0 <= first col < last col <= 79

If an edge of a window is not at the edge of the screen, a further row or
column is used to draw a border around the window.

The contents of the window are determined by specifier.  This has the same
form as that used in the 'for' statement in ECL, namely:

          lines(charfile)

gives the lines of the character file charfile and

          files(pattern)

gives the list of files whose names conform to pattern.

Cursor is used to indicate whether a cursor is required in the window.  If
cursor < 0, no cursor is provided, otherwise the left hand column of the
window is left blank except for a cursor character (>) on one row, initially
the first row.

Flag is zero for success.

Example

   emas3 window(1, "files(a*)", 0, 19, 0, 18, 0, flag)

creates window 1 containing names of files beginning with 'a'.  They are
displayed in groups of 20 in lines 0-19.  A cursor is displayed in column 0
and the (first part of the) name of each file is displayed in columns 1-18.
!>
!<emas3 move cursor

   %external %routine %spec emas3 move cursor(%integer %name n,
          %string %name act, %integer %name flag)               {irsriw}

This is used both to move the cursor in window n and to display the
next/previous set of lines.  Act is a single letter: U, D, F or B.

F displays the next set of lines in the window and B the previous
set (unless we are already at the start of the file).

If the window has no cursor, D brings a new line into the window at the
bottom and loses a line from the top.  U does the reverse operation.

If the window does have a cursor, D moves the cursor down one line.  If
it is already on the last line of the window, F is invoked and the cursor
reset to the first line.  Conversely, U moves the cursor up one line.
If it is already on the first line of the window, B is invoked and the
cursor reset to the last line (unless we have reached the start of the
file).
!>
!<emas3 set screen vector

   %external %routine %spec emas3 set screen vector(%string %name v)  {sr}

By default, windows are displayed in the sequence 1, 2, ... i.e. window 1
goes at the back and may be partially overwritten by window 2 etc.  The
sequence can be changed by this routine, the parameter giving the sequence
required. For example

          emas3 set screen vector("21")

displays window 2 behind window 1.  If window 1 'encloses' window 2, this has
the effect of making window 2 invisible.  Resetting the vector to "12" restores
any information that had been lost from window 2.
!>
!<emas3 get line from window

   %external %routine %spec emas3 get line from window(%integer %name n,
         %string %name line, %integer %name flag)           {irswiw}

This routine returns the line referenced by the cursor in window n.
!>
!<emas3 clear screen

   %external %routine %spec emas3 clear screen

This routine clears the video and, in addition, resets the screen vector
to its default value and clears the definitions of all the windows.
Setting the screen vector to "0" has the effect of clearing the screen
without losing the definitions.
!>
!>
!<The System Stack
The stack may be accessed with the commands:
         push expr
         queue expr
         exec filename
         hide
         reveal
The string function pop returns and removes the top item from the stack.
         push -->  ---  --> pop
                   ---
                   ---
                   ---
        queue -->  ---
hide adjusts the start and end of data pointers in the file
header so that the stack file appears to be empty. Reveal resets them.

exec does an 'obeyfile' on the stack with output optionally
directed to the file given as parameter.
!>
!<Calling External Procedures
In addition to emas3integer, emas3string and emas3longreal, ECL knows about 
some other EMAS3 routines, namely:
            emas3checkname
            emas3clearscreen
            emas3comreg
            emas3cputime
            emas3exist
            emas3getlinefromwindow
            emas3helpinfo
            emas3movecursor
            emas3setcomreg
            emas3setscreenvector
            emas3window
Other external code routines may be called, provided they are written to
EMAS-3 standards, by including the appropriate 'spec' statement in the
calling ECL procedure. A spec statement is written as:
            spec localname/actualname template
for example
            spec pdt/emas3packdateandtime srsriw
The template (described in Appendix 3 of the EMAS-3 User Guide) is required
only if the routine requires parameters. If the localname and the actualname
are the same, only one need be given, for example
            spec emas3clearjournal
External functions of type integer, string or longreal may also be called by
including a suitable spec statement. The format is similar to that of a
routine spec but indicates the type of the function:
            ifnspec localname/actualname template
            rfnspec localname/actualname template
            sfnspec localname/actualname template
!>
!<Diagnostic Facilities
!>
!<Related EMAS-3 Routines
!STOP
!<emas3 variable declared
   %external %routine %spec emas3 variable declared(%string %name vname,
      %integer %name flag)                             {sriw}

flag is set to 1 if vname is the name of an ECL variable else 0.
!>
!<emas3 set variable
   %external %routine %spec emas3 set variable(%string %name vname,
      %integer %name type, ivalue, %long %real %name rvalue,
      %string %name svalue, %integer %name flag)        {sririrrrsriw}

Allows a code routine to set the value of a global ECL variable vname.
The value may be integer (type=0), long real (type=1) or string (type=2).
The value itself should be put into ivalue, rvalue or svalue as appropriate.
!>
!<emas3 get variable
   %external %routine %spec emas3 get variable(%string %name vname,
      %integer %name type, ivalue, %long %real %name rvalue,
      %string %name svalue, %integer %name flag)      {sririrrrsriw}

If the variable vname exists, its type (0, 1, or 2) is returned and its
value in ivalue, rvalue or svalue as appropriate.
!>
!>
!<Examples

Example1
         procedure incontext
         /* This procedure searches for and lists occurrences of
         /* a piece of text within a file
         emas3string "file;file,char,exist", file
         emas3string "text", text
         destroy t#junk
         edit <file>,t#junk
         ----
         i/Occurrences of <text> in <file>
         
         /
         s
         (
         m.<text>.u1
         )*
         d-*
         e
         ++++
         send t#junk
         end

Example2
         procedure types
           /* This procedure scans through a set of files and reports their
           /* filetype. If a group or a PD file is encountered, the procedure
           /* is called recursively to determine the types of the members.
         emas3string "Pattern;any,verbatim,nowild", pat
         say pat+newline
         for 'files('+pat+')'
            file = next
            type = filetype(file)
            say file - type + newline
            type = 0 if type = 6
            if type = 0
               types <file>
            fi
         repeat
         end

Example3

         procedure wordcount

         /* This is a simple 'word' counting procedure

         emas3string "File;file,char,exist", file
         words = 0

         for 'lines('+file+')'
            a=next  /* a is now a line of the file
            cycle
               words = words + 1  /* assume at least one word per line
            repeat if a -> (' ') a  /* chop off a word
         repeat  /* to end of file
         say 'Number of words in' - file - 'is' - words + newline
         end

Example4
         procedure browse
         /* this procedure allows you to browse through a set of
         /* files and issue commands to examine them
         cycle  /* outer cycle to get a pattern
            emas3string "Pattern;literal", pat
            return if pat = 'q'
            emas3clearscreen
            specifier = 'files('+pat+')'
            emas3window 1,specifier,0,19,0,18,0,flag
               /* down the LHS of the screen
            
            cycle
               saychs pos(22,0)+vdus(3)  /* 'vdus(3)' is 'clear to end of line'
               emas3string "Now?;literal;;", x
               exit if x = 'q'
               if x = ''  /* press 'return' to move cursor down in window 1
                  emas3movecursor 1,'d',flag
                  continue
               fi
               if x = '-'  /* - takes it up again
                  emas3movecursor 1, 'u',flag
                  continue
               fi
               if x='>'  /* down on window 2, to get the next screen full
                  emas3movecursor 2,'d',flag
                  continue
               fi
               if x = '<'
                  emas3movecursor 2,'u',flag
                  continue
               fi
               emas3getlinefromwindow 1,s,flag  /* referenced by the cursor
               if x -> left ('@') right
                  x = left + s + right  /* replace @ by filename
               else
                  /* append filename unless 'command' includes a sp
                  unless x -> (' ')
                     x = x - s
                  fi
               fi
               unless x -> x (' ') s then s = ''
               <x> <s> > T#X  /* obey command with output to file T#X
               specifier = 'lines(t#x)'
               emas3window 2, specifier,0,19,20,79,-1,flag
                /* display output in window 2
            repeat
         repeat
         end
!>