PrfWriteProfileString

This function writes a string of character data into the specified profile.

Syntax

PrfWriteProfileString(hini, pszApp, pszKey, 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.

pszApp (PSZ) - 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.

pszKey (PSZ) - 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.

pszData (PSZ) - 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

See Also

• PrfQueryProfileString