!=============================================================================!
!  DIVISION   I	:				     HELP MODULE DECLARATION  !
!=============================================================================!
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 01 :					 INITIAL VERSION      !
!      -----------------------------------------------------------------      !
!									      !
!      File Specification: ACCSRC_HELPUSER:TESTFILE.HLP			      !
!      Author		 : Marlys A. Nelson				      !
!      Initial version	 : 01.00.00 17-JUN-1984	VMS 3.6			      !
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 02 :				    MODIFICATION HISTORY      !
!      -----------------------------------------------------------------      !
!									      !
!      01.00.01 22-JUN-1985 VMS 4.1: Marlys A. Nelson			      !
!		Updated for the new TESTFILE procedure.			      !
!									      !
!=============================================================================!
!  DIVISION  II	:				  HELP MODULE SPECIFICATIONS  !
!=============================================================================!
!									      !
!      Key 1 (Command name)............	TESTFILE			      !
!        Key 2 ........................   Parameters			      !
!	 Key 2 ........................   Operation			      !
!	 Key 2 ........................	  Exit_Status                         !
!	 Key 2 ........................	  Examples                            !
!									      !
!=============================================================================!
!  DIVISION III	:					       SPECIAL NOTES  !
!=============================================================================!
!									      !
!									      !
!=============================================================================!
!
!=============================================================================!
! Key 1							             TESTFILE !
!=============================================================================!
!
1 TESTFILE
Allows  the  user to determine if a given file specification is valid.
The existence or non-existence of the file  may  also  be  determined.
This command is intended for use in command procedures.

Format:

     TESTFILE filespec [option]

This procedure is located in the ACC_USERCOM area.  You may call it by
entering the command:

     $ @ACC_USERCOM:TESTFILE filespec [option]

Optionally, you may wish to define a symbol to invoke  TESTFILE,  such
as:

     $ TESTFILE :== @ACC_USERCOM:TESTFILE
     $ TESTFILE filespec [option]
!
!=============================================================================!
! Key 2 						           Parameters !
!=============================================================================!
!
2 Parameters
filespec

  The file specification of the file  to  be  tested.   Standard  file
  specification   rules   are   followed.   You  may  specify  device,
  directory, name, type and version number.  Defaults for  fields  not
  specifically  entered  are  the  standard  system  defaults  and are
  usually derived from your current process defaults.

option

  Specifies  how the filespec is to be tested.  This can be any of the
  following keywords:

    EXISTS      Filespec must be valid and must exist.
    NOEXISTS    Filespec must be valid and must NOT exist.
    VALID       Filespec must be valid; no check for existence or non-
                  existence is made.

  If no option is specified, the default is EXISTS.
!
!=============================================================================!
! Key 2 						            Operation !
!=============================================================================!
!
2 Operation
DCL procedures often manipulate files.  It can then  become  necessary
to  determine  if  a  given  file exists or does not exist so that the
procedure can take appropriate  action.   Also,  if  the  filespec  is
user-supplied,  it becomes critical to know if the user has provided a
valid filespec before attempting to use the filespec in the procedure.
TESTFILE provides an easy, standard method of determining these items.
Spurious diagnostic messages are avoided.  $STATUS is left in a  small
set  of  known  states  which  the  calling  DCL command procedure can
examine and take action accordingly.

TESTFILE  uses  the  lexical  function  F$PARSE to check the specified
filespec for correct syntax.  If this check succeeds, and  either  the
EXISTS  or  the  NOEXISTS  option  was  requested,  TESTFILE  uses the
DIRECTORY command to check for the actual existence of the filespec.

Please note, however, if you request ONLY a VALID  check  on  a  given
filespec,  this  DOES NOT guarantee that the device or directory named
in the filespec actually exists.  Errors could occur when the filespec
is  actually used.  For example, if the following TESTFILE command was
entered:

     $ TESTFILE USERDISC:[MARVIN]NAMELIST.TXT VALID

TESTFILE will  return  a  success  status  code  of  %X10000001.   The
filespec  is  correctly  formed, even though the disk USERDISC and the
directory [MARVIN] do not actually exist.  If this filespec were  used
in  other  commands  within  the  DCL  command procedure, errors would
occur.

This situation is avoided if either EXISTS or NOEXISTS is specified.

TESTFILE returns a finite set of $STATUS codes to indicate the results
of execution.  These codes are listed under the topic "Exit_Status".
!
!=============================================================================!
! Key 2 						          Exit_Status !
!=============================================================================!
!
2 Exit_Status
TESTFILE  can  return  one  of  the following $STATUS values.  All are
expressed as hexidecimal values:

  %X10000001    TESTFILE completed execution  successfully.   This  is
                interpretted based on the option specified:

                  VALID     Filespec valid.
                  EXISTS    Filespec valid and does exist.
                  NOEXISTS  Filespec valid and does not exist.

  %X10000004    TESTFILE procedure has been called incorrectly.   This
                can occur for any of the following reasons:

                  1. More than two parameters specified in the calling
                     line.
                  2. The second parameter is not one of the recognized
                     keywords.

  %X10000012    The specified filespec is not valid.

  %X10000022    The specified filespec is valid, however, it does  not
                exist and option EXIST was specified.

  %X10000032    The  specified  filespec  is  valid,  however, it does
                exist and option NOEXIST was specified.

Note  that  the  high order bit is set on in all cases.  This prevents
DCL from attempting to interpret the  $STATUS  code  and  display  and
error message.

All codes other than the success code %X10000001 are at severity level
WARNING or ERROR.  DCL  command  procedures  calling  TESTFILE  should
include  a  SET NOON or ON severity statement before the TESTFILE call
if termination of the procedure on a warning or error is not  desired.
This  is  necessary  even  if  you  wish  to test the $STATUS code and
provide your  own  error  recovery.   See  the  topic  "Examples"  for
specific illustrations of this.
!
!=============================================================================!
! Key 2 						             Examples !
!=============================================================================!
!
2 Examples
TESTFILE can be used within a command procedure to delete a file if it
exists, thereby avoiding warning messages to the terminal if  it  does
not  exist.   The  code  within a command procedure to use TESTFILE in
this manner is shown below:

  $SET NOON
  $@ACC_USERCOM:TESTFILE BAD.DAT EXISTS
  $IF $STATUS .EQ. %X10000001 THEN $DELETE BAD.DAT;*
  $SET ON

The  command procedure code shown below uses TESTFILE to create a file
if it does not already exist.

  $SET NOON
  $@ACC_USERCOM:TESTFILE NEEDED.DAT NOEXISTS
  $IF $STATUS .EQ. %X10000001 THEN $@MAKEFILE.COM
  $SET ON

The following command procedure section examines all the possible exit
status  values  and  displays  a  message  indicating   how   TESTFILE
completed.   Note  that  if  you  wish  to test for multiple values of
$STATUS you must save the  value  returned  by  TESTFILE  in  a  local
symbol; otherwise, the IF statements will set $STATUS and the TESTFILE
$STATUS value is lost.

  $! P1 = Filespec to test
  $! P2 = VALID    check only valid
  $!      EXISTS   check valid and exists
  $!      NOEXISTS check valid and does not exists
  $!
  $SET NOON
  $@ACC_USERCOM:TESTFILE "''P1'" "''P2'"
  $RESULT = $STATUS
  $IF RESULT .EQ. %X10000001 THEN GOTO L1
  $IF RESULT .EQ. %X10000004 THEN GOTO L2
  $IF RESULT .EQ. %X10000012 THEN GOTO L3
  $IF RESULT .EQ. %X10000022 THEN GOTO L4
  $IF RESULT .EQ. %X10000032 THEN GOTO L5
  $WRITE SYS$OUTPUT "Unknown $STATUS value"
  $EXIT
  $L1:WRITE SYS$OUTPUT "Success"
  $   EXIT
  $L2:WRITE SYS$OUTPUT "TESTFILE called incorrectly."
  $   EXIT
  $L3:WRITE SYS$OUTPUT "Filespec is not valid."
  $   EXIT
  $L4:WRITE SYS$OUTPUT "Filespec is valid but does not exist."
  $   EXIT
  $L5:WRITE SYS$OUTPUT "Filespec is valid but does exist."
  $   EXIT
!
!=============================================================================!
!							   END OF HELP MODULE !
!=============================================================================!
