Macro structure

This chapter describes the general structure of a macro as it can be seen in an XML macro script.

Macro script

A macro script is an XML script used to store a macro. You can view and edit the XML text of a macro script by using the source view of the VME or the basic Macro Editor.

Learning a little about the XML elements of the macro language will greatly increase your understanding of important topics, including the following:

This book refers not only to the input fields, buttons, and list boxes provided by the macro editors, but also to the corresponding XML elements in which the same information is stored.

XML elements

To understand macro scripts you do not need to learn a great deal about XML, just the basics of the syntax. If your knowledge of XML syntax needs brushing up, you can learn more about it in XML syntax in the Host On-Demand macro language. However, almost all of what you need to know is covered in this subsection.

An XML script consists of a collection of XML elements, some of which contain other XML elements, in much the same way that some HTML elements contain other HTML elements. However, unlike HTML, XML allows a program developer to define new XML elements that reflect the structure of the information that the developer wishes to store. The Host On-Demand macro language contains approximately 35 different types of XML elements for storing the information needed to describe a macro. This macro language is described at length in The Host On-Demand macro language.

XML macro element names are enclosed in angle brackets. Examples: <HAScript> element, <screen> element.

Figure 2 shows an example of an XML element:

Figure 2. Sample XML element
<SampleElement attribute1="value1" attribute2="value2">
...
</SampleElement>
The element <SampleElement> shown in Figure 2

contains the key components of every macro element. The first line is the begin tag. It consists of a left angle bracket (<), followed by the name of the XML element (SampleElement), followed by attribute definitions, followed by a right angle bracket (>). The second line consists of an ellipsis (...) that is not part of XML syntax but is used in the figure above to indicate the possible presence of other elements inside the <SampleElement> element. The third line is the end tag. It contains the name of the element enclosed in angle brackets with a forward slash after the first angle bracket (</Sample Element>).

In the begin tag, the attributes are specified by using the attribute name (such as attribute1), followed by an equals sign (=), followed by an attribute value enclosed in quotation marks (such as "value1"). Any number of attributes can occur within the begin tag.

If the macro element does not contain other XML elements then it can be written in the shorthand fashion shown in Figure 3:

Figure 3. Sample XML element written in the shorthand format
<SampleElement attribute1="value1" attribute2="value2"  />
In Figure 3,

the element <SampleElement> is written with a left angle bracket (<) followed by the name (SampleElement), followed by the attributes, followed by a forward slash and a right angle bracket (/>). Thus the entire XML element is written within a single pair of angle brackets.

Conceptual view of a macro script

A Host On-Demand macro script consists of a single <HAScript> element that can contain up to three major types of subelements:

Figure 4 shows a conceptual view of a sample macro script.

Figure 4. Conceptual view of a macro script
Conceptual view of a macro script

Figure 4 displays a <HAScript> element that contains instances of the major types of subelements: an <import> element (Import), a <vars> element (Variables), and three <screen> elements (Screen1, Screen2, and Screen3).

All macro scripts are structured like this, except that most have more screens. If there were 50 screens in the above macro, then Figure 4 would look much the same, except that after Screen3 there would be additional screens: Screen4, Screen5, and so on, up to Screen50. However, the order in which the screens are stored does not necessarily represent the order in which the screens are executed when the macro is played. See How the macro runtime processes a macro screen.

The <HAScript> element is the master element of a macro script. (HAScript stands for Host Access Script.) It encloses the entire macro and also contains, in its begin tag, attributes that contain information applicable to the entire macro, such as the macro's name. For an example of an <HAScript> element, see Figure 1.

The <import> element is used to import Java™ classes and is optional. Importing Java classes is an advanced topic that is discussed in Variables and imported Java classes.

The <vars> element is used to declare and initialize variables belonging to one of the standard data types (boolean, integer, double, string, or field). Using standard variables is an advanced topic that is discussed in Variables and imported Java classes.

The <screen> element is used to define a macro screen. The <screen> element is the most important element that occurs inside the <HAScript> element. As you can see in Figure 4, a macro script is composed mostly of <screen> elements (such as Screen1, Screen2, and Screen3 in the figure). Also, most of the other kinds of XML elements in a macro script occur somewhere inside a <screen> element.

The macro screen and its subcomponents

This section describes the macro screen and its major subcomponents. The definition of macro screen depends on another term, application screen.

Application screen

An application screen is a meaningful arrangement of characters displayed on the host terminal by a host application. An example of an application screen is the OS/390® ISPF Primary Option Menu, which is displayed in Figure 5.

Figure 5. A sample application screen, the OS/390 ISPF Primary Option Menu
A sample application screen, the OS/390 ISPF Primary Option Menu
In Figure 5

you can see that this application screen has menu selections displayed in a row across the top (Menu, Utilities, Compilers, Options, and so on), a title near the top (OS/390 Primary Option Menu), a list of options along the left side (0 through DAT), and an input field in which to type an option number or letter (Option ===>). When the user provides input, for example by typing a 3 (for Utilities) followed by the enter key, the ISPF application removes all these visible items from the host terminal and displays a different application screen.

Macro screen

A macro screen is a set of instructions that tell the macro runtime how to manage a visit to a particular application screen. A macro screen includes:

Although the concept is not very intuitive at this point, there might be within the same macro several macro screens that refer to the same application screen. Because of the way macro screens are linked to one another, the macro runtime might visit the same application screen several times during macro playback, processing a different macro screen at each visit.

Also, one macro screen might refer to more than one application screen. When several application screens are similar to each other, you might build a macro screen that handles all of the similar application screens.

Nevertheless, each macro screen corresponds to some application screen. When you record a macro, the Macro object creates and stores a macro screen for each application screen that you visit during the course of the recording. If you visit the same application screen more than once, the Macro object creates and stores a macro screen for each visit.

When you play back a recorded macro, the macro runtime processes one or more macro screens for each application screen that it visits during the course of the playback. Typically, a single macro screen runs for a given application screen. However, it is possible for a macro to be edited in such a way that the actions of the first macro screen do not cause the application screen to advance, and a second macro screen then matches the same application screen.

Conceptual view of a macro screen

A macro screen consists of a single <screen> element that contains three required subelements:

Each of the subelements is required, and only one of each can occur.

Figure 6 shows a conceptual view of a <screen> element:

Figure 6. Conceptual view of a <screen> element
Conceptual view of a <screen> element

Figure 6 shows a <screen> element (Screen1) that contains the three required subelements: a <description> element (Description), an <actions> element (Actions), and a <nextscreens> element (Valid Next Screens).

All <screen> elements are structured in this way, with these three subelements. (A fourth and optional type of subelement, the <recolimit> element, is discussed later in this book.)

The <screen> element is the master element of a macro screen. It contains all the other elements that belong to that particular macro screen, and it also contains, in its begin tag, attributes that contain information applicable to the macro screen as a whole, such as the macro screen's name.

The <description> element contains descriptors that enable the macro runtime to recognize that the <screen> element to which the <description> element belongs is associated with a particular application screen. The descriptors and the <description> element are described in Screen description.

The <actions> element contains various actions that the macro runtime performs on the application screen, such as reading data from the application screen or entering keystrokes. The actions and the <actions> element are described in Macro actions.

The <nextscreens> element (Valid Next Screens in Figure 6) contains a list of the screen names of all the <screen> elements that might validly occur after the current macro screen. The <nextscreens> element and the elements that it encloses are described in Screen recognition.