Before using this information and the product it supports, read the information in Appendix B. Notices.
This edition applies to Version 10.0 of IBM(R) WebSphere Host On-Demand (IBM Host Access Client Package for Multiplatforms V6.0, program number 5724-I20) and to all subsequent releases and modifications until otherwise indicated in new editions.
The Macro Programming Guide guide helps you write better Host On-Demand macros. This book is written for Host On-Demand macro developers and ordinary users. There are three parts.
Macro basics describes basic concepts, introduces the tools, and gives a step-by-step description of how to record and play back a simple macro.
Developing macros describes in detail the capabilities of the Host On-Demand macro system.
The macro language describes the XML macro language.
The Macro Programming Guide is also available on the Host On-Demand CD-ROM and at the Host On-Demand online Information Center at http://publib.boulder.ibm.com/infocenter/hod9help.
The MySupport feature enables you to personalize your support view and register to receive weekly e-mail notifications alerting you to new patches, downloads, and other timely technical support information for IBM products. To register for MySupport, follow the instructions in the Technote found at the following URL (this URL is written as two lines so that it will fit on the page):http://www.ibm.com/support/docview.wss?rs=132&context=SS5RCF &uid=swg21168680&loc=en_US&cs=utf-8&lang=en+en
In addition to the Macro Proramming Guide, Host On-Demand also provides other sources of information to help you use the product. To access the documentation described here, go to the Host On-Demand library page at http://www.ibm.com/software/webservers/hostondemand/library.html. Most of the documentation is also included on the Host On-Demand product or Toolkit CD-ROMs.
The following typographic conventions are used in the Macro Programming Guide:
| Convention | Meaning |
|---|---|
| Monospace | Indicates text you must enter at a command prompt and values you must use literally, such as commands, functions, and resource definition attributes and their values. Monospace also indicates screen text and code examples. |
| Italics | Indicates variable values you must provide (for example, you supply the name of a file for file_name). Italics also indicates emphasis and the titles of books. |
| Return | Refers to the key labeled with the word Return, the word Enter, or the left arrow. |
| > | When used to describe a menu, shows a series of menu selections. For example, "Click File > New" means "From the File menu, click the New command." |
When used to describe a tree view, shows
a series of folder or object expansions. For example, "Expand HODConfig
Servlet > Sysplexes > Plex1 > J2EE Servers > BBOARS2" means:
|
|
| Java 1 | In this book, Java 1 means implemented in a Java 1.1.x JVM. |
| Java 2 | In this book, Java 2 means implemented in a 1.3 and later JVM. |
|
|
This graphic is used to highlight notes to the reader. |
|
|
This graphic is used to highlight tips for the reader. |
A Host On-Demand macro is a XML script that allows a Host On-Demand client to interact automatically with a host application running on a terminal emulator session (a 3270 Display session, a 5250 Display session, a VT Display session, or a CICS Gateway session). A Host On-Demand macro is usually written to perform a specific task or set of tasks involving a single host application.
Compared to a human operator, a macro interacts with a host application more quickly and with a smaller risk of error. A macro does not require that the person who runs it be trained in operating the host application. A macro can in many instances run unattended. A macro can be used again and again. A macro can be copied and distributed to multiple users. And most importantly, a macro can serve as a part of a broader solution to a customer requirement that involves both host applications and workstation applications.
An unsophisticated user can create a basic macro for automating a tedious or time-consuming interaction with a host application. The user navigates the host application to the screen at which he or she wishes to start, selects the Record Macro icon, and performs a task using the host application. For each application screen that the user visits, Host On-Demand records an impression of the application screen and the user's input to the application screen. When the user plays back the recorded macro starting at the same application screen as before, Host On-Demand recognizes each host application screen based on the previously recorded impression and repeats the actions that the human operator previously performed.
A more sophisticated user can add to or improve a recorded macro using the Host Access Macro Editor (Macro Editor). This tool, which is available by clicking an icon on the session panel, provides a graphical user interface (consisting of input fields, text boxes, checkboxes, and so on) with which a user can modify or add features to each screen interaction with the host application. Besides allowing a user to edit and enhance the macro's screen recognition behavior and user input, the Macro Editor provides features that allow a user to add more intelligent behavior to the macro, such as choosing between alternate paths through an application, skipping a screen that should not be processed, or backing up to a previous screen. And there are more powerful capabilities including the ability to read and process data from the session screen, to notify the operator of status, to prompt the operator for an important decision, to download or upload files from the host, and to automate the printing of application screens.
The Macro Editor also provides programming features. A user with programming experience can add functionality to a Host On-Demand macro by creating and manipulating variables, using arithmetic and logical expressions, writing if-then-else conditions, chaining to another macro, calling Java methods stored in external Java libraries, launching native applications, and writing trace information.
The Code Editor, a text editor that is launched from the Macro Editor, allows the user to view and modify the XML elements that make up the macro script, and also to cut and paste text through the system clipboard.
This book contains macro code samples throughout. The chapter Sample macro code contains an example of a macro that reads entries from a sample CICS database and writes them into a Microsoft Excel spreadsheet.
The Host On-Demand Deployment Wizard includes settings that enable system administrators to deploy macros to users in server libraries located at Web locations or on LAN or CD-ROM drives.
For more information see "Creating and deploying server macro libraries" in the document Planning, Installing, and Configuring Host On-Demand.
A local user can save a macro in any location where they have write-access.
You can use Host On-Demand macros to integrate your Telnet-accessible applications with your workstation applications. Macros provide a path for data to flow into or out of your Telnet-accessible applications.
Host On-Demand includes two programming interfaces that allow you to drive macros:
This is a set of Java APIs that allows developers to integrate various pieces of the Host On-Demand client code, such as terminals, menus, and toolbars, into their own custom Java applications and applets.
For more information see the document Programmable Host On-Demand in the Host On-Demand documentation.
Session Manager APIs are JavaScript APIs for managing host sessions and text-based interactions with host sessions.
For more information see the document Session Manager API Reference in the Host On-Demand documentation.
The Host Access Toolkit is a separate product that provides programmatic control of the Host On-Demand client and other features, includes Java APIs for launching and interacting with Host On-Demand macros.
Because a macro is an easily transportable, unencrypted, text-based representation of interactions between a user and a host application, you should consider protecting your macros as valuable pieces of intellectual property.
In particular, you should consider not storing unencrypted passwords or other sensitive data in a macro script. Instead:
Although macros can be used with 3270 Display sessions, with 5250 Display sessions, with VT Display sessions, and with CICS Gateway sessions, this book focuses almost entirely on 3270 Display sessions and 3270 host applications.
This chapter describes the components that you will encounter as you use the macro capabilities of Host On-Demand. Here is an overview of the main components:
The remaining sections of this chapter describe these components in more detail. The final section of this chapter defines other macro terms that you might encounter in this book.
The Macro Manager is the umbrella term for all the macro user interfaces. There are three main interfaces: the Macro Manager toolbar, the Macro Editor, and the Code Editor.
The Macro Manager toolbar is a toolbar that contains icons for common macro operations. All of these icons can be used by macro developers, while at least one of the icons is also for users of macros (the Play macro icon). Figure 1 shows the Macro Manager toolbar. (For the purpose of illustration, this figure is inaccurate in one respect: it shows all the buttons on the toolbar enabled at the same time.)
To view the Macro Manager toolbar follow these steps:
Depending on your company's configuration of the display session, you might notice that a few of the icons on the Macro Manager toolbar also appear on the main toolbar. This placement is for extra convenience and should not cause you any concern. The icons work the same no matter which toolbar they appear on.
Here is a quick summary of the function of each part of the Macro Manager toolbar, from left to right. You will learn more about each of these functions later in the book.
To step through the process of recording and playing back a simple macro, see Recording and playing back a simple macro.
The Macro Editor (the full name is the Host Access Macro Editor) is a graphical user interface (with buttons, input fields, list boxes, and so on) for editing the parts of a macro. Figure 2 shows the Macro Editor.
You will probably use the Macro Editor for most of your macro development. It is more powerful (in terms of managing data more easily) than the Code Editor described in the next subsection, although it cannot do everything that the Code Editor can do.
To bring up the Macro Editor go to the Macro Manager toolbar.
Both the Macro Editor and the Code editor edit macros. Both tools read from and write to the same type of underlying macro source, an XML script. However, each tool is better for certain tasks.
The Macro Editor provides a graphical user interface that is powerful and user-friendly. It is the superior tool for creating and editing macros.
On the other hand, the Code Editor provides a text editor interface that allows you to edit directly the XML elements of which a macro is made. Figure 3 shows the Code Editor displaying a macro script.
You should use the Code Editor for more technical editing tasks, such as:
To bring up the Code Editor:
The macro runtime is the program module that plays back a macro when a user clicks the Play Macro icon. Specifically, the macro runtime reads the contents of the current macro script and generates the macro playback.
The Macro object is the Java instance that provides the capabilities underlying the Macro Manager Toolbar, the Macro Editor, the Code Editor, and the macro runtime.
The IBM Host Access Toolkit, a separately purchased product, provides programming access to the Macro object through the many methods in the Macro class. This book does not describe how to use IBM Host Access Toolkit.
Here are the definitions of a few other terms that you will encounter in this book.
| action | An action is an instruction that specifies some activity that the macro runtime is to perform when it plays back the macro (such as sending a sequence of keys to the session window, displaying a prompt in a popup window, capturing a block of text from the screen, and other actions). You can edit or create actions in the Macro Editor. You can view and modify individual action elements in the Code Editor. See Macro actions. |
| application screen | An application screen is a meaningful arrangement of characters displayed on the Host On-Demand session window by a host application. See Application screen. |
| descriptor | A descriptor is an instruction that describes one characteristic of an application screen. You can edit or create descriptors in the Macro Editor. You can view and modify individual descriptor elements in the Code Editor. See Introduction to the Description tab. |
| macro screen | A macro screen is a set of instructions that tells the macro runtime how to manage a particular visit to a particular application screen. See Macro screen. |
| macro script | A macro script is an XML script in which a macro is stored. You can edit a macro script directly using the Code Editor or indirectly using the Macro Editor. When you play a macro, the macro runtime executes the instructions in the script. See Macro script. |
| valid next screen | A valid next screen is a macro screen that, during macro playback, is a valid candidate to be the next macro screen to be processed. See Closer look at stage 1. |
The purpose of this chapter is to give you a hands-on introduction to the Macro Manager by stepping through three basic tasks:
You can follow these same steps yourself by starting a Host On-Demand 3270 Display session, connecting to an MVS system, and logging on to TSO. The ISPF Primary Option Menu is the first application screen to appear after you log on (see Figure 5).
Be sure to get permission from your systems administrator before doing this, and have an experienced ISPF user sitting next to you, if necessary.
This section shows you how to record a very simple macro. This macro changes the application screen from the ISPF Primary Option Menu to the Data Set List Utility screen (passing through the Utility Selection Panel screen on the way).
Before recording this macro, assure that:
If the Macro Manager toolbar is not displayed on your system, click View > Macro Manager.
For more information on the Macro Manager toolbar, see Macro Manager toolbar.
To record the macro follow these steps:
Some observations:
You can record interactions with more than one session into the same macro. This is an advanced feature (see Interacting with more than one session).
This section shows how to play back the macro that you just recorded. Before you start, go back to ISPF Primary Option Menu. This is the starting point for this macro.
Some observations:
Host On-Demand allows you to assign a macro to a particular keystroke combination. To assign the macro that you just recorded to a keystroke combination, follow these steps:
To play back the macro using the assigned key combination, follow these steps:
This chapter has two purposes, first to describe the general structure of a macro as it can be seen in an XML macro script, and second to show some of the connections between the Macro Editor and specific XML elements in the macro script.
A macro script is an XML script used to store a Host On-Demand macro. You can view and edit the XML text of a macro script by using the Code Editor (shown in Code Editor). The Macro Editor displays the same information that you see in the Code Editor, but the Macro Editor displays the information in a more user-friendly format, using listboxes, checkboxes, input fields, and the other controls of the graphical user interface (see Macro Editor).
Learning a little about the XML elements of the macro language will greatly increase your understanding of important topics, including the following:
Therefore this book frequently refers not only to the input fields, buttons, and listboxes of the Macro Editor but also to the corresponding XML elements in which the same information is stored.
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.
As you probably know already, 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 macro language.
This book, when referring to an XML macro element, uses the element name enclosed in angle brackets. Examples: <HAScript> element, <screen> element.
Figure 8 shows an example of an XML element:
<SampleElement attribute1="value1" attribute2="value2"> ... </SampleElement>
The <SampleElement> element shown in the figure above 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 in 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 9:
<SampleElement attribute1="value1" attribute2="value2" />
In the figure above the <SampleElement> element 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.
A macro script consists of a single <HAScript> element that can contain up to three major types of subelements:
Figure 10 shows a conceptual view of a sample macro script containing three <screen> elements.
The figure above shows an <HAScript> element (HAScript) 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 the diagram above 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.)
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 12.
The <import> element is used to import Java classes and is optional. Importing Java classes is an advanced topic that is not discussed until Creating an imported type for a Java class.
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 not discussed until Variables and imported Java classes.
The <screen> element is used to define a macro screen. The <screen> element is the most important of the elements that occur inside the <HAScript>. As you can see in Figure 10 above, 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.
For the purpose of getting you acquainted with the Macro Editor, this section consists of a very simple comparison between the Macro tab of the Macro Editor and the <HAScript> element described in the previous section.
The Macro Editor has four tabs: Macro, Screens, Links, and Variables. The first tab, the Macro tab, corresponds very closely to the <HAScript> element. In fact, the Macro tab is the graphical user interface for some of the information that is stored in the attributes of the begin tag of the <HAScript> element.
Therefore, as the <HAScript> element is the master element of a macro script and contains in its attributes information that applies to the entire macro (such as the macro name), similarly the Macro tab is the first tab of the Macro Editor and provides access to some of the same global information.
Figure 11 shows the Macro Editor with the Macro tab selected.
In the figure above you can see that the Macro tab has input fields for Macro Name, Description, and other information, along with several checkboxes. You should notice two fields:
Figure 12 shows a sample <HAScript> element that contains the same information as is shown on the Macro tab in Figure 11 , as well as some additional information. In the Code Editor an <HAScript> element is written on a single line, but here the element is written on multiple lines so that you can see the attributes.
<HAScript
name="ispf_ex1"
description=" "
timeout="60000"
pausetime="300"
promptall="true"
author=""
creationdate=""
supressclearevents="false"
usevars="false"
ignorepauseforenhancedtn="false"
delayifnotenhancedtn="0">
...
</HAScript>
In the <HAScript> element in the figure above you should notice that there is an attribute corresponding to each input field of the Macro tab shown in Figure 11. For example, the name attribute in the <HAScript> element (name="ispf_ex1") corresponds to the Macro Name field on the Macro tab. Similarly, the usevars attribute in the <HAScript> element (usevars="false") corresponds to the Use Variables and Arithmetic Expressions checkbox on the Macro tab.
This section describes the macro screen and its major subcomponents. The definition of macro screen depends on another term that needs defining, application screen.
An application screen is a meaningful arrangement of characters displayed on the Host On-Demand session window by a host application.
As you probably realize, you are already very familiar with the concept of an application screen. An example of an application screen is the ISPF Primary Option Menu, which is displayed in Figure 13. (This same application screen is displayed in Figure 5.)
In the figure above you can see that this application screen has menu selections displayed in a row across the top (Menu, Utilities, Compilers, Options, and so on), function key assignments displayed in a row across the bottom (F1=Help, F2=Split, and so on), a title near the top (ISPF Primary Option Menu), a list of options along the left side (0 through V), 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 session window and displays a different application 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 in 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, a macro developer 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. Similarly, when you play back a recorded macro, the macro runtime processes a single macro screen for each application screen that it visits during the course of the playback.
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 14 shows a conceptual view of a <screen> element:
The figure above 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 and recognition.
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 14) 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, Part 2.
This section shows some of the ways in which the Screens tab of the Macro Editor is related to the XML <screen> element described in the previous section. Figure 15 shows the Macro Editor with the Screens tab selected:
In the figure above, notice that the Screens tab contains:
Currently the General tab is selected.
You should notice that there are two Screen Name fields on the Screens tab:
In the Screen Name listbox at the top of the Screens tab, you click the name of the macro screen that you want to work on (such as Screen1), and the Macro Editor displays in the subtabs the information belonging to that macro screen. For example, in Figure 15 the listbox displays the macro screen name Screen1 and the subtabs display the information belonging to Screen1. If the user selected another macro screen name in the listbox, perhaps Screen10, then the Macro Editor would display in the subtabs the information belonging to macro screen Screen10.
In the Screen Name input field under the General tab, you type the name that you want to assign to the currently selected macro screen. A screen name such as Screenx, where x stands for some integer (for example, Screen1), is a temporary name that the Macro object gives to the macro screen when it creates the macro screen. You can retain this name, or you can replace it with a more descriptive name that is easier to remember. (When all your macro screens have names such as Screen3, Screen10, Screen24, and so on, it is difficult to remember which macro screen does what.)
You have probably already noticed that the subtabs General, Description, and Actions on the Screens tab correspond to the main parts of the XML <screen> element described in the previous section. Specifically,
But what about the <nextscreens> subelement? For usability reasons the information belonging to the <nextscreens> element is presented in a higher-level tab, the Links tab. You can see the Links tab immediately to the right of the Screens tab in Figure 15.
Figure 16 shows the XML begin tag and end tag of a sample <screen> element named Screen1:
<screen name="Screen1" entryscreen="true" exitscreen="false" transient="false"> ... </screen>
In the figure above, the ellipsis (...) is not part of the XML text but indicates that the required elements contained inside the <screen> element have been omitted for simplicity. You should notice that the attributes in the begin tag correspond to fields on the General tab in Figure 15. For example, the name attribute (name="Screen1" ) corresponds to the Screen Name input field on the General tab, and the entryscreen attribute (entryscreen="true") corresponds to the Entry Screen listbox on the General tab.
Figure 17 shows the XML text for the entire <screen> element including the enclosed elements:
<screen name="Screen1" entryscreen="true" exitscreen="false" transient="false">
<description>
<oia status="NOTINHIBITED" optional="false" invertmatch="false" />
</description>
<actions>
<mouseclick row="4" col="15" />
<input value="3[enter]" row="0" col="0" movecursor="true"
xlatehostkeys="true" encrypted="false" />
</actions>
<nextscreens timeout="0" >
<nextscreen name="Screen2" />
</nextscreens>
</screen>
In the figure above you should notice that the <screen> element contains the required <description>, <actions>, and <nextscreens> elements.
You must choose the format that you want your macro to be stored in: either the basic macro format or the advanced macro format.
The basic macro format is the default format. It supports a basic level of function but it does not include support for expression evaluation, variables, or some other features supported by the advanced macro format. Nevertheless, you should choose the basic macro format initially unless you already know that you are going to use expressions and variables. You can easily switch your macro to the advanced macro format later on. (In contrast, if you start out with the advanced macro format it is much more difficult to switch your macro to the basic macro format.)
You indicate which format you want with the Use Variables and Arithmetic Expressions in Macro checkbox on the Macro tab of the Macro Editor:
The basic macro format:
In contrast the advanced macro format:
You must write strings and the two special characters single quote (') and backslash (\) differently in the macro depending on whether you have chosen the basic macro format or the advanced macro format. Also, some characters that are ordinary characters in the basic macro format are used as operators in the advanced macro format.
However, these rules affect only input fields located on the following tabs:
The input fields that are affected on these tabs are as follows:
For input fields on all other tabs than those listed above, always use the rules for the basic macro format.
The following two sections describe these differing rules.
If you have chosen the basic macro format, use the following rules for input fields on the Description tab, Actions tab, and Variables tab:
apple banana To be or not to be John Smith
New Year's Day c:\Documents and Settings\User
If you have chosen the advanced macro format, use the following rules for input fields on the Description tab, Actions tab, and Variables tab:
'apple' 'banana' 'To be or not to be' 'John Smith'
'New Year\'s Day' c:\\Documents and Settings\\User
You can easily convert your macro from the basic macro format to the advanced macro format, just by checking the "Use Variables and Arithmetic Expressions in Macro" checkbox on the Macro tab. As a result the Macro object does the following:
That is, the Macro object will find all the strings in your macro and surround them with single quotes, and the Macro object will change all occurrences of ' and \ to \' and \\. Also, any operator characters will be treated as operators.
Converting your macro from the advanced macro format to the basic macro format can be very difficult. There are no automatic conversions when you uncheck the "Use Variables and Arithmetic Expressions in Macro" checkbox. The only automatic result is that the Macro object:
You yourself must change, one at a time, by hand, all the representations of strings and of the two special characters back to the basic representations. Also, you will have to delete any instances where advanced features have been used in the macro. If you do not do so then you might encounter errors or unexpected results when you try to save or run the script. Any remaining operator characters will be treated as literal characters rather than as operators.
The Macro object supports the following standard data types:
These types are described in the subsections below.
The boolean values true and false can be written with any combination of uppercase and lower case letters (such as True, TRUE, FALSE, falsE, and so on).
An example of a input field that requires a boolean value is the Entry Screen field on the General tab of the Screens tab. Enter true to set the condition to true or false to set the condition to false.
The boolean values are not strings and therefore never need to be enclosed in single quotes. To repeat, whether you use the basic macro format or the advanced macro format, booleans are always written true and false, not 'true' and 'false'.
However, string values are converted to boolean values in a boolean context (see Conversion to boolean). Therefore with the advanced macro format you could enter the string 'true' in a boolean field, because the Macro Editor would convert the string 'true' to the boolean value true.
Integers are written without commas or other delimiters. Examples:
10000 0 -140
The Macro Editor has a number of integer constants that are written using all uppercase characters. These values are treated as integers not strings. Examples:
Doubles are written without commas or other delimiters. Examples:
3.1416 4.557e5 -119.0431
A string is any sequence of characters and can include leading, trailing, or intervening blank characters. Strings in some input fields must be represented differently depending on whether the macro has been set to use the basic macro format or the advanced macro format. See Representation of strings and special characters, treatment of operator characters.
The following examples use the representation for the advanced macro format:
'apple' 'User4' 'Total number of users' ' This string has 3 leading blanks.' 'This string has 3 trailing blanks. '
Here are the same examples using the representation for the basic macro format.
apple User4 Total number of users This string has 3 leading blanks. This string has 3 trailing blanks.
Notice that with the basic macro format trailing blanks are still allowed but are difficult to detect. If in doubt see the representation of the string in the Code Editor.
See Field variables.
The value null is a reserved word, not a string. When used in place of an object belonging to an imported Java class, it has the same meaning as it does in the Java language.
Do not use null to signify an empty string. To signify an empty string, use a pair of single quotes ('') in the advanced macro format, or nothing at all in the basic macro format. If you use the value null in a string context (for example, by assigning it to a string variable), then the Macro Editor or the macro runtime will convert the value null to the string 'null'.
In order to use arithmetic expressions you must first check the "Use Variables and Arithmetic Expressions in Macro" checkbox on the Macro tab (see Representation of strings and special characters, treatment of operator characters).
The arithmetic operators are:
| Operator | Operation |
|---|---|
| + | Addition |
| - | Subtraction |
| * | Multiplication |
| / | Division |
| % | Modulo |
In an arithmetic expression the terms are evaluated left to right. The order of precedence of the operators is: *, /, %, +, -. For example, the result of :
4 * 2 + 16 / 8 - 1 * 2
is 8. You can use parentheses to indicate the order in which you want expressions to be evaluated:
(4 * 2) + (16 / 8) - (1 * 2) evaluates to 8 but 4 * (( 2 + 16) / (8 - 1)) * 2 evaluates to 20.571
You can use an arithmetic expression almost anywhere that you can use an arithmetic value. Examples:
You can use the string concatenation operator '+' only if you check the "Use Variables and Arithmetic Expressions in Macro" checkbox on the Macro tab. See The basic macro format versus the advanced macro format.
The string operators are shown in the table below.
| Operator | Operation |
|---|---|
| + | Concatenate |
You can write a string expression containing multiple concatenations. The following examples use the string representation required for the advanced format (see Representation of strings and special characters, treatment of operator characters).
Expression: Evaluates to: 'Hello ' + 'Fred' + '!' 'Hello Fred!' 'Hi' 'There' (Error, a + operator is required to concatenate strings) 'Hi' + 'There' 'HiThere'
The conditional operators are:
| Operator | Operation |
|---|---|
| == | Equal |
| != | Not equal |
| > | Greater than |
| < | Less than |
| >= | Greater than or equal |
| <= | Less than or equal |
The logical operators are:
| Operator | Operation |
|---|---|
| && | AND |
| || | OR |
| ! | NOT |
If you are entering && in an HTML or XML editor you might have to enter &&
In a conditional expression the terms are evaluated left to right. The order of precedence of the operators is the same order in which they are listed in the tables above. You can use parentheses to indicate the order in which you want expressions to be evaluated. Examples:
Expression: Evaluates to: (4 > 3) true !(4 > 3 ) false (4 > 3) && (8 > 10) false (4 > 3) || (8 > 10) true