|GUI ScreenIO for Windows|
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.
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 available to copy to your system:
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:
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.
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.
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:
...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.
Write/update data in the Registry.
Retrieves a value from the registry.
Deletes a value from the registry.
Delete a key and all descendants from the registry, including all subkeys and values
Extended version. Allows writing data in any register hive (hkey) and is client server aware.
Extended version. Allows reading data from any registry key.
Extended version. Allows deleting a value for any registry key. (Use with caution).
Extended version. Allows deleting a complete registry subkey and values. (Use with EXTREME caution).
* ------------------------: Call the API.
Note: The keys and section names are NOT case sensitive.
Name of the subkey, up to 254 bytes in length.
Your name for this data item. You can store multiple data items under the same subkey name.
Data associated with your key, up to 1023 bytes in length.
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.
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:
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.
Byte count. Not used for TEXT format, required for BINARY data.
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:
* ------------------------: Call the API.
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:
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:
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:
SET EX-REG-HKEY-LOCAL-MACHINE TO TRUE.
DELIMITED SIZE INTO REGISTRY-SUBKEY.
MOVE 'ProcessorNameString' TO REGISTRY-VALUENAME.
SET FUNC-EX-REGISTRY-GET TO TRUE.
CALL 'GSWINAPI' USING WIN32API-PARMS
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.
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,
Error code that was returned by Windows. This is not generally useful unless you have the Windows Platform SDK documentation available to you.
Plain-text error message that describes why the operation failed.
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|