PrfWriteProfileString: Difference between revisions
Appearance
mNo edit summary |
No edit summary |
||
Line 2: | Line 2: | ||
==Syntax== | ==Syntax== | ||
PrfWriteProfileString(hini, pszApp, pszKey, pszData) | PrfWriteProfileString(HINI ''hini'', PSZ ''pszApp'', PSZ ''pszKey'', PSZ ''pszData'') | ||
=== Parameters === | === Parameters === | ||
;hini ( | ;HINI ''hini''(input) | ||
:Initialization-file handle. | |||
:;HINI_PROFILE:User profile | :;HINI_PROFILE:User profile | ||
:;HINI_USERPROFILE:User profile | :;HINI_USERPROFILE:User profile | ||
:;HINI_SYSTEMPROFILE:System profile | :;HINI_SYSTEMPROFILE:System profile | ||
:;Other:Initialization-file handle returned by [[PrfOpenProfile]]. | :;Other:Initialization-file handle returned by [[PrfOpenProfile]]. | ||
;pszApp ( | ;PSZ ''pszApp'' (input) | ||
:Application name | |||
:The case-dependent name of the application for which profile data is to be written. Names starting with the characters "PM_" are reserved for system use. | :The case-dependent name of the application for which profile data is to be written. Names starting with the characters "PM_" are reserved for system use. | ||
;pszKey ( | ;PSZ ''pszKey'' (input) | ||
:Key name. | |||
:The case-dependent name of the key for which profile data is to be written. | :The case-dependent name of the key for which profile data is to be written. | ||
:This parameter can be NULL, in which case all the pszKey or pszData pairs associated with the pszApp parameter are deleted. | :This parameter can be NULL, in which case all the pszKey or pszData pairs associated with the pszApp parameter are deleted. | ||
;pszData ( | ;PSZ ''pszData'' (input) | ||
:Text string. | |||
:This is the value of the pszKey or pszData pair that is written to the profile. | :This is the value of the pszKey or pszData pair that is written to the profile. | ||
:If this parameter is NULL, the string associated with the pszKey is deleted (that is, the entry is deleted). | :If this parameter is NULL, the string associated with the pszKey is deleted (that is, the entry is deleted). |
Revision as of 21:09, 21 November 2023
This function writes a string of character data into the specified profile.
Syntax
PrfWriteProfileString(HINI hini, PSZ pszApp, PSZ pszKey, PSZ pszData)
Parameters
- HINI hini(input)
- Initialization-file handle.
- HINI_PROFILE
- User profile
- HINI_USERPROFILE
- User profile
- HINI_SYSTEMPROFILE
- System profile
- Other
- Initialization-file handle returned by PrfOpenProfile.
- PSZ pszApp (input)
- Application name
- The case-dependent name of the application for which profile data is to be written. Names starting with the characters "PM_" are reserved for system use.
- PSZ pszKey (input)
- Key name.
- The case-dependent name of the key for which profile data is to be written.
- This parameter can be NULL, in which case all the pszKey or pszData pairs associated with the pszApp parameter are deleted.
- PSZ pszData (input)
- Text string.
- This is the value of the pszKey or pszData pair that is written to the profile.
- If this parameter is NULL, the string associated with the pszKey is deleted (that is, the entry is deleted).
- If this parameter is not NULL, the string is used as the value of the pszKey or pszData pair, even if the string has zero length.
Returns
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion
- FALSE
- Error occurred.
Errors
Possible returns from WinGetLastError:
- PMERR_INVALID_PARM (0x1303)
- A parameter to the function contained invalid data.
- PMERR_CAN_NOT_CALL_SPOOLER (0x130D)
- An error occurred attempting to call the spooler validation routine. This error is not raised if the spooler is not installed.
Remarks
If there is no application field in the file that matches the pszApp, a new application field is created before the pszKey or pszData entry is made.
If the key name does not exist for the application, a new pszKey or pszData entry is created for that application. If the pszKey already exists in the file, the existing value is overwritten.
Sample Code
This function writes and then reads a string written to the profile associated with the application STRINGY.EXE.
/* This programs writes and then read string data to a profile. */ /* Some error checking has been omitted for brevity. */ #define INCL_WINSHELLDATA #define INCL_WINERRORS #define INCL_DOSERRORS #include <os2.h> #include <stdio.h> #include <string.h> INT main(VOID) { HAB hab = NULLHANDLE; HINI hini = NULLHANDLE; PSZ pszFileName = "STRINGY.INI"; BOOL rc = TRUE; ULONG i = 0L; PSZ pszAppName = "STRINGY.EXE"; PSZ pszKeyName = "STATUS"; PSZ pszString = "The string is alive."; PSZ pszStringRead = NULL; APIRET ret = NO_ERROR; ULONG ulDataSize = 0L; hab = WinInitialize( 0 ); hini = PrfOpenProfile( hab, pszFileName ); rc = PrfWriteProfileString( hini, pszAppName, pszKeyName, pszString); if(rc == FALSE) { printf("PrfWriteProfileString error code: %X\n", WinGetLastError(hab)); return 1; } /* Retrieve size of string in profile, and allocate memory for it */ rc = PrfQueryProfileSize( hini, pszAppName, pszKeyName, &ulDataSize ); ret = DosAllocMem( (PPVOID)&pszStringRead, ulDataSize, (ULONG)PAG_COMMIT | PAG_READ | PAG_WRITE ); /* Retrieve data string */ rc = PrfQueryProfileString( hini, pszAppName, pszKeyName, (PSZ)"Error Retrieving Data", (PVOID) pszStringRead, ulDataSize ); if(rc==FALSE) { printf("PrfQueryProfileData error code: %X\n", WinGetLastError(hab)); return 1; } printf("Profile String read: '%s'\n", pszStringRead ); PrfCloseProfile( hini ); /* Close the profile */ DosFreeMem( pszStringRead ); /* Free memory */ return NO_ERROR; /* Return to the call