Using the ZIE Host Access Toolkit product with macros

The separate ZIE Host Access Toolkit product includes classes that allow you to dynamically create macro variables, perform macro actions, and run macros. This section contains an example of using the ZIE Host Access Toolkit product.

Sample macro that prompts for user's ID and password shows the first version of a macro that prompts for the user's ID and password, logs on to a host, and says Welcome! This version of the macro does not use the ZIE Host Access Toolkit:
Figure 1. Sample macro that prompts for user's ID and password
<HAScript name="Logon" description="" timeout="60000" pausetime="300"
          promptall="true" author="" creationdate="" supressclearevents="false"
          usevars="true" >

  <screen name="Screen1" entryscreen="true" exitscreen="false" transient="false">

    <description>
      <oia status="NOTINHIBITED" optional="false" invertmatch="false" />
    </description>

    <actions>
      <prompt name="'UserID:'" description="" row="20" col="16" len="8"
              default="" clearfield="false" encrypted="false" movecursor="true"
              xlatehostkeys="true" assigntovar="" varupdateonly="false" />
      <input value="'[tab]'" row="0" col="0" movecursor="true"
              xlatehostkeys="true" encrypted="false" />
      <prompt name="'Password:'" description="" row="21" col="16" len="8"
              default="" clearfield="false" encrypted="true" movecursor="true"
              xlatehostkeys="true" assigntovar="" varupdateonly="false" />
      <input value="'[enter]'" row="0" col="0" movecursor="true"
              xlatehostkeys="true" encrypted="false" />
    </actions>
    <nextscreens timeout="0" >
      <nextscreen name="Screen2" />
    </nextscreens>
  </screen>

  <screen name="Screen2" entryscreen="false" exitscreen="true" transient="false">
    <description>
      <oia status="NOTINHIBITED" optional="false" invertmatch="false" />
      <numfields number="7" optional="false" invertmatch="false" />
      <numinputfields number="1" optional="false" invertmatch="false" />
    </description>
    <actions>
      <message title="" value="'Welcome!'" />
    </actions>
    <nextscreens timeout="0" >
    </nextscreens>
  </screen>

</HAScript>
Assume that you want to use this macro in a Host Access Beans program and that you want to store the user ID into a variable and save it for later use (for example, in the Welcome message). You can do this directly by modifying the macro, but one reason for writing a program for this is to avoid having to maintain many different macros for different situations. You could instead have a basic version of the macro and use a program to modify it depending on the situation. The following is an example of how you can do this in Java:
Figure 2. Java code to modify a Variable update action and a Prompt action
// Assume macro is an instantiated Macro with the appropriate listeners set up.
// (See the Javadoc for the Macro bean and the Macro variables demo program,
// MacroVariablesDemo.java, in the ZIE Host Access Toolkit samples directory
// for details.)
// Assume macroString is a String containing the previous macro script

macro.setMacro(macroString);
MacroScreens ms = macro.getParsedMacro();
ms.createVariableString("$userid$", null);   //creates a variable $userid$ with
                                             //initial value of ""
MacroScreen mscrn = ms.get(0);   //get the first screen
MacroActions mas = mscrn.getActions();   //get the actions from the first screen
MacroActionPrompt map = (MacroActionPrompt)mas.get(0);   //get the first prompt action
map.setAssignToVar("$userid$"); //assign the prompt response to the variable $userid$
MacroScreen mscrn2 = ms.get(1); //get the second screen
MacroActions mas2 = mscrn2.getActions(); //get the actions from the second screen
MacroActionMessage mam = (MacroActionMessage)mas2.get(0); //get the message action
mam.setMessage("'Welcome ' + $userid$ + '!'"); //change the message to now be a
                                               //personalized message using $userid$
macro.setParsedMacro(ms); //reset the macro with the updated MacroScreens
macro.play(); //play the macro with the changes for variables 
Suppose that you now want to add a second message to the actions for Screen2. In this message, you want to display the time and date, which you extract from the screen. You would add the following lines before macro.setParsedMacro(ms):
Figure 3. Adding a second message
//create a variable $datetimestamp$ with initial value ""
ms.createVariableString("$datetimestamp$", null);

//create new extract to get date and time from second row of screen
MacroActionExtract mae = new MacroActionExtract(2, 35, 2, 71, "'datetimeextract'");

//assign the date and time string to $datetimestamp$
mae.setAssignToVar("$datetimestamp$");

//add the extract after the first message
mas2.add(mae);

//create a new message to display the date and timestamp
MacroActionMessage mam2 = new MacroActionMessage(
   "'You have logged on at ' + $datetimestamp$", "'Date Time Stamp'");

//add the message after the extract
mas2.add(mam2);
Note that at the point when the attribute containing the variable(s) is associated with the MacroScreens, you must have already created the variable (through one of the createVariable() methods). For example, this code sequence would also be valid:
Figure 4. Alternate code sequence
MacroActionExtract mae = new MacroActionExtract(2, 35, 2, 71, "'datetimeextract'");
mae.setAssignToVar("$datetimestamp$");
ms.createVariableString("$datetimestamp$", null);
mas2.add(mae);
MacroActionMessage mam2 = new MacroActionMessage("'You have logged on at ' +
   $datetimestamp$", "'Date Time Stamp'");
mas2.add(mam2);

The above sequence is valid because $datetimestamp$ is created before the MacroActionExtract is added to the MacroActions (which are already associated with the MacroScreens because they were pulled from the MacroScreens originally). If the createVariable() method was called at the end of the sequence above, you would have an invalid sequence because the variable $datetimestamp$ would not have been available at the time that the MacroActionExtract and MacroActionMessage were added to the MacroActions and associated with the MacroScreens.

The default value of the MacroScreens method isUseVars() is false. However, if you call one of the createVariable() methods on your MacroScreens, isUseVars() will return true automatically. If you don't create any variables, but want to have your attributes scanned for variables and arithmetic anyway (e.g. you might be writing a chained child macro that has no variables of its own but is anticipating some from the parent), you must call setUseVars(true) on your MacroScreens.

Attributes that can now take variables or expressions as arguments have setAttribute(String) and either getAttributeRaw() or isAttributeRaw() methods available. If you wanted to use an expression now to represent the row attribute for a MacroActionInput, you could call setRow("$rowvar$ + 1"). Subsequently calling getRow() would return the evaluated value of this expression (an integer), whereas calling getRowRaw() would return "$rowvar$ + 1." Note that if you do the following you will get a NumberFormatException:
Figure 5. Code that causes a NumberFormatException
MacroActionInput mai = new MacroActionInput();
mai.setRow("$rowvar$ + 1");
int row = mai.getRow(); 
This is because mai has not yet been associated with any MacroScreens with isUseVars() returning true. Therefore, "$rowvar$ + 1" is being treated as a string rather than a variable plus one. Note also that if you had call the setAttribute() methods to set up variables and expressions after the object containing these attributes have been associated with the MacroScreens, you will likely experience a savings in processing time as the attributes would otherwise need to be reparsed for variables/expressions at the point when they are added to the MacroScreens.

The VariableException class is available for catching exceptions such as illegal expressions (e.g., "45 *") or illegal arithmetic operands (e.g., "'3a' * 2").

A sample program that uses programmed macros, MacroVariablesDemo.java, can be found in the ZIE Host Access Toolkit samples directory.