7 Mar 1995 - Preliminary Information

Bugs can be most easily fixed when they are reported with enough information to reproduce or at least localize the problem. Suggestions will be most helpful if the user understands what things are simple and what changes will be most difficult. For these reasons, it is a good idea to provide at least a high level review of SpHyDir program logic.

SpHyDir is driven by the abilities and limitations of the OS/2 operating system, the Rexx language, and the VX-Rexx development environment. It would not have been possible to develop SpHyDir so quickly with anything like its current function in any other environment.

Rexx is an interpreted language. This means that execution works directly off a version of the source. Development is fast, and debugging is easy. However, some errors that in other languages would be detected by the compiler are, in Rexx, not found until execution time.

An important limit of Rexx is that programs in two separate source files cannot share global variables. A program like SpHyDir works only if it can be packaged as one massive source file. Using a normal editor, such a large program becomes unmanagable. VX-Rexx addresses this problem by dividing the code into "sections." Each section has a name and logically appears to the programmer as if it were a separate file. In the end, VX-Rexx combines all the sections into a single file so that variables can be shared.

Although IBM is distributing a test version of an Object Oriented Rexx, SpHyDir is written in the traditional SAA OS/2 Rexx language. Object would probably have been useful, but many current Warp users will not have access to the Object Rexx package and PCLT cannot redistribute it.

VX-Rexx creates its own objects to manage the Graphic User Interface. A Rexx program, such as SpHyDir, cannot define new types of objects, but there are a few general purpose VX-Rexx objects that are quite flexible. In particular, the Document is expanded in the Workarea as a sequence of Record Objects with a Container. VX-Rexx created (actually OS/2 PM created) the Container and Record. Records have attributes (the icon displayed, the caption, the parent and sibling order that creates the tree). VX-Rexx provides functions that SpHyDir can call to set or interrogate these attributes or to create new instances of Records. The rest of the VX-Rexx objects (windows, buttons, lists, and menus) are defined statically during development using the VX-Rexx tools.

The objects exist in memory managed by the VX-Rexx system outside the scope of Rexx internal variables. Statically defined objects have a name which is set at design time and can be added to any program. Dynamic objects, such as records, have an internally generated id (the "handle"). Handles can be passed as arguments or stored in global variables. However, the currently selected record in the Workarea can be determined at any time by calling a VX-Rexx function (to essentially ask the workarea what record is selected), and much of the code interrogates the VX-Rexx objects for information rather than relying on global variables or other ugly interface options.

The Main Window contains the Toolbar, Workarea, and entry fields. It is loaded when SpHyDir starts and goes away when the program ends. The other windows (Link Manager, Table of Contents, Text Edit, and Hotword Selection) are loaded as needed. Because the Main Window is always loaded, the Workarea object (and its Records) are available to every part of the code.

In VX-Rexx, a secondary window is created during program design and is populated with lists, fields, buttons, and menus. The Rexx code that will be called when the user types data into or uses controls on a secondary window can be a separate file, but SpHyDir chooses to make it part of the one large common code routine.

However, the objects on a secondary window do not exist until that window is "loaded." SpHyDir loads secondary windows in response to actions in the Main Window. The Table of Contents and Link Manager are loaded from the "Window" menu, the Clipboard loads when the user puts something in it, and the Text Edit window loads when the user doubleclicks on a Paragraph, Point, or other record containing text content. In all cases, the objects in the secondary window do not exist until it has been loaded.

Secondary windows are created by default as "children" of the main window. This means that when the secondary and main windows overlap, the secondary window is alway "on top." A secondary window can also be created as a child of the desktop, which would allow the main window to be on top. SpHyDir doesn't use the latter option (it didn't seem to look right, but that is a value judgement).

The Workarea is a container permanently set to a Tree-Name view. The Toolbar is a Value Set whose contents are icons. Normally a value set is a kind of radio button (one value is selected) but that is not how the Toolbar is used. Rather, sometimes the icons are double-clicked and sometimes they are drag-dropped. The Value Set was chosen simply because it is a convenient way to arrange a bunch of icons.

VX-Rexx provides a function that returns the handle of the first record in a Container. In SpHyDir, this is the Document record. Other functions can find the first child of any parent record, or the next record among a collection of siblings. All the information about the document (text, links, structure, etc.) can be globally accessed by any function in the SpHyDir program by simply "walking" the tree of container records.

Records have attributes and data fields.

• Attributes apply to all records. They are defined by PM or VX-Rexx. They include the Icon, Caption text, and emphasis (looks Selected, looks Open, etc.). Attributes are set when the record is created, and can be changed by calling the method functions provided by the Container object. A record can be moved, for example, by changing the two attributes that determine position: Parent that determines what if any record is directly above it in the tree, and Previous that determines the record in front of it among all the records under that parent (though if Previous is set to "FIRST" it goes in front of its siblings just after the Parent).
• Fields contain the data that an application chooses to define. Normally, the Fields of a record are the columns displayed when the container is put in Details View. However, SpHyDir doesn't ever change the container view, so the Field contents are never displayed on the screen. What does show up to the right of the Icon is the Caption, which is an attribute as described above. SpHyDir assigns five text string fields to every record:
  1. Type is a word that determines the type of the object. The Type value is always capitalized. Types include DOC, SECTION, PARA, IMG, OLIST, ULIST, DLIST, POINT, TOC, TARGET, PRE, HR, SUBDOC, FORM, ENTRY, MLE, RADIOBUT, CHECKBOX, SPIN, and LISTBOX.
  2. The Text string contains the text of the paragraph, point, or preformatted section, the title of a document, the header of a section, the alternate text of an image, or the caption of a box or button. Conceptually, Text is what is "inside" the object in the sense that when you double click on an object to open the text window, this is what shows up.
  3. The Name string contains the file name of the Document or Image object, the term of a Defininition List item, the label of a Target, or the name of a variable associated with a Form object.
  4. The Links string contains a list of file references or URLs. An image has only one link. A paragraph or point can have multiple hotword links. Each 0x10,0x11 character pair in the Content string correspond to one filename/URL in the Links string.
  5. Align was originally used only with images and contained the alignment option. When Forms objects were added, the field was reused to contain shape information (height, width, length) but it has not yet been renamed.
  6. Entry contains the static default string for a simple text entry area. The Text field contains the caption, and there was no other field to put this in.

  The Text field contains a string that represents the contents of the paragraph or list point. Within this string, <BR> tags have been converted to Carriage Return, Linefeed. Hotwords start with a 0x10 and end with a 0x11. Each consecutive hotword string in the text corresponds to one file/URL in the Link field. The character format tags (I, B, CITE, CODE, etc.) are embedded in the text, but the < and > have been replaced by 0x1E and 0x1F respectively. The &amp, &lt, and &gt entities have been converted back to &, <, and > for easy editing. They will be converted back to entities when the file is written out.