Writes a value in a profile file for a PowerBuilder application.
SetProfileString ( filename, section, key, value )
Argument |
Description |
|---|---|
filename |
A string whose value is the name of the profile file. If you do not include the full path in filename, PowerBuilder 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, PowerBuilder 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, PowerBuilder 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. If any argument’s value is null, SetProfileString returns null.
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 PowerBuilder application at runtime.
ProfileInt, ProfileString, and SetProfileString can read or write to files with ANSI or UTF16-LE encoding on Windows systems, and ANSI or UTF16-BE encoding on UNIX systems.
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 Application Techniques.
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")
