FINDFILE

8.5D

The FINDFILE instruction locates and retrieves statistical data about a file. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

filename

Required. A previously defined Character String Variable or literal that contains a file or a directory name that is accessed.

filesize

Optional. A previously defined Numeric Variable that returns the file size.

lastwritetime

Optional. A previously defined Character String Variable that returns the last write/modification timestamp.

name

Optional. A previously defined Character String Variable that returns the file name with no pathing information.

altname

Optional. A previously defined Character String Variable that returns the alternate file name with no pathing information.

attributes

Optional. A previously defined Numeric Variable that contains an OS specific bit mask with the attributes of the file.

path

Optional. A previously defined Character String Variable that returns the path of the file.

altpath

Optional. A previously defined Character String Variable that returns the alternate path of the file.

modeflags

Optional. A previously defined numeric variable or decimal number that gives special operational control for the FINDFILE instruction.

Flags Affected: ZERO, EOS, OVER

Note the following:

1. This instruction processes the data for a file without opening the file.

2. Some operations of the FINDFILE instruction are operating system dependent.

3. The {filename} format is the same as for an OPEN statement and the same rules for locating a file are used. Under some operating systems the {filename} can include wildcard characters (i.e., 'test*' ).

4. No assumption regarding the file name extension is made. The extension, if needed, must be specified.

5. The format of {lastwritetime} is 'yyyymmddhhmmss' as follows:

 

Format	Contains the ...
yyyy	year.
mm	month.
dd	day.
hh	hour.
mm	minute.
ss	second.

 

6. If the program is executing In Windows, the {name} is the long name format.

7. Under Windows, the {altpath} string is the short name format. For other operating systems, the string is the same as the {path}.

8. Under Windows, {attributes} contain the following bit definitions:

 

Bit	Meaning
0x1	Read Only
0x2	Hidden
0x4	System
0x10	Directory
0x20	Archive
0x40	Encrypted
0x80	Normal
0x100	Temporary
0x200	Sparse file
0x400	Reparse point
0x800	Compressed
0x1000	Offline
0x2000	Not content indexed

 

9. Under Linux, {attributes} contain the following bit definitions:

 

Bit	Meaning
0x1	Others have execute permission
0x2	Others have write permission
0x4	Others have write permission
0x7	Others have read, write and execute
0x8	Group has execute permission
0x10	Group has write permission
0x20	Group has read permission
0x38	Group has read, write and execute permission
0x40	User has execute permission (same as S_IEXEC, which is not POSIX)
0x80	User has write permission (same as S_IWRITE, which is not POSIX)
0x100	User has read permission (same as S_IREAD, which is not POSIX)
0x1C0	User (file owner) has read, write and execute permission
0x200	Sticky bit (not POSIX)
0x400	Set GID bit
0x800	Set UID bit
0x1000	FIFO (not POSIX)
0x2000	Character device (not POSIX)
0x4000	Directory (not POSIX)
0x6000	Block device (not POSIX)
0x8000	Regular file (not POSIX)
0xA000	Symbolic link (not POSIX)
0xC000	Socket (not POSIX)
0xF000	Bitmask for the file type bitfields (not POSIX)

 

10. The {modeflags} bit mask values (added in runtime version 9.1D) are defined as follows:

 

Value	Meaning...
0x4F	Reserved bits
0x80 128	Process and report the file and path names in a mixed case sensitive mode.
0x100 256	Return the raw last WRITE modification timestamp. The value is the actual OS timestamp value adjusted to a timezone. (9.3A)
0x200 512	Return the raw last WRITE modification timestamp. The value is the actual UTC timestamp maintained by the OS for a file or directory. (9.3A)
0x400 1024	Disable I11 filename error (10.7A)
0x800 2048	Output fully qualified path with file name mode (10.7A)

 

11. By default the WRITE keyword returns the last WRITE modification timestamp that is adjusted by a timezone and daylight savings when the 0x100/0x200 MODE value is not used. The default action provides consistent and compatible results as reported by a DOS Shell DIR command and the Windows Explorer as reported for the modification timestamps.

12. The source file name may be resolved by either the runtime or the data manager for $MACRO or Datapoint formats. If the PLBENV_ or PLBVOL_ is found in the runtime INI file, the name is resolved and used. However, if the PLBENV_ or PLBVOL_ is not found in the runtime INI file, the file name string is passed to the SUNDM data manager to be resolved when an IP address is specified.

13. When the {filename} contains a leading '!' character, the findfile operation executes at the client workstation rather than the server. A leading '!' character in the {filename} is ignored for all runtimes other than the Application Server.

14. The ZERO flag is set when the {filename} has been found.

15. The EOS flag indicates that data has been lost when storing information into one of the output string variables.

16. The OVER flag indicates that data has been lost when storing information into one of the output numeric variables.

17. The FINDFILE instruction supports Windows Drive Substitution. (9.6)

18. The FINDFILE instruction behavior is modified by the SETMODE *OPENUSEIP control. When the control is defined, FINDFILE will access files on the data manager

19. The FINDFILE instruction gives an I11 error which is an invalid file or directory specification. This error can occur as follows:

 

                   a. A name specification is all blanks.

                   b. A name specification is larger than 500 characters.

                   c. A name with an invalid $MACRO env variable.

                   d. A name with an invalid/unresolved Datapoint format.

                   e. A name with invalid Windows Drive Substitution.

.

See Also: Example Code, Disk I/O Instructions