;
                                 DSKNUM.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
DSKNUM.CIM     3k (21)   4F2B  1.5        Gene Pizzetta 9/90       Z3COM4
DSKNUM.COM     3k (21)   6126  1.5        Gene Pizzetta 9/90       Z3COM4

  1- Syntax  2- Disk Labels  3- 1-Drive Opn  4- Errors  5- Config  6- Notes   

   DSKNUM creates consecutively numbered disk labels  (null files) for  use by 
the most popular disk  cataloging  programs,  such as MCAT, NCAT,  and FATCAT.  
The last number used is  normally  stored  internally  so you  don't  have  to 
remember where you left  off.   ZCPR 3.3 or higher,  which includes  NZCOM and 
Z3PLUS, is required.
:1
 Syntax:   DSKNUM {dir:}{label}{.num} {{/}options}

If no  DIR  or  DU  specification is given,  the current drive  and/or user is 
assumed, unless an internal default user has been installed, in which case the
given user specification will be ignored.

If no label name is given, an internal default is used.  The label tag charac-
ter need not be included.   If the given name is longer than seven characters, 
only the first seven will be used.

If no disk number is given, the next number after the internally stored one is
used.

If no option is given, DSKNUM labels a single disk, saves the number used, and
exits.
 Options:   

          A leading slash is not required unless no other parameters 
          are given on the command line.

     M    Multiple label mode.  DSKNUM prompts for a key-press
          before each label is written to disk.  If ESC is
          pressed, the last number used will be saved, and
          DSKNUM will exit.  A ^C will abort the program
          immediately and the internal number will remain as it
          was before the session began.

     S    Do not save last disk number.  Used with or without the
          M option, the internally stored number will remain
          unchanged.


   The target drive will be reset (for safety) before  writing each disk label
under ZSDOS and  CP/M-3 (Z3PLUS);  otherwise,  the entire disk system  will be
reset.   Whether a  reset is done before  saving the  last  number used  is  a
configuration option (see below).

   The last used label number is saved internally in a very simple way.  It is
stored as  a two-byte  word in the first record of the program in memory.   At
each exit that record is  written back to the program's COM file on disk.   On
initial invocation DSKNUM gets its current name and the DU where it is located
from the ZCPR external file control block.   That data is  stored in memory so
that if DSKNUM is invoked  again  with the GO or JUMP command,  it won't think
its name is "GO" or "JUMP".
:2
 Disk Labels - 1/3 

   DSKNUM creates consecutively numbered disk labels  compatible with commonly
used disk cataloging programs, such FATCAT, MCAT, and NCAT.   These labels are
null (0k) files with  a three-digit  number in the filetype.   As distributed,
DSKNUM starts with number  "001".   FATCAT does  not  allow  a  disk number of
"000".   Of course,  you can start with  any number by entering that number on
the command line.  DSKNUM will store the number and increment it from there.

   The name part of the label  may be almost anything, but the first character
must be  a special "tag" character that  makes the label unique.   FATCAT,  in
addition,  requires that the label come  first (excluding a !!!TIME&.DAT file)
after the filenames on the disk are sorted.   Thus the tag character should be
one that is early in the  ASCII  order and that is not  used  by  other files.
Here are the possibilities:

     !    Earliest legal character in ASCII order, but a label
          with this character cannot be manipulated by the CCP
          under CP/M-Plus.
 Disk Labels - 2/3 

     #    Earliest legal character with no known limitations.

     $    Commonly used by temporary files, particularly by SUB
          and SUBMIT.

     %    Used as leading filename character by CP/M MUMPS.

     &    No known limitations.

     +    No known limitations.

     -    Probably most commonly used tag character, but it is
          also used by many other files, such as -READ.ME,
          SIG/M's -CATALOG.nnn, etc.

     /    No known limitations, but it's getting late in the
          ASCII order.  There is also a CP/M program named "/".
 Disk Labels - 3/3 

   I strongly recommend that you use  "!" or "#" as your tag character because
they are the earliest in ASCII order and they are used by few other filenames.
Do not use the hyphen ("-").   It is used by too  many  other  files and it is
late in the ASCII order.

   DSKNUM will not  let  you  write a label to  a disk that already contains a
filename beginning  with  the  tag  character.   Thus  you  are protected from
forgetting to change disks when using  the  M option and  from  confusing your
cataloging program.   The tag character is the distributed version is "#", but
that can be changed (see below).
:3
 Single-Drive Operation 

   If you have a  single  floppy  disk  drive and you want to load DSKNUM from
disk, you should have no problem.

   Use the  M (multiple label) option  on the  command  line  and then,  while
DSKNUM is running you can change disks freely.  When you press ESC to quit the
program,  DSKNUM will look at the  drive  for its COM file and,  if it doesn't
find it, will prompt for the program disk.

   If this mode of operation is  to  be  used,  you should configure DSKNUM to
reset the drive before saving the last number (see Configuration).
:4
 Errors 

   If an error occurs,  DSKNUM will exit  with an error message in most cases.
Under the M option, however, a full directory or an existing label will merely
cause DSKNUM to prompt again for a disk.

   All errors will set the ZCPR3 error flag to the following values:
     2    Invalid DU or DIR given on the command line
     9    Invalid number given or number exceeds 999
    11    Out of directory space
    16    Label already exists on target disk
    19    Invalid option given
     4    User aborted (^C) or file write error

   In multiple label mode (M option), where errors 11 and 16 do not cause the
program to exit,  the error flag  will set according to the most recent error
encountered.
:5
 Configuration - 1/5 

   The various configuration options discussed  below can be  easily set using
ZCNFG   (version   1.6  or  later)   with  the   included  configuration  file
(DSKNUMnn.CFG).   Do not  change the  name of  the  configuration  file.   The
configuration filename is held internally in DSKNUM.COM so that ZCNFG can find
it even if you rename DSKNUM to something else.   For  instance,  I maintain a
second version  version  of DSKNUM,  called LBRNUM,  that  I  use  to label my
archival library disks.  The DSKNUMnn.CFG file is found automatically by ZCNFG
for LBRNUM too.

   As an alternate,  the COM  file  can  be patched with any patching tool, if
that's what you prefer.   The configuration bytes are preceded by ASCII labels
ending with a ">".

   Following is a discussion of each configuration item identified by both the
ZCNFG menu selection number:
 Configuration - 2/5 

     1    Read-only attribute.  If set to YES, the disk label
          will have its read/only attribute set so the label
          cannot be accidentally erased.  This is recommended.
          As distributed: NO.

     2    System attribute.  If set to YES, the disk label will
          have its system attribute set so that the label will
          not appear in ordinary disk directories.  As
          distributed: NO.

     3    Archive attribute.  If set to YES, the disk label will
          have its archive attribute set so that the label will
          not be copied to another disk during an archival
          backup.  As distributed: NO.

 Configuration - 3/5 

     4    Reset drive.  If set to YES, the drive or drive system
          will be reset before DSKNUM tries to save the last
          number used into itself.  If you run DSKNUM from a hard
          disk, a reset is unnecessary and will slow things down
          slightly.  If DSKNUM is loaded from a floppy, it's a
          good idea to activate this reset.  As distributed: NO.

     5    Label tag.  The tag character used as the first
          character of each label name.  The tag character must
          not be the first character of any other file on the
          disk.  "!" or "#" is recommended (see the discussion of
          disk labels above).  As distributed: "#".

     6    Default label.  This is the default label name to be
          used if no label name is given on the command line.  A
          maximum of seven characters is allowed.  Do not include
          the tag character.  As distributed: "DISK".
 Configuration - 4/5 
 
     7    Label user area.  If you always want your labels in the
          same user area, you can set that here (0-31).  All
          labels will then be created in that user and any user
          given on the command line will be ignored.  This
          configuration option also allows labels to be created
          in users beyond the maximum set in the environment,
          which is not possible from the command line.  If this
          configuration byte is set to value greater than 31
          (decimal), DSKNUM will create the label in the user
          given on the command line or, if none is given, in the
          current user.  Since cataloging programs only allow one
          label per disk, setting this byte to your preferred
          user area is highly recommended.  As distributed: FFh
          (use command line).
 Configuration - 5/5 
 
     8    Lower-case labels.  If you want to use lower-case disk
          labels, select YES here.  Lower-case labels will stand
          out more in your disk directories (they will be in
          upper-case in a D.COM display, for instance).  These
          labels cannot be easily manipulated with most
          utilities, however.  A wildcard erase using the
          transient ERASE.COM ("ERASE #*.*") will allow deleting
          a label, even if it is read-only, so another label can
          be written to the disk.  As distributed: NO.
:6
 DSKNUM Notes - 1/3 

   a. The idea for DSKNUM came from a similar program,  VOLNUM, which ran only
      from drive A and then only if A  was the default drive.  The target disk
      had to be on drive B, which,  for many, is a hard drive.   Nevertheless,
      VOLNUM internally saved the last number used.  

   b. Vs 1.5 updates (23 September 1990, Gene Pizzetta):
      - Now allows lower-case disk labels, which stand out more in a disk 
        directory and are not easily manipulated with most utilities.  ASCII 
        configuration labels removed.

   c. Vs 1.4 updates (28 July 1990, Gene Pizzetta):
      - Complete rewrite.  Requires ZCPR 3.3 or higher.  
      - Name changed to DSKNUM from DISKNUM.  
      - Labels a  single disk from command line.   Still labels multiple disks
        interactively.
      - Accepts label name from command line in lieu of internal default label
        name.   Accepts disk number  from command  line  in  lieu  of internal
        stored number.  
 DSKNUM Notes - 2/3 

      - Label attributes configurable.  
      - Gets its  own  filename  and  directory  location  from  external file
        control block on first invocation.  
      - Name is stored for subsequent execution with GO command.  
      - Has type 3 header.  
      - Resets only target disk instead of entire disk system under Z3PLUS and
        ZSDOS.   Configurable to  reset  disk  or not  when saving last number 
        internally (resets not needed for hard drives).  
      - Accepts target  user  area  from  command  line or configurable to use 
        internal default user.
      - Aborts if label already exists on disk.  ^C aborts to operating system
        at any prompt.  
      - Brief usage screen if "//" is given.  
      - Configurable with ZCNFG 1.6 or higher.

   d. Vs 1.3 updates (3 March 1989, Gene Pizzetta):
      - Minor bug correction.
 DSKNUM Notes - 3/3 

   e. Vs 1.2 updates (28 February 1989, Gene Pizzetta):
      - Rewritten for CP/M 2.2 after discovering version 1.1 didn't work!  
      - Added user  area  support.   Must  be configured  to  find itself in a
        specific DU.  Runs on all CP/M and compatible machines.

   f. Vs 1.1 updates (26 December 1987, Gene Pizzetta):
      - Attempt to add CP/M 2.2 support.

   g. Vs 1.0 (24 December 1987, Gene Pizzetta):
      - First version for CP/M-Plus, named DISKNUM.  Finds itself by detecting
        which drive it  was loaded from  (which is  possible under CP/M-Plus), 
        but runs only from the current user area.
