Daily Archives: February 28, 2014

StrFile

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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()

FileDate

Posted on by vivaclipper

FileDate

Determines the file date

Syntax

      FileDate([<cFileMap>, [<nFileAttr>]]) --> <dFileDate>

Arguments

<cFileMap> : Designates a file name, including its path and drive designation. <nFileAttr> : Designates the file attribute explained in the table below. The default value is 0. () If you call this function without parameters, it returns the file date from the current FileSeek() buffer.

Returns

<dFileDate> : the date of the searched for entry, the date from the FileSeek() buffer (when called without parameters), or an empty date.

Description

You can implement FileDate() alone or in conjunction with FileSeek(). If you use the <cFileMap> parameter to call this function, it returns the date of the first entry found. If a suitable entry is not present, an empty date is returned.

When called without parameters, FileDate() returns the date of the last file it located with FileSeek(). You could also determine the dates for a file group (wildcards), when used it in conjunction with FileSeek().

The attribute for the desired file can be specified 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        DIR (Directory)
          32      FA_ARCHIVE          ARCHIVE (Changes since last backup)
          ---------------------------------------------------------------

To find a file, specify only the SYSTEM, HIDDEN, VOLUME, or DIR attributes. If multiple attributes are implemented simultaneously, the table values are added accordingly. Of course, not all combinations are useful.

Examples

      .  Show the date of a particular file:

         ? FileDate("C:\TEXT\TEXT.TXT")     // The date

      .  The date of an ARCHIVE/HIDDEN file:

         ? FileDate("C:\HIDE.TXT", 34)      // The date

      .  Used in conjunction with FileSeek():

         cFile  :=  FileSeek("C:\TEXT\*.TXT")
         DO WHILE .NOT. EMPTY(cFile)
            ? cFile, FileDate()             // Name & date of file
            cFile  :=  FileSeek()           // Search for next entry
         ENDDO

Seealso

FileSeek(), FileAttr(), FileSize(), FileTime()

FileAttr

Posted on by vivaclipper

FileAttr

Determines a file’s attributes

Syntax

      FileAttr([<cFile>]) --> <nFileAttr>

Argument

<cFile> : File name, including the path and drive designation.

Returns

<nFileAttr> : a numeric value for file attributes

Description

FileAttr() is implemented alone or in conjunction with FileSeek(). If the function is called with the <cFile> parameter, it returns the attribute of the first entry found. If no acceptable entry is available, a value of 0 is returned.

When called without a parameter, FileAttr() returns the attribute for the most-recent file located with FileSeek(). When used with FileSeek(), you can determine the attribute for file groups (wildcards).

When you call FileAttr() with the <cFile> parameter, the function internally passes 63 (all attributes) as a mask. When used in conjunction with FileSeek(), you should also designate all 63 as an attribute mask, if all files are to be acknowledged.

          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)
          8       FA_VOLUME           VOLUME (Name of a floppy/hard disk)
          16      FA_DIRECTORY        DIR (Directory)
          32      FA_ARCHIVE          ARCHIVE (Changes since last backup)
          ---------------------------------------------------------------

If multiple attributes are implemented for a file, the value of each corresponding attribute is added.

Examples

      .  Show the attribute of a specific file:

         ? FileAttr("C:\TEXT\TEXT.TXT")      // 32  ARCHIVE

      .  The attribute for an ARCHIVE/HIDDEN file:

         ? FileAttr("C\HIDE.TXT")            // 34  HIDDEN + ARCHIVE

      .  Used in conjunction with FileSeek():

         cFile  :=  FileSeek("C:\TEXT\TEXT.TXT")
         DO WHILE .NOT. EMPTY (cFile)
            ? cFile, FileAttr()              // Name & file attribute
            cFile  :=  FileSeek()            // Search for next entry
         ENDDO

Seealso

FileSeek(), FileDate(), FileSize(), FileTime()

FileAppend

Posted on by vivaclipper

FileAppend

Appends data to a file

Syntax

      FileAppend(<cSourceFile>, <cTargetFile>)
             --> <nAttachedByte>

Arguments

<cSourceFile> : Designates the file that is appended to <cTargetFile>. <cTargetFile> : Designates the file to which <cSource> is appended. Drive and path designation are permitted for both files, wildcards are not.

Returns

<nAttachedByte> : the number of characters appended on to <cTargetFile>.

Description

FileAppend() takes fragmented files, split them up on different floppies and reassemble them. This sort of fragmented file could be created with the FileCopy(). Only need is explicit information, such as VOLUME labels, to recognize the different disks.

If the target file does not exist, it is created with FileAppend(). If an error occurs while appending to the target file, the file deletes completely to avoid accidental and incorrect results. Never append data to file if there is no backup copy.

Examples

      Shown below is a simplified program to reassemble a file that is
      divided among several disks by a FileCopy() backup.

       A catalog contains a list of the disks used during backup in the
      form of volume labels and backup file names.

      Structure of the DISKLIST catalog:

      DISKLIST File Structure
      --------------------------------------------------------------------
      Field Name     Field Content
      --------------------------------------------------------------------
      VolLabel       Back up disk drive and volume label
      BackupName     Back up file name, incl. drive and path
      --------------------------------------------------------------------

      The data in DISKLIST is created by a FileCopy() backup:

      USE DISKLIST                                 // Saved volume labels
      cTargetFile  :=  "C:\TARGET.TXT"
      DO WHILE .NOT. EOF()
         IF .NOT. EMPTY( FileSeek(cVolLabel, 8)     // Correct disk ?
            FileAppend(cBackupName, cTargetFile)   // Yes, append data
            SKIP
         ELSE
            ? "Please insert the correct disk  !"
         ENDIF
      ENDDO

Seealso

FileCopy(), FileSeek()