OS/2 e-Zine! - the REXX Files

the REXX Files

- by Dr. Dirk Terrell

Very often is it necessary to save information about a program when it is shut down. For example, a programmer may wish to save the location of a program's window, the color and typeface of a font being used, or the name of data files that the program has used so that they can be recalled when the program is restarted.

One could, of course, write routines to create and manage files to store this kind of information, but OS/2 comes with all the tools needed to perform such tasks with minimal coding. The solution lies in the OS/2 INI files. INI files are a relatively painless way of storing information across program invocations or sharing information between processes in a type of poor-man's interprocess communication. You could even use INI files to create a simple database.

Unlike Windows 3.1 INI files, OS/2 INI files are not in a pure ASCII format, and therefore can not be edited with a text editor like EPM. Fortunately, the REXXUTIL library has a function for reading and manipulating INI files. The function name is SysIni. This function can read, set, and delete entries from INI files. The hierarchy of INI file data goes like this:

Application ----> Key ----> Key Value

That is, the uppermost level is represented as an application name, with keys representing variables for that particular application.

The calling form for SysIni varies depending on what you are doing. To read the value of a particular key, the call is:

value=SysIni(IniFile,ApplicationName,KeyName)

To set the value of a key (or create it) you would use:

rc=SysIni(IniFile,ApplicationName,KeyName,Value)

And to delete a key you would use:

rc=SysIni(IniFile,ApplicationName,KeyName,"DELETE:")

Practical Uses

Suppose you need to determine the names of all keys associated with a particular application. SysIni makes this very easy too. A call of the form:

rc=SysIni(IniFile,ApplicationName,"ALL:",Stem)

where Stem represents a REXX stem variable, will return a list of all of the keys associated with the application stored in the stem variable. Following the usual convention for returned stems, Stem.0 contains the number of keys returned , and the key names are in Stem.1, Stem.2, ...

If you need to delete an application (and therefore all of its keys),

rc=SysIni(IniFile,ApplicationName,"DELETE:")

will do the trick. If, like me, you test many applications and then delete them, this is very handy for cleaning up your INI files.

Finally, if you need to get a list of all the applications in the INI file, use:

rc=SysIni(IniFile,"ALL:",Stem)

where Stem behaves as before.

Real World Examples

As an example of using INI files, let's look at how HTML Wizard, an HTML editor that I wrote mainly in REXX, uses them.

As a programmer, one thing I learned very quickly is that people want configurability in a program. For an editor, things like font type, colors, window size and position, and word wrap should be user-configurable and, of course, not require that the user set them every time the program is run. In HTML Wizard, the user can configure these things, and when the program exits, it saves the values in the HTMLWIZ.INI file.

A simple example of this is 'word wrap'. When editing HTML files, I can't stand it, but other people can't do without it. HTML Wizard allows everyone to do it their way with a menu item that can be set on or off. Now, it would be a pain for people to have to set that menu item every time they started the program, so when the program detects that the user has requested a shutdown, it determines the value of the word wrap menu item, and then saves that in the HTMLWIZ.INI file with application name "MainWindow", key name "WordWrap" and a key value of either 1 or 0 depending on whether word wrap is on or off. If word wrap is on, the call looks like:

rc=SysIni("HTMLWIZ.INI","MainWindow","WordWrap",1)

Other values are set in the same way. For example, people often use the same HTML tags repeatedly. To make things a little easier (and allow some flexibility as new HTML tags are added to the language), HTML Wizard allows the user to program buttons that insert whatever HTML code they want. And how does HTML Wizard remember these customized tags? By storing them in the HTMLWIZ.INI file:

rc=SysIni("HTMLWIZ.INI","User Tag 1","Tag","<MYTAG></MYTAG>")

When the program is started, it calls SysIni to find out what it should use for the user's programmable tags:

UserTag1=SysIni("HTMLWIZ.INI","User Tag 1","Tag")

Other Uses

Of course, there are many uses for INI files. You could probably implement a simple address book application using an INI file, with people's names as the application and phone number, e-mail address, etc. as keys. Or perhaps you might use a social security number in the application field, and put the names in key values.

One common need in REXX programming is to know when an application has finished so that another can then be started. Using an INI file, you could pull off such interprocess communication by setting a key value. When the one app finishes, it would set a key value which the second program is watching, and then the second program would continue with its processing. (There are, of course, better ways to accomplish this with some available third party libraries.)

Finally, there are two special values for the name of the INI file when calling SysIni. "USER" will point to the OS2.INI file and "SYSTEM" to the OS2SYS.INI file. I would caution you against messing with those files, however, unless you are sure you know what you are doing. If you mess them up, it could cause no end of problems with your OS/2 setup.

The example file (ZIP, 2k) this month contains a program that lists all applications and their associated keys in a given INI file. I have also included a sample HTMLWIZ.INI file that you can use for testing. Good luck!

Dr. Dirk Terrell is an astronomer at the University of Florida specializing in interacting binary stars. His hobbies include cave diving, martial arts, painting and writing OS/2 software such as HTML Wizard.

--
[Our Sponsor: MR/2 ICE Internet Email Client - Delivering the Email features of the future, today.]

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