[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

PrfQueryProfileInt

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

Syntax

 lRC = PrfQueryProfileInt( hini, pszAppName, pszKeyWord, lDefault );

Parameters
HINI hini (input)
Handle to profile to be searched for data. This may be one of the following:

HINI_PROFILE Search both the USER and SYSTEM profiles.
HINI_USERPROFILE Search only the USER profile.
HINI_SYSTEMPROFILE Search only the SYSTEM profile.
a variable Search a program-defined profile. This is a HINI returned by PrfOpenProfile().

PSZ pszAppName (input)
Pointer to a null-terminated string that holds the application name to search for within the profile. This string is case-sensitive.
PSZ pszKeyWord (input)
Pointer to a null-terminated string that holds the keyword name to search for within the application name specified. This is case-sensitive as well.
LONG lDefault (input)
The value of lDefault is returned if the application/keyword pair cannot be located in the specified profile.

Returns
LONG lRC
This return value is the result of searching for the application/keyword pair in the specified profile. It may be:

0 The data associated with the application and keyword is not an integer.
lDefault The last parameter of PrfQueryProfileInt() is returned to you if the application or keyword could not be found in the profile.
otherwise The value associated with the application/keyword pair is returned.

If lDefault, you may use WinGetLastError() to find out what went wrong. Possible errors PrfQueryProfileInt() may incur:

PMERR_INVALID_PARM 0x1303 One of the parameters to PrfQueryProfileData() was invalid.
PMERR_NOT_IN_IDX 0x1304 The application name, keyword, or program handle was not found.
PMERR_CAN_NOT_CALL_SPOOLER 0x130D An error related to the spooler occured. (?)

Include Info

 #define INCL_WINSHELLDATA
or
#define INCL_WIN
or
#define INCL_PM
#include <os2.h>

Usage Explanation

 The one feature that makes PrfQueryProfileInt() useful is how it interprets data. If you store a long integer as a four byte data type, then you'll have to use PrfQueryProfileData() to retrieve it. However, PrfQueryProfileInt() allows you to store an integer as an ASCII string. For example, if the string "32462" is stored in a profile and PrfQueryProfileInt() is called, it will convert this string to its binary equivalent for you.

Relevant Structures

Gotchas

 Both the application name and the keyword are CASE SENSITIVE. It is recommended that all your references to these strings come from a single source, such as a #define or a global variable, so as not to get tripped up on this. It is recommended that strings are null-terminated to reduce errors, but it seems that PrfQueryProfileInt() will just stop reading the string when it hits a non-numeric character. So, "123xyz" will return 123. The implication is that comma-delimited strings make this function useless. For example, "100,000" will return 100. Obviously, floating point numbers get truncated. Also, the numerics must be the first characters in the string. The one non-numeric character that seems to be allowed is a '-', to signify a negative integer. "-123" returns -123. If there's a possibility that you might pass a zero for the last parameter, or the string should legitimately return a zero, then you should call WinGetLastError() to see if there was a problem.

Sample Code

 #define INCL_WINSHELLDATA #include <os2.h> #include <stdio.h> static UCHAR szAppName[] = "MyApp"; static UCHAR szKeyName[] = "MyKey"; int main(void) { HINI hini; LONG lRC; /* I write this string to give you a basis for experimentation... */ PrfWriteProfileString(HINI_USER, szAppName, szKeyName, "-100.10,000x"); /* * I specified 2 for the last param, as there's no way a two will get * returned by accident in this experiment. */ lRC = PrfQueryProfileInt(HINI_USER, szAppName, szKeyName, 2); printf("PrfQueryProfileInt returned %d\n", lRC); return(0); } /* main */

See Also

 PrfQueryProfileData, PrfWriteProfileString

Author

Ryan C. Gordon -- warped42@ix.netcom.com

Additions

Last modified June 13/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

PrfQueryProfileInt