Introduction

INI Basics

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:

• Open the REXX Information book and do a search for "SysIni".
• Use Copy in the Services menu (or just press Ctrl-Ins) to grab the entire section text and paste it into your favourite editor.
• Cut away all of the text except for the last few lines that contain the second sample program (there are two code snippets presented) and then save the file with a .cmd extension.

INI File Access with the REXX Utility Functions DLL

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

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

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

References