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()
Standardizes the path designation
TRUENAME(<cPathDesignation>) --> cStandardizedPath
<cPathDesignation> Designates a path as a standard. It is assumed
that it is in accordance with DOS rules.
TRUENAME() returns the standardized path whenever possible.
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
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>
. 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
cPath := TRUENAME(cOldPath)
cToken1 := TOKEN(cPath, ":\", 1)
cToken2 := TOKEN(cPath, ":\", 2)
cToken3 := TOKEN(cPath, ":\", 3)
cPath := cToken1 + AFTERATNUM(cToken2 + cToken3, cPath)
See Also: TOKEN() AFTERATNUM()
Creates a file for temporary use
TEMPFILE([<cDirectory>], [<cExtension>], [<nFileAttr>])
<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 the name of the temporary file. If no file is created, the
function returns a null string.
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
Table 7-24: File Attribute Coding
Value Symb. constants Definition
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)
. 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().
. 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()
Writes a string to a file
STRFILE(<cCharacterstring>, <cFile>, [<lOverwrite>],
[<nOffset>], [<lCutOff>]) --> nRecordedByte
<cCharacterstring> Designates the character string to write to a
<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.).
STRFILE() returns the actual number of bytes written.
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
. The attribute to create a new file, can be designated with the
. 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().
. 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
? 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()