RomWBW/Source/Images/d_zsdos/u0/FA16.DOC

                            FILEATTR
                           Version 1.6

                          Gene Pizzetta
                        January 18, 1992
      A ZSDOS utility, copyright (c) 1988 by Carson Wilson.


FILEATTR (FA) is a utility that allows rapid settin, resetting, 
or displaying of file attributes under ZSDOS, ZRDOS, and CP/M 
2.2.  Several additional features are available under ZCPR3, 
including error flag setting, error handler invocation, an 
enhanced display, and better error detection.

FA will not run under CP/M 3.0 or Z3PLUS.

USAGE:

     FILEATTR {dir:}{afn} {{/}options}

If a DIR or DU specification is not given, the current directory 
is assumed (under vanilla CP/M only the drive is significant).  
If no ambiguous or unambiguous filename is given, all files 
("*.*") are matched.

If no attribute options are given, FILEATTR merely displays the 
current state of each file's attributes.  Files are displayed in 
the order that they appear in the directory.

Once operation begins, FA cannot be aborted by the user.  If a ^C 
is entered at the keyboard, all screen output stops, but file 
attribute operations continue to completion.  If that was not the 
case, attributes might be set on some entries for a file and not 
on others.  Nevertheless, suppressing screen output speeds things 
up a bit.

OPTIONS:  A leading slash is required unless the option list is 
the second parameter on the command line.  Options may be 
separated by spaces, commas, or nothing at all.

ATTRIBUTE OPTIONS:  These options set (turn on) corresponding 
attributes on files matching the file specification.  Attributes 
not specified by an attribute option remain unchanged.

If the option is preceded by a minus ("-") or by an "N", the 
corresponding attribute is reset (turned off).

     1    F1.  This is a user attribute which has no predefined 
          meaning.

     P    Public (f2).  Under ZSDOS, when this attribute is set, 
          a file is available from any user area of the disk on 
          which it resides.  A file cannot be made public if 
          another file with the same name exists in any other 
          user area on that drive.  In that case FA will issue an 
          error message and leave the attribute off.

     D    Inhibit access datestamp (f3).  Under ZSDOS, when this 
          attribute is set, the file's access datestamp will not 
          be updated, which may speed file access slightly.  If 
          the attribute is turned off, normal access datestamping 
          resumes.

     4    F4.  This is a user attribute which has no predefined 
          meaning.

     W    Wheel protect (f8).  Under ZSDOS, when this attribute 
          is set, the file becomes read-only when the wheel byte 
          is off and cannot be erased.  If the wheel byte is on, 
          the file can be erased normally.

     R    Read only (t1).  When this attribute is set, the file 
          cannot be erased or modified by most programs.

     S    System (t2).  When this attribute is set, the file 
          becomes a "hidden" file that will not be found by most 
          directory programs or by most well-behaved utilities 
          that accept ambiguous filenames.  (FA must find system 
          files, of course.)

     A    Archive (t3).  When this attribute is set, it signals 
          some archival programs that the file has not been 
          modified since it was last backed up.  If a file is 
          modified, ZSDOS and ZRDOS turn this attribute off.  
          CP/M does not fully support this attribute, however.

OTHER OPTIONS:  These options affect only the screen display.

     Q    Quiet mode.  Console output is suppressed unless there 
          is an error.  All other operations are performed 
          normally.

     X    Screen paging off.  With this option, screen paging is 
          turned off.  The screen can still be paused by pressing 
          any key except ^C.

ERRORS:  Under ZCPR3, errors will cause FA to set the program 
error flag and to invoke the error handler.  The error flag will 
be set to the following values:
      2   invalid directory specification
      4   miscellaneous (conflicting file, no files on disk)
     10   no matching files found (no error handler)
     18   Disk read-only
     19   Invalid option

For error code 10 (no matching files found), the error flag is 
set, but the error handler is not called.

In addition, under ZCPR 3.3 and above, an invalid directory 
specification will abort FA to the error handler, but no message 
is printed.

The following error messages may be seen:

Conflicting entry, can't set public attribute
     If there are files with the same name in other user areas of 
     the disk, the public attribute cannot be set.

No files on disk
     The disk directory is empty.

Bad Option: /o
     The command line option shown is unknown to FILEATTR.

Drive R/O
     The drive is set to read-only by the operating system and 
     attributes cannot be changed.

CP/M version 2.x required
     FILEATTR will not run on this system.

BIOS write error near directory sector n
     An error occurred at or near the given directory sector, 
     which is expressed as a decimal offset from the beginning of 
     the directory.

BIOS set track detected - FA aborting
     A background program is attempting to modify the current 
     track setting.  The background program must be removeed 
     before running FA again.
     
Not Wheel
     Under ZCPR3 the wheel byte must be set before FILEATTR can 
     be run.

CONFIGURATION:  While no installation is necessary, all options 
can be set as defaults, if you prefer, using ZCNFG.  The 
configuration options are fully explained on the ZCNFG help 
screens.

It is best not to change the name of the configuration file.  Its 
special name assures that ZCNFG will always find the correct CFG 
file, even if the name of FA has been changed or if more than one 
version of FA is online.

HISTORY:

Version 1.6 -- April 14, 1991 -- Gene Pizzetta
     Now displays target DU and directory name in summary.  Fixed 
     bug that caused "GO" to be displayed as program name, if it 
     was re-invoked with the GO command.

Version 1.5 -- March 27, 1991 -- Gene Pizzetta
     Now calls CP/M version checking routine (it was there, but 
     it wasn't called).  Changed error codes:  10, no matching 
     files found.  "No files on disk" error now gets 
     miscellaneous error code (4).  Error 10 does not invoke 
     error handler.  Not released.

Version 1.4 -- March 20, 1991 -- Gene Pizzetta, Howard Goldstein
     Code to check module data byte (S2) was replaced by Howard 
     Goldstein's elegant solution which uses a "true" extent 
     number:  ((data_mod * 32) + extent).  Entering a ^C no 
     longer really aborts FILEATTR; instead FA immediately prints 
     "Wait..." on the screen, turns off paging, turns on quiet 
     mode, sets the results flag, and finishes what it was doing. 
     All this is to prevent unexpected results when only some of 
     a file's directory entries are changed.  All errors 
     including a conflicting file found during a PUBLIC request, 
     now set the program error flag and invoke the error handler 
     so an active SUBMIT or ZEX script can be aborted.  The error 
     flag will have the following values:  2, invalid directory; 
     10, no files on disk; 18, disk is read-only; 19, invalid 
     option; 4, all other errors.  If no matching files are 
     found, the program error flag will be set to FFh, but the 
     error handler will not be invoked.  A few other code changes 
     were made, including a check for CP/M-Plus, under which 
     FILEATTR will not work.  Not released.

Version 1.3 -- February 22, 1991 -- Gene Pizzetta
     Corrected bug that caused faulty operation on large files:  
     The module data byte (S2) byte was not being checked, so 
     such files appeared 2 or more times in the directory display 
     and the public routine was often not finding conflicting 
     files.  Added configuration byte and command line option (X) 
     for screen paging (paging is suppressed in quiet mode).  
     Made quiet mode responsive to ZCPR quiet flag and changed Q 
     command line option to toggle.  Usage screen reflects 
     current effect of X and Q toggles.  Attribute configuration 
     area changed to be compatible with ZCNFG TOGL3 routine.  
     Actions of D and ND options reversed so they work the same 
     as the others.  Added configuration byte for printing 
     summary line even in quiet mode, as suggested by Howard 
     Goldstein.  Removed blank lines from screen display, 
     allowing three more filenames to be shown.  Removed tabs 
     from usage screen so PRINT and PSTR are not needed.  
     Eliminated leading zero from user number display.  Now 
     prints "file" instead of "files" in summary when only 1 
     matching file is found.  Ditto for attribute(s) altered.

Version 1.2 -- November 30, 1988 -- Carson Wilson
     Fixed bug of no program name display when FILEATTR's name 
     was 8 characters long.

Version 1.1 -- October 30, 1988 -- Carson Wilson
     Now wildcards the command forms "FA d: /options" and "FA d: 
     options."

Version 1.0 -- September 26, 1988 -- Carson Wilson
     If a filespec is given, no leading slash is required before 
     the options.  Link with version 4 libraries.  Removed /X 
     option--ZSDOS 10T always closes the first extent when a file 
     is written to.  Changed summary to read "files matched".

Version 0.9 -- July 7, 1988 -- Carson Wilson
     Increased length of search FCB (AMBFIL) by one byte.  Set up 
     AMBFIL as '?' + 35 binary 0's.  ZRDOS and CP/M zero the 
     drive byte (FCB+0) during search next calls, so reinitialize 
     it to '?' before rescanning the directory.  PROGID now 
     prints stored name on GO/JUMP.

Version 0.8 -- June 26, 1988 -- Carson Wilson
     Use SYSLIB PRINT for help display.  VPRINT does not expand 
     tabs.  Now traps disk track changes at the BIOS level.  
     Allows '-' as well as 'N' for "negate option." Auto- 
     wildcards FCB1 for attribute set as well as display.

Version 0.7 -- May 24, 1988 -- Carson Wilson
     Cosmetic changes to help, display.  Made public routines 
     faster by 1/2 directory scan average.  Consolidated file 
     attribute setting/resetting routines for efficiency and 
     clarity.

Version 0.6 -- May 14, 1988 -- Carson Wilson
     Changed "Publ" to "Publc" and "Priv" to "Privt".  Added Q 
     and X options, made options installable.  Added test for bad 
     ZCPR directory & chain to error handler.

Version 0.5 -- May 4, 1988 -- Carson Wilson
     Fixed bug at CHKRO inherited from MAKE.ASM.  Uses Bridger 
     Mitchell's FRESET to reset disks.  Uses ZCPR invocation name 
     in signon, help, etc.  Added F4 attribute.  Now includes all 
     valid ZSDOS attributes.  Help now fully "smart" under ZCPR.  
     Reworked VID3.Z80 and VID4.Z80 from VLIB11 and moved them 
     into FA.Z80 (see end of file).  Put STNDOUT mode ON by 
     default at beginning of each attribute display sequence for 
     faster ZCPR displays.

Version 0.4 -- April 27, 1988 -- Carson Wilson
     Tests for matching files at other user areas before setting 
     the public attribit.

Version 0.3 -- April 26, 1988 -- Carson Wilson