Writes a value in a profile file for a PocketBuilder application.
File format
On the desktop, SetProfileString writes
to the file in the format, ANSI or Unicode, in which it was opened.
On a deployment device, SetProfileString can write
to files in Unicode format only. To write Unicode characters to
an initialization file, open the file and save it as Unicode before
calling SetProfileString.
SetProfileString ( filename, section, key, value )
Argument |
Description |
|---|---|
filename |
A string whose value is the name of the profile file. For desktop applications, if you do not include the full path in filename, PocketBuilder searches the DOS path for filename. |
section |
A string whose value is the name of a group of related values in the profile file. If section does not exist in the file, PocketBuilder adds it. |
key |
A string whose value is the key in section for which you want to specify a value. If key does not exist in section, PocketBuilder adds it. |
value |
A string whose value is the value you want to specify for key. |
Integer. Returns 1 when it succeeds and -1 if it fails because filename is not found or cannot be accessed. On a deployment device, SetProfileString returns -1 if the file is not in Unicode format.
A profile file consists of section labels, which are enclosed in square brackets, and keys, which are followed by an equal sign and a value. By changing the values assigned to the keys, you can specify custom settings for each installation of your application. When you are planning your own profile file, you select the section and key names and determine how the values are used.
For example, a profile file might contain information about the user. In the sample below, User Info is the section name and the other values are the keys. There is no space before and after the equal sign used in the keys or in the section label (if you use a section name such as Section=1):
[User Info]
Name="James Smith"
JobTitle="Window Washer"
SecurityClearance=9
Password=
Call SetProfileString to store configuration information, supplied by you or the user, in a profile file. You can call the functions ProfileInt and ProfileString to use that information to customize your PocketBuilder application during execution.
Accessing the profile file SetProfileString uses profile calls to write data to the profile file. Consequently it does not control when the profile file is written and closed. If you try to read data from the profile file immediately after calling SetProfileString, the file may still be open and you will receive incomplete or incorrect data.
To avoid this problem, you can use the PowerScript FileOpen, FileWrite, and FileClose functions to write data to the profile file instead of using SetProfileString. Or you can add some additional processing after the SetProfileString call so that the profile calls have time to complete before you try to read from the profile file.
Windows registry
SetProfileString can also be used to obtain
configuration settings from the Windows system registry. For information
on how to use the system registry, see the discussion of initialization
files and the Windows registry in the Resource Guide.
This statement sets the keyword Title in
section Position of file C:\PROFILE.INI to
the string MGR:
SetProfileString("C:\PROFILE.INI", &
"Position", "Title", "MGR")
