;


                            Summary of ARUNZ Parameters

                                     Jay Sage
                                   March 2, 1989

                                                     
                           A-  Parameter Summary     
                           B-  Qualifier Symbols     
                           C-  Parameter Expressions 
                           D-  Special Directives    
                                                     
:A
 Parameter Summary - 1/3 


format	'f'	=	H   hex			D   3 decimal
			F   floating decimal	T   two decimal
                        A   ASCII               O   one decimal


module	'm'	=	B   BIOS		M   MSG
			C   CCP/CPR		N   NDR
			D   DOS			P   PATH
			E   ENV			R   RCP
			F   FCP			S   SHL
			I   IOP			X   XFCB
			L   MCL
 Parameter Summary - 2/3 


component  'c'	=	N   FN			D   drive or default
			T   FT			U   user or default
			F   FN[.FT]		P   prefix (with colon)
			Z   Crunched Type	S   short prefix
			Q   Squeezed Type	C   converted token (to DU:)


units	'u'	=	Y  year			H  hour (mil)
			M  month		C  hour (civ)
			D  day			N  minute
						A  AM/PM
 Parameter Summary - 3/3 


parameter forms:	full token		$#
			parsed token		$Tc#
			home directory		$HD  $HU  $HB
			full command line	$!
			full command tail	$*
			tail less tokens	$-#
			memory contents		$Mf####
			register contents	$Rf##
			system file		$Sc#
			get prompted input	$"prompt"
			use prompted input	$'c#  ( c: L ; E )
			ENV address		$Am
			offset ENV address	$+m
			ENV address content	$@fAm
			offset ENV content	$@f+m####
			date/time		$Du

:B
 Definitions - 1/6 

     A line in the ALIAS.CMD file takes the following form:

	alias_name_form   alias_script

The alias script is the prototype command line.  It contains normal characters
and parameter expressions,  as discussed in detail in  this  DOC file.   It is
separated from the alias_name_form by any number of tabs and spaces.  Thus the
scripts can be formatted neatly to make the file easier to read.

     The  alias_name_form consists  of  any  number of  individual  alias name
expressions connected  by  equal signs.   There must be no imbedded  spaces or
tabs.   An individual alias name  expression can be of any length.   It is not
limited to the  eight characters of file  names,  and  it  can contain control
characters,  unlike file names.   The alias  name  may contain several special
symbols which  qualify comparisons with  the  command  verb  passed  to ARUNZ. 
These are as follows:
 Definitions - 2/6 

underscore (_)	This  character in  the  alias  name will match any character.
		Thus the alias  name "_DIR"  will  match  the  commands  LDIR,
		XDIR, and so on.  Their must be a character present.

comma (,)	Characters  that appear  after  this  character  are optional.
		If  characters are present in the command,  they  must  match;
		However,  the characters  need  not be present.   For example,
		"ZP,ATCH" will  respond to  ZP  or  ZPATCH  but not  to ZPTCH.
greater (>)	This  special  character  represents  any name followed  by  a
		period.  It is used with ZCPR34,  which can  accept  a command
		like "PROG.Z80" and pass it to the extended command processor.
		An example alias definition would be

			>Z80  z80asm $tn0

		Just entering the name  with its file type of Z80 would invoke
		the Z80ASM assembler on the file name.
 Definitions - 3/6 

colon (:)	An  alias name  that  begins  with  this  character will match
		any command and is thus the default alias definition.  If used
		at all, it should be the last alias defined.  A command use is
		to make ARUNZ chain to LX or another extended command
		processor.
    
     Several parameters use  qualifiers to further define the data returned by
that parameter.   Since a number of parameters share some of these qualifiers,
we would like to list them here at the beginning.
 Definitions - 4/6 

   Conversion formats (f):

   When byte values are returned by parameters, the values can be converted to
various  formats.  These  formats are  indicated  by a format qualifier in the 
parameter expression as follows.

	 format qualifier		meaning
	 ----------------		-------
                A               ASCII, uses the value AS IS
		H		return two hexadecimal characters
		F		return value as floating decimal
				(leading 0s suppressed)
		D		return three decimal characters
		T		return value as two decimal characters
		O		return value as one decimal character
 Definitions - 5/6 

   System memory module (m):

   For parameters  that obtain  the value of  a memory module from the environ
descriptor, the module is specified by one of the following letters:

	 module qualifier		memory module
	 ----------------		-------------
		B			BIOS	(basic i/o system)
		C			CCP/CPR	(command processor)
		D			DOS	(disk operating system)
		E			ENV	(environment descriptor)
		F			FCP	(flow command package)
		I			IOP	(input/output package)
		L			MCL	(multiple command line)
		M			MSG	(message buffer)
		N			NDR	(named directory register)
		P			PATH	(command search path)
		R			RCP	(resident command package)
		S			SHL	(shell stack)
		X			XFCB	(external command FCB)
 Definitions - 6/6 

   File specification components (c):

      Several parameters return various information about file specifications.
The following  parts  of the file specification  token  can  be returned.  The
first three  letters can  be used  with  all  such parameters.   The remaining
letters can be  used with those  parameters that refer to tokens that can have
directory prefixes as well as file names.

	    file part		meaning
            ---------           -------
	 	N	FN (file name)
		T	FT (file type)
		F	FN[.FT] (complete file name -- name and type)
		D	drive (or logged drive if no explicit value)
		U	user (or logged user if no explicit value)
		P	directory prefix (including the colon)
		S	short prefix (without the colon)
		C	converted file specification (DIR: form, if
			present changed to equivalent DU: -- if invalid
			name, then no conversion is performed)
:c
 Parameter Expressions - 1/12    Command line token parameters: $#


     The  parameter expression  $#,  where '#'  is  a number between 0  and 9,
returns a complete token  from the command line.  $0  returns the command verb
(alias name)  exactly as it  was entered on  the command  line,  including any
directory  prefix and/or file type.   Parameters numbered from  1 to 9  return
the  corresponding  token from the  command line tail.  Tokens  are defined as
contiguous strings of characters.  ARUNZ  is normally configured  to take only
spaces as delimiters between tokens,  but it  can be configured  to allow tabs
as delimiters as well.
 Parameter Expressions - 2/12    Command line token parsing parameter: $T


     The command line tokens  are returned whole,  as is,  by the $# parameter
described above  but  can be  parsed as  file specification expressions  using
the  parameter form  $Tc#,  where 'c'  is  the  component  part  of  the  file
specification to use  (see definition 3 in Section B above)  and  where '#' is
a number from 0 to 9.   The value  0  refers to  the command verb;  the values
1..9 refer to the corresponding token in the command line tail.

     Under ZCPR33 and earlier,  if  the  command  verb  contained  an explicit
directory prefix or if it included a file type, the extended command processor
could not be invoked.  Thus $TT0,  the  file  type  of the command verb, would 
always be null.  The expressions $TD0 and $TU0 would always return the logged-
in drive and user, respectively.  With ZCPR34 this is no longer true.  All the
parameters can take on more general values.
 Parameter Expressions - 3/12    Home directory parameter: $H


     Since $TD0 and $TU0 cannot be counted on  to return  the currently logged
directory values,  special  parameters  have  been provided  for this purpose. 
They are:

		$HD		the home (logged) drive
		$HU		the home (logged) user
		$HB		the home (logged) drive and user together
 Parameter Expressions - 4/12    Command tail parameters: $!  $*  $-#


     The parameter $! represents the entire command line as entered, including
the command verb (alias name) and  the  tail.  It is  useful  in aliases whose 
only purpose  is  to  put  an  explicit DU:  or DIR: directory  prefix  on the 
command.

     The parameter $* represents the  entire  command tail  (after the command
verb),  not including  any leading space characters.   It is useful in aliases
which substitute another command  verb for  the  one actually given  but which
leave the command tail as it was.

     The parameter expression $-#,  where '#' is  a  number  between 0  and 9,
returns  the  command line tail  with the  designated number of leading tokens
removed.   Thus $-0 is the same as $*.   These parameters are useful when some
number of leading tokens  are  given some  special treatment  using  the token
parsing parameters and the rest of the command line is to be passed intact.
 Parameter Expressions - 5/12    Memory contents parameters: $M


     A parameter expression of  the  form $Mf#### returns  the contents of the
memory address given  by ####,  a  four digit hexadecimal address.   Note that
there must be exactly four hex digits,  even  if the  value has leading zeros. 
The 'f' term is the conversion format (see definition 1 in Section B above).
 Parameter Expressions - 6/12    Register value parameters: $R


     The  byte contained in  any  of the 32 user  registers  is returned  by a
parameter expression of the form $Rf##.   The register number must be given as
exactly two hex digits.   The value must be  in the range 00 to 1F.   The  'f' 
term is the conversion format (see definition 1 in Section B above).
 Parameter Expressions - 7/12    System file parameters: $S


     Parameters can return  values based on  the four system file names stored
in  the environment.   The general expression is $Sc#,  where  '#' is  a digit
from 1 to 4 and  where 'c' is  the  component of the file.   Since these files
have no associated directory,  only the first three values usually allowed for
'c' (see definition 3 in Section B above) can be used (N, T, and F)
 Parameter Expressions - 8/12    Prompted input parameters: $"  $'


     The double-quote  parameter  is used to  prompt  for user input.  If  the
parameter expression  $"..." appears,  where  the  dots refer to any string of
characters,  that string of characters will be sent to the screen as a prompt, 
and  one line  of user input  will be  read  into  a  buffer.   In  the normal 
configuration of ARUNZ there can be up to four such prompts and responses.

     The prompt  is sent without case conversion.   A character preceeded by a
caret  is converted to a control character  (^M for return,  ^J for linefeed). 
The dollar sign acts as  an escape character.   Any character after it is sent
as is.  Thus $$ produces '$' in the prompt;  $^ produces '^'; $" produces '"'; 
and so on.
 Parameter Expressions - 9/12    Prompted input parameters: $"  $'

     The  single- quote parameter  is  used  to process the  user's reponse to
prompts.   The parameter expression $'c# is used in the script to retrieve all
or part of the  user's response.   The number '#'  is in the  range 1 to 4 but 
must not be larger  than  the  number of  prompts up  to  that point.   (It is
recommended  that all  the prompts  be placed  at  the  very  beginning of the
script.)  The term 'c' indicates the component to be extracted from the user's
response.   The usual  values described  under definition 3 in Section B above 
can be specified.  In addition, the following values are also allowed:

	L	the entire line of user input
	;	one complete command (i.e., the input is terminated either
		by the end of the input or by a semicolon)
	E	exactly the first token from the user's input

The user's input  can be used repeatedly and  in different ways throughout the
script.  Here is an example:

  TEST  $"Enter a file spec: "echo directory prefix is $'p1;echo file name
	is $'f1
 Parameter Expressions - 10/12    Environment data parameters: $A  $+  $@


     Several parameter  expressions  can  return  information  related to data
extracted from the Z-System environment descriptor.  In this way,  aliases can 
determine   information  independent   of   system   configuration.   This  is
particularly important in the new dynamic systems (NZCOM and Z3PLUS) where the
operating system configuration can change at any time.

     The  $A  paramter  returns  the address  of  various system modules.  The
parameter expression is $Am, where 'm' designates  the module  (see definition
2 in Section B of this document).
 Parameter Expressions - 11/12    Environment data parameters: $A  $+  $@


     The $+ parameter is similar but allows one to compute  an offset from the
address that would be returned by a $A parameter.   The form is $+m####, where 
#### is an exactly four hex digit offset value and 'm' is the memory module to
use as the base address.  The expression $+m0000 is equivalent to $Am.

     The $@ parameter expression is $@fam or $@f+m####.   It performs the same 
calculation as the parameter expression following the '@f' except that instead
of returning the calulated address it  returns the value of the byte stored at 
that address converted according to the format specified by 'f'.
 Parameter Expressions - 12/12    Date and time parameters: $D

     The  parameter expression $Du returns a unit of the date/time supplied by
DateStamper.  The unit 'u' can be any of the following:

	Y	Year (YY)
	M	Month (MM)
	D	Day (DD)
	H	Hour in military form 00-23 (HH)
	C	hour in Civil form 01-12 (HH)
	N	miNute (MM)
	A	Am/pm flag (AM or PM)

In  all cases,  two characters  are  returned  if DateStamper  is running.  If
DateStamper  is  not  running,  then  values  of  '00'  are  returned  for all
parameters except the AM/PM flag,  for which a null string is returned.   Note
that 'M',  having been used for 'month',  could not be used for 'minute';  'N'
was used instead.
:D
 ARUNZ Directives - 1/2 


     There are  two  expressions  that look  like parameters  but are actually
directives  that tell ARUNZ  how  to  work (and  not  parameters  that  return
character strings).

1. ZEX input redirection control: $I

     Whenever  user input  is requested  (as  with the $" parameter), one must
consider  whether  or not  ZEX should be allowed  to supply the input from its
character stream.  ARUNZ normally turns ZEX redirection off.  If the directive 
$I is  placed  before one occurrence of prompted input requested by $"prompt", 
then ZEX input redirection  will be turned on,  but for that prompt only.   If 
there are  two prompts  and you want ZEX to answer both of them, then you must 
put a $I before each prompt.
 ARUNZ Directives - 2/2 


2. Recursive alias mode: $Z

     Normally,  after  a  script  is interpreted and converted into  a command
line, any  commands still pending in  the  multiple  command  line  buffer are
appended to  the alias command line (separated by a semicolon).  This complete
command is then copied into the multiple command line buffer.

     The $Z  directive  tells ZEX  to discard any pending commands and to load
the  multiple  command line buffer with  the  alias  command  line only.  This
capability  was  developed  to  allow  recursive  aliases.   However,   better
techniques are now available.
