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