Macros

Overview

Genie includes macro capability which allows for keystroke automation. For example, users can be brought to specific menus or programs automatically, or certain screens can be bypassed by automatically entering data for users and pressing keys automatically.

Genie macros are created using XML files that are stored on the IFS.

XML File Creation

Genie looks for macros in folder PROFOUNDUI_SERVER_ROOT/macros.

In a default installation, this folder is:

/www/profoundui/macros

Macros are created by placing XML documents into this folder.  Files must be created with the “.xml” extension.

For example, to create a macro named “mymacro”, the file name should be:

“mymacro.xml”

XML File Encoding

Genie supports the following file encodings for macros:

• UTF-8 (CCSID 1208)

• UTF-16  (CCSID 1200)

• ISO-8859-1  (CCSID 819 or CCSID 1252)

For customers outside of the United States, it’s recommended to use UTF-8 encoding.

The encoding type for Genie macros must be specified using an XML declaration, for example:

<?xml version="1.0" encoding="UTF-8" ?>

The file encoding specified in the XML declaration must match to the actual file encoding as controlled by the file’s CCSID.

The CPY command can be used to change the CCSID of an IFS file by copying over (replacing) an existing file and using the TOCCSID and DTAFMT(*TEXT) parameters.

XML Document Syntax

The specifics of XML document syntax are outside the scope of this document. For information on this, see the W3C XML reference here:

http://www.w3.org/TR/REC-xml/

The W3C also has a tutorial here:

http://www.w3schools.com/xml/default.asp

Row and Column Numbers in Genie Macros

Genie macros refer to row/column positions of fields as rendered by Genie. This is different than the simple position of text on a 5250 terminal emulator screen. These can be viewed in the Genie designer by looking at the "id" property of a field. The ids use this format:

D_ROW_COL (for output field)

I_ROW_COL ( for input field)

When the field is inside of a DDS WINDOW record format, the ids look slightly different. The row and column reported by Genie in this case are relative to the WINDOW record format area, and Genie appends a window index:
D_ROW_COL_WINDOWNUMBER

I_ROW_COL_WINDOWNUMBER ( for input field)

Important: See the individual macro command descriptions for instructions on specifying row/column values.

Genie Macro XML Elements

Genie macros are created using the following XML elements:

• <macro>
  This element is the XML document root element that contains all other elements.

• <detect>
  This element allows you to specify a location on the screen to locate certain text. If successful, the actions defined inside this element will be performed.
  This element serves as a container that holds other elements that define actions. The actions will be performed any time that the detection is successful in the session.

• <detectonce>
  This element is similar to <detect> except that the actions will happen only 1 time in a session – the first time the screen is detected.

• <id row=”1” col=”1”>Text</id>
  This element specifies the location and text to search for on the screen.
  Attributes “row” and “col” are required on this element. They specify the row and column locations to search for text on the screen. The row/col numbers given should be based on the element id assigned to the field in Genie.
  This element must also contain content which defines the text to search for at the given location.  The text is case sensitive, but leading or trailing blanks will not affect a match.

• <input row=”1” col=”1”>MyText</input>
  This element allows you to automatically input text into a 5250 entry field.
  Attributes “row” and “col” are required on this element. They specify the row and column locations for the entry field. The row/col numbers given should be based on the element id assigned to the field in Genie, except if inputting into a field in a WINDOW record format. In this case the row/col position should be given relative to the entire screen. An easy way to get the correct values for a WINDOW field is to use the rol/column values reported by a TN5250 emulator when placing the cursor on the first position of the field. This element must also contain content which defines the text to place into the entry field. The text will be put into the field exactly as specified – including any leading blanks. 

• <key>F1</key>
  This element allows you to automatically press a function key. The key is specified as text content in the element.  The following key names are valid with this element:

• F1-F24

• ENTER

• CLEAR

• HELP

• ROLLDOWN

• ROLLDN

• ROLL DOWN

• PAGEUP

• PAGE UP

• ROLLUP

• ROLL UP

• PAGEDOWN

• PAGEDN

• PAGE DOWN

• PRINT

• ATTN

• SYSREQ

The values are not case sensitive.

• <cursor row=”1” col=”1” />
  This element allows you to set the cursor to a specific location. This is useful for those screens that have cursor-sensitive functionality – such as selecting a subfile record where the cursor is located.
  Attributes “row” and “col” are required on this element. They specify the row and column locations for a field where the cursor will be placed. The row/col numbers given should be based on the element id assigned to the field in Genie, except if setting the cursor within a WINDOW record format. In this case the row/col position should be given relative to the entire screen. An easy way to get the correct values for a WINDOW field is to use the rol/column values reported by a TN5250 emulator when placing the cursor on the first position of the field.

• <selectionField row="1" col="1" [option="0"] [value="on"]>Name</selectionField> This element is used with 5250 selection fields including menu bars (MNUBAR), single choice fields (SNGCHCFLD), and multiple choice fields (MLTCHCFLD).  The "row" and "col" attributes are required and indicate the selection field itself (not individual choices within it.)  For example, if you have a menu bar containing three choices "File Edit Help", the row/col attributes should identify the letter "F" in "File" because this is the very first position of the selection field, and is used to identify the selection field itself.  The particular choice desired is selected using either the "option" attribute to selection the choice by its zero-based ordinal position, or Name to select it by its name. The "value" attribute is used when checking/unchecking a radio button or check box and may be set to "on" or "off".  See "Menu Bar Example" (below) for more information.

• <close />
  This element closes down the Genie session.

Genie Macro Processing

Genie macros are created by specifying <detect> or <detectonce> elements with one or more <id> elements and placing other elements inside to perform actions.

This is called a “detect block”. A detect block must contain an action.

Possible Actions:

• Place the cursor into a field with the <cursor> element.

• Input text into one or more input fields with <input> elements

• Press a key with at least one <key> element. Every action must contain a <key> element.

A Macro can be thought of as a list of screens that Genie will fill in and submit automatically.The <cursor> and <input> elements allow Genie to place the cursor and/or fill in one or more fields on the screen and  the <key> element instructs Genie to press Enter or a number of other keys (see above for a full list)

There is one other type of Action

•  A <close> element will shut down the session. No <key> element is required for this action type.

If you create a detect block with no action elements, an error will occur when you attempt to run the macro.

The ordering of detect blocks in a macro does not matter since only 1 will function at a time, based on screen detection.

Macro Example

The following macro makes use of both types of detect blocks. Also note that each detect block contains an action (<cursor>, <input>, <key> and/or <close> elements)   The macro will:

• Bypass the Display Program Messages screen the first time it is encountered in a session by pressing the enter key.

• Enter the command WRKSPLF into the command line the first time the i5/OS main menu screen is detected in a session.

Note that the <cursor> element is not necessary here as the menu panel is not cursor sensitive. This is included simply to show how the element is specified.

The example also shows using multiple <id> elements to detect this panel, although it’s not really necessary.

• Automatically close the session any other time the i5/OS main menu screen is detected.

  <?xml version="1.0" encoding="UTF-8"?> <macro> <detectonce> <id row="1" col="16">Display Program Messages</id> <key>Enter</key> </detectonce> <detectonce> <id row="1" col="2">MAIN</id> <id row="1" col="32">IBM i Main Menu</id> <cursor row="20" col="7" /> <input row="20" col="7">WRKSPLF</input> <key>Enter</key> </detectonce> <detect> <id row="1" col="2">MAIN</id> <id row="1" col="32">IBM i Main Menu</id> <close /> </detect> </macro>

   

Since this example declares encoding type UTF-8, the IFS file should be created with CCSID 1208.

Menu Bar Example

Support for 5250 menu bars (DDS MNUBAR keyword) was added in Profound UI 6 fix pack 11. 

Navigating menu bars and pull-down fields can be challenging because there is rarely a unique screen identifier for each pulldown menu.  Instead, you must rely on using <detectonce> elements to select each option in a particuar sequence.  For example, suppose you have the following menu screen and you wish to first open the View pull down menu, and then select the Status option and press Enter. 

Open

To do that, you will need to:

1. Identify the screen using <detectonce> and <id> elements to find the screen identifier MENUTSTD which is in row 23 and column 70.

2. Find the selection field for the top menu bar.  This is identified by the first letter of the first choice, in this case the "F" in "File" which is located at row 1, column 3.

3. Use a <selectionField> element to select the View option from the selection field. (Use the row/col from the last step.)

4. Press ENTER to open the View menu.  Since this submits the screen, it is the last part of the <detectonce> block.

5. Identify the screen again using <detectonce> and <id> elements, the same way as the first step.

6. Find the pull-down menu under View.  Pull-down menus in 5250 are created by overlaying the screen with a window format, and placing a single choice selection or multiple choice selection field in that window.  Keep in mind that Genie Macros always use the row/col from the entire screen (whereas the Genie Designer works with coordinates relative to the window.)  Since the "Zoom" option is in row 3, column 30 and is the first option in the single choice selection field, the pulldown menu will be identified as row 3, column 30.

7. Use a <selectionField> element to set the "Status" option on in the selection field identified by the row/col from the previous step.

8. Press ENTER to submit the "Status" option.

In this example, the View and Status options were selected by their names.  However, sometimes its better to select options by their position, for example when a menu option's name is a variable that can change frequently its not practical to select the option by its name.  Selecting by its position within the selection field is done with the "option" attribute.  The "option" attribute must be a number from 0-99 identifying its position within the selection field.  The first choice is option 0, the second is option 1, and so forth.

In the previous example, the menu bar contained choices 0=File, 1=Edit, 2=Format, 3=View and 4=Help.   Once the View menu is pulled down, it contained choices 0=Zoom and 1=Status.  With this in mind, I could rewrite the above macro as follows:

Substitution Variables in Macros

Genie allows substitution variables in macros to allow for dynamic processing. Substitution variables can be used in any element attribute or text content.

Substitution variables are defined by placing the variable name in brackets at the desired location. For example, the above macro could be adjusted to create a multipurpose macro for launching Genie to any OS command like this:

In this case, a substitution variable named ‘Command’ is defined which is used to populate the value that is entered into the command line on the i5/OS main menu panel.

When Genie is launched, the substitution variable values can be passed in. Genie will replace the values before running the macro.

An error will result if Genie is unable to replace any substitution variables defined in the document – i.e. they are not passed correctly.

Calling Genie to Run a Macro

To run a macro in Genie, the macro name must be specified as a query string parameter named “macro”.  The macro name is the name of the XML file. The “.xml” extension should be omitted as Genie will append this automatically. The macro name is not case sensitive.

Assuming that the first example above was called “test.xml”, it could be launched as follows:

http://Systemi:8080/profoundui/auth/genie?macro=test

Calling Genie to Run a Macro with Substitution Variables

When running a macro that includes substitution variables, all variable values must be passed as query string parameters.

This is done using query string parameters “varX” and “valueX”. For example, if you have 1 variable, you will use parameters “var1” and “val1”. If you have 2 variables, you will use “var1”, “value1”, “var2”, and “value2”.

“varX” gives the variable name, and “valueX” gives the value to associate with it.

For example, assuming the 2^nd example macro above was called “test2.xml”, it could be launched like this:

http://Systemi:8080/profoundui/auth/genie?macro=test2&var1=command&value1=WRKMSG

The variable names are not case sensitive. The variable value will be placed into the macro exactly as specified.

Macro Errors

If Genie is unable to process the macro for any reason (i.e. file not found, no authority, XML syntax error, etc.), the session will not be started and an error screen will display.

If the error is inside the XML document itself, line and column numbers will display. For example:

Below is a common error.  This is caused by a detect block with no action elements.  See the section Genie Macro Processing above on how to add actions to a detect block