InfoCenter

Editing macro screens: Actions

Lists the actions to be performed when a screen within a macro is recognized.

The Actions tab provides all of the actions to perform on the selected screen when it is identified by the macro. To modify an action, choose the action from the Action list. The name of each action is created automatically based on the action type and the contents of the action. To create a new action, choose the appropriate type of action you want to create (for example, <new input action>).

For any field except Screen Name, you can use a variable name or an arithmetic expression as the field value. You can enter these variable names and expressions directly into text areas or add them to lists by selecting <Expression> from the list. If you select <Expression> from the list and the only other options in the list are True and False, the expression must return either True or False.

A variable name should have the following format: $var_name$, where var_name can be alphanumerics, the dash symbol, and the underscore symbol. Variable names must be enclosed in dollar signs. Variable names are case sensitive.

If an action requires row and column values, you can click on the session window at the desired position and the values appear in the row and column field. Click once to give the session window focus, and again for the values of the position you select to appear in the row and column field.

For more information see the Macro Programming Guide.

To delete a defined action, select it and click Delete.

Click Order to change the order the actions should be performed on the screen.

For more information about the macro script syntax see the Macro Programming Guide.

Input

Inputs a string or an action key, or both, at the selected position.

Row and column
Row and column define the position on the session screen to place the string.
String
String (including the action keys) that is placed on the session screen.
Action Keys
To enter an action key into the String field, select an action key and click Insert Action Key. The Action key appears at the end of String field.
Translate Host Action Keys
Translates host key mnemonics, for example [enter], as input for a field on the session screen.
Move Cursor to End of Input
Places the cursor at the end of the input string on the session screen.
Note: If action keys such as [tab], [up], or [down] are included in the String field, the Move Cursor to End of Input option is ignored by the macro. That is because the action keys require the cursor to move to a specific place on the screen.

Extract

The extract action allows you to capture text that the application is displaying on the screen, or to capture other screen information (depending on the plane selected). You can set options that will save this extracted data into a variable for use later on, or print the data.

To create a new extract action use either of the following methods:

Start Row and Start Column
Top left position of the bounding extract rectangle.
End Row and End Column
Bottom right position of the bounding extract rectangle.
Extraction Name
Name of the extraction. Use a name to identify what is being extracted from the session screen. This name is passed to the MacroExtractEvent.
Data Plane
Select one or more of the following planes to extract. You must select at least one plane.
TEXT_PLANE
The text plane contains the text on the screen. When you add a new extract action, TEXT_PLANE is the default data plane.
COLOR_PLANE
The color plane contains color information for each character of the presentation space.
FIELD_PLANE
The field plane represents the field positions and their attributes in the presentation space.
EXFIELD_PLANE
The extended field plane contains extended character attribute data.
DBCS_PLANE
The DBCS plane contains double-byte character set attribute data for each character and field attribute in the presentation space. You can only select DBCS_PLANE when you are running a DBCS session.
GRID_PLANE
The grid plane contains information for displaying the grid.
Unwrap Text
Unwrap text in a field that spans multiple lines on the screen.
Assign Text Plane to a Variable
Assigns the extracted texts into a specified variable.
You can enter negative numbers for rows and columns. Negative numbers are virtual positions from the bottom row.

Prompt

Prompts the user for information while the macro is running.

Row and Column
Identifies the row and column on the session screen where the macro will place the prompt response value. For example, if you prompt the user for a User ID, the value they enter will be placed on the screen in this location.
Prompt Name
Text inside the prompt message box that asks the user for input. For example, if you are asking for a user ID, the prompt text could be, Enter your user ID. Remember that the text must be enclosed in single quotation marks if the checkbox for Use Variables and Arithmetic Expressions in Macro is checked. For example, 'Enter your user ID'.
Prompt Text
A description of the prompt. This description is for your information only. It is not displayed.
Clear Host Field
Clears the host field before placing the prompt text. This is useful when host applications populate a host field when the screen is sent.
Default Response
Default value, if any, for the prompted response value. When the user is prompted, this value will be in the response field by default. The user can change this value.
Password Response
Hides the response for the prompt by displaying asterisks instead of the characters typed.
Response Length
The maximum length for the response value (number of characters).
Translate Host Action Keys
Accepts host key mnemonics, for example [enter], as input for a field on the session screen. The default is true.
Move Cursor to End of Input
Places the cursor at the end of the input value on the session screen for subsequent input actions. If action keys such as [tab], [up], or [down] are included in the String field, the Move Cursor to End of Input option is ignored by the macro. That is because the action keys require the cursor to move to a specific place on the screen.
Assign to a Variable
Assigns a user's input to a specified variable. If the variable is an integer, a double, a boolean, or a field, the user input or response must match, otherwise an error or unexpected result occurs. For more information about variable types, see the online help for Variables.
Don't Write to Screen
Enabled only if you select Assign to a Variable. If you select true, the user's input is assigned to a variable, but does not appear on the screen. The default is false.
The prompt value is placed on the screen in the specified location. The enter key will not automatically be pressed. If you want the value entered, create a new Input action for the Enter action key.

Message

Displays a message to the user.

Message Title
Caption that appears in the title bar of the message window. The default is to use the macro name.
Message Text
Message displayed in the message window.

Pause

Pauses the macro for the specified amount of time.

Duration
Time in milliseconds to pause the macro when it is running.

Transfer

Transfers a file to or from a host. Click Advanced for more options.

Send/Receive
Select if you are sending or receiving files from the host.
Host File Name
Enter the name of the file that you are sending or receiving. The file name must be in the host file format.
PC File Name
Enter the path name and file you are sending or receiving. The file name must be in PC file format. Click Browse to locate the file on your system.

Advanced Options

Clear before Transfer
Clears the host screen before transferring the file. You should not change this setting because in nearly every case, CMS and CICS require that this command be sent, whereas TSO and OS/400 do not.
Timeout
Specify the length of time (in milliseconds) to wait for a file to transfer. If the transfer does not complete in this time, the macro ends and displays a message. The default is 10000 milliseconds, or 10 seconds.
Options
Enter the host specific options for the file transfer. Options are different for each type of host system.
PC Code-page
Select the PC code-page for the transfer. This code page should match the code-page set in the session configuration properties. The code-page is a table that translates EBCDIC codes to PC 1-byte codes, or vice versa, when files are transferred. Only valid code pages for your computer's locale are included in this list.
Host File Orientation
Specify whether the host files will be saved in left-to-right or right-to-left format. Use this option if the session is configured to use an Arabic or Hebrew host code-page. The default is left-to-right.
PC-File Orientation
Specify whether the PC files will be saved in left-to-right or right-to-left format. Use this option if the session is configured to use an Arabic or Hebrew host code-page. The default is left-to-right.
PC-File Type
Specify whether the PC files you transfer will be saved in the format in which they are saved (implicit) or in the format which they should be displayed. The default is implicit. Use this option if the session is configured to use an Arabic or Hebrew host code-page.
Lam-Alef Expansion
Specify if files containing the character Lam_alef should be expanded into two characters, Lam followed by Alef, when received from the host. Use this option if the session is configured to use an Arabic host code-page.
Lam-Alef Compression
Specify if files containing the characters Lam followed by Alef should be compressed into one character, Lam_alef, when sent to the host. Use this option if the session is configured to use an Arabic host code-page.
Symmetric Swapping
Specify whether brackets are reversed from the source to the target. If symmetric swapping is enabled, brackets are reversed from the source to the target. For example, ( is replaced by ) and ) is replaced by ( when host file orientation is right-to-left. If symmetric swapping is not enabled, the brackets are not reversed. Use this option if the session is configured for an Arabic or Hebrew host code-page and affects the brackets during file transfer.
Numerals Shape
Specify how numerals appear when sending files to the host. The Numerals Shape indicates one of the following: Use this option if the session is configured for an Arabic host code-page.
Round Trip
Specify that if numerals are preceded by Arabic characters, the numerals exchange places with the Arabic characters when transferring files. Use this option if the session is configured for an Arabic host code page.

Comm wait

Waits for a communication status from the host while the macro is running.

Connection Status
The type of communication status, as defined by the ECLConnection class, to wait for.
Timeout
Time to wait, in milliseconds, for the communication wait. If a status is not received by the specified time, that macro stops.

More information about the ECL Connection class can be found in the Host Access Class Library for Java document included with the Host On-Demand Toolkit.

Trace

Writes out a trace record.

Trace Handler
Where the trace text is sent.
Trace Text
Text sent to the trace handler.

Mouse click

Sets the cursor using a mouse click at the specified row and column.

Row and column
The host screen row and column position for the mouse click.

Box select

Marks an area on the screen, replacing a previous selection.

Row (top) and Column (top)
Top left row of the marked rectangle. These values must be numbers within the host screen coordinate system, for example, 24 rows by 80 columns. Negative numbers are virtual positions from the last row.
Row (bottom) and Column (bottom)
Bottom right row of the marked rectangle. These values must be numbers within the host screen coordinate system, for example, 24 rows by 80 columns. Negative numbers are virtual positions from the last row.

Run program

Runs a program while the macro plays.

Program
The name of the program.
Parameters
The program parameters.
Wait for Program
If you select true, the macro pauses until the program completes. The default is false.
Assign Exit Code to Variable
Enabled only if Wait for Program is true. Select a variable from the list.

Variable update

Updates a variable with a new value.

Name
Select the name of the variable to update.
Type
Displays the type of the currently selected macro. If the variable is not defined in the current macro, no type appears.
Value
Any valid expression, for example, 'hello', 5, or $var$ + 1.
Current
Click Current to assign the content of the screen at the current cursor position to a variable. When the macro runs, the content of the screen at the cursor position you specify becomes the value for the variable. Current is enabled only for field variables.

Play macro

Stops the currently running macro and starts playing the macro you specify. You can only select macros that are available in your current session.

Macro Name
Lists the available macros by name.
Macro Description
The description you gave the macro when you created it.
Start Screen Name
Lists all screens for the macro you select, as well as *DEFAULT*. If you select a specific screen from the list, the chained macro starts at the screen you specify. If you select *DEFAULT*, the macro starts at the screen you defined as the start screen when you created the macro.
Variable Transfer
If you select Transfer, all of the current variables are transferred to the next running macro. The default is No Transfer.

Perform

Invokes a method on an instance of a class. The type which represents the imported class must be declared on the Variables tab, unless the variable containing the instance is inherited from another macro. See the Play macro action.

Action to perform
The call to the method or constructor.
Example Comments
$fis.close()$ Calls the close() method of the Java class (such as java.io.FileInputStream) underlying the imported type to which the variable fis belongs.
$zis.createZipEntry( $name$ )$ Calls the createZipEntry() method of the Java class (such as java.util.zip.ZipInputStream) underlying the imported type to which the variable zis belongs.
$userVar.update( 5, 'Application', $str$)$ Calls the update() method of the Java class (such as mypackage.MyClass) underlying the imported type to which the variable userVar belongs.

Conditional

Allows you to place conditions around actions. If you want to use the Conditional action, select Use Variables and Arithmetic Expressions in Macro on the Macro tab in the Macro Editor. Otherwise, your macro might not work as expected.

Condition
Type a valid condition, for example, ($varA$ == 'abc') && ($varB$ != 1). If you do not type a conditional, the default is true. The following table shows the syntax for conditionals:
Symbol Definition
== equal to
!= not equal to
< less than
> greater than
<= less than or equal to
>= greater than or equal to
|| or
&& and
! not

You can use parentheses to show the order of operations,, and you can include arithmetic expressions as terms in conditional expressions. For example, the following expression evaluates to true:
(((5+2)*3) == 21)

Condition is true
The actions that appear in the Actions list will be performed on the screen if the condition is true. For each conditional action you create, you can specify one condition, along with a set of actions to perform if the condition is true and a different set of actions to perform if the condition is false.
Action
You can create any action for a conditional action except another conditional action.
  • Input
    Sends keystrokes to the screen.
  • Extract
    Extracts data from the screen.
  • Prompt
    Prompts the user for information while the macro is running.
  • Message
    Displays a message to the user.
  • Pause
    Pauses the macro for the specified amount of time.
  • Transfer
    Transfers a file to or from the host.
  • Comm wait
    Waits for a communication status.
  • Trace
    Writes out a trace record.
  • Mouse click

    • Simulates a user mouse click.
  • Box select

    • Marks an area on the screen.
  • Run program

    • Runs any program that can be executed by the run time.
  • Variable update

    • Updates a variable with a new value.
  • Play macro

    • Stops the currently running macro and starts playing the macro you specify.
Condition is false
The actions that appear in the Actions list will be performed on the screen if the condition is false.

The Condition field is grayed out. For each conditional action you create, you can specify one condition, along with a set of actions to perform if the condition is true and a different set of actions to perform if the condition is false.

Action
You can create any action for a conditional action except another conditional action.
  • Input
    Sends keystrokes to the screen.
  • Extract
    Extracts data from the screen.
  • Prompt
    Prompts the user for information while the macro is running.
  • Message
    Displays a message to the user.
  • Pause
    Pauses the macro for the specified amount of time.
  • Transfer
    Transfers a file to or from the host.
  • Comm wait
    Waits for a communication status.
  • Trace
    Writes out a trace record.
  • Mouse click

    • Simulates a user mouse click.
  • Box select

    • Marks an area on the screen.
  • Run program

    • Runs any program that can be executed by the run time.
  • Variable update

    • Updates a variable with a new value.
  • Play macro

    • Stops the currently running macro and starts playing the macro you specify.

Example of a conditional

In this example, your macro has a run program action that assigns an exit code to the variable $exit$ (0 if the program executes successfully, non-zero if not). You can use the conditional action to display one message if the exit code is 0 (success), and another message if the exit code is not zero (failure). Complete the following steps to create the conditional action:

  1. In the Macro Editor, open your macro that runs the program.
  2. On the Screens tab, select the screen with the run program action. On the Actions tab, select <new conditional action> from the Action list.
  3. In the Condition field, type the condition $exit$ == 0.
  4. On the Condition is True tab, select <new message action> from the Action list.
  5. In the Message Text field, type 'Program executed successfully.'

    If the condition is true, for example, the exit code for your program is 0, a message appears saying the program executed successfully. You can specify more actions on this tab. The macro performs these actions if the exit code is 0.

  6. On the Condition is False tab, select <new message action> from the Action list.

    Note: The Condition field is grayed out. For each conditional action you create, you can specify one condition, along with a set of actions to perform if the condition is true and a different set of actions to perform if the condition is false. Currently, there should be no actions defined on the Condition is False tab.

  7. In the Message Text field, type 'Program exited abnormally with an exit code of: ' + $exit$

    If the condition is false, for example, the exit code for your program is not 0, a message appears saying the program exited with an error and the exit code will be displayed. You can specify more actions on this tab. The macro performs these actions only if the exit code is not 0.

Your macro is now ready. If you select Edit Code on the Macro Editor window, you should see the following code: 


        <actions>
           ...
            <if condition="$exit$ == 0" >
                  <message title="" value="'Program executed successfully'" />
            </if>
            <else>
                  <message title="" value="'Program exited abnormally with an exit code of: '+$exit$" />
            </else>
           ...
        </actions>

Note: Toggling back and forth between the Condition is True tab and the Condition is False tab populates the Action list with the actions from the <if> block and the actions from the <else> block, respectively.

Print Start

Starts a print session for this macro. If a print session is already started for this macro, then the print session is ended and a new print session is started using the printer setup and page setup specified for this Print Start action.

Note Print Start is supported for 3270 Display sessions only.

Printer Setup
Displays a printer setup window that allows you to configure the printer setup for this print session. This printer setup window is similar to the Printer window that is displayed for a 3270 Printer session.
Page Setup
Displays a page setup window that allows you to configure the page setup for this print session. This page setup window is similar to the Page Setup window that is displayed for a 3270 Printer session.
Assign Return Code to a Variable
Allows you to assign to a variable the return code from the attempt to start a print session. To choose a variable, either click the name of an existing variable or click <New Variable> to create a new variable.

Print Extract

Copies data from a rectangular area of the screen and sends it to the current print destination. If a Print Start action has not been performed then a Print Start with a default printer setup and a default page setup is sent to the print destination before this Print Extract action is performed.

Note Print Extract is supported for 3270 Display sessions only.

You should use the Print Extract action with the Print Start and Print End actions as follows:

  1. Do a Print Start action to start a print session.
  2. Do Print Extract actions to send data to the print destination.
  3. Do a Print End action to end the print session.

Start Row and Start Column
Top left corner of the bounding extract rectangle.
End Row and End Column
Bottom right corner of the bounding extract rectangle.
Assign Return Code to a Variable
Allows you to assign to a variable the return code from the attempt to send the extracted data to the print destination. To choose a variable, either click the name of an existing variable or click <New Variable> to create a new variable.

Print End

Allows you to end a print session.

Note Print End is supported for 3270 Display sessions only.

Assign Return Code to a Variable
Allows you to assign to a variable the return code from the attempt to send the extracted data to the print To choose a variable, either click the name of an existing variable or click <New Variable> to create a new variable.

To delete a defined action, select it and click Delete.

Click Order to change the order the actions should be performed on the screen.

Related topics

  • Bidirectional language support
  • Transferring files
  • Variables
  • Macro Programming Guide
    •