StrFile

StrFile

Writes a string to a file

Syntax

      StrFile(<cCharacterstring>, <cFile>, [<lOverwrite>],
             [<nOffset>], [<lCutOff>]) --> <nRecordedByte>

Arguments

<cCharacterstring> : the character string to write to a file. <cFile> : File name. Drive and path designations are permitted, but no wildcards. <lOverwrite> : If NIL or .F., determines whether or not a new file is created. When .T., it writes to an existing file. The default is create new file (.F.).

<nOffset> : An offset within the file from which the <cCharacterstring> string is to be written. The default is End of file. <lCutOff> : When this optional parameter is designated as .T., the function truncates the file if data written ends before the last file byte. The default is no cut off (.F.).

Returns

<nRecordedByte> : the actual number of bytes written.

Description

This function provides another capability besides writing the contents of a string to a file. In contrast to the Fxxxx() functions, only one function call is necessary to write data to a file. However, it can result in some speed disadvantages, since files acted on by StrFile() cannot be held open. If the target file is unavailable, the StrFile() function always creates it.

Notes

. The attribute to create a new file, can be designated with the SETFCREATE() function.

. As recommended with the share mode, reads and writes from other network programs should be locked out with SETSHARE() for this period of time.

. This function acknowledges the setting for CSETSAFETY().

Examples

      .  Add to the end of a file:
         ? StrFile("ABCDEFGH", "TEST.TXT", .T.)             // Result: 8

      .  A file with drive and path designations, result: 10:

         ? StrFile("0123456789", "C:\TEXT\TEST.TXT", .T.)

      .  Data in an existing file is overwritten from position 20 with
         a designated string:

         ? StrFile("NANTUCKET", "TEST.TXT", .T., 20)        // Result: 9

      .  A 5-character string is written starting at position 10 in an
         existing file 20-characters long.  Since the final parameter is
         specified as .T. once, and specified as .F. once, you see different
         results:

         ? StrFile(REPLICATE("X", 20), "TEST.TXT")
         ? StrFile("AAAAA", "TEST.TXT", .T., 10, .F  // "XXXXXXXXXXAAAAAXXXXX"
         ? StrFile("AAAAA", "TEST.TXT", .T., 10, .T  // "XXXXXXXXXXAAAAA"

Seealso

FileStr()

RenameFile

RenameFile

Fault tolerant renaming of a file.

Syntax

      RenameFile(<cOldFileName>, <cNewFileName>) --> <nErrorCode>

Arguments

<cOldFileName> : The name and path of the existing file. <cNewFileName> : The new name and path for the file.

Returns

<nErrorCode> : A 0 when the file can be renamed; otherwise, it returns an error code. The codes are defined below:

          RenameFile() Error Codes
          ----------------------------------------
          Code    Definition
          ----------------------------------------
           0      No error found
          -2      File not found
          -3      Path not found
          -5      Access denied (e.g., in network)
          -17     Target file not on same network
          ----------------------------------------

Description

Currently, you may not be able to rename a file on a network drive. Another user may currently have the file open. RenameFile() actually says “attempt a RENAME and, should the situation arise, return an error code”. This follows the basic programming philosophy: never fall into an error trap when you can avoid it.

Notes

. The <cNewFileName> must always contain the complete path for the designated file (see Examples).

. Wildcard characters cannot be used.

Examples

      .  Rename a file from OLD to NEW:

         IF RenameFile("OLD", "NEW") = 0
            ? "The file is renamed!"
         ENDIF

      .  Use the path from the old file specification for the new name:

         cFSpecOld   := "C:\TEST\TEST.TXT"
         cFileName   := TOKEN(cFSpecOld, ":\")      // last token
         cFSpecNew   := BEFOREATNUM(cFileName, cFSpecOld) + "TEST.NEW"
         RenameFile(cFSpecOld, cFSpecNew)

See also

DeleteFile()

FileTime

FileTime

Determines a file’s time

Syntax

      FileTime([<cFileMap>, [<nFileAttr>]]) --> <cFileClockTime>

Arguments

<cFileMap> : Designates the file name, including the path and drive designation.

<nFileAttr> : Designates the file attribute explained in the table below. The default value is 0.

() : If the function is called without parameters, it returns the file time from the current FileSeek() buffer.

Returns

<cFileClockTime> : the clock time for the <cFileMap>; the clock time from the FileSeek() buffer (when called without parameters), or a null string.

Description

Implement FileTime() alone or in conjunction with FileSeek(). If the function is called with the <cFileMap> parameter, it returns the time of the first entry found. If no matching entry is available, a null string is returned.

When called without parameters, FileTime() returns the clock time of the last file found with FileSeek(). You can also determine the clock time of file groups (wildcards) when the function is used in conjunction with FileSeek().

You can designate the attribute for the desired file in numeric form:

          Coding the File Attribute
          ---------------------------------------------------------------
          Value   Symb. constants     Assigned attribute
          ---------------------------------------------------------------
          0       FA_NORMAL
          1       FA_READONLY         READ ONLY (Read-only)
          2       FA_HIDDEN           HIDDEN (Hidden files)
          4       FA_SYSTEM           SYSTEM (System files)
          16      FA_DIRECTORY        (Subdirectory)
          32      FA_ARCHIVE          ARCHIVE (Changes since last backup)
          ---------------------------------------------------------------

Only the SYSTEM, HIDDEN, VOLUME, or DIR attributes must be specified for an entry to be found. If multiple attributes are implemented simultaneously, the table values are added accordingly. Of course, not all combinations are useful.

Examples

      .  The clock time of a particular file:

         ? FileTime("C:\TEXT\TEXT.TXT")      // File clock time or ""

      .  The clock time of an ARCHIVE/HIDDEN file:

         ? FileTime("C:\HIDE.TXT", 34")      // File clock time or ""

      .  Used in conjunction with FileSeek():

         cFile  :=  FileSeek(C:\TEXT.TXT")
         DO WHILE .NOT. EMPTY(cFile)
            ? cFile, FileTime()              // File name and clock time
            cFile  := FileSeek()             // Search for next entry
         ENDDO

Seealso

FileSeek(), FileAttr(), FileDate(), FileSize()

FileStr

FileStr

Reads a portion of a file into a string

Syntax

      FileStr(<cFile>, [<nLength>], [<nOffset>],
             [<lCtrl-Z>]) --> <cCharacterstring>

Arguments

<cFile> : Designates the file from which a string is read.

<nLength> : Designates how many characters you want to read from a file. The default is read all characters.

<nOffset> : Designates an offset within the file from which the

<nLength> : characters or the rest of the file, are read. The default is from the first character (0).

<lCtrl-Z> : If this parameter is designated as .T., only data up to the first Ctrl-Z is read in. The default is read all data (.F.).

Returns

<cCharacterstring> : the string read in from the designated file.

Description

FileStr() also offers the capability to read files or a portion of them, into a string. This is only possible with a function call, where the file name may contain a drive and path designation. If you implement the <lCtrl-Z> parameter, you can be sure the function only reads data up to the first Ctrl-Z and ignores whatever might remains in of the file.

In contrast to the Fxxxx() functions, a disadvantage of FileStr() is a slower access speed, since the file you want to read cannot be held open.

Examples

      .  Read in a file completely:

         ? FileStr("C:\TEXT\TEST.TXT")            // Displays file text

      .  Read in everything to the first Ctrl-Z:

         cVar  := FileStr("C:\TEXT\TEST.TXT", .T.)

      .  The file TEST.TXT contains "ABCDEFGHIJ".  Four characters,
         beginning from position 3, are to be read:

         ? FileStr("C:\TEXT\TEST.TXT", 4, 3)      // "CDEF"

      .  Read the maximum that fits into the available working memory:

         cVar  := FileStr("C:\TEXT\TEST.TXT", MEMORY(1) *1024 -100)

Seealso

StrFile()

FileSize

FileSize

Determines the size of a file

Syntax

      FileSize([<cFileMap>, [<FileAttr>]]) --> <nFileSiz>

Arguments

<cFileMap> : Designates the file name, path, and drive designation.

<FileAttr> : Designates the file attribute that is explained in the table below. The default value is 0. () : If the function is called without parameters, it returns the file size from the current FileSeek() buffer.

Returns

<nFileSiz> : a numeric value designated file’s size, the size from the FileSeek() buffer (when called without a parameter), or -1.

Description

Implement FileSize() alone or in conjunction with FileSeek(). If the function is called with the <cFileMap> parameter, it returns the size of the first entry found. If no matching entry is available, then a value of -1 is returned

When called without parameters, FileSize() returns the size of the most recent file found with FileSeek(). Used in conjunction with FileSeek(), you can also determine the size of file groups (wildcards).

You can designate the attribute for the desired file in numeric form:

          Coding the File Attribute
          ----------------------------------------------------------------
          Value   Symb. constants     Assigned attribute
          ----------------------------------------------------------------
          0       FA_NORMAL
          1       FA_READONLY         READ ONLY (Read-only)
          2       FA_HIDDEN           HIDDEN (Hidden files)
          4       FA_SYSTEM           SYSTEM (System files)
          32      FA_ARCHIVE          ARCHIVE (Changes since last backup.)
          ----------------------------------------------------------------

Specify only the SYSTEM, HIDDEN, VOLUME, or DIR attributes for an entry to be found. If multiple attributes are implemented simul-taneously, the table values are added accordingly. Of course, not all combinations are useful.

Examples

      .  Show the size of a particular file:

         ? FileSize("C:\TEXT\TEXT.TXT")      // File size or -1

      .  The size of an ARCHIVE/HIDDEN file:

         ? FileSize("C:\HIDE.TXT", 34")      // File size or -1

      .  Used in conjunction with FileSeek():

         cFile  :=  FileSeek(C:\TEXT.TXT")
         DO WHILE .NOT. EMPTY(cFile)
            ? cFile, FileSize()              // File name and size
            cFile  := FileSeek()             // Search for next entry
         ENDDO

Seealso

FileSeek(), FileAttr(), FileDate(), FileTime()

FileMove

FileMove

Moves files to another directory

Syntax

      FileMove(<cSourceFile>, <cTargetFile>) --> <nResultCode>

Arguments

<cSourceFile> : Designates the name and the path of the source file.

<cTargetFile> : Designates the name and the path of the target file.

Returns

<nResultCode> : a value of 0 when the file can be moved; otherwise, an error code is returned. The codes are defined below:

          FileMove() Return Codes
          ------------------------------------------------------------
          Code    Symb. constants        Definition
          ------------------------------------------------------------
           0      NO_DISK_ERR            No errors
          -2      ER_FILE_NOT_FOUND      File not found
          -3      ER_PATH_NOT_FOUND      Access path not found
          -5      ER_ACCESS_DENIED       Access denied (e.g., network)
          -17     ER_DIFFERENT_DEVICE    Target file not on same drive
          ------------------------------------------------------------

Description

If a file is to be copied within a drive and then deleted it from the original position, it is quicker to move the file. FileMove() makes this possible. The directory entries are also changed, which is much quicker than copying and deleting.

Notes

. You can use drive designators and access paths in <cSourceFile> and <cTargetFile> file names. Wildcards are not permitted.

. You can only move a file within a drive. If the target directory already contains a file with the same name as the one from <cSourceFile>, the move is not completed. In this case, FileMove() returns a value of -5. The only option available in this situation, is to delete the file in the target directory.

Example

      Move a file from "\OLD" to "\NEW":

      IF FileMove("\OLD\CUST.DBF", "\NEW\CUST.DBF") = 0
         ? "The file is now in the \NEW directory"
      ENDIF

Seealso

FileCopy()

FileDelete

FileDelete

Deletes file(s) by name and attribute

Syntax

      FileDelete(<cFileMask>, [<nFileAttr>]) --> <lDeleted>

Arguments

<cFileMask> : Designates the file or files to delete.

<nFileAttr> : Designates one of the following file attributes. The default value is 32.

          File Attribute Coding
          ---------------------------------------------------------------
          Value     Symb. constants   Definition
          ---------------------------------------------------------------
          0         FA_NORMAL
          1         FA_READONLY       Read-only
          2         FA_HIDDEN         HIDDEN (Concealed files)
          4         FA_SYSTEM         SYSTEM (System files)
          8         FA_VOLUME         VOLUME (Name of floppy/hard disk)
          32        FA_ARCHIVE        ARCHIVE (Changed since last backup)
          63        Everything
          ---------------------------------------------------------------

Returns

<lDeleted> .T. when at least one or more files are deleted; otherwise, .F. is returned.

Description

ERASE command and FErase() function doesn’t support “wildcard” ( “*” / “?” ) characters in file specification. FileDelete() function of tools library does. Occasionally, you will need to clean up a floppy or a hard disk or delete whole file groups. This function deletes entire file groups with a function call, without using the RUN command.

Notes

Warning! FileDelete() can also can delete system files.

. The default standard attribute is archive (32). Drive and path designations, and wildcards are permitted.

. Subdirectories must be deleted with the help of the DirRemove() function.

Example

      Attempt to delete all index files, then display the completion status:

      IF FileDelete("*.NDX")
         ? "Files deleted."
      ELSE
         ? "No files found."
      ENDIF

Seealso

DeleteFile()