GUI ScreenIO for Windows

Registry Functions

This API lets you use the standard Windows functions to read or update values in the registry. You can use this to save information for your application from session to session.

There are two versions. The basic set, and the extended set. The Extended set are intended to replace the basic set, and new applications should not deploy the basic set. The basic set may be withdrawn in future releases. Converting from the basic set to the extended set is as simple as changing the Function name called, and adding one additional argument to the function call.

Client/Server issues

The basic version of this API will behave as if it were running locally on the server. That is, it will access the server's registry, not the client's.

The Extended versions are Client/Server aware, and normally operate on the Client side, but can be forced to run on the Server side, and as such can be used to completely replace the basic version.

Files

Files available to copy to your system:

REGISTRY.COB - COBOL copybook with arguments for this function
REG-EX.COB - COBOL copybook for the Extended version of these APIs
WIN32API.COB - COBOL copybook common to all APIs and functions
Sample application - Demonstrates the use of this API

Application notes

You cannot access the registry except under the key that is appropriate for your application software. The subkey you specify is automatically appended to the correct high-order key value, so the full key will be:

HKEY_CURRENT_USER\Software\Company\Application\Subkey

You must provide your company name and the name of your application when you opened (or designed) your main/container panel
You must provide the subkey when you use this function
Total length of this key must be LESS THAN 255 bytes

The Extended version of these APIs (FUNC-EX... below) do not have these limitations and can be used to manipulate any registry key. As well, they are Client/Server capable.

Panel state-saving

You do not need to use this function to save the state of your panels; GUI ScreenIO does that automatically, using the key structure shown above. The subkey used by GUI ScreenIO to save the panel state is:

\GUI ScreenIO\Saved State

and the panel-specific data uses the panel name as the key. You can inspect it yourself by using the Windows program Regedit.exe. Note that these automatic panel state variables are always stored on the Client side if running under the Client/Server.

Using the registry for other data

Your data is stored beneath your key in name/data pairs.

You may have many named elements beneath your key. For example, you can use the Windows program Regedit.exe to inspect the registry entries belonging to GUI ScreenIO. Look under this key:

HKEY_CURRENT_USER\Software\Norcom\GUI ScreenIO Editor\Settings

Under this key, you will find several item:

Advanced (hex values, stored as a BINARY type)
Base (hex values, stored as a BINARY type)
CompanyName (Text, stored as a TEXT type)

...and so on. If you selected the option to save user preferences in your GUI ScreenIO application, GUI ScreenIO creates a GUI ScreenIO\Saved State subkey automatically. The names of the items are your panel names, and the panel state is stored as a binary item.

Functions

FUNC-REGISTRY-PUT

Write/update data in the Registry.

FUNC-REGISTRY-GET

Retrieves a value from the registry.

FUNC-REGISTRY-DELETE-VALUE

Deletes a value from the registry.

FUNC-REGISTRY-DELETE-SUBKEY

Delete a key and all descendants from the registry, including all subkeys and values

FUNC-EX-REGISTRY-PUT

Extended version. Allows writing data in any register hive (hkey) and is client server aware.

FUNC-EX-REGISTRY-GET

Extended version. Allows reading data from any registry key.

FUNC-EX-REGISTRY-DELETE-VALUE

Extended version. Allows deleting a value for any registry key. (Use with caution).

FUNC-EX-REGISTRY-DELETE-SUBKEY

Extended version. Allows deleting a complete registry subkey and values. (Use with EXTREME caution).

Usage

COPY WIN32API.
COPY REGISTRY.

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

     SET FUNC-REGISTRY-GET TO TRUE.

     CALL 'GSWINAPI' USING WIN32API-PARMS
                           REGISTRY-PARMS
                           WIN32API-B
                           WIN32API-C
                           WIN32API-D
                           WIN32API-E
                           WIN32API-F.

For the WRITE functions:

If a key does not exist, it will be created.
If the key does exist, it will be updated.

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

Parameters specific to this function

REGISTRY-SUBKEY

Name of the subkey, up to 254 bytes in length.

REGISTRY-VALUENAME

Your name for this data item. You can store multiple data items under the same subkey name.

REGISTRY-DATA

Data associated with your key, up to 1023 bytes in length.

For WRITE: Value to store/update; If none specified, delete key and value.
For GET: Value retrieved; If not found, this will be unchanged.

This version of our API supports only 1023 bytes (we reserve space to insert a low-value terminator in case you forget to do so). Do not attempt to store longer data because we will internally limit it to 1023 bytes.

REGISTRY-DATA-FORMAT

Specifies the type of data in REGISTRY-DATA. Set the desired value to TRUE. Example:

SET REGISTRY-DATA-IS-TEXT TO TRUE.

For a GET, it returns the format of the data. Values are:

REGISTRY-DATA-IS-TEXT
REGISTRY-DATA-IS-BINARY
REGISTRY-DATA-IS-DWORD
REGISTRY-DATA-IS-QWORD
REGISTRY-DATA-IS-EXPAND-SZ
REGISTRY-DATA-IS-MULTI-SZ

See the copybook for explanations of these values. You should always set the data format when putting data into the registry and Windows will tell you the format for data you retrieve.

REGISTRY-DATA-LENGTH

Byte count. Not used for TEXT format, required for BINARY data.

For WRITE: Number of bytes of binary data to be written
For GET: Number of bytes of binary data returned in REGISTRY-DATA

EXTENDED-REGISTRY-PARMS - For EX versions only

The single argument in the REG-EX.COB copybook replaces the WIN32API-B argument in the call illustrated above, and is used ONLY when you are calling the Extended version of the APIs.

The purpose of using the Extended registry parms in conjunction with the FUNC-EX calls is to store or retrieve registry values in locations of the registry other than your own applications registry area. For example, if you wanted to store information for other applications, or retrieve settings from other applications registry entries, you must use the FUNC-EX calls.

The call then, would look like this:

COPY WIN32API.
COPY REGISTRY.

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

     SET FUNC-EX-REGISTRY-GET TO TRUE.

     CALL 'GSWINAPI' USING WIN32API-PARMS
                           REGISTRY-PARMS
                           EXTENDED-REGISTRY-PARMS
                           WIN32API-C
                           WIN32API-D
                           WIN32API-E
                           WIN32API-F.

This argument is used to select the HIVE (the HKEY portion of the registry key). This argument contains a data name EX-REGISTRY-MAJOR-KEY , and appropriate 88 names to specify each hive of the registry:

EX-REG-HKEY-DEFAULT
EX-REG-HKEY-CURRENT-USER
EX-REG-HKEY-CLASSES-ROOT
EX-REG-HKEY-LOCAL-MACHINE
EX-REG-HKEY-USERS
EX-REG-HKEY-CURRENT-CONFIG

If you select EX-REG-HKEY-DEFAULT, GUI ScreenIO will automatically attempt to store your application data in the correct (default) location in the Registry, complying with Microsoft Windows standards. This is not perfect, and you would be well advised to manually select the hive you want.

The high-order node of the registry key uses the Company and Application values supplied in your MAIN panel (when using hkey-default), and the value you supply in SUBKEY is appended to it. The complete registry key generated by GUI ScreenIO is:

HKEY_CURRENT_USER\Software\Company\Application\Subkey

However, to reference other areas of the registry you can not use EX-REG-HKEY-DEFAULT, and must specify the hive explicitly.

NOTE: You are responsible for building the entire subkey, below the Hkey portion when you use OTHER than EX-REG-HKEY-DEFAULT. For Example, to find out what type of processor is installed on the target machine:

     COPY WIN32API.
     COPY REGISTRY.
     COPY REG-EX.
     .
     .

     SET EX-REG-HKEY-LOCAL-MACHINE TO TRUE.

     STRING 'HARDWARE\'
          'DESCRIPTION\'
          'System\'
          'CentralProcessor\'
           '0'
           DELIMITED SIZE INTO REGISTRY-SUBKEY.

     MOVE 'ProcessorNameString' TO REGISTRY-VALUENAME.

     SET FUNC-EX-REGISTRY-GET TO TRUE.
     CALL 'GSWINAPI' USING WIN32API-PARMS
       REGISTRY-PARMS
       EXTENDED-REGISTRY-PARMS
       WIN32API-C
       WIN32API-D
       WIN32API-E
       WIN32API-F.

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.

TOC

Send feedback to Norcom