ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/robot-pd/12400.ZIP/12400B.DSK/manual03.txt

Text File | 1998-04-30 | 17KB | 540 lines

                C H A P T E R   T H R E E


3.1 External Commands

External commands are commands that were not  included  in
the operating system code due to memory  restrictions,  or
because their  use  is  somewhat  limited.  Such  commands
aren't   restricted by memory  and  frequently  allow  for
more flexible operation.

Note, however, that none of these commands (or their  type
selectors) may be abbreviated.


3.2 External Command Dictionary

3.2.1 The COPY Command

Format :COPY ++[<selector>] <source file path>
 ++<++[<selector>] <destination file path>>

If the selector "A" is used, ASCII files  can  be  copied.
Place the selector in front of the file that is  (or  will
be)ASCII. Thisoption MUST be used to COPY COMP  object
files-ie the &A selector should appear in  front  of  both
file paths.

The selectors W & C can also be used to count and  display
the number of words and characters respectively.

By placing the "A" selector in  front  of  either  the
source or destination files but not both, the format of  a
file can be changed in the process-say from ASCII to text.

If a list of destinations (and their selectors) are  given
then multiple copies of the source file can be made.

AMSDOS can't keep track of  two  disks  sharing  the  same
drive. As a result, special buffered copying routines have
to be usedwith singledrive machines. This may lead  to
some copying problems, particularly when the files contain
numeric data. This problem  will  not  bother  dual  drive
owners.

Example:1>COPY login.usr login.old
This makes  a  copy  of  the  login  file,  and  calls  it
"login.old".
          2>COPY &A myprog.bas &A ../myprog.bas
This makes a copy of the ASCII file "myprog.bas" and  puts
it-still in ASCII format-into the parent directory.


3.2.2 The REMOVE Command

Description :REMOVE

Format :REMOVE <object name> [++<operand>]

The REMOVE command  removes  objects  from  their  current
environment, eg the disk. The types of objects  which  can
be removed are given below, along with the related  object
name.


"DDIR" - Data DIRectory.

This is followed by a <directory path> which must point to
a data directory. This directory will then be removed from
the disk. Note that any files will  be  removed,  but  the
presence of subdirectories will  cause  the  operation  to
abort.


"SDIR" - System DIRectory.

This is followed by a <directory path> which must point to
a system directory. This directory will  then  be  removed
from  the  disk.  Note  that  files  will   removed,   but
subdirectories will cause abortion of the operation.  Note
that the main system directories can't be removed.


"FILE"

This is followed by a <file path>.  The  given  file  will
then  be  removed  from  the  disk,  unless  it  is  write
protected. Never remove any of the system files (which may
be write protected anyway). If a star follows a file  name
when the contents of a directory are listed on screen,  it
indicates that it is write protected.

In this instance, AMSDOS wild cards can be used eg;
1>REMOVE *.BAK

Several operands can be given to each  directive  allowing
multiple examples of the SAME type to be  removed  in  one
go.

Example:1>REMOVE FILE ../myprog.bas /COM/oops.dat
This removes two files, one  is  called  "myprog.bas"  and
exists in the parent directory. The other is called "oops.
dat" and exists in the COMmand directory.


Error Messages

"Can't REMOVE <item>"-REMOVE doesn't recognise  the  given
item directive.

"Not a data directory path"-You have attempted to remove a
system directory using the DDIR directive.

"DATA directory(s) removed"-Operation complete.

"<directory.name> is a parent directory-ReMove  subdirect-
ories first"-Use REMOVE to erase subdirectories first eg;

                RM DDIR sub1 sub2 parent

"Not a system directory path"-You have attempted to remove
a data directory using the SDIR directive.

"SYS directory(s) removed"-Operation complete.

"Attempted to  remove  a  reserved  system  directory"-You
can't remove the main system directories.


3.2.3 The MAKE Command

Format :MAKE <object name> ++<operand>

This command creates various objects, as indicated by  the
object name:-


"DDIR" - Data DIRectory

Format:MAKE DDIR <file path> <disk number>

This command allows the user to create a  directory  whose
files will be held on a data disk. Such a  directory  can,
however, belong to a system directory. Also, with  version
11, Centrox allows disks to  hold  both  system  and  data
directories. In practice  this  likely  to  be  of  little
advantage!

The "file name" given with the file path is treated  as  a
directory name eg;
1>MAKE DDIR ../example 2
This will create a "brother" or "sister" directory on  the
second disk (which is usually a data disk).


"SDIR" - System DIRectory

Format:MAKE SDIR <file path> <disk number>

This command allows the user to create a  directory  whose
files will be held on a system disk. Such a directory can,
however, belong to a data directory.


Error Messages

"Can't  make  <item>"-MAKE  doesn't  recognise  the   item
directive given.

"Can't hold any more data directories"-There  is  no  more
room to define data directories.

"Data directory made"-Completion message.

"Illegal disk number"-only ten disks can be defined,  with
numbers between 1 & 10.


3.2.4 The PCAT Command

Description :Print ConCATenated

Format :PCAT ++<[&<selectors>] <file path>>

Works in the same way as the CAT command, except that  the
text is sent to the printer. This  means  that  PCAT  will
"join together" the given files and send the result to the
printer.

PCAT uses the standard printer variables  to  control  the
printer  but  these  can  be  set  using   the   following
selectors:-

A-Select print out of true ASCII. This allows the user  to
print out listings of compiler object code.

L<length>-Set page length.

S-Skip perforations.

W-Wait at perforations.

I-Ignore perforations.

PCAT automatically switches the  printer  to  the  English
character set  when  printing  pound  signs,  and  to  the
American character set when printing hash signs.  For  all
other characters the printer is set  to  the  default  set
(either American or English).

The following selectors control this function:-

E-Select English character set to be the default character
set.

U-Select USA character set to be the default.

e++<Hex ASCII  codes>.<space>-Define  sequence  to  change
printer to English character set.

u-As above, but defines codes for USA character set.

PCAT defaults to standard EPSON codes, these are:-

ESC R 0 - USA set
ESC R 3 - English set.

These could be defined as:-

&u1B5200.  - USA {1B, 52, 00}
&e1B5203.  - UK  {1B, 52, 03}

If the switch is not required,  simply  define  both  code
sequences to be NULL:-

                          &u. e.

Note that the dot MUST be followed  by  a  space  if  more
selectors follow.

PCAT is ideal for a draft output  of  text  but  the  more
flexible FORMAT  should  be  used  to  produce  the  final
document. Note also that  PCCs  will  be  indicated  by  a
double strike type face instead of the VDU inverse colours
system.

Note that unlike CAT, PCAT does  correctly  translate  the
backward "straight" quote into a double  quote  (").  This
conforms with the Centrox text standard.

Error Messages

"Can't open <file name>"-The given file  can't  be  opened
for reading.

"<value>lines  and  <value>  characters  printed"-standard
report.


3.2.5 The MAIL Command

Format :MAIL [<user name>]

The MAIL command allows users to  exchange  messages  with
each other. Since such messages are stored on  the  system
disk, users must share the same system disk. MAIL does not
check that the user specified  actually  exists-it  simply
saves the message onto the disk.

If no user name is given, the contents of  your  mail  box
will be displayed on screen.

When entering the message the DEL and RETURN keys  act  as
normal. Press [CONTROL+D]  to  exit  and  send  the  mail.
Pressing  [CONTROL+C]  will  exit  to  the  Shell  without
sending any mail.

Error Messages

"Mail box full"-There is no more room in  the  recipient's
mail box for new messages or any more lines of the message
being sent.

"Mail read"-You have seen all the mail sent to you.

"No mail"-You haven't received any mail.


3.2.6 The Hook Command

Format :HOOK [<file path> [[++<<selectors>]
 ++<arguments>]

Hook is used to  extend  the  power  of  the  login  file.
Without using Hook, only one external or transient program
can be invoked  by  the  login  mechanism.  Such  external
invocations  operate  correctly,   but   cause   automatic
termination of the login process. This means that  further
commands in the login file will be ignored.

Note:Use of external or transient programs in ANY  way  in
the login file will disable the MAIL detection facility.


3.2.6.1 Shell Script

HOOK provides a simple but useful extension to the  normal
range of Centrox  Commands.  By  invoking  HOOK  from  the
command line, and supplying it with a file path. This file
should contain a program  written  in  a  language  called
"Shell Script". The details of  this  language  are  given
below:-


3.2.6.2 Shell Speak (Commands)

All commands are prefixed by a single dot (".").

Syntax :.writes <string>

Write the given string to the VDU.

Syntax :.written <Numeric Expression>

Write the given number to the VDU.

Syntax :.writec <Numeric Expression>

Write the given character to the VDU.

Syntax :.repeat

Causes HOOK to store the current line number on  the  loop
stack. For further details see UNTIL and WHILE.

Syntax :.until <Numeric Expression>

The numeric value is evaluated and if the result is  false
(zero), then the top loop address is retrieved and a  jump
made to that line.

Syntax :.while <Numeric Expression>

Works  in  the  same  way  as  UNTIL,  but  jumps  if  the
expression yields a TRUE value.

Syntax :.set <0..9> <Numeric Expression>

Sets the indicated variable (number 0 to 9) to  the  given
value.

Syntax :.dec <0..9> <Numeric Expression>

Subtract the given value from the given variable.

Syntax :.inc <0..9> <Numeric Expression>

INCrement variable.

Syntax :.end

Finish program.

Syntax :.onlyif <Numeric Expression>

If the <Numeric Expression> yields FALSE,  then  skip  the
next line in the program.

Syntax :.oldloop

After a WHILE or UNTIL command, the loop address is  lost.
This command restores the last  loop  address.  Successive
OLDLOOP commands can restore successive (ie; nested)  loop
addresses provided they have not  been  overwritten.  This
can be used to simulate logic AND.

Syntax :<Shell command line>

Invokes the specified Shell command-internal or  external.
Note  that  execution  will   be   slower   than   normal,
particularly when executing external commands.

Note the omission of the leading dot.

WARNING:Hook pulls a couple of dirty tricks  in  order  to
retain control of the computer when the  external  command
has  finished.  It  is  possible  that  this  could  cause
problems. In particular, the ^C abort  function  may  only
work temporarily.


Syntax :.goto <Numeric Expression>

Jump to the given TEXTUAL line number. Jumps past the  end
of the program will simply cause the program to end.

Syntax :.exec <string expression> [<Shell command tail>]

Evaluates the given string, then passes it-followed by the
command tail-to the Shell for interpreting.


3.2.6.3 Numeric Expressions

ERR - Return last error number.
#<number> - Return number.
v<0..9> - Return value of variable.
=<0..9> <0..9>  -  Return  result  of  comparing  the  two
variables for equality.
k<char> - Returns true if the given character is  returned
by the keyboard. Note that HOOK waits for a new  character
to be typed, rather than just looking in the buffer.

3.2.6.4 String Expressions

a<0..9> - Returnargument#n,as passed  along  with  the
HOOK invocation. The arguments are terminated by spaces.

$<string>  - Return string. The string is terminated by  a
space, but the underscore character `_' is converted  into
a space by the routine.

ERR - Return last error message.


3.2.7 SYMBOL

Format :SYMBOL [<file name>]

Redefines the character set. The optional <file.name>  can
be specified to cause a different set to  be  loaded  from
disk. The file should be the "slice" of memory relating to
characters  32  to  127  inclusive.  Always  ensure   that
character 127 is defined as in the manual.

If the file path is given  as  "AMSDOS"  then  the  normal
characters will be adopted. If no file path is given, then
the Centrox characters will be loaded.  Note  that  FORMAT
and LOGON  will  ALWAYS  restore  the  system  to  Centrox
characters, unless the file "0:CENTROX.CHR" is changed.

There are several ways of generating a data file:-

         1.Use "Art  Studio"  or  some  other  package  to
redefine characters. Follow the program's instructions  on
loading the data back into the computer  from  BASIC.  Now
enter:-
              h=HIMEM+1:SAVE"<file.name>",b,h,97*8

Note thatthe fileMUST be saved into USER area#0 of the
SYSTEM disk.


         2.Enter the following:-

         SYMBOL AFTER 32
         ++<<SYMBOL <code>,n0,..n7>
         h=HIMEM+1:SAVE"<file.name>",b,h,97*8

Where the second  line  indicates  a  sequence  of  SYMBOL
commands. See your manual for details on using the  SYMBOL
command.  Try  to  ensure  that  all  vertical  lines   of
characters are two pixels thick.  Vertical  lines  of  one
pixel will appear faint, or may even disappear completely.

Please note that codes above 127 are used by the operating
system, in particular, the "Wall" graphics  (&83  to  &8F)
and the "Bar" graphics (&90 to  &9F)  are  used  "as  they
stand". While the graphics &A4 to  &D8  are  redefined  as
inverse video characters for CTX.

If the file name is given as  DEFN,  followed  by  a  file
path, then SYMBOL will read the file and define characters
from the following data:-

<character>
++<bit.pattern>

Eg:-
A             NB:SYMBOL can't  be  used  to  redefine  the
00111000      double quote character. This  limitation  is
01111100      due to CTX  (in  common  with  most  Centrox
11000110      programs) translating the double quote  into
11000110      character 161.
11111110
11000110      In practice, this translation means that the
11000110      double quote will appear as a single  quote.
00000000      From my own experience I have found that  it
              is easy to get  confused  between  a  double
quote and a single quote. SYMBOL can be  used  to  rectify
this problem.

The result will only be visible when  running     01100110
programs such as CTX. This  should  cause  no     01100110
problems as at the  other  times  the  double     01100110
quote character is easily distinguishable.        01100110
                                                  00100100
Given opposite are the codes to redefine  the     00000000
character. Note that the double  quotes  will     00000000
not appear as such from within CTX.               00000000


3.2.8 DMAP

Format :Directory MAPper

Syntax :DMAP

This program simply examines the directory  structure  and
reports the numberof disks in use.It shows Graphically
how the directories inter relate.

3.2.9 TWITCHER

Syntax :TWITCHER <file path> <exec line> <Tick rate>

Adds an  event  to  the  event  schedule.  The  file  path
indicates what file  to  load  before  adding  the  event.
Typically, this file will contain the event  handler.  The
exec line is the line to  be  called  when  the  event  is
kicked. The tick rate (in fiftieths of a second) indicates
how often to kick the routine. Since  only  one  timer  is
used, the highest requested  tick  rate  is  always  used.
Events should check the  value  in  E.TICK%  to  determine
whether they should respond on every tick, or skip  a  few
ticks.

3.2.10 PATH

Syntax :PATH ++<Directory path>

Lists the directories in which the Shell is to  look  when
an external command is issued if the external  command  is
not found in one of  these  directories,  then  the  error
message "<name> ?" is issued. Note the the path "/COM"  is
always searched, and  that  the  Shell  defaults  to  also
searching "." (the current directory).

t  inc