CT_ATADJUST

 ATADJUST()
 Adjusts the beginning position of a sequence within a string
------------------------------------------------------------------------------
 Syntax

     ATADJUST(<cSearchFor>,<cString>,<nEndpoint>,
        [<nCounter>],[<nIgnore>],[<nCharacter|
        <cCharacter>]) --> cString

 Arguments

     <cSearchFor>  Designates the character string for which the function
     searches, or the character string that provides the reference point for
     adjustment.

     <cString>  Designates the character string within which the
     adjustment occurs.

     <nTargetPosition>  Designates from which position within the
     character string the search expression is adjusted.

     <nCounter>  Designates which occurrence of the <Searchexpression> is
     taken into account.  The default value is for the last occurrence.

     <nIgnore>  Designates the number of characters at the beginning of
     the search string that are removed.  The default value is none.

     <nCharacter|cCharacter>  Designates a character, as necessary, to
     carry out the adjustment.  It can be an individual character or an ASCII
     value between 0 and 255.  The default value is a space CHR(32).

 Returns

     ATADJUST() returns the modified character string.

 Description

     The function first looks for the <cSearchFor> parameter within the
     character string.  From this point, the rest of the <cString> is moved
     (adjusted) by either inserting or removing blanks until the
     <nTargetPosition> is reached.  In lieu of blanks, <nCharacter>|
     <cCharacter> can be used as a fill character.

     Additionally you can specify that the nth occurrence of <cSearchFor> be
     used and whether or not a specific number of characters at the beginning
     of the search string is eliminated.

 Note

     .  Using CSETATMUPA() can influence how the search is performed.
        Using SETATLIKE() permits the use of wild cards within the search
        sequence.

 Examples

     .  Align comments at column 60.  The search is for the first
        occurrence of "//".  Since there is usually at least one space before
        each "//", search for " //":

        ? ATADJUST(" //", Line, 60, 1)

     .  Move the extensions for the following list of file names to
        position 10 and eliminate the ".":

        WINDOW.DBF
        PLZ.DBF
        BACK.DBF
        HELP.DBF
        LOG.DBF

        CHARREM(".", ATADJUST(".", File, 10))

        WINDOW      DBF

        PLZ         DBF
        BACK        DBF
        HELP        DBF
        LOG         DBF

     .  Use ATADJUST() with CSETATMUPA().  There is always a problem
        determining whether "AA" occurs twice or three times in "AAA".
        Depending on CSETATMUPA(), the function searches behind the last
        character, or starts from the last character of a located sequence:

        CSETATMUPA(.F.)
        ? ATADJUST("AA", "123AAABBB", 7, 2)       // Sequence not found

        CSETATMUPA(.T.)
        ? ATADJUST("AA", "123AAABBB", 7, 2)       // "123A  AABBB"

See Also: SETATLIKE() CSETATMUPA()

CT_ASCPOS

 ASCPOS()
 Determines the ASCII value of a character at a particular position within a
 string
------------------------------------------------------------------------------
 Syntax

     ASCPOS(<cString>,[<nPosition>]) --> nAsciiValue

 Arguments

     <cString>  Designates the character string that is searched.

     <nPosition>  Designates the character of <cString> for which the
     ASCII value is determined.  The default character is the last character.

 Returns

     The function returns the ASCII value for the character at <nPosition>
     within <cString>.

 Description

     ASCPOS() allows you to determine the ASCII value of a selected key
     within a character string.

 Notes

     .  The returned value can be between 0 and 255.

     .  If <cString> is a null string, or <nPosition> is larger than
        the length of the string, ASCPOS() returns 0.

     .  If <nPosition> is 0, the ASCII value for the last character is
        returned.

 Examples

     .  You can specify:

        ? ASCPOS(String, 5)

     .  Or you can specify:

        ? ASC (SUBSTR(String, 5, 1))

See Also: VALPOS()

 

CT_ASCIISUM

 ASCIISUM()
 Finds the sum of the ASCII values of all the characters of a string

 Syntax

     ASCIISUM(<cString>) --> nASCIISum

 Argument

     <cString>  Designates the character string for which the sum of all
     the ASCII values is computed.

 Returns

     ASCIISUM() returns a number that corresponds to the sum of the ASCII
     codes of all the characters in <cString>.

 Description

     ASCIISUM() allows you to form simple checksums for character strings.
     For example, this can be implemented during remote data transmission to
     identify transmission errors.

 Note

     .  This function does not take character position into account,
        so it cannot determine a character transposition.  The CHECKSUM()
        function should be used to determine character transposition.

 Examples

     .  Transposed characters yield identical results:

        ? ASCIISUM("abc")          // Result: 294
        ? ASCIISUM("cba")          // Result: 294

     .  A null string returns 0:

        ? ASCIISUM("")             // Result: 0

See Also: CHECKSUM()

 

CT_AFTERATNUM

 AFTERATNUM()
 Returns the remainder of the string after the nth appearance of a sequence

 Syntax

     AFTERATNUM(<cSearchFor>,<cString>,[<nCounter>],
        [<nIgnore>]) --> cString

 Arguments

     <cSearchFor>  Designates the string for which the function searches.

     <cString>  Designates the string to search.

     <nCounter>  Designates which occurrence of <cSearchFor> within
     <cString> is found.  The default value specifies the last occurrence in
     the search expression.

     <nIgnore>  Designates the number of characters that are eliminated
     from the search.  The default value ignores none (0).

 Returns

     AFTERATNUM() returns the remainder of the <cString> string from the
     first character after the nth (<nCounter>) occurrence of <cSearchFor>.
     If the last character in the sequence located is also the last character
     in the string being searched, then a null string is returned.

 Description

     This function finds the nth (<nCounter>) occurrence of <cSearchFor>
     within <cString> and returns the remainder of the string from the first
     position behind the located sequence.

     In order to determine the nth (<nCounter>) occurrence of <cSearchFor>,
     AFTERATNUM() searches from the left for each instance of this sequence.
     If CSETATMUPA() is off, then the search is continued after the last
     character of the sequence most recently found.  Otherwise the search is
     continued after the first character of the sequence most recently found.

 Note

     .  Implementing SETATLIKE() allows you to use wild card
        characters within <cSearchFor>.

 Examples

     .  Search a string for the last appearance of "aa" in two
        different ways:

        CSETATMUPA(.T.)
        ? AFTERATNUM("aa", "aBaaBaaX")   // "X"

        CSETATMUPA(.F.)
        ? AFTERATNUM("aa", "aBaaBaaX")   // "aX"

     .  Search a string for the third existing "xx" within the string,
        where the first four characters are ignored!  Notice the differing
        results, depending on the multi-pass mode!

        String  := " AxxBBBBxxCCCCxxxDxxEExx"

        CSETATMUPA(.T.)
        ? AFTERATNUM("xx", String, 3, 4)   // "DxxEExx"

        CSETATMUPA(.F.)
        ? AFTERATNUM("xx", String, 3, 4)   // "EExx"

     .  Examples for SETATLIKE() can be found under the corresponding
        function description.

See Also: CSETATMUPA() SETATLIKE()

 

CT_ADDASCII

 ADDASCII()
 Adds a value to each ASCII code in a string
------------------------------------------------------------------------------
 Syntax

     ADDASCII(<cString>,<nValue>,[<nPosition>]) --> cString

 Arguments

     <cString>  [@]  Designates the character string that is processed.

     <nValue>  Designates the value that is added to the ASCII value of
     the character.

     <nPosition>  Designates the position of the character to which the
     <nValue> is added.  The default value tells Clipper Tools to add to
     the ASCII value of the last character.

 Returns

     ADDASCII() returns the modified character string.

 Description

     This function is very useful when you call procedures using macros.
     When you use ADDASCII(), the string representing the macro can be
     changed without needing to include functions like LEFT(), RIGHT(),
     ASC(), or SUBSTR() (see example).

     This function also allows you to subtract a value.  However, a
     conversion is necessary.  If a lower case letter is converted into an
     upper case letter, a value of 32 must be subtracted.  This occurs
     according to the following formula:

     CHR((ASC(<Character>) + 256 - Difference) % 256)

 Notes

     .  If the <nPosition> is greater than the length of <cString> or
        less than 0, the string remains unchanged.

     .  Zero changes the value of the last character.

     .  CSETREF() can be used to suppress the returned value for this
        function in order to save space in working memory.

 Examples

     .  A value of 1 is added to the next to the last position in a
        string and to the last position in a string (CHR(ASC("2")+1) yields
        "3" etc.):

        ? ADDASCII("macro21", 1, 6)        // "macro31"
        ? ADDASCII("macro21", 1)           // "macro22"

     .  You can also subtract; -- 32 is the difference between lower
        case and upper case letters, therefore CHR((ASC("m")+256-32) %256):

        ? ADDASCII("macro21", 224, 1)      // "Macro21"

 

CT_VOLUME

 VOLUME()
 Establishes a volume label for a floppy or hard disk

 Syntax

     VOLUME(<cDiskName>) --> lEstablished

 Argument

     <cDiskName>  Designates a name to use on a new volume label.  A
     drive designation is allowed; path designation and wildcards are not.

 Returns

     VOLUME() returns .T. when the new volume entry is created.

 Description

     DOS provides a volume label as a disk identifier.  With the VOLUME()
     function you can establish this label.  There is never more than one
     label per floppy or hard disk.  A volume label can be up to 11
     characters long, but when you use a period (.) it must always follow the
     eighth character.

     You can query the volume label with FILESEEK(), since the value 8 is
     assigned as the volume attribute.

 Notes

     .  A new volume label is always created in the root directory.

     .  The function acknowledges the CSETSAFETY() setting and, if
        necessary, does not overwrite an existing label.

 Examples

     .  Establish a volume label for A: drive:

     .  Query the A: drive volume label:

        ? FILESEEK("A:\*.*", 8)      // Based on example 1 "VOLO815"

See Also: FILESEEK()

 

CT_VOLSERIAL

 VOLSERIAL()
 Determines the DOS disk serial number

 Syntax

     VOLSERIAL([<cDrive>]) --> nVolSerial

 Argument

     <cDrive>  Designates the drive whose volume serial number is
     queried.  The default is the current disk drive.

 Returns

     VOLSERIAL() returns the volume serial number of the DOS  disk, hard
     disk, or a 0, when you are not dealing with a DOS 4.0 or higher disk
     (see Notes).  When the current drive is unavailable, it returns -1.

 Description

     VOLUME SERIAL NUMBER
     Beginning with DOS version 4.0, every floppy or hard disk receives a
     volume serial number during formatting.  This is a 32-bit number is
     created by DOS using the date, clock time, and a counter.

 Notes

     .  Incompatibilities are possible.

     .  The function always returns a value from the disk parameter
        block of a floppy or hard disk.  Based on the Microsoft
        recommendation for DOS versions prior to 4.0, a value of 0 is
        returned.

 Example

     Query the volume serial number:

     ? VOLSERIAL()            // 0, when no DOS 4.x disk

See Also: OSVER()

 

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