Running EXTRA! Macros in Reflection and InfoConnect

  • 7021465
  • 04-Mar-2010
  • 01-Apr-2018

Environment

Extra! X-treme version 9.0 or higher
Reflection Desktop
Reflection Desktop Pro
Reflection Desktop for IBM
Reflection Desktop for UNIX and OpenVMS
Reflection 2014
Reflection for IBM 2014
Reflection for UNIX and OpenVMS 2014
Reflection Standard Suite 2011
Reflection for IBM 2011
Reflection for UNIX and OpenVMS 2011
InfoConnect Desktop Pro for Unisys
InfoConnect Desktop Pro for Airlines

Situation

This technical note describes how to run and edit EXTRA! Basic macros (*.ebm files) in Reflection and InfoConnect products.

Resolution

Support for EXTRA! Macros

In Reflection Desktop, 2014, and 2011 (hereinafter called Reflection), you can run and edit *.ebm files that were created in EXTRA! Also, InfoConnect Desktop 16.0 supports .ebm files created in EXTRA! or earlier InfoConnect versions.

Note: To use EXTRA! macros in Reflection or InfoConnect, you must install the “Legacy EXTRA!” feature (in Setup, on the Feature Selection tab, under Compatibility). Reflection Desktop, Reflection 2014, and InfoConnect Desktop install this feature by default. Reflection 2011 does not install it by default, unless an existing EXTRA! installation is detected.

Running EXTRA! Macros

To run an EXTRA! macro:

  1. Verify that the macro you want to run is in a trusted location.
  2. Open the Workspace Settings dialog box. (With no session running, click the Document Settings icon on the Quick Access Toolbar.)
  3. Under Trust Center, select Set Up API and Macro Security.
  4. In the Legacy API preference list, select EXTRA!.
  5. Close the workspace and then reopen it.
  6. Open a session.
  7. On the Session ribbon, in the Macros group, click Run Macro.
  8. In the Run Macro dialog box, click Legacy EXTRA! Macro.
  9. Browse to the macro file, and then click Open.

Note: If the macro contains unsupported objects, its functionality may be limited or it may not run. (See Unsupported EXTRA! Methods and Properties for details.)

Editing an EXTRA! Macro

To make changes to a legacy EXTRA! macro (.ebm file), use the EXTRA! Basic Editor. To start the EXTRA! Basic Editor, you must first associate the Run EXTRA! Basic Editor action with a custom control, such as a keyboard shortcut or a button. The button option is described in the steps below.

After you set up the EXTRA! Basic Editor, if your macro uses the HostOptions object, you can then edit the HostOptions properties to make the macro work with Reflection or InfoConnect.

Before you distribute a legacy macro, review the Unsupported EXTRA! Methods and Properties and remove any references to unsupported objects that throw exceptions.

Setting Up the EXTRA! Basic Editor

  1. Open the Workspace Settings dialog box. (With no session running, click the Document Settings icon on the Quick Access Toolbar.)
  2. Under Trust Center, click Set Up API and Macro Security.
  3. In the Legacy API preference list, select EXTRA! and click OK.
  4. With a session document open, on the Appearance tab, click UI Designer.
  5. In the Design View pane, click the Session tab and then click the Macros group.
  6. In the Insert Controls pane, click Button.
  7. In the Settings pane, click the Select Action button.
  8. In the Select Action dialog box, from the Action category drop-down list, select Macro.
  9. In the Action list, select Run EXTRA! Basic Editor.
  10. Click OK and then click OK in the Design View.
  11. If prompted, save the new xuml file.
  12. In the workspace, on the Session tab, click the Run EXTRA Basic Editor button to open the editor.

Editing HostOptions Properties

If your macro uses the HostOptions object, you need to edit the HostOptions properties.

Legacy EXTRA! macros and Visual Basic applications that contain parameterized properties cause an error to occur in Reflection or InfoConnect. When you run the macro or application, the HostOptions object returns the error "Method or property not found" if it encounters one of the following parameterized properties:

  • AttributeForeground
  • AttributeBackground
  • Color

Reflection and InfoConnect are based on C# and do not support parameterized properties; therefore, statements that ‘get’ and ‘set’ these properties have no effect. To avoid this problem, edit each parameterized property and replace it with an equivalent form.

To edit the property:

  1. Start the EXTRA! Basic Editor. (See step 12 above.)
  2. Open the macro.
  3. Replace the AttributeForeground, AttributeBackground, and Color properties with one of the following equivalent forms:
??HostOptions.set_[property] x, y
??y = HostOptions.get_[property] x

For example, change

HostOptions.AttributeForeground(x) = y

to

HostOptions.set_AttributeForeground x, y

or

y = HostOptions.get_AttributeForeground x

Improving the Performance of Macros

You can improve the performance of many older IBM session macros by recording the same screen navigation steps with the Reflection or InfoConnect macro recorder instead of using the legacy EXTRA! macro file. Recorded EXTRA! macros typically run slower than Reflection recorded macros because of differences in how the recorded code detects when the IBM host screen is ready for input.

EXTRA! macro recording is based on the concept of host screen settled detection. This check waits for a given time to satisfy the wait state. If there is additional screen data or if key state changes within the stated wait time, the wait duration resets and starts over. In essence, the call to WaitHostQuiet() always requires at least the given host settle time value (g_HostSettleTime). (The host settle time is set to 3 seconds by default. You can tune this value per screen transition, but screen navigation fails if the value is set too low.) The net result is that performance is slow, especially when the macro navigates a large number of host screens.

In Reflection (2011 R2 or higher) and InfoConnect, newly recorded code for 3270 and 5250 sessions detect when the host screen is ready for input based on keyboard enabled state, cursor position, and display text. Recorded macros that use this type of detection run significantly faster than those that use WaitHostQuiet(). To further optimize your macro, you can customize the generated recording for any one of the three checks (WaitForKeyboardEnabled, WaitForCursor1, and WaitForText1) that has been recorded for each screen transition.

The following example shows legacy EXTRA! macro code compared to Reflection code generated for a given screen transition detection.

EXTRA!:

Sess0.Screen.WaitHostQuiet(g_HostSettleTime)

Reflection:

returnValue = ibmCurrentScreen.WaitForKeyboardEnabled(timeout, 1)
'Wait for cursor to be in position before continuing
returnValue = ibmCurrentScreen.WaitForCursor1(timeout, 4, 14)
If (returnValue <> ReturnCode_Success) Then
Err.Raise(5001, "WaitForCursor1", "Timeout waiting for cursor position.", "VBAHelp.chm", "5001")
End If
returnValue = ibmCurrentScreen.WaitForText1(timeout, "===>", 4, 9, TextComparisonOption_MatchCase)

Unsupported EXTRA! Methods and Properties

Reflection and InfoConnect do not support EXTRA! macros and COM applications that contain certain methods and properties. If your macro includes an unsupported method or property that has no operation, your macro will run but without the functionality provided by that object.

Methods and Properties that Throw Exceptions

If your macro includes an unsupported method or property that throws an exception, your macro will not run until the object is removed. The methods and properties that throw exceptions are listed below by class.

ExtraKermitOptions Class

BlockCheck
CompressionCharacter
ControlQuoteCharacter
EightBitQuoteCharacter
Enable8thBitQuoting
EnableCompression
EnableTxPacketEndCharacter
ErrorRetryLimit
PadCharacter
PadCharacterCount
QuitHostServer
RemoteKermit
RxPacketLength
RxPacketStartCharacter
RxTimeoutInSeconds
StartHostReceiving
StartHostSending

ExtraModemSetup Class

AreaCode
BreakLength
CloseOnDisconnect
CountryCode
DataBits
FlowControl
MaximumRedials
ModemType
Parity
PhoneNumber
ReceiveBuffer
ReceiveXoffPoint
Speed
StopBits
TimeBetweenRedials
TransmitBuffer
UseCountryCodeAndAreaCode

ExtraSerialSetup Class

BreakLength
DataBits
DisconnectOnExit
FlowControl
ModemDisconnect
Parity
Port
ReceiveBuffer
ReceiveXoffPoint
Speed
StopBits
TransmitBuffer

ExtraSession Class

NavigateTo
PageRecognitionTime

ExtraSystem Class

GetSystemTime

ExtraTelnetSetup Class

CloseOnDisconnect
CustomType
DataBits
HostName
InitiateNegotiation
PairCRWithLF
Port
PromptHost
ProxyType
SOCKSProxyAddress
SOCKSProxyPort
SSHUserID
SSHUserPassphrase
SSHUserPassword
SSHUserPrivateKey
TelnetCommand
TelnetProxyAddress
TelnetProxyPort
TerminalType
VerifySSLDestination
WindowSizeOption

ExtraZmodemOptions Class

AutoStart
CheckFileSize
MaximumErrors
PacketSize

Additional Information

Legacy KB ID

This document was originally published as Attachmate Technical Note 2483.