CP/M/CPM_CDROM.iso/jsage/zsus/z3help/b.lbr/BA.HZP/BA.HLP

Text File | 1991-11-18 | 10.8 KB | 297 lines

;
                               Program BA (Build Alias)

                           I-
 Introduction               
                           F-
 BA Features                
                           U-
 Using BA                   
                           C-
 Call Syntax                
                           S-
 Getting Started            
                           W-
 Warnings and Cautions      
                           H-
 Hints                      
                           D-
 Display Management         
                           N-
 File Name Syntax           
                           T-
 Technical                  
                           O-
 Operating System Interface 
                           R-
 Restrictions               
                           Z-
 Acknowledgements           
:I


 Introduction: 


   BA (Build Alias) is  a Z-System tool  that  lets  you  develop  and upgrade
aliases with your favorite editor.   No more wondering "what do I do now" when
bringing up a utility with yet another set of editing commands.

   The alias commands are  kept in an ASCII text (non-DOC) file.   BA combines
them with an alias skeleton to make an alias.COM file with the new
commands.
:F


 BA Features: 

   o ZCPR3 environment is supported, but not needed.
   o Restartable; BA can re re-executed with the system GO command.
   o The default alias script file type is "CMD;" the user may supply another.
   o Ambiguous script file names accepted; update all aliases at one run.
   o The CP/M file format of blanks packed to tabs is accepted.
   o Command script may be on separate lines or separated by semicolons.
   o Script lines with a semicolon in column one are retained as comments.
   o Both the old and the new aliases are displayed for reference.
   o The CRC of the new alias file is displayed for reference.
   o The size of the alias is displayed in two forms -
       how many characters are from the scriptfile;
       how many characters would result if all $-fields are fully expanded.
   o These counts are compared with the length of the Command Line Buffer to
       warn you of an impending operational overflow.
   o The pointer to the Environment table is corrected if necessary.
   o The pointer to the Command Line Buffer is corrected if necessary.
:U


 Using BA: 


   Develop the commands to be incorporated into an  alias into a command file,
such  as scriptfile.CMD.   Formats of  a separate command per line or multiple
commands per line,  separated  by  semicolons,  are accepted.   Lines  with  a
semicolon in column one are retained as comments.

The data flow is -

      scriptfile.CMD
          \
        \
          BA ==> scriptfile.COM
        /
           /
      oldalias.COM or DUMMY.COM
:C


 Call Syntax: 

   BA<cr>
The scriptfile name is requested from the console.  The skeleton alias is read
from DUMMY.COM.  The new alias is written to scriptfile.COM.

   BA scriptfile /options<cr>
Commmands are read  from scriptfile.CMD.   The  skeleton  alias  is  read from
scriptfile.COM or DUMMY.COM.  The new alias is written to scriptfile.COM.

   BA scriptfile oldalias /options<cr>
Commmands are read  from scriptfile.CMD.   The  skeleton  alias  is  read from
oldalias.COM.  The new alias is written to scriptfile.COM.

   BA //<cr>
Display on-line help.

For all call formats, the scriptfile will will be supplied a type of CMD and
the aliasfile will will be supplied a type of COM as needed.




 Call Syntax (cont'd): 


Program options -
   F - Display flow control, resume on any character.
   Z - Enable additional program messages.
:S


 Getting Started: 

   Begin by making  a default oldalias skeleton,  named DUMMY.COM.   Make this
file with  an ALIAS call  and  a  one line  command which will be overwritten.
Keep DUMMY.COM in the directory that BA will be running in, as BA will request
it if there is no old alias available.

   Create a file of your alias commands in a lfn.CMD file.

   Run BA with the following call -
   BA lfn<cr>

This will make a lfn.COM file that is your new alias.



 Getting Started (cont'd): 

   Note - A DUMMY.COM alias file  is supplied on  the release diskette.   This
file is  from  a  system  with  the  Environment  table  at  0E6F0.   If  your
Environment table is  NOT at this  address,  BA will  install  the  pointer at
address 0109.

   Note - The alias to start up a system without the current environment table
installed must have the  current address  of  the Command Line Buffer  patched
into it.   BA  will install the  CLB pointer per the running system.   If your
target system is  different,  use your debugger to set address 0369 to the CLB
address.

   Above as of ALIAS 1.1; see Technical to change these addresses.
:W


 Warnings and Cautions: 

   A  caution  message  is  displayed  if  the  number  of  characters  from $
parameters  being  fully expanded might  exceed the length of the Command Line
Buffer.  This estimate is based on the following assumptions -
    $$ is assumed to be 1 character.
    $n is assumed to be 12 characters.
   .$n is assumed to be 3 characters.
   $Fn is assumed to be 12 characters
   $Nn is assumed to be 8 characters.
   $Tn is assumed to be 3 characters.

   A  warning message is  displayed if the  number of characters in  the alias
script does exceed the length  of the Command Line Buffer.   The alias file is
NOT written.  If processing ambiguous scripts, BA reverts to DUMMY.COM for the
oldalias file with the next alias.
:H


 Hints: 

   An alias to update an alias is -
      EDIT $1.CMD;BA $1<cr>

   Having the alias commands in  a separate text file is especially useful for
both program development and for the final documentation.   For example,  when
developing  a Menu system that  calls several aliases,  put the  text  of each
alias into a screen and you have immediate access to the logic.   And when the
project is  operational,  include the  alias  text into  the documentation and
voila` - instant and up-to-date documentation.

   Use I/O redirection  or your print screen  capability to capture the screen
display of a BA run;  the CRC is available to uniquely identify the alias file
later on.
:D


 Display Management: 

   The display  driver  recognizes  XOFF (a Control-S)  to  stop  the display.
Unless the option F is specified, an XON (Control-Q) is necessary to continue.
For the option F, any keyboard character will resume the display.  A Control-C
will abort the program.

   During  a file name input request from  the console,  the following editing
controls are available -
   Backspace - erase the previous character.
   Control-C - abort the execution.
   Control-V - enter the following character literally.
   Control-X - erase all entered data.
   Carriage Return - end the field.
:N


 File Name Syntax: 

   File names may be specified with any of the following forms -
      name.ext - current user, current disk, file name.ext.
      d:name.ext - current user, disk d, file name.ext.
      u:name.ext - current disk, user u, file name.ext.
      du:name.ext - disk d, user u, file name.ext.
   On systems with ZCPR3 -
      ndir:name.ext - named directory ndir, file name.ext.

   If disk "Z:" is assigned to  a BA file,  all data written to that file will
be discarded.



 File Names (cont'd): 

   During  a file name input  request from the console,  the following editing
controls are available -
   Backspace - erase the previous character.
   Control-C - abort the execution.
   Control-V - enter the following character literally.
   Control-X - erase all entered data.
   Carriage Return - end the field.

   The scriptfile may be an ambiguous specification.  For example,
      BA *<cr>
   will create/update all aliases in the current directory.

The new alias goes to the disk/user the scriptfile came from.
:O


 Operating System Interface: 

   BA  operates  on  unmodified  CP/M  without  change.      It  installs  itself
automatically on versions of ZCPR3 and the Z-System.   Since  the self-install
procedure may be incompatible with some or future systems,  the following is a
brief description and a program change to defeat it.

   For the Z-System,  program  address 0109h points  to  an environment table.
The newer versions of ZCPR3 update this  address when  the program is  loaded.
Or,  with the older versions of ZCPR3, the user must update this address, such
as with Z3INS.

   BA validates that  0109h points to  an environment table.   But if  none is
found at that address,  BA scans for an environment table from the fwa(DOS) to
0FF40h.

   If this scan  causes problems,  install  BA with  Z3INS for your system and
disable the scan with the environment table scan control (see Technical).



 Operating System Interface (cont'd): 

   BA requires CP/M 2.0  or greater  for correct operation.   This requirement
may be defeated by the system version check control (see Technical).
:T


 Technical: 

The following locations can be user patched -

   013C    Alias skeleton file name  00-byte termination.
   0156    Alias identification string.           [Z3ENV]
   015C    Default script extension.              [CMD]
   015F    Default alias extension.              [COM]
   0162    Default offset of the script in an alias.  [001Ch]
   0164    Length of an alias file.              [0400h]
   0166    Default offset of the Environment pointer. [0009h]
   0168    Default offset of the CLB pointer.          [0269h]
   016A    Default size of the CLB.              [00C0h]



 Technical (cont'd): 

Default option values; values can be zero or non-zero:

   016C    F-option, zero = resume display on any character.
   016E    Z-option, zero = no detail messages.
   016F    Environment table scan control, zero = do scan.
   0170    System version check control, zero = do check.

The presence of the option letter in the command tail reverses the
default.
:R


 Restrictions:

   CP/M 2.0 or greater or equivalent operating system required.

   Z80 or equivalent computer is required.

   32 user areas/named directories can be accessed.

   16 disk drives (Drives A...P) can be referenced.

   If the System Environment table cannot be found, the message -
      Not a ZCPR3 System.
   is displayed and  a default Command Line  Buffer  length  of  192 bytes  is
   assumed.

   The skeleton alias must have 'Z3ENV' at the standard location  of 0103h and
   be exactly 0400h bytes long.
:Z


 Acknowledgements: 

Trademarks -
    BA: Skunk Creek Computing Services
    CP/M: Digital Research, Inc.
    Z80: Zilog, Inc.
    Z-System, ZCPR3: Echelon, Inc.


Copyright (c) 1985, 1988 Skunk Creek Computing Services
88/10/14