ARCterm 7 script command summary         Hugo Fiennes            22-April-1992
--------------------------------          The Serial Port

Applicable to ARCterm 7 version 1.41

Integer expression evaluation
-----------------------------

  [0-9]                           Base 10 numbers, eg 155.

  0x[0-f]                         Hexadecimal, eg 0x9b = 155.

  +,-,*,/
                                  Self explanitory!


  %
                                  Modulus (like MOD in BASIC).


  <<
                                  Left shift (like BASIC).


  >>
                                  Right shift (like BASIC).


  = or ==
                                  Equal to.


  <> or !=
                                  Not equal to.


  <=
                                  Less than or equal to.


  >=
                                  Greater than or equal to.


  <
                                  Less than.


  >
                                  Greater than.


  !
                                  Logical NOT.


  ~
                                  Bitwise NOT.


  &&
                                  Logical AND.


  &
                                  Bitwise AND.


  ||
                                  Logical OR.


  |
                                  Bitwise OR.


  ^
                                  Bitwise EOR.


  len(string)
                                  Returns length of string.

  asc(string)
                                  Returns ASCII value of first character in
                                  string.

  'x'
                                  Returns the ASCII value of the character x,
                                  like asc("x").

  val(string)
                                  Returns numeric value of string.

  compare(string1,string2)
                                  Returns 0 if string1 and string2 are not
                                  equal, returns non-0 if strings are equal.
                                  CASE SENSITIVE.

  comparei(string1,string2)
                                  Returns 0 if string1 and string2 are not
                                  equal, returns non-0 if strings are equal.
                                  CASE INSENSITIVE.

  strcmp(string1,string2)
                                  String compare like C.
                                  CASE SENSITIVE.

  stricmp(string1,string2)
                                  String compare like C.
                                  CASE INSENSITIVE.

  instr(string1,string2)
                                  Returns position in string1 (numbered from 1)
                                  where string2 first ocurrs. Returns 0 if
                                  string2 not found in string1.


String expression evaluation
----------------------------

  +
                                  Add two strings together.

  $left(string,howmuch)
                                  Returns the first howmuch characters of
                                  string (like LEFT$ in BASIC).

  $right(string,howmuch)
                                  Returns the last howmuch characters of
                                  string (like RIGHT$ in BASIC).

  $mid(string,where[,howmuch])
                                  Returns howmuch (if specified, otherwise
                                  assumed to be 1) characters of string,
                                  starting at point where (numbered from 1).

  $chr(asciivalue)
                                  Returns a string of the single ASCII
                                  character specified.

  $str(expression)
                                  Returns a string of the expression evaluated
                                  in decimal.


Variables
---------

Variable names and values are searched for in the order most volatile
downwards. Called functions inherit the variables of the caller.

  integer name[[arraysize]][=expression][,...]
  int name[[arraysize]][=expression][,...]
                                  Makes a variable 'name' (the name can be
                                  the same as another defined at another
                                  nesting level), and optionally assigns
                                  a value to it. Multiple creations and
                                  assignments can be separated by commas.
                                  eg:

                                  integer a,b=(5*function()),c

                                  Arrays may also be created, but NOT
                                  initialised:

                                  integer a[20],b
                                  
                                  (elements are accessed as in C, with
                                  variable[element] - elements are numbered
                                  from zero).

  string name[[arraysize]][size][=stringexpression][,...]
  char name[[arraysize]][size][=stringexpression][,...]
                                  Makes a variable 'name' (the name can be
                                  the same as another defined at another
                                  nesting level), and optionally assigns
                                  a value to it. Multiple creations and
                                  assignments can be separated by commas.
                                  Lengths MUST be defined and cannot be
                                  exceeded.
                                  eg:

                                  string a[50],b[10]="hello"

                                  Arrays may also be created, but NOT
                                  initialised:

                                  string a[20][10],b[5]

                                  (elements are accessed as in C, with
                                  variable[element] - elements are numbered
                                  from zero).

Structures
----------

  for... works just like FOR...NEXT in BASIC.

    for variable = start to end [step value]
      {
      ... instructions ...
      }

  while... works like while() {} in C.

    while(expression!=0)
      {
      ... instructions ...
      }

  repeat...until works like REPEAT...UNTIL in BASIC.

    repeat
      {
      ... instructions ...
      }
    until(expression==0)

  if...else works like IF...THEN...ELSE in BASIC. The else part is optional.

    if(expression!=0)
      {
      ... instructions for !=0 ...
      }
    else
      {
      ... instructions for ==0 ...
      }

  switch...case...[default] works a bit like switch...case in C. Aswell as
  case(), case$() and case$i() can be used which cause the instructions to be
  executed if the string expression in switch() matches the one in the case$,
  case sensitively or insensitively.

    switch(expression1)
      {
      case(expression2)
        {
        ... instructions for expression1==expression2 ...
        }
      case(expression3,expression4)
        {
        ... instructions for expression1==expression3 or
                             expression1==expression4 ...
        }
      default
        {
        ... (must be at the end of the list of case's)
            instructions if no case's were executed ...
        }
      }

Returning values
----------------

  return([expression])
                                  Returns the numeric expression to the caller
                                  of the routine. If no expression is
                                  specified, 0 is returned.

  $return(stringexpression)
                                  Returns the specified string expression.
                                  To use this, the function name being returned
                                  from must start with a '$'.

Serial port
-----------

  Serial port control lines
  -------------------------

  port_dtr(newstatus)
                                  Sets the DTR line high (newstatus!=0) or low
                                  (newstatus==0).

  port_rts(newstatus)
                                  Sets the RTS line high (newstatus!=0) or low
                                  (newstatus==0).

  port_dcd()
                                  Reads the DCD status (actually RI on the
                                  serial port). Non-zero for DCD high.

  port_break([breaktime])
                                  Sends a break level on the serial port for
                                  'breaktime' centiseconds (if this is not
                                  specified, the default time of 250cs is
                                  used).


  ---- Note! The following extra_ commands are only intended for use in
       modem drivers for very dumb modems.

  extra_setbaud(demonrate)
                                  When used with a Demon I modem, this sets
                                  the correct baudrate using 30us pulses of
                                  the DTR line.

  extra_dtrdial(digit)
                                  Pulses the DTR line at 67% break, 33% make
                                  digit times (if digit is 0, 10 pulses are
                                  generated).

  extra_rtsdial(digit)
                                  As for extra_dtrdial() except less accurate
                                  and with the RTS line.

  extra_dtrpulse(time)
                                  Send a low pulse of time us with the DTR
                                  line.

  Serial port setup
  -----------------

  serial_local([portnumber])
                                  Selects which local (ie on the machine that
                                  ARCterm is running on) serial port to use -
                                  if none is specified, then the standard port
                                  (0) is assumed.

  serial_remote(network,station[,password])
                                  Attempts to establish a connection with a
                                  remote modem server at network.station
                                  [network is 0 if no bridges are installed].
                                  Returns a non-zero value if a connection was
                                  made.

  port_txspeed([newspeed])
                                  If newspeed is not specified, this just
                                  returns the current transmit speed, otherwise
                                  the new speed is set and the old speed
                                  returned.

  port_rxspeed([newspeed])
                                  As port_txspeed except for the receive
                                  speed.

  $port_wordformat(["newformat"])
                                  If newformat is not specified, this returns
                                  a string indicating the current word format.
                                  If newformat is specified, the new word
                                  format is set and the old one returned.
                                  [returns and takes a string]


  Serial port data transfer
  -------------------------

  port_tx(data)
                                  Sends the byte specified.

  port_rx()
                                  If there is data waiting in the receive
                                  buffer this returns the first byte in the
                                  buffer otherwise it returns -1 to indicate
                                  buffer empty.

  port_txbuffer()
                                  This returns the number of free bytes in
                                  the transmit buffer.

  port_rxbuffer()
                                  This returns the number of bytes waiting in
                                  the receive buffer.

  port_txclear()
                                  Clears the transmit buffer.

  port_rxclear()
                                  Clears the receive buffer.

  type(string)
                                  Send the specified string to the serial port.
                                  (Brackets are optional)

  waitfor(string[,maxwait])
                                  Waits for the specified string to be
                                  received. If maxwait (maximum time to wait
                                  for string in cs) is not specified, it will
                                  wait indefinitely. waitfor() returns a non-0
                                  value if the string is not seen in the
                                  specified time.

File transfer
-------------

Valid download protocols are: xmodem, xmodem1k, ymodem, ymodemg, zmodem,
                              sealink, kermit, cet.

Valid upload protocols are  : xmodem, xmodem1k, ymodem, ymodemg, zmodem,
                              sealink, kermit, ascii.

  download(protocol[,whereto])
                                  Initiates a download using the specified
                                  protocol to the specified path - this must
                                  be a '.' terminated directory name for
                                  batch transfers and a filename for non batch
                                  transfers. The system variable 'defaultpath'
                                  is set to the default batch path (as
                                  configured on menus). download() returns the
                                  number of files sucessfully transferred.

  upload(protocol)
                                  Initiates an upload using the specified
                                  protocol. The files to be uploaded must have
                                  been added to the batch previously (see
                                  below). upload() returns the umber of files
                                  sucessfully transferred.


  batch_clear()
                                  Clear the file batch.

  batch_add(filename[,alias])
                                  Adds the specified file to the batch. An
                                  alias for the file (sent to the remote end)
                                  can be specified - if not, this will default
                                  to the leafname of the file.

  batch_remove(filename)
                                  Removes the specified file from the batch.

  batch_load(filename)
                                  Loads a previously saved upload batch from
                                  the specified file.

  batch_save(filename)
                                  Saves the current upload batch to the
                                  specified file.

  batch_count()
                                  Returns the number of files currently in the
                                  upload batch.

Kermit server functions
-----------------------

These functions allow you to interact with a remote Kermit server from the
script language. To send a file to a Kermit server, just use the normal
upload(kermit,xxx) function.

  kermit_get(remotename,localpath)
                                  Requests the file(s) in 'remotename'
                                  (wildcards are usually accepted by Kermit
                                  servers) and stores them in the path
                                  specified - this must be terminated in a '.'.
                                  Returns the number of files sucessfully
                                  transferred.

  kermit_finish()
                                  Stops the remote Kermit server.

  kermit_bye()
                                  Stops the remote Kermit server and logs out.

  kermit_dir(directory)
                                  Displays (in the terminal window) the remote
                                  directory specified. To see the current
                                  remote directory, use "".

  kermit_cwd(directory)
                                  Changes the remote current working directory,
                                  directory specifier syntax is invariably
                                  host specific.

  kermit_login(idandpw)
                                  Logs in to a permanent Kermit server.

  kermit_query()
                                  Requests information about the remote Kermit
                                  server.

  kermit_usage()
                                  Requests information about free space on the
                                  remote Kermit server.


Data logging/output facilities
------------------------------

spoolfile refers to the spoolfile number - 1 or 2.

  spool_open(spoolfile,filename)
                                  Opens the specified spoolfile to the
                                  specified filename. If the file already
                                  exists, new data will be appended to the
                                  existing file. Returns a non-zero value if
                                  the opening was sucessful. Upon sucessful
                                  opening of the spoolfile, it is automatically
                                  selected.

  spool_close(spoolfile)
                                  Closes the specified spoolfile.

  spool_select(spoolfile)
                                  Selects which spoolfile to spool incoming
                                  data with.

  spool_strip(spoolfile,strip)
                                  Sets the 'strip codes' option for the
                                  specified spoolfile. If strip is non-0 then
                                  control codes are not put into the file
                                  and plain text only is stored in the file,
                                  otherwise a direct, raw spoolfile will be
                                  generated [suitable for later replay].

  savescr_text(filename)
                                  Saves a text image of the current screen to
                                  the specified file. If the file already
                                  exists, the text is appended.

  savescr_area(filename,top,bottom)
                                  Saves a text image of the current screen
                                  between lines top and bottom (both counted
                                  from 0). If the file already exists, the
                                  text is appended.

  savescr_sprite(filename)
                                  Saves the current screen as a spritefile.

  print_screen()
                                  Prints the current screen image to the
                                  selected printer. This is the same as doing
                                  a savescr_text("printer:")

f-key functions
---------------

  fkey_set(bank,key,string)
                                  Sets the specified function key (bank=0 for
                                  no shift or control, =1 for shift, =2 for
                                  control and =3 for shift-control) to the
                                  supplied string.

  fkey_load(filename)
                                  Loads the specified f-key file.

  fkey_save(filename)
                                  Saves the current f-key setting to the
                                  specified file.

Keyboard input
--------------

As default when a script is running, keyboard input will be treated as if the
script was not running - ie it will be transmitted - however, it can be
claimed for the script's use (see below).

  key_claim()
                                  Claims the keyboard for script use - after
                                  this call is used, all keyboard input is
                                  buffered for use by the script program with
                                  the calls documented below until
                                  key_release() is called.

  key_release()
                                  Releases the keyboard back to ARCterm.

  key_wait()
                                  Waits for a key to be pressed and returns
                                  its ASCII value (like GET in BASIC).

  key_get()
                                  If a keypress is waiting to be processed,
                                  this call returns the ASCII value of the
                                  keypress, otherwise it returns -1.

  key_ready()
                                  Returns a non-0 value if there is at least
                                  1 keypress waiting to be processed.

Screen output
-------------

These functions pass data to the current terminal emulation.

  prints(string)
                                  Displays string. Brackets are optional.

  print(expression)
                                  Displays expression evaluated in decimal.
                                  Brackets are optional.

  vdu(byte)
                                  Displays byte.

File functions
--------------

filenumber is a number used to refer to a file, and is in the range 1-4.


  file_openin(filenumber,filename)
                                  Tries to open filename for input as
                                  filenumber. Returns a non-0 value if the
                                  open suceeded.

  file_openout(filenumber,filename)
                                  Tries to open filename for output as
                                  filenumber. Returns a non-0 value if the
                                  open suceeded.

  file_openup(filenumber,filename)
                                  Tries to open filename for update (input/
                                  output) as filenumber. Returns a non-0 value
                                  if the open suceeded.

  file_close(filenumber)
                                  Closes the specified filenumber.

  $file_readline(filenumber)
                                  Returns a string read from the specified
                                  filenumber. Strings are LF terminated in the
                                  file, and the LF is not returned by this
                                  call.

  file_writeline(filenumber,string)
                                  Writes string as a LF terminated line to
                                  the specified filenumber.

  file_readbyte(filenumber)
                                  Reads a byte from file filenumber and returns
                                  it.

  file_writebyte(filenumber,byte)
                                  Writes byte to file filenumber.

  file_eof(filenumber)
                                  Returns non-0 if filenumber is at EOF.

  file_ptr(filenumber)
                                  Returns the offset of the file pointer
                                  from the beginning of the file (in bytes)
                                  on file filenumber.

  file_setptr(filenumber,newpointer)
                                  Sets the file pointer for file filenumber
                                  to newpointer bytes into the file.

  file_ext(filenumber)
                                  Returns the extent (length) of the specified
                                  filenumber.

  $dirscan("wildcarded string")
                                  This function will scan directories: call it
                                  first with the wildcarded specification,
                                  then call it subsequently with "" until it
                                  returns an empty string to read all entries.
                                  eg to read and display the current directory
                                  you would use:

                                  string file[40]

                                  file=$dirscan("@.*")
                                  repeat
                                    {
                                    prints file+newline
                                    file=$dirscan("")
                                    }
                                  until(len(file)==0)


Miscellaneous functions
-----------------------

  screen(x,y)
                                  Returns the ASCII value of the character
                                  on the screen at coordinates (x,y) (both
                                  numbered from 0).

  xpos()
                                  Returns the X-cursor position (numbered
                                  from 0).

  ypos()
                                  Returns the Y-cursor position (numbered
                                  from 0).

  tab(x,y)
                                  Moves the cursor to (x,y) (both numbered
                                  from 0).

  pause(time)
                                  Pauses for time cs. This does not process
                                  any incoming data.

  pauseshow(time)
                                  Pauses for time cs. This processes any data
                                  waiting in the receive buffer.

  doubleclick(file)
                                  Issues a wimp message to indicate that the
                                  file 'file' needs loading/running/whatever.
                                  This will *not* load any applications to
                                  do the task, merely pass it to any loaded
                                  ones.

  logging_name(nameforlogfile)
                                  This should be used after a connection
                                  has been established and defines a name for
                                  the connection to be used in the phone log
                                  (if enabled).

  logging_rate(callrate)
                                  This is used (usually at the same time as
                                  logging_name) to set a call rate to be used
                                  to calculate the cost of the call for the
                                  phone log.

  hostmode()
                                  This enters the hostmode. If the hostmode
                                  is terminated via the terminate option on
                                  the maintenance menu, the script will
                                  continue to execute, but if the hostmode
                                  is closed down by any other methods, it will
                                  not.

  sound_replay(file)
  replay_sound(file)
                                  This will replay the specified Armadeus
                                  sound sample direct from disk (hard disk
                                  users only!). It expects the file in
                                  linear signed format.

  window_open()
  openwindow()
                                  This will open the ARCterm terminal window
                                  and any associated keypads.

  window_close()
  closewindow()
                                  This will close the ARCterm terminal window
                                  and any associated keypads.

  end()
                                  Terminates script execution.

  shutdown()
                                  Terminates ARCterm run.

  chain(filename)
                                  Terminates current script execution and runs
                                  specified script.

  $getenv(variablename)
                                  Returns the value of the OS variable
                                  specified, eg to display the time you
                                  might use:

                                  prints $getenv("sys$time")+newline

  oscli(command)
                                  Executes the specified *-command. Do not use
                                  this function to run programs - only non
                                  memory corrupting tasks. 

  system(command)
                                  Executes the specified *-command after moving
                                  ARCterm out of the way. The *-command will
                                  have whatever space is left over, so to run
                                  big tasks you will need to increase the
                                  wimpslot in the !ARCterm.!Run file.

  swi(swinr,regs)
                                  Works this way: swinr is the swi number, regs
                                  is an integer array of at least 10 elements:
                                  When the swi is executed, r0-r9 are set up
                                  to regs[0] - regs[9]. After the swi, regs[0]-
                                  regs[9] are the values of r0-r9 on exit.
                                  For example:

                                  main()
                                    {
                                    integer r[10]

                                    r[0]=0
                                    r[1]=1
                                    swi(6,r)
                                    prints "Version="+$str(r[1])+newline
                                    }

                                  Calls FX 0 to get the OS version and prints
                                  it.

  swinr(swistring)
                                  This complements swi, providing a swi name to
                                  number conversion. For example, the swi(6,r)
                                  above could have been made more readable using
                                  swi(swinr("OS_Byte"),r).

  address(variable)
                                  For use with swi, this returns the address
                                  where the specified variable is stored (if
                                  the variable is an array, then the start of
                                  the array is returned). For example, to call
                                  OS_ReadVduVariables, you pass it an 'in'
                                  array of integers and an 'out' array:

                                  main ()
                                    {
                                    integer regs[10],in[4],out[4]

                                    in[0]=150
                                    in[1]=256
                                    in[2]=257
                                    in[3]=-1

                                    regs[0]=address(in)
                                    regs[1]=address(out)
                                    swi(swinr("OS_ReadVduVariables"),regs)

                                    prints "Total screen size="+$str(out[0])
                                    prints " bytes"+newline
                                    prints "Characters/line  ="+$str(out[1])+newline
                                    prints "Rows/screen      ="+$str(out[2])+newline
                                    }

                                  Be careful not to overrun the array end etc -
                                  it could cause ARCterm to crash.

  time()
  clock()
                                  Return the current value of a centisecond
                                  timer (like TIME in BASIC).

  set(parameter,value)
                                  Sets the specified parameter to value.
                                  Parameters are discussed in the ARCterm
                                  manual.

  whenever(whenevernr,string|off,function)
                                  whenevernr is in the range 1-4.
                                  Up to 4 'whenever's can be executing
                                  concurrently. Whenever the supplied string
                                  is 'seen', the function passed is called.
                                  To disable an enabled whenever, pass
                                  'off' in place of the string (NOT as a string
                                  though, eg: whenever(1,off) ).

                                  An example of its use:

                                  whenever(1,"Press any key",presscr)

                                  presscr ()
                                    {
                                    type cr
                                    }

Modem driver functions
----------------------

The execution of these function depends on the modem driver code, which
can vary depending on the capabilities of the modem.

  modem_dial(numberstring,how)
                                  Dials and tries to connect to the supplied
                                  number. If how!=0 then it will tone dial
                                  (if the modem is capable!) otherwise pulse
                                  dialling will be used. It returns:

                                  0 - sucessful connect
                                  1 - no connection (no more info)
                                  2 - busy
                                  3 - no dial tone
                                  4 - number blacklisted by modem

  modem_disconnect()
                                  Disconnects the modem.

  modem_connect()
                                  Makes modem go online in originate mode
                                  and try to connect. Returns:

                                  0 - sucessful connect
                                  1 - no connection

  modem_answer()
                                  Waits for an incoming call and tried to
                                  connect. Returns:

                                  0 - sucessful connect
                                  1 - no connection
                                  (depending on the modem, modem_answer might
                                  return periodically with a no connection
                                  code).

  modem_errorcontrol(typestring)
                                  Tries to implement the specified error
                                  correction on the modem connected (this
                                  must be done before a connection is
                                  established with a remote system). Valid
                                  parameters are:

                                  "off"       - disable error correction
                                  "vasscom"   - enable vasscom error correction
                                  "mnpx"      - enable MNP level x (1-5)
                                                error correction.

                                  (on most modems if you specify mnp5 it will
                                  imply v42 and v42bis).

  modem_standard(standardstring)
                                  Tries to set modem and serial port up for
                                  the supplied standard, eg.

                                  modem_standard("v22bis")

                                  tries to configure modem and computer for
                                  v22bis operation (2400/2400). Not to be
                                  relied upon as it's shaky with a number of
                                  modems!

  modem_shutdown()
                                  Unused in most modem drivers, this is called
                                  as ARCterm quits to perform any last minute
                                  tidy of the modem.

Predefined or system strings
----------------------------

  cr                = $chr(13)
  return            = $chr(13)
  lf                = $chr(10)
  newline           = $chr(13)+$chr(10)
  escape            = $chr(27)

  downloadpath      = the default download batch path
  runpath           = the path of the currently running scriptfile.
                      For example, if the script

                      SCSI::SCSI_540.$.Cdev.Seven.Test

                      was being run, runpath would be:

                      SCSI::SCSI_540.$.Cdev.Seven.

                      (Note that runpath includes the terminating '.').

System integer
--------------

  filesdone         = number of files transferred by last upload() or
                      download() command.
