Adjusts the beginning position of a sequence within a string
<cCharacter>]) --> cString
<cSearchFor> Designates the character string for which the function
searches, or the character string that provides the reference point for
<cString> Designates the character string within which the
<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).
ATADJUST() returns the modified character string.
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.
. Using CSETATMUPA() can influence how the search is performed.
Using SETATLIKE() permits the use of wild cards within the search
. 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 ".":
CHARREM(".", ATADJUST(".", File, 10))
. 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:
? ATADJUST("AA", "123AAABBB", 7, 2) // Sequence not found
? ATADJUST("AA", "123AAABBB", 7, 2) // "123A AABBB"
See Also: SETATLIKE() CSETATMUPA()
Determines the ASCII value of a character at a particular position within a
ASCPOS(<cString>,[<nPosition>]) --> nAsciiValue
<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.
The function returns the ASCII value for the character at <nPosition>
ASCPOS() allows you to determine the ASCII value of a selected key
within a character string.
. 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
. You can specify:
? ASCPOS(String, 5)
. Or you can specify:
? ASC (SUBSTR(String, 5, 1))
See Also: VALPOS()
Finds the sum of the ASCII values of all the characters of a string
ASCIISUM(<cString>) --> nASCIISum
<cString> Designates the character string for which the sum of all
the ASCII values is computed.
ASCIISUM() returns a number that corresponds to the sum of the ASCII
codes of all the characters in <cString>.
ASCIISUM() allows you to form simple checksums for character strings.
For example, this can be implemented during remote data transmission to
identify transmission errors.
. 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.
. Transposed characters yield identical results:
? ASCIISUM("abc") // Result: 294
? ASCIISUM("cba") // Result: 294
. A null string returns 0:
? ASCIISUM("") // Result: 0
See Also: CHECKSUM()
Returns the remainder of the string after the nth appearance of a sequence
[<nIgnore>]) --> cString
<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).
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.
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.
. Implementing SETATLIKE() allows you to use wild card
characters within <cSearchFor>.
. Search a string for the last appearance of "aa" in two
? AFTERATNUM("aa", "aBaaBaaX") // "X"
? 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"
? AFTERATNUM("xx", String, 3, 4) // "DxxEExx"
? AFTERATNUM("xx", String, 3, 4) // "EExx"
. Examples for SETATLIKE() can be found under the corresponding
See Also: CSETATMUPA() SETATLIKE()
Adds a value to each ASCII code in a string
ADDASCII(<cString>,<nValue>,[<nPosition>]) --> cString
<cString> [@] Designates the character string that is processed.
<nValue> Designates the value that is added to the ASCII value of
<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.
ADDASCII() returns the modified character string.
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)
. 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.
. 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
? 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"
Establishes a volume label for a floppy or hard disk
VOLUME(<cDiskName>) --> lEstablished
<cDiskName> Designates a name to use on a new volume label. A
drive designation is allowed; path designation and wildcards are not.
VOLUME() returns .T. when the new volume entry is created.
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
You can query the volume label with FILESEEK(), since the value 8 is
assigned as the volume attribute.
. 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.
. Establish a volume label for A: drive:
. Query the A: drive volume label:
? FILESEEK("A:\*.*", 8) // Based on example 1 "VOLO815"
See Also: FILESEEK()
Determines the DOS disk serial number
VOLSERIAL([<cDrive>]) --> nVolSerial
<cDrive> Designates the drive whose volume serial number is
queried. The default is the current disk drive.
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.
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.
. 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
Query the volume serial number:
? VOLSERIAL() // 0, when no DOS 4.x disk
See Also: OSVER()