CT_TRUENAME

 TRUENAME()
 Standardizes the path designation

 Syntax

     TRUENAME(<cPathDesignation>) --> cStandardizedPath

 Argument

     <cPathDesignation>  Designates a path as a standard.  It is assumed
     that it is in accordance with DOS rules.

 Returns

     TRUENAME() returns the standardized path whenever possible.

 Description

     Path designations are made for the drive as well as the path itself,
     with regard to the current position designation.  With TRUENAME(),
     related path designations are changed around so that they relate to the
     root directory of a particular drive.

     The function does not test to see if a path exists.  If the designated
     path is not valid or the specified drive is unavailable, it returns a
     null string.

 Note

     Warning!  Additional information is built into the path of network
     drives. Under PC-LAN/MS-NET, the path contains the
     designation:\\<ServerName>.  Under Novell, \\<ServerName>\ <VolumeName>
     (see Examples).

 Examples

     .  Which complete path corresponds to the current disk drive?

        ? TRUENAME(".")                        // e.g. "C:\TEST1"

     .  Anything valid under DOS is acceptable:

        ? TRUENAME("..\..\TEST1\.\TEST2")      // e.g. "C:\TEST1\TEST2"

     .  In a Novell network, remove tokens 2 and 3, server name, and
        volume name:

        IF NNETWORK()
           cPath   := TRUENAME(cOldPath)
           cToken1   := TOKEN(cPath, ":\", 1)
           cToken2   := TOKEN(cPath, ":\", 2)
           cToken3   := TOKEN(cPath, ":\", 3)
           cPath   := cToken1 + AFTERATNUM(cToken2 + cToken3, cPath)
        ENDIF

See Also: TOKEN() AFTERATNUM()

 

CT_TEMPFILE

 TEMPFILE()
 Creates a file for temporary use

 Syntax

     TEMPFILE([<cDirectory>], [<cExtension>], [<nFileAttr>])
         --> cFileName

 Arguments

     <cDirectory>  Designates the drive and directory where the temporary
     file is to be created.  The default is the current drive/directory.

     <cExtension>  Designates the file extension for the file.  The
     default is no extension.

     <nFileAttr> Designates a file attribute for the file.  The default
     is the SETFCREATE() setting.

 Returns

     Returns the name of the temporary file.  If no file is created, the
     function returns a null string.

 Description

     If you only need a file for a short time and want to avoid conflicts
     with existing files, use TEMPFILE() to create a file with a unique name.
     Names created by TEMPFILE() use the system date and system time.  You
     can hide the file, if you specify an attribute.  Attributes are coded as
     follows:

     Table 7-24:  File Attribute Coding
     ------------------------------------------------------------------------
     Value   Symb. constants     Definition
     ------------------------------------------------------------------------
     0       FA_NORMAL
     1       FA_READONLY         READ ONLY
     2       FA_HIDDEN           HIDDEN (Hidden files)
     4       FA_SYSTEM           SYSTEM (System files)
     32      FA_ARCHIVE          ARCHIVE (Changed since last backup)
     ------------------------------------------------------------------------

 Notes

     .  The temporary file name is always 8 characters long and
        consists exclusively of numbers with a period, if no extension has
        been specified.  The file is created with a length of 0 bytes.

     .  A designated file attribute has precedence over a setting
        created with SETFCREATE().

 Examples

     .  Create a temporary file in the current drive and directory:

        cTempFile := TEMPFILE()

     .  Create a temporary file in the root directory of the E: drive:

        cTempFile := TEMPFILE("E:\")

     .  Create a temporary file with a .TMP extension and a HIDDEN
        attribute in the root directory of the A: drive:

        cTempFile := TEMPFILE("A:\", "TMP", 2)

See Also: SETFATTR() SETFCREATE()

 

CT_STRFILE

 STRFILE()
 Writes a string to a file

 Syntax

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

 Arguments

     <cCharacterstring>  Designates the character string to write to a
     file.

     <cFile>  Designates a file name.  Drive and path designations are
     permitted, but no wildcards.

     <lOverwrite>  If not designated or designated as .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>  Designates 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

     STRFILE() returns 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 Clipper 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"

See Also: FILESTR() SETSHARE() SETFCREATE() CSETSAFETY()

 

CT_SETSHARE

 SETSHARE()
 Sets the default opening mode (share mode) for Clipper Tools file
 functions

 Syntax

     SETSHARE(<nShareMode>) --> lAccepted

 Argument

     <nShareMode>  Designates the desired share mode.

 Returns

     SETSHARE() returns .T. when the desired share mode is implemented (must
     be DOS version - 3.1 or higher).

 Description

     The setting you implement here influences all Clipper Tools functions
     that open, read, or write to a file.  The share mode can be set here.
     It determines when a program opens a file under DOS and how other
     programs within a network may address this file.  The Clipper Tools
     default is 0, compatibility mode.  The following codes apply:

     Table 7-23: Share Mode Coding
     ------------------------------------------------------------------------
     Code    Share Mode
     ------------------------------------------------------------------------
     0       Compatibility mode.  Here DOS or the network software itself
             determines the share mode.  In Novell networks, the SHAREABLE
             attribute plays an important role in this relationship.
     1       Both read and write by other programs are locked out.
     2       Write by other programs are locked out.
     3       Read by other programs are locked out.
     4       Not locked.  Read and write by other programs is allowed
     ------------------------------------------------------------------------

 Note

     Important!  This function can only be used with DOS versions 3.1 or
     higher.  Older versions return .F..

 Examples

     .  Change share mode, prohibit writing by others:

        ? SETSHARE(2)          // .T., when >= DOS 3.1

     .  Bad parameter:

        ? SETSHARE(12)         // .F.

See Also: GETSHARE()

 

CT_SETFDATI

 SETFDATI()
 Sets the date and time of a file

 Syntax

     SETFDATI(<cFile>, [<dFileDate>], [<cFileTime>]) --> lAmended

 Arguments

     <cFile>  Designates for which file the date and/or time is changed.
     Drive and path designations are possible, wildcards are not.

     <dFileDate>  Designates the date for the file.  The default is the
     system date.

     <cFileTime>  Designates the time for the file.  The default is the
     system time.

 Returns

     SETFDATI() returns .T. when the change is successfully executed.

 Description

     SETFDATI() permits you to set the clock date and time of a file.  Since
     the date and time of a file usually change at the same time, these have
     been brought together in one function.  It is possible to only change
     the time or the date, when one parameter is given and the other is not.
     The different parameter types tell the function what is to change.

 Note

     .  The time is given in a 24-hour format, that is between
        "00:00:00" and "23:59:59".

 Examples

     .  Set the date and time:

        SETFDATI("C:\TEXT\TEST.TXT", CTOD("01/01/91"), "01:10:00")

     .  Set current date and time:

        SETFDATI("TEST.TXT")                  // DATE() + TIME()

     .  Only change the date:

        SETFDATI("TEST.TXT", DATE() -10)      // Ten days prior to today

     .  Only change the time, resetting to start time:

        SETFDATI("TEST.TXT", SECTOTIME(Start))

See Also: FILESEEK() FILEDATE() FILETIME() SECTOTIME()

 

CT_SETFCREATE

 SETFCREATE()
 Default attribute for creating with Clipper Tools functions

 Syntax

     SETFCREATE([<nNewFileAttr>]) --> nOldFileAttr

 Argument

     <nNewFileAttr>  Designates a file attribute for a new file.

 Returns

     SETFCREATE() returns the current default attribute or the previous file
     attribute, if the parameter is specified.

 Description

     Clipper Tools functions use a value of 32 (setting the ARCHIVE bit)
     to preset the default for file creation.  For example, use SETFCREATE()
     when a file needs to acquire another attribute in a network environment.

     Table 7-22:  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)
     ------------------------------------------------------------------------

 Note

     .  The set values only apply to files you create with Clipper
        Tools functions.

 Examples

     .  Create a read-only file:

        SETFCREATE(1)
        STRFILE("Nantucket", "TEST.TXT")

     .  Query the attribute set:

        ? SETFCREATE()

See Also: STRFILE() FILECOPY() FILECCONT() FILEAPPEND()

 

CT_SETFATTR

 SETFATTR()
 Sets a file's attributes

 Syntax

     SETFATTR(<cFile>, <nFileAttr>) --> nErrorCode

 Arguments

     <cFile>  Designates the file that has attributes you want to change.
     Drive and path designations are allowed, but no wildcards.

     <nFileAttr>  Designates the new attributes in numeric form.  The
     default is 32 (ARCHIVE).

 Returns

     SETFATTR() returns the attribute implemented to the designated file or a
     negative value as an error code.  The codes are explained below:

     Table 7-20:  SETFATTR() Error Codes
     ------------------------------------------------------------------------
     Code    Symb. constants     Definition
     ------------------------------------------------------------------------
      0      NO_DISK_ERR         No error found
     -2      ER_FILE_NOT_FOUND   File not found
     -3      ER_PATH_NOT_FOUND   Path not found
     -5      ER_ACCESS_DENIED    Access denied (e.g., in network)
     ------------------------------------------------------------------------

 Description

     This function permits you to change a file attribute.  The attributes
     are represented as a numeric value and explained in the table below:

     Table 7-21:  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)
     ------------------------------------------------------------------------

     If you implement multiple attributes for a file, you must also add the
     individual values.

 Notes

     .  Use the VOLUME() function to create volume labels and
        directories through the DIRMAKE() function.  Additional attributes
        can also be set at directory level.

     .  The BITTOC() and CTOBIT() functions can prove helpful in
        conjunction with the file attributes.

     .  An attempt to set (.AND...) attributes at pseudo files can
        trigger a system crash.

 Examples

     .  Set a file to HIDDEN:

        ? SETFATTR("TEST.TXT", 2)       // Returns 0, if successful

     .  When a file is not available:

        ? SETFATTR("ABCDEFGH"), 2)      // Returns: -2

     .  Influence the return value:

        nAttribute  := SETFATTR("TEST.TXT", 7)
        IF nAttribute <> 7
           *...
        ENDIF

See Also: FILESEEK() FILEATTR() BITTOC() CTOBIT()