!*************************** AMUS Program Label ******************************
! Filename: DIRHSH.BAS                                      Date: 2/27/90
! Category: UTIL         Hash Code: 723-641-516-067      Version: 1.0(102)       
! Initials: GR/AM        Name: James A. Jarboe IV
! Company: Educational Video Network, Inc.         Telephone #: 4092955767
! Related Files: DIRHSH.M68, DIRHSH.SBR
! Min. Op. Sys.: AMOSL 1.3                     Expertise Level: BEG
! Special: Must have DIRHSH.SBR
! Description: An example basic program to show how to use DIRHSH.SBR from
! within a BASIC program.
! 
!*****************************************************************************
!*! Updated on 27-Feb-90 at 7:52 PM by James A. Jarboe IV; edit time: 1:22:41
!****************************************************************************
!                                                                           *
!  DIRHSH.BAS - Example to show DIRHSH.SBR usage.                           *
!                                                                           *
!****************************************************************************
! 
! This program was designed and implemented by
!     
!        James A. Jarboe IV             
!        Educational Video Network, INC.
!        1401 19th Street
!        Huntsville, TX 77340
!        1-409-295-5767
!     
!	 AMUS Network Email - GR/AM
!    
! Edit History:
!     
!    [102] 27-Feb-90  Added fifth argument demonstration.  [JAJ]
!    [101] 23-Feb-90  Modified, cleaned up, Sent to AMUS.  [JAJ]
!    [100] 14-Feb-90  Written - James A. Jarboe IV
!     
! -NOTICE- Not sure if this subroutine will work under AMOS 2.x operating
!          system extended file format. MFD's and UFD's are read manually
!          inside this program and follow the format for 1.3x operating
!          systems. Works well on AMOS 1.3C - 1.3D, AMOS BASIC and d/BASIC.
!
! Description: A basic subroutine which will return device spec, filename,
!              extension, PPN, version number, and hash total of 
!              requested files in an array in the same format as the AMOS
!	       command DIR/V/H/D. This subroutine WILL accept wildcard
!              filename and file extensions. This subroutine will NOT
!              accept wildcard Device and/or PPN specifications. This 
!              subroutine will also return a success flag of 0 or an
!              unsuccessful flag if an error occurs as listed in this
!              program. The fifth argument is optional. If used, it allows
!              the user to set characteristics of how the ARRAY will be
!              handled as defined in OPTIONS below.
!
!            
!  Usage: XCALL DIRHSH, DEVICE'SPEC, FILE'SPEC, ARRAY, FLAG, OPTION
!
!  Where: DEVICE'SPEC = A valid Device/PPN specification, ERSATZ
!                       device. If DEVICE'SPEC is an empty string 
!                       then DIRHSH will default to the current logged
!                       in device and PPN.
!
!         FILE'SPEC   = A filename.extension of the file to find. This
!                       can also be a valid AMOS wildcard specification
!                       using "*" and "?" as wildcard characters. If this
!                       is an empty field the default will be a "*.*"
!                       wildcard search.
!         
!         ARRAY       = Found file specifications will be returned in
!                       this argument. Minimum size must be equal to
!                       or greater than the L..STR constant (74 bytes in 
!                       this version). When doing a wildcard match there
!                       is no way to assume how many files will be found.
!                       Make sure this array is large enough to hold the
!                       number of expected files you are looking for to
!                       hash. Multiply the number of files you expect
!                       by the value in L..STR to get the correct size
!                       of this variable. If more files are found than
!                       this array can hold an error flag of 1 will be
!                       returned.
!
!         FLAG        = A one byte binary number that will return the value
!                       of any errors found while processing.
!                               0   = Everything OK.
!				1   = Did not allocate enough arg space.
!				2   = Device does not exist.
!				3   = PPN does not exist.
!				4   = Control C interrupt.
!				255 = Subroutine ERROR. (255 in BASIC)
!
!	  OPTION      = An optional flag consisting of a one byte binary
!	                number that will set the following options
!                       to the output of the array:
!                         0   = Leave array as is, and overwrite existing
!                               data if user failed to preclear the array
!                               from the basic program.
!                               NOTE: In version 102 it was assumed that
!                               the BASIC program would preclear the 
!                               ARRAY if multiple calls were made.
!                               Now the user has options.
!                         1   = Prelcear ARRAY to nulls.
!                         2   = Append the output of this call to the
!                               existing data in the ARRAY.
!
! Notes:
!
!     Argument 1 - String  - Device, PPN specification.
!     Argument 2 - String  - File, extension specification.
!     Argument 3 - String  - File results are returned.
!     Argument 4 - Binary  - Returned error flags.
!     Argument 5 - Binary  - (optional) Set array output characteristics.
!
!
PROGRAM DIRHSH, 1.0(102)
!
MAP1 DEV'SPEC, S, 20  		! Device, drive, PPN specification.
	                        ! DIRHSH.SBR will accept valid ERSATZ
				! device names.
MAP1 FIL'SPEC, S, 10  		! File(s) to search for.
MAP1 OPTS(3),S,60               ! Define 5th argument options.
	OPTS(1) = "Leave array as is."
	OPTS(2) = "Preclear array with nulls."
	OPTS(3) = "Append new files to existing array."

! ARRAY size has been made large enough to be useful but hopefully
!  small enough to show how the errors will be reported in the event
!  a user requests more files than the array can hold.

MAP1 MAX'FILES, F, 6, 5	        ! Number of files to return.
				! This number should be the same
				! value as the number of FNAMES
				! you desire to use.
MAP1 ARRAY			! Returned filespecs from DIRHSH.SBR
	MAP2 FNAMES(5), S, 74 ! Returned files.(make as large as you
				! deem necessary for your application.
!
! DIRHSH will return the file information in the ARRAY, just as if 
!  an AMOS command DIR/V/H/D was given.
!
! Example of DIR???.*
!
!TOA0:DIRHSH.OBJ[160,50]                                 325-432-346-070  
!TOA0:DIR.M68[160,50]                                    265-736-016-304  
!TOA0:DIRHSH.SBR[160,50]               1.0(100)          341-424-770-117  
!TOA0:DIRHSH.SYM[160,50]                                 504-067-537-513  
!TOA0:DIR.RUN[160,50]                  1.0(100)          442-315-406-237  
!TOA0:DIRHSH.RUN[160,50]               1.0(100)          174-244-627-755  
!TOA0:DIRHSH.BAS[160,50]                                 776-127-052-360  
!TOA0:DIRHSH.BAK[160,50]                                 723-631-003-606  
!TOA0:DIRHSH.M68[160,50]                                 126-114-424-115  
!
MAP1 FLAG, B, 1			! Returned error flag.
MAP1 OPTI, B, 1                 ! Array characteristics option.
MAP1 I, F			! Counter
MAP1 A, F                       ! Total files.

! Error FLAG is offset by 1 to report these errors on terminal.
!
MAP1 DH'ERROR(5),S, 50
	DH'ERROR(1) = "No errors."
	DH'ERROR(2) = "Array not large enough to hold all files."
	DH'ERROR(3) = "Device does not exist."
	DH'ERROR(4) = "PPN does not exist."
	DH'ERROR(5) = "Control C exit."
!
SETUP:	? TAB(-1,0)		! Clear Screen.
	CALL MESSAGE		! Report how to use.
!
START:
	DEV'SPEC = ""		! Preclear Device specification.
	FIL'SPEC = ""		! Preclear File specification.

	? "Device spec cannot contain any wild cards."
	? "If Device spec is left empty, it will default to current"
	? "logged in device and PPN."
	?

	INPUT LINE "Enter Device to search (DSK3:[20,10]) : ",DEV'SPEC
	IF UCS(DEV'SPEC[1,3]) = "END" THEN GOTO OUT
	?
	? "File(s) to search can contain wildcards."
	?
	INPUT LINE "Enter File(s) to search (*.BAS) : ",FIL'SPEC

D'OPT:
	OPTI = 0
	INPUT "Enter Option (0, 1, or 2 )", OPTI
	
	IF OPTI>2 THEN GOTO D'OPT

	? 
	? "Using option: ";OPTS(OPTI+1)
	?
	? "Hashing ";DEV'SPEC;FIL'SPEC
	?

! Call Hashing subroutine.
! The fifth argument (OPTI) can be dropped from the XCALL list
!  if the user wants. Not using the fifth argument it is best to 
!  preclear the array from within the BASIC program.

	XCALL DIRHSH, DEV'SPEC, FIL'SPEC, ARRAY, FLAG, OPTI
!!!	XCALL DIRHSH, DEV'SPEC, FIL'SPEC, ARRAY, FLAG  ! Also valid use.

SHOW:	?
	FOR I = 1 TO MAX'FILES
		IF FNAMES(I) <> "" THEN ? FNAMES(I)     &
			: A=A+1        
!!!	FNAMES(I)=""                    ! Use this if you don't use OPTI.
	NEXT I
	?
	? A;" Total files"
	CALL ERRFLG			! Show error flag of 0.
	IF FLAG> 4 THEN GOTO START
	A = 0				! Reset file count.
	? DH'ERROR(FLAG+1)
	?
	GOTO START			! Try again.
OUT:
	END				! Quit this program.

ERRFLG:
	?
	? "Returned error flag ";FLAG
	?
	RETURN

MESSAGE:
	?
	? "This program demonstrates how to use DIRHSH.SBR. "
	? "DIRHSH.SBR will return an array of filenames to the BASIC "
	? "program just like the AMOS command DIR/V/H/D. "
	?
	?
	RETURN