Paradox Community
Search:

 Welcome |  What is Paradox |  Paradox Folk |  Paradox Solutions |
 Interactive Paradox |  Paradox Programming |  Internet/Intranet Development |
 Support Options |  Classified Ads |  Wish List |  Submissions 


Paradox Programming Articles  |  Beyond Help Articles  |  Tips & Tricks Articles  


Using ini-files and two other useful functions
© 2001 Arthur van Lokhorst

My homepage, which is all Dutch and has nothing to do with Paradox, except that almost every single page was written to a html-text file with Paradox


Introduction

You can give your application the memory of an elephant by either using a table, the registry or an ini-file. With tables, yo can use any variable type you like. The procedures for the registry and for ini-files use strings.

ObjectPAL provides user friendly procedures to read from and write to the registry. But if you like to use an ini-file instead, or want to read somebody else's ini-file, you only have two ObjectPAL-procedures at your disposal: ReadProfileString and WriteProfileString. The read-procedure requires that you know the section name(s) and key name(s) in advance. If you wanted to read all section names from an ini-file, or retrieve all keys and values from a section with one call, you would have to use windows API functions (and in that case, you don't need to know the section names or key names in advance).

The Windows GetPrivateProfileString function does almost the same as the ReadProfileString procedure in ObjectPAL, except that OjectPAL always returns an empty string on failure. With the Windows API function you can set a default value (which might differ for every single read operation); on failure, that string is returned.

The rule for the location of ini-files is simple: if you use a full file name for your ini-file (including drive, path, filename and extension), that file is used. If you only pass a filename and extension, the file is created in the Windows dir on writing to the file if it does not already exist, and is searched for in the windows dir on reading from the file. So, if you don't use a full file name, you never have to worry about the location of your ini-file.

The form frmIniFiles.fsl demonstrates four of these functions:

GetPrivateProfileSectionNames
GetPrivateProfileSection
GetPrivateProfileString
WritePrivateProfileString

The form further demonstrates how to get the users temporary directory (using GetPempPath) and how to launch an application (using ShellExecute).

In the following explantion reference is made to NULL. This is a value used by Windows which equates to ASCI character 0 (zero). Windows sometimes returns a NULL-terminated string, or a set of strings packed in one string where every single string is terminated by a NULL (and the entire string by a NULL as well). Be aware that you can not set chr(0) in ObjectPAL, because the value for x in chr(x) has to be a value between 1 and 255 (both included). The same goes for chrOEM(x).


ObjectPAL declarations

The way these Windows functions are declared (in a uses block) with ObjectPAL is:
Uses "kernel32.dll"
GetPrivateProfileSectionNames(lpszReturnBuffer CPTR,
                              nSize CLONG,
                              lpFileName CPTR) CLONG [stdcall "GetPrivateProfileSectionNamesA"]
GetPrivateProfileSection(lpAppName CPTR,
                         lpReturnedString CPTR,
                         nSize CLONG,
                         lpFileName CPTR) CLONG [stdcall "GetPrivateProfileSectionA"]
GetPrivateProfileString(lpAppName CPTR,
                        lpKeyName CPTR,
                        lpDefault CPTR,
                        lpReturnedString CPTR,
                        nSize CLONG,
                        lpFileName CPTR) CLONG [stdcall "GetPrivateProfileStringA"]
WritePrivateProfileString(lpAppName CPTR,
                          lpKeyName CPTR,
                          lpString CPTR,
                          lpFileName CPTR) CLONG [stdcall "WritePrivateProfileStringA"]
GetTempPath (nBufferLength CWORD,
             lpBuffer CPTR) CLONG [stdcall "GetTempPathA"]
endUses
Uses "shell32.dll"
ShellExecute (hwnd CLONG,
              lpOperation CPTR,
              lpFile CPTR,
              lpParameters CPTR,
              lpDirectory CPTR,
              nShowCmd CLONG) CLONG [stdcall "ShellExecuteA"]
endUses

GetPrivateProfileSectionNames

This function retrieves the names of all sections in an initialization file.

How Windows sees the function
DWORD GetPrivateProfileSectionNames(
LPTSTR lpszReturnBuffer, // address of return buffer
DWORD nSize, // size of return buffer
LPCTSTR lpFileName // address of initialization filename
);

Parameters
lpszReturnBuffer: Pointer to a buffer that receives the section names associated with the named file. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character.

nSize: Specifies the size, in characters, of the buffer pointed to by the lpszReturnBuffer parameter.

lpFileName: Pointer to a null-terminated string that names the initialization file. If this parameter is NULL, the function searches the WIN.INI file. If this parameter does not contain a full path to the file, the system searches for the file in the Windows directory.

Return values
The return value specifies the number of characters copied to the specified buffer, not including the terminating null character. If the buffer is not large enough to contain all the section names associated with the specified initialization file, the return value is equal to the length specified by nSize minus two.

Remarks
No updates to the initialization file are allowed while the section names are being copied to the buffer.


GetPrivateProfileSection

This function retrieves all of the keys and values for the specified section from an initialization file.

Windows 95: The specified profile section must not exceed 32K.
Windows NT: The specified profile section has no size limit.

How Windows sees the function
DWORD GetPrivateProfileSection(
LPCTSTR lpAppName, // address of section name
LPTSTR lpReturnedString, // address of return buffer
DWORD nSize, // size of return buffer
LPCTSTR lpFileName // address of initialization filename
);

Parameters
lpAppName: Pointer to a null-terminated string containing the section name in the initialization file.

lpReturnedString: Pointer to a buffer that receives the key name and value pairs associated with the named section. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character.

nSize: Specifies the size, in characters, of the buffer pointed to by the lpReturnedString parameter.
Windows 95: The maximum buffer size is 32,767 characters.

lpFileName: Pointer to a null-terminated string that names the initialization file. If this parameter does not contain a full path to the file, the system searches for the file in the Windows directory.

Return values
The return value specifies the number of characters copied to the buffer, not including the terminating null character. If the buffer is not large enough to contain all the key name and value pairs associated with the named section, the return value is equal to nSize minus two.

Remarks
The data in the buffer pointed to by the lpReturnedString parameter consists of one or more null-terminated strings, followed by a final null character. Each string has the following format:

key=string

The GetPrivateProfileSection function is not case-sensitive; the string pointed to by the lpAppName parameter can be a combination of uppercase and lowercase letters.

No updates to the specified initialization file are allowed while the key name and value pairs for the section are being copied to the buffer pointed to by the lpReturnedString parameter.


GetPrivateProfileString

This function retrieves a string (the value of a key) from the specified section in an initialization file.

How Windows sees the function
DWORD GetPrivateProfileString(
LPCTSTR lpAppName, // points to section name
LPCTSTR lpKeyName, // points to key name
LPCTSTR lpDefault, // points to default string
LPTSTR lpReturnedString, // points to destination buffer
DWORD nSize, // size of destination buffer
LPCTSTR lpFileName // points to initialization filename
);

Parameters
lpAppName: Pointer to a null-terminated string that specifies the section containing the key name. If this parameter is NULL, the GetPrivateProfileString function copies all section names in the file to the supplied buffer.

lpKeyName: Pointer to the null-terminated string containing the key name whose associated string is to be retrieved. If this parameter is NULL, all key names in the section specified by the lpAppName parameter are copied to the buffer specified by the lpReturnedString parameter.

lpDefault: Pointer to a null-terminated default string. If the lpKeyName key cannot be found in the initialization file, GetPrivateProfileString copies the default string to the lpReturnedString buffer. This parameter cannot be NULL.

Avoid specifying a default string with trailing blank characters. The function inserts a null character in the lpReturnedString buffer to strip any trailing blanks.

Windows 95: Although lpDefault is declared as a constant parameter, the system strips any trailing blanks by inserting a null character into the lpDefault string before copying it to the lpReturnedString buffer.

Windows NT: The system does not modify the lpDefault string. This means that if the default string contains trailing blanks, the lpReturnedString and lpDefault strings will not match when compared.

lpReturnedString: Pointer to the buffer that receives the retrieved string.

nSize: Specifies the size, in characters, of the buffer pointed to by the lpReturnedString parameter.

lpFileName: Pointer to a null-terminated string that names the initialization file. If this parameter does not contain a full path to the file, the system searches for the file in the Windows directory.

Return values
The return value is the number of characters copied to the buffer, not including the terminating null character.

If neither lpAppName nor lpKeyName is NULL and the supplied destination buffer is too small to hold the requested string, the string is truncated and followed by a null character, and the return value is equal to nSize minus one.

If either lpAppName or lpKeyName is NULL and the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters. In this case, the return value is equal to nSize minus two.

Remarks
The GetPrivateProfileString function searches the specified initialization file for a key that matches the name specified by the lpKeyName parameter under the section heading specified by the lpAppName parameter. If it finds the key, the function copies the corresponding string to the buffer. If the key does not exist, the function copies the default character string specified by the lpDefault parameter.

If lpAppName is NULL, GetPrivateProfileString copies all section names in the specified file to the supplied buffer. If lpKeyName is NULL, the function copies all key names in the specified section to the supplied buffer. An application can use this method to enumerate all of the sections and keys in a file. In either case, each string is followed by a null character and the final string is followed by a second null character. If the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters.

If the string associated with lpKeyName is enclosed in single or double quotation marks, the marks are discarded when the GetPrivateProfileString function retrieves the string.

The GetPrivateProfileString function is not case-sensitive; the strings can be a combination of uppercase and lowercase letters.


WritePrivateProfileString

This function copies a string into the specified section of the specified initialization file.

How Windows sees the function
BOOL WritePrivateProfileString(
LPCTSTR lpAppName, // pointer to section name
LPCTSTR lpKeyName, // pointer to key name
LPCTSTR lpString, // pointer to string to add
LPCTSTR lpFileName // pointer to initialization filename
);

Parameters
lpAppName: Pointer to a null-terminated string containing the name of the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case-independent; the string can be any combination of uppercase and lowercase letters.

lpKeyName: Pointer to the null-terminated string containing the name of the key to be associated with a string. If the key does not exist in the specified section, it is created. If this parameter is NULL, the entire section, including all entries within the section, is deleted.

lpString: Pointer to a null-terminated string to be written to the file. If this parameter is NULL, the key pointed to by the lpKeyName parameter is deleted.

Windows 95: The system does not support the use of the TAB (\t) character as part of this parameter.

lpFileName: Pointer to a null-terminated string that names the initialization file.

Return values
If the function successfully copies the string to the initialization file, the return value is nonzero.

If the function fails, or if it flushes the cached version of the most recently accessed initialization file, the return value is zero.

Remarks
Windows 95: Windows 95 keeps a cached version of WIN.INI to improve performance. If all three parameters are NULL, the function flushes the cache. The function always returns FALSE after flushing the cache, regardless of whether the flush succeeds or fails.

If the lpFileName parameter does not contain a full path and filename for the file, WritePrivateProfileString searches the Windows directory for the file. If the file does not exist, this function creates the file in the Windows directory.

If lpFileName contains a full path and filename and the file does not exist, WriteProfileString creates the file. The specified directory must already exist.


ShellExecute

This functions opens or prints a specified file, or opens Explorer. With ShellExecute you can bring a user online by providing the full name of a web page instead of the file-name - and windows will launch the default browser; to bring a user online, use the following (which requires only one line of code in a push button event, provided you have declared the Windows function in a uses-section):
ShellExecute (0, "open", "http://www.paradoxcommunity.com", "", "", 3)
You might even omit the word "open", and pass an empty string instead, because "open " is usually the default behavior.

How Windows sees the function
HINSTANCE ShellExecute(
HWND hwnd,
LPCTSTR lpOperation,
LPCTSTR lpFile,
LPCTSTR lpParameters,
LPCTSTR lpDirectory,
INT nShowCmd
);

Parameters
hwnd: Window handle to a parent window. This window receives any message boxes that an application produces. For example, an application may report an error by producing a message box.

lpOperation: Address of a null-terminated string that specifies the operation to perform. The following operation strings are valid:

"open"
The function opens the file specified by the lpFile parameter. The file can be an executable file or a document file. It can also be a folder.

"print"
The function prints the file specified by lpFile. The file should be a document file. If the file is an executable file, the function opens the file, as if "open" had been specified.

"explore"
The function explores the folder specified by lpFile.

This parameter can be NULL. In that case, the function opens the file specified by lpFile.

lpFile: Address of a null-terminated string that specifies the file to open or print or the folder to open or explore. The function can open an executable file or a document file. The function can print a document file.

lpParameters: If the lpFile parameter specifies an executable file, lpParameters is an address to a null-terminated string that specifies the parameters to be passed to the application. If lpFile specifies a document file, lpParameters should be NULL.

lpDirectory: Address of a null-terminated string that specifies the default directory.

nShowCmd: If lpFile specifies an executable file, nShowCmd specifies how the application is to be shown when it is opened. This parameter is usually called with the use of a constant. Constants (feel free to use your own), their value and their meaning are:
  • SW_HIDE = 0; Hides the window and activates another window.
  • SW_SHOWNORMAL = 1; Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.
  • SW_SHOWMINIMIZED = 2; Activates the window and displays it as a minimized window.
  • SW_SHOWMAXIMIZED = 3; Activates the window and displays it as a maximized window.
  • SW_MAXIMIZE = 3; Maximizes the specified window.
  • SW_SHOWNOACTIVATE = 4; Displays a window in its most recent size and position. The active window remains active.
  • SW_SHOW = 5; Activates the window and displays it in its current size and position.
  • SW_MINIMIZE = 6; Minimizes the specified window and activates the next top-level window in the z-order.
  • SW_SHOWMINNOACTIVE = 7; Displays the window as a minimized window. The active window remains active.
  • SW_SHOWNA = 8; Displays the window in its current state. The active window remains active.
  • SW_RESTORE = 9; Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.
  • SW_SHOWDEFAULT = 10; Sets the show state based on the SW_ flag specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application. An application should call ShowWindow with this flag to set the initial show state of its main window.
Return values
Returns a value greater than 32 if successful, or an error value that is less than or equal to 32 otherwise. The following table lists the error values.
  • 0 The operating system is out of memory or resources.
  • ERROR_FILE_NOT_FOUND The specified file was not found.
  • ERROR_PATH_NOT_FOUND The specified path was not found.
  • ERROR_BAD_FORMAT The .exe file is invalid (non-Win32 .exe or error in .exe image).
  • SE_ERR_ACCESSDENIED The operating system denied access to the specified file.
  • SE_ERR_ASSOCINCOMPLETE The file name association is incomplete or invalid.
  • SE_ERR_DDEBUSY The DDE transaction could not be completed because other DDE transactions were being processed.
  • SE_ERR_DDEFAIL The DDE transaction failed.
  • SE_ERR_DDETIMEOUT The DDE transaction could not be completed because the request timed out.
  • SE_ERR_DLLNOTFOUND The specified dynamic-link library was not found.
  • SE_ERR_FNF The specified file was not found.
  • SE_ERR_NOASSOC There is no application associated with the given file name extension.
  • SE_ERR_OOM There was not enough memory to complete the operation.
  • SE_ERR_PNF The specified path was not found.
  • SE_ERR_SHARE A sharing violation occurred.

GetTempPath

The GetTempPath function retrieves the path of the directory designated for temporary files.

How Windows sees the function
DWORD GetTempPath(
DWORD nBufferLength, // size, in characters, of the buffer
LPTSTR lpBuffer // pointer to buffer for temp. path
);

Parameters
nBufferLength specifies the size, in characters, of the string buffer identified by lpBuffer. Call the function with lpBuffer set to 256 and you'll be safe.

lpBuffer is a pointer to a string buffer that receives the null-terminated string specifying the temporary file path. The returned string ends with a backslash, for example, C:\TEMP\

Initialize lpBuffer to a string holding nBufferLength spaces before passing it to the function.

Return values
If the function succeeds, the return value is the length, in characters, of the string copied to lpBuffer, not including the terminating null character. If the return value is greater than nBufferLength, the return value is the size of the buffer required to hold the path.

If the function fails, the return value is zero.

Remarks
Windows 95, Windows 98 en Windows ME: The GetTempPath function gets the temporary file path as follows:
  1. the path specified by the TMP environment variable.
  2. the path specified by the TEMP environment variable, if TMP is not defined or if TMP specifies a directory that does not exist.
  3. the current directory, if both TMP and TEMP are not defined or specify nonexistent directories.
Windows NT: The GetTempPath function does not verify that the directory specified by the TMP or TEMP environment variables exists. The function gets the temporary file path as follows:
  1. the path specified by the TMP environment variable.
  2. the path specified by the TEMP environment variable, if TMP is not defined.
  3. the Windows directory, if both TMP and TEMP are not defined.

Code:

If you have any suggestions about the code please send me mail at a.van.lokhorst@hccnet.nl

Arthur van Lokhorst, Rotterdam
31 August 2001


Discussion of this article


 Feedback |  Paradox Day |  Who Uses Paradox |  I Use Paradox |  Downloads 


 The information provided on this Web site is not in any way sponsored or endorsed by Corel Corporation.
 Paradox is a registered trademark of Corel Corporation.


 Modified: 15 May 2003
 Terms of Use / Legal Disclaimer


 Copyright © 2001- 2003 Paradox Community. All rights reserved. 
 Company and product names are trademarks or registered trademarks of their respective companies. 
 Authors hold the copyrights to their own works. Please contact the author of any article for details.