GUI ScreenIO for Windows

 ScreenIO.com


Initialization File (.INI file) Functions

This API lets you use the standard Windows functions to read or update initialization files.

Note that modern 32-bit Windows applications generally use the registry to store configuration data. However INI files are seeing a resurgence for several reasons: there are significant advantages to using ini files because they can be more easily distributed with your application, more easily backed up, can be shared in a common location for multiple users on a local area network, can be managed without administrative privileges, and edited with a standard text editor.  

For these reasons, Microsoft has significantly backed off its suggestion to rely solely on the registry.

Client/Server issues

This API will maintain .ini files located on the client.

To maintain .ini files on the server:

     SET WIN32API-EXECUTE-API-ON-SERVER TO TRUE

Files

Files available to copy to your system:

Functions

API-GETPRIVATEPROFILESTRING

Retrieves a string from the specified section of an initialization file.

API-WRITEPRIVATEPROFILESTRING

Copies a string into the specified section of an initialization file.

API-WRITEPRIVATEPROFILESECTION

Copies multiple strings into the specified section of an initialization file.

Usage

     COPY WIN32API.
     COPY INIFILE.

* ------------------------: Call the API.

     SET API-GETPRIVATEPROFILESTRING TO TRUE.

     CALL 'GSWINAPI' USING WIN32API-PARMS
                           INI-FILE-PARMS
                           INI-FILE-FILENAME
                           WIN32API-C
                           WIN32API-D
                           WIN32API-E
                           WIN32API-F.

For the WRITE functions:

Note: The keys and section names are NOT case sensitive.

Parameters specific to this function

INI-FILE-SUBKEY

Name of the [Section].

INI-FILE-VALUENAME

Your name for this data item. You can store multiple data items under the same [Section] name. 

For Write functions:

INI-FILE-DATA

Text data associated with your key. 

Note:  Binary values are unsupported; this must be TEXT data. If you're storing numeric data, save it as DISPLAY, not binary (COMP-4 or COMP-5) format.

INI-FILE-DATA-LENGTH

For GET:  Number of bytes returned to your program; if your buffer was not large enough,  number of bytes required.

INI-FILE-FILENAME

Name of the .INI file.

For Write functions:  If you do not specify a full path, create in the Windows directory.

For Get functions:  If you do not specify a full path, looks in the Windows directory.

WIN32API-PARMS - Used in all GSWINAPI calls

This argument is standard for all CALLs to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.

WIN32API-RC

Used to return the status of a call to GSWINAPI.  A value of zero is a failure, any other value indicates success.

Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.

* ------------------------: If function failed,
*                         :   display the error in a message box.
*
     IF WIN32API-FAILED
       MOVE WIN32API-ERROR-TEXT TO panel-MESSAGE-TEXT
       SET panel-MESSAGE-IN-MESSAGEBOX TO TRUE.

WIN32API-ERROR-CODE

Error code that was returned by Windows.  This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

Plain-text error message that describes why the operation failed.

WIN32API-A through WIN32API-F

The number of these present varies depending on how many arguments are used by the desired function.  These are not used, but must be present because this CALL requires seven arguments.


2000-2006 Norcom, all rights reserved 

TOC

Send feedback to Norcom