ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/JSAGE/ZSUS/Z3HELP/A.LBR/ARUNZ.HZP/ARUNZ.HLP

Text File | 2000-06-30 | 13KB | 372 lines

;
                        -- ARUNZ --

                O -- 
 Overview of ARUNZ 

                C -- 
 Configuring ARUNZ 

                -- Programming ALIAS.CMD --

N --  
 Alias Names             P -- 
 Script Parameters 
E --  
 Example ALIAS.CMD       S -- 
 Programming Summary 
      
 file 
:O.

 Program:   ARUNZ 0.8.


 Syntax:   ARUNZ aliasname commandtail


 Function: 

  ARUNZ  searches  through  the file ALIAS.CMD for an alias name
  matching the indicated alias name.  If a  match  is  found ARUNZ
  expands  the  script associated with the alias name and  creates  a
  new  command  line  from  this   expanded script.


 Options:   None.


 Comments: 

  ALIAS.CMD is a standard text file.  Each line of the file contains
  an alias name followed by a space and the script associated with
  the alias name. Information on how to program ALIAS.CMD files is
  located elsewhere in this help file.


 Selected Error Messages:   Self-explanatory.


 Examples of Use: 

  A typical use of ARUNZ would be as an extended command processor
  (ECP). The user might rename it to CMDRUN so that ALIAS.CMD is
  automatically searched when the command processor fails to find a
  program the user attempted to invoke.
:C

 Configuring  ARUNZ.COM 

As with all ZCPR3 tools ARUNZ is installed with Z3INS.COM and
SYS.ENV.  It also has other options that can be set by using a
debugger such as DDT to change flag bytes at the beginning of the
program.  Two flags are used to determine what messages the program
displays to the user as it runs.  The others determine the path ARUNZ
uses when searching for the file ALIAS.CMD.

The flag bytes are easily located using a debugger.  The program
begins at 100h.  The very first instruction of the program is a jump
to the actual start of the program.  The six bytes preceding the
address in the jump instruction are the flag bytes.

If, for example, the first instruction is "C3 11 01" then the start
of the program is at address 0111 and the bytes 010B - 0110 are the
flag bytes.  The following code segment of ARUNZ shows the relative
position of the flag bytes.


 Configuring ARUNZ.COM 


 ARUNZ SOURCE CODE SEGMENT 

quietecp:
         db  00000100b  ;quiet flag for ECP invocation
quietf:  db  00001110b  ;flag to control display of messages
          ;  ||||||||  ;set bit to display designated msg
          ;  |||||||*---- signon message
          ;  ||||||*----- running alias "x" message
          ;  |||||*------ alias.cmd file not found
          ;  ||||*------- alias "x" not found
          ;  |||*-------- extended command processor error
          ;  ||*--------- shell invocation error
          ;  **---------- bits not yet assigned

pathf:   db  0         ;path search flag (0 = do not use path)
rootf:   db  0         ;0 = use entire path / FF = root only
cmddrv:  db  0         ;drive to use if not path (A=0)
cmdusr:  db  0         ;user to use if not path
start:


 Configuring ARUNZ 


 Message Display Control 

The bits making up the message display flag bye control the display
of the various messages produced by ARUNZ.  If a bit is set, the
message is displayed; if it is zero, then the message is not
displayed.

There is a special feature for those who are running the new version
(3.1) of the ZCPR3 command processor (CP).  With that CP a program
can tell if it was called as an extended command processor (ECP) or
by the user (just as error handlers and shells can tell how they were
called).  One may then wish to have messages displayed or suppressed
in different ways depending on how ARUNZ was invoked.  If you are
running the new CP, then you can set the alternate quiet flag.
QUIETECP will be substituted for QUIETF when ARUNZ is invoked as an
ECP.  Users with the standard CP should be concerned only with QUIETF
since all calls to ARUNZ will appear to be manual calls.


 Configuring ARUNZ.COM 


 Search Path 

By setting the appropriate flags, ARUNZ can be configured to search
for ALIAS.CMD along the current ZCPR3 path, in the root directory or
in some specified directory.
:N

 Alias Names 

There are a number of forms that an alias name may take.  It may be an
unambiguous name, an ambiguous name, have multiple names, be a
default name or some mix of these forms.


 Unambiguous Names. 

The simplest form an alias name can take is an unambiguous name.


 Example: 

  RDIR DIR $*

This alias script "DIR $*" will be expanded only if the alias name
passed to ARUNZ matches "RDIR".


 Alias Names 


 Ambiguous Names 

Alias names may also contain wildcards.  The wildcard character is
"?".  The wildcard character will match any character.


 Example: 

  ?DIR DIR $*

The alias script "DIR $*" would be expanded if the alias name passed
to ARUNZ were, for example, "RDIR" or "XDIR".


 Alias Names 


 Multiple Names 

ARUNZ will also accept multiple alias names.  The names must be
separated by the character "=".


 Example: 

  XDIR=RDIR=SD=D=XD DIR $*

The script "DIR $*" would be expanded and a command line built if any
of the names were passed to ARUNZ.


 Alias Names 


 Default Name 

ARUNZ also accepts a default alias name.  This default is any
alias name preceded by the character ":".


 Example: 

  :Default SAK /bp3 The program "$1" was not found.

Any alias name passed to ARUNZ will match this default alias name.  If
used, it should be the last alias name in the ALIAS.CMD file since
ARUNZ will not search for matches beyond the default alias name.  It
could be used, as above, to create an error handler.


 Alias Names 


 Mixed names 

The different forms of alias names can be mixed on one line.


 Example: 

  ?DIR=SD=XD=D DIR $*

This alias name will match "XDIR" and "RDIR" as well as "SD".
:P

 Script Parameters 

Any command that is acceptable at the command console prompt may be
in an alias script in ALIAS.CMD.  In addition there are many
parameter expressions that may be placed in ALIAS.CMD that ARUNZ will
expand before building a new command line. The following is a list of
the parameters with a description of how they will be expanded:

Parameter     Operation

^             precedes character to be expanded as control
              character
$^,$$"        "$^" quotes "^" and "$$$ quotes "$".

$*            returns entire command line tail.
$-n           returns the command tail less the first n
              tokens, n = 0..9 ($-0 is equivalent to $*).
$0            returns the alias name passed to ARUNZ.
$n            returns the command line parameter token n,
              where n = 1..9.


 Script Parameters 

$:n           returns the file name only in command line
              token n, n = 1..9
$.n           returns the file type only in token n, n =
              1..9

$Dn           returns the currently logged drive, A..P, if
              n=0 or the drive specified in token n if n =
              1..9
$Un           returns the currently logged user, 0..31, if
              n=0 or the user specified in token n if n =
              1..9.

(The ALIAS.CMD programmer should note that the above drive
and user parameters are implemented in ARUNZ differently
than they are in ALIAS.COM.)


 Script Parameters 

$Fn           returns the full name and type of system file
              n, n = 1..4.
$Nn           returns the name only of system file n, n =
              1..4.
$Tn           returns the type only of system file n, n =
              1..4.



 Script Parameters 

$"            All the text between this parameter and a matching
              quote (") in the script (or the end of the line if that
              comes first) will be echoed on a new console line as a
              prompt. The user's response to the prompt will then be
              included in the new command line.  Any input after a
              semicolon is ignored. This ensures that the user cannot
              slip in an extra command when you want only the
              parameters to a command.  Note that single quote may be
              included in the prompt string.

$'            This parameter functions much like the above $" except
              that it does not ignore input after the semicolon.
              Since the parameter takes the entire input line from
              the user, it can be used to prompt the user for a
              series of commands with semicolon separators.  One may
              also embed double quotes within the prompt.



 Script Parameters 

$Mnnnn        This parameter returns the hexadecimal value of
              hexadecimal address "nnnn". The address must be exactly
              four characters representing a hexadecimal address.
              The contents of that address is memory will be
              converted to two characters representing the hex value
              and placed into the command line.

$Rn           This parameter returns the value of system register n,
              n= 1..9.  The value of the system register n is given
              as two characters.

$Z            causes the alias to be executed as a recursive alias
              (clears any commands on command line after alias
              invocation)

(NOTE: If you have an alias call itself without using the parameter
for recursion you will eventually get a command line overflow as
result of the stacking of the command tails.  If you use the
recursion parameter, however, you will be able to go on indefinitely.)
:E

 Example ALIAS.CMD File 

ARUNZ.CMD is a text file and can be created with any editor or word
processor that produces standard ASCII files.  Each line of this file
consists of the name of the alias script and a space, followed by the
prototype command line, including the parameter expressions allowed
in aliases. There is no limit to the number of such lines that the
file may contain.  Here is an example ALIAS.CMD file that defines
aliases using many of the extended parameters now allowed (lines are
wrapped here but must not be wrapped in the actual ALIAS.CMD file):

     param echo parameters are "$1 $2 $3";echo
     tail echo tail is "$*";echo
     tail2 echo this is the tail less two parameters;echo --> "$-2";echo
     name echo alias name is "$0";echo
     diskuser echo logged disk is $d0 / logged user is $u0;echo
     disk echo logged disk is $d0;echo
     user echo logged user is $u0;echo


 Example ALIAS.CMD File 


     sysfile1 echo system file 1: "$f1";echo name is "$n1";echo type is
                "$t1";echo
     recurse $zxif;echo loop again?;if in;arunz $0;else;echo the loop
                is now complete;fi

(Recurse would not cause a command line overflow.)


     norecurs xif;echo loop again?;if in;arunz $0;else;echo the loop
                is now complete;fi

(Norecurs would eventually cause such an overflow.)


 Example ALIAS.CMD File 


     parse parsing parameter 1;echo directory: $D1;echo user: $U1;
                echo file name: $:1; echo file type: $.1

     D DIR $"enter file spec: "

(D would run the Dir command with a file spec given by the user in
response to the prompt.)
:S

 Programming Summary 

 ^             precedes character to be expanded as control character
 $^, $$        "$^" quotes "^" and "$$" quotes "$".

 :             precedes the default alias
 =             separates names in multiple name alias
 ?             matches any character in alias name

 $*            entire command line tail
 $-n           command line tail less first n tokens, n = 0..9
 $0            the alias name passed to ARUNZ
 $n            command line parameter token n, n = 1..9
 $:n           file name in token n, n = 1..9
 $.n           file type in token n, n = 1..9


 Programming Summary 

 $Dn           currently logged drive, if n=0 or drive
               specified in token n if n = 1..9
 $Un           currently logged user, if n=0 or user specified in token
               n if n = 1..9

 $Fn           full name and type of system file n, n = 1..4
 $Nn           name only of system file n, n = 1..4
 $Tn           type only of system file n, n = 1..4

 $"            echos text between " and following " (or EOL)
               as a prompt and includes the user's response
               in the command line.  All input after a
               semicolon is ignored.

 $'            similar to $"text except that it does not
               ignore input after the semicolon.



 Programming Summary 

 $Mnnnn        hexadecimal value of hexadecimal address
               "nnnn".

 $Rn           value of system register n, n= 1..9

 $Z            execute as a recursive alias (clears any
               commands on command line after alias
               invocation)



  0131Háááá '╖'          F╖áattributσáoptioεácharacte≥ááááá          ì
áá0132Háááá OFF (00H)    F╖áattr