OS/2 INI File Access with REXX- by Chris Peake

Introduction

Programs written for OS/2's graphical user interface often have to store program initialization information and keep track of settings between executions. To handle this storage of information efficiently, OS/2 makes use of INI files to store text or binary data that is easily accessible by the application. This article will describe the basic internal structure of an INI file and show how to access INI file information using the standard REXX Utility Functions DLL (REXXUTIL.DLL) and Watcom's VX-REXX (v2). To demonstrate the practicality of INI files, a simple VX-REXX skeleton application that maintains window size and location between executions using an INI file will be created. A basic understanding of REXX and VX-REXX is assumed throughout this article.

INI Basics

OS/2 uses two main INI files for storing information between boots. OS2SYS.INI contains OS/2 system initialization information and OS2.INI contains user setup information pertaining to your specific system. Applications may have their own INI file for storing information or may share INI files with others (many use OS2.INI). Preferably, each program should have its own INI file to provide easier system maintenance and keep the OS/2 INI files uncluttered.

INI files are divided into separate Application sections for each application that uses the INI file. Under each Application heading in the INI file, there are keywords that have some binary or text information associated with them. An analogous situation is the way files are stored on a hard drive; the actual INI file being analogous to the root, Applications representing subdirectories and keywords representing files that contain the information required.

To become familiar with how applications use (and share) an INI file, the REXX Information book in the OS/2 Information folder has a useful sample program. To run the program:

Now the program can be run to see how information in the User INI file (OS2.INI) is arranged. It becomes apparent how an INI file may become cluttered by looking at the amount of information presented and the variety of applications sharing the User INI file (depending on applications installed on a machine).

INI File Access with the REXX Utility Functions DLL

The REXX Utility Functions DLL (REXXUTIL.DLL) uses the SysIni command to access INI files. A program can set, retrieve and query information contained with the INI file using various combinations of parameters with the SysIni command. Programs can make good use of INI files by just setting and retrieving keywords so only the set and retrieve functions are discussed here. For those who would like to know more, the REXX Information on-line book describes all of the options available for INI file access under the SysIni section.

Before using the SysIni command, it must be loaded from the DLL using the following command:

call RxFuncAdd SysIni, REXXUTIL, SysIni

Now that the command is available to all REXX programs (until it is unloaded using RxFuncDrop), SysIni can be used to set a keyword value:

result = SysIni(inifile, application, keyword, value)

where inifile is the filespec of the INI file to be accessed, application and keyword are strings naming the application and its keyword and value is the binary or text data to be stored. If successful, result will be set to the null string ('').

The command to retrieve a keyword value is very similar:

value = SysIni(inifile, application, keyword )

The value variable will now contain the keyword value associated with application. If the application and keyword pair are not present, value will contain the string ERROR:.

To access OS/2's System and User INI files, the strings SYSTEM or USER can be used as the inifile parameter.

INI File Access with VX-REXX

Watcom's VX-REXX has three commands for handling INI files: VRDelIni, VRGetIni and VRSetIni. As with the REXX Utility Functions SysIni command, only setting and retrieving INI keyword values is described here.

The syntax for setting an application's keyword value is

rc = VRSetIni(application, keyword, value,[inifile], ["NoClose"])

The inifile, application, keyword and value variables have the exact same meaning as with the SysIni command. If the inifile parameter is omitted, the User INI file is assumed (OS2.INI). The optional "NoClose" parameter causes the application to keep the INI file open to speed up subsequent access. The rc variable will be set to 1 if the operation is successful, 0 otherwise.

To retrieve an application's keyword value, the command is

value = VRGetIni(application, keyword, [inifile], ["NoClose"])

No surprises here; the syntax is again very similar to the equivalent SysIni command, but the parameters are switched around and the "NoClose" parameter is added. The value variable will contain the keyword value if it is present in the specified INI file. If the keyword is not found, value will be set to the null string ('').

To access OS/2's System and User INI files, the strings 'System' or 'User' can be used as the inifile parameter.

INI Files by Example

INI files are excellent for saving window size and position between program executions. VX-REXX programs can handle this task with simple modifications to the Fini and Init sections of the main window file.

To retrieve and use window size and position information before the main program window is drawn, several steps must be taken in the Init section. First, the filespec of the application's INI file must be found. If the INI file exists, the window coordinate information can be retrieved. If the INI file doesn't exist, default values should be used instead.

To locate the INI file, the steps described in the Programmer's Manual included with VX-REXX (p.139) can be used.

rc = VRGet( "Application", "Program" )
WorkingDir = VRParseFileName( rc, "DP" )
INIFile = WorkingDir||'\MyApp.INI'

Now that the filename for the INI file is available, the application should check to see if the INI file exists (i.e. is this the first time the program has been run?). If the INI file does not exist, default values should be used when drawing the main program window.

ok = VRFileExists( INIFile )
if \ok then do
WindowTop = ''
WindowLeft = ''
WindowWidth =
WindowHeight =
end

The WindowTop and WindowLeft variables are set to null strings because the window will be centred later using a window method. The WindowWidth and WindowHeight variable are set to the values obtained from the Size page of the main program window's properties book. If the INI file does exist, the VRGetIni command retrieves the main window's coordinate information. This piece of code is the second half of the if statement above:

else do
WindowTop = VRGetIni( " MyApp ", "WindowTop", INIFile, "NoClose" )
WindowLeft = VRGetIni( " MyApp ", "WindowLeft", INIFile, "NoClose" )
WindowWidth = VRGetIni( " MyApp ", "WindowWidth", INIFile, "NoClose" )
WindowHeight = VRGetIni( " MyApp ", "WindowHeight", INIFile, )
end

The "NoClose" parameter is used repeatedly in the VRGetIni command until the last call in order to keep the INI file open for successive access and to speed things up. Now the coordinate information is ready for passing to the main program window.

To change the dimensions and position of the window, the VRSet command is used to change the window's Width and Height properties as shown here:

window = VRWindow()
/* Restore window position. */
if WindowLeft \= '' then ok = VRSet( "Window1", "Left", WindowLeft )
if WindowTop \= '' then ok = VRSet( "Window1", "Top", WindowTop )
ok = VRSet( "Window1", "Width", WindowWidth )
ok = VRSet( "Window1", "Height", WindowHeight )
if WindowTop = '' then call VRMethod window, "CenterWindow"
call VRSet window, "Visible", 1
call VRMethod window, "Activate"
drop window
return

Note that the instructions to set the main window's width and height occur before the instruction to make the window visible. In this way, the window is resized before it is drawn. Any other events that are triggered on a window resize event will happen before the window becomes visible, allowing other elements contained in the window to be resized appropriately before drawing as well.

To save window size and position upon exit, the Fini section of the main program needs to be modified. The window's position and size is fully described by its upper left x,y coordinates along with the window's width and height. To get this window information, the VRGet command is used.

WindowLeft = VRGet( "Window1", "Left" )
WindowTop = VRGet( "Window1", "Top" )
WindowWidth = VRGet( "Window1", "Width" )
WindowHeight = VRGet( "Window1", "Height" )

Once this information is obtained, it can be transferred to the application's INI file using VRSetIni.

ok = VRSetIni( "MyApp", "WindowTop", WindowTop, INIFile, "NoClose" )
ok = VRSetIni( " MyApp ", "WindowLeft", WindowLeft, INIFile, "NoClose" )
ok = VRSetIni( " MyApp ", "WindowWidth", WindowWidth, INIFile, "NoClose" )
ok = VRSetIni( " MyApp ", "WindowHeight", WindowHeight, INIFile, )

Again, the "NoClose" parameter is used repeatedly until the last INI file access has occurred to keep the INI file open. These two sets of lines can be placed anywhere in the Fini section of the main window file.

Functionality that is taken for granted in most programs can be added to a VX-REXX program with relatively few lines of code. Taken to the extreme, the method shown could be used to make an application customizable by saving and retrieving font/colour information for interface objects when shutting down or starting up the application.

Conclusion

When used effectively, an INI file can really make a program shine. REXX and VX-REXX both help by making INI file access an easy and painless addition to a program. As well as storing window configuration information, any settings such as working directories or hot-key values are ideal candidates for storage in a program INI file. The uses are only limited by one's imagination.

References

VX-REXX Programmer's Reference Manual, Watcom Inc., p139, p520, p679.

OS/2 Procedures Language/2 Reference on-line manual, IBM Inc.


Chris Peake is somewhere between 3rd and 4th year in the Engineering Science program at Simon Fraser University in beautiful B.C. He will be working at Nortel in Ontario for co-op this fall. In his spare time he... uhh... can't remember what it's like to have spare time.

[Index]  [ Previous] - [Feedback] - [Next ]
[Our Sponsor: Prominic Technologies - Software developer and IBM PC VAR preloading OS/2.]


This page is maintained by Falcon Networking. We welcome your suggestions.

Copyright © 1996 - Falcon Networking