Run your existing emulator macros

Most organizations moving to WND Terminal have years of macros written for their old emulator. WND Terminal runs them as they are, on the session they’re started in:

PCOMM macros (.mac) convert to WND Terminal macros, as before (see Macros).

Importing and running one

Open the Macros panel (Ctrl+K > Macros…) and choose Import a macro…. Pick the macro file, or the Reflection session document that holds the VBA macros. WND Terminal reads it and tells you:

• It runs in WND Terminal as it is. Choose Add to my macros. A VBA project with several macros becomes one macro for each (Payroll - SignOn, Payroll - SpooledFiles, ...).
• Or the lines that use something WND Terminal doesn’t have, each with its line number and what it is (Line 9: Session.FileTransferScheme isn't something WND Terminal's EXTRA! objects have). Those macros don’t run until the lines are changed. Suggest a fix asks the AI for the changes (see below).

When the macro only types, presses keys, waits, asks and shows messages, Convert to a WND Terminal macro is offered too. You get the same steps as a WND Terminal macro, to edit in the macro editor.

Run it like any other macro: Run in the panel, Ctrl+K ("Run macro: TSOLogon"), or a key you give it in Keyboard maps. A running macro shows its progress and can be stopped. When it asks something (InputBox, PasswordBox, PowerTerm’s input-line) the app’s small question window opens, and a password is typed into a hidden box. A MsgBox with Yes and No (or OK and Cancel) shows those buttons. A MsgBox with only OK is shown as the macro’s message, and the macro goes on.

What they can use

The Basic of all these emulators is one family (Cypress Enable, Sax Basic and VBA), and WND Terminal has its own interpreter for it. Microsoft hasn’t licensed VBA to new products since 2007, and macros for a terminal don’t need it. Everything they use is here.

The language. Sub and Function (with ByVal, ByRef, Optional, ParamArray), Dim, ReDim [Preserve], Const, Global, Static, Type ... End Type and Enum. String, Integer, Long, Double, Single, Currency, Boolean, Date, Variant, Object and arrays (several dimensions, Option Base). If / ElseIf / Else (on one line too), Select Case (with To and Is >), For / Next (with Step), For Each, Do / Loop with While or Until at either end, While / Wend, Exit For, Exit Do, Exit Sub, GoTo and labels (line numbers too), GoSub / Return, On Error Resume Next, On Error GoTo, Resume, Resume Next, Err.Number, Err.Description, Err.Raise, With blocks, End and Stop, Option Explicit and Option Compare Text, Collection and Scripting.Dictionary.

Functions. Left, Right, Mid (and the Mid(...) = statement), Len, InStr, InStrRev, Trim, LTrim, RTrim, UCase, LCase, Space, String, Replace, Split, Join, StrComp, StrConv, StrReverse, Chr, Asc, Hex, Oct, Val, Str, CStr, CInt, CLng, CDbl, CBool, CDate, Format (numbers, dates and text, and the named formats), FormatNumber, FormatDateTime, IsNumeric, IsDate, IsEmpty, IsNull, IsArray, IsObject, IsMissing, TypeName, VarType, IIf, Choose, Switch, Abs, Int, Fix, Round, Sgn, Sqr, Rnd, Now, Date, Time, Timer, DateAdd, DateDiff, DatePart, DateSerial, TimeSerial, Year, Month, Day, Hour, Minute, Second, Weekday, MonthName, UBound, LBound, Array, MsgBox, InputBox, PasswordBox, Sleep, Wait, DoEvents, Environ (the user and computer name), FreeFile, EOF, LOF, Dir, FileLen. A Declare of Windows' Sleep or GetTickCount works. Other Windows library functions don’t.

Files. Open ... For Input / Output / Append As #1, Line Input #, Input #, Print #, Write #, Close, Kill. A file name without a folder is in the macro folder (Documents/WND Terminal macros). Other folders work only when your organization lists them (see below). Files are written as Windows-1252 text with CRLF line ends, as the old emulators wrote them.

Binary and random-access files work too: Open ... For Binary and Open ... For Random ... Len = n (with Access Read), Get # and Put # with or without a position, Seek #, and the functions Seek(), Loc(), EOF() and LOF(). Values are laid out byte for byte as Visual Basic wrote them (an Integer is 2 bytes, a Long 4, a String * 30 30 characters, a Type its fields in order, a Variant its type and then its value), so files the old macros wrote read back the same. Len(rec) of a Type gives its record length. The folder rules are the same as for text files.

Dialog boxes and the clipboard. Begin Dialog ... End Dialog with Text, TextBox (hidden for a password), CheckBox, ListBox, DropListBox, ComboBox, OptionGroup and OptionButton, OKButton and CancelButton, then Dialog(dlg) or Dialog dlg: each box is asked in the app’s question window, and OK gives -1, Cancel 0. Screen.Select, Screen.Copy, Screen.Paste, Area.Copy and VB’s Clipboard object (SetText, GetText, Clear) use a clipboard the macro keeps while it runs. Other programs don’t see it, and a password can’t be put on it.

EXTRA!. CreateObject("EXTRA.System") (or GetObject(, "EXTRA.System")). System’s ActiveSession, Sessions and TimeoutValue. A Session’s Screen, Name, Connected, Visible, Activate, Disconnect and Close. The Screen’s GetString, PutString, SendKeys (with <Enter>, <Tab>, <Pf3>, <Clear>, <EraseEOF>, <Reset> and the other keys), SendInput, WaitHostQuiet, WaitForString (anywhere, or at a row and column), WaitForCursor, MoveTo, Row, Col, Rows, Cols, Search and Area (with Value, Top, Left, Bottom, Right), Updated, and OIA.XStatus.

Sessions has every session open in WND Terminal. Sessions(1) is the one the macro was started in, then the others in the order they were opened, by number or by name (Sessions("CICS")), with Count and For Each. Sessions.Open("CICS.edp") opens the saved connection with that name (the file’s folder and extension don’t matter) as you would, in a tab of its own, and gives its session; when it’s already open, that one. Each session object keeps to its own session, so a macro can read one screen and type into another. Session.Activate makes it the active session, which ActiveSession gives from then on. In a browser (the gateway) a macro uses the sessions already open, and Sessions.Open says to open the connection first.

Reflection Basic (and the older Reflection API in VBA). The Session object has Transmit, TransmitANSI, TransmitTerminalKey rcIBMEnterKey (and every rcIBM...Key), WaitForEvent (rcKbdEnabled, rcEnterPos), WaitForDisplayString, WaitForHostSettle, GetDisplayText, GetText, SetCursorPosition, CursorRow, CursorColumn, FindText with FoundTextRow and FoundTextColumn, Wait, Connected, KeyboardLocked, MsgBox, InputBox. Timeouts are written as Reflection writes them ("30", "0:0:30").

Reflection Desktop (VBA). ThisIbmTerminal (Screen, IsConnected, Disconnect) and ThisIbmScreen / an IbmScreen with GetText, GetTextEx, PutText2 (and PutText1), SendKeys, SendControlKey ControlKeyCode_Transmit (and every ControlKeyCode_... WND Terminal has a key for), WaitForHostSettle, WaitForText1, WaitForCursor1, WaitForKeyboardEnabled, MoveCursorTo1, CursorRow, CursorColumn, Rows, Columns, SearchText, and the ReturnCode_... values. A document’s modules can call each other (Helpers.Summary(...)).

For UNIX and Linux (VT) sessions, ThisTerminal (Screen, IsConnected, Disconnect) and ThisScreen with GetText, GetText2, SendKeys, SendControlKey (ControlKeyCode_Return, _Tab, _Escape, _F1 to _F20, the arrows and the others a VT keyboard has), WaitForString, WaitForString2 and WaitForString3 (the timeout in milliseconds, or "hh:mm:ss"), WaitForHostSettle, CursorRow, CursorColumn, DisplayRows, DisplayColumns and SearchText. A wait looks for what the host wrote after the macro last sent keys, so WaitForString3 "$ " after a command finds the new prompt, not the one already on the screen.

HostExplorer. CreateObject("HostExplorer") and its CurrentHost, with Keys (with ^M for Enter, ^I for Tab), RunCmd (key names), WaitForString, WaitIdle, WaitPSUpdated, Row, Column, SetCursor, Area, TextRC, Text, PutText, Search, and Fields (Count, Fields(i).Text to read or fill an input field, Row, Column, Length).

PowerTerm PSL. PSL is a language of its own, Tcl-like, as Ericom’s PSL reference describes it. WND Terminal has name = value (and set name value, arrays cel($i)), $name, [command], {...}, if / elseif / else, while, for, foreach, switch, break, continue, proc / return, goto to a label, expr, string, format, lists, catch / error and exit. Then send (text with <enter>, <cr>, <tab>, <pf3> and the other keys), wait N for "text", wait N, wait N silent, screen, cursor, get row / get col, message, input-line, input-password, and open, gets, puts, eof and close. Emulator settings (set hide-toolbar on) are left alone.

Rumba. Rumba’s text macros (.rmc) and the scripts of its older Script Editor (.csf) are lists of commands that type text, press keys, wait for text or for the host, move the cursor, ask the person, show a message or pause. Each becomes a WND Terminal macro line by line (Wait For Text "READY" 15 becomes wait "READY" 15, Prompt "Password" Password becomes ask password "Password" and type password), and runs as that. Command names are read in any case and spacing, with arguments in quotes or bare, Command=argument lines, numbered steps, keys as <Enter>, [PF3], {Tab} or @E, comments after ;, ', // or REM, and macros saved as XML. Rumba’s jumps and decisions (Label, Goto, If), running other macros or programs, file transfer and printing are listed by line, and those macros need a person. A .rmc that isn’t text is Rumba’s own format and is recorded again, as before.

Other programs you allow. Shell "RptView.exe report.txt" starts the program when your organization turned on AllowLegacyMacroShell and lists it in LegacyMacroPrograms (see below). It starts directly, not through a command shell, so &, | and > in the line are just text, and the line gives the program’s task ID as Shell did. AppActivate with that task ID (or the program’s name) is accepted. Any other program is refused at that line, saying it isn’t one of the listed programs.

Other programs (Windows). CreateObject("Excel.Application"), GetObject(, "Excel.Application") and any other program’s objects work on Windows, late-bound through COM, as in VBA: methods, properties with arguments, named arguments, objects returned, For Each, and Excel’s ranges of values as arrays. On a Mac, in Linux or in a browser such a macro stops at that line, saying it needs Windows.

Rows and columns count from 1 in all of these, as they did in the emulators.

What they can’t do

These lines are listed when you import the macro, with their line numbers:

• Shell and AppActivate, unless your organization allows the program. The message names the two settings that would.
• SendKeys to Windows (typing into other programs), DDE, and dialog functions that change a dialog while it’s shown (DlgText, DlgValue).
• Windows library functions from a Declare (except Sleep and GetTickCount).
• Reflection’s windows and workspace (ThisFrame, Application, GetObject("Reflection Workspace")), file transfer, printing, and anything else of an emulator’s objects that WND Terminal’s objects don’t have.

A name the macro uses that nothing sets and WND Terminal doesn’t know (a constant of another product, say) is listed too.

Suggest a fix

When a macro has lines WND Terminal can’t run, Suggest a fix asks the AI model your organization (or you, in AI settings) set up for Ask WND. What it sends:

• The macro with its line numbers, masked first. Card numbers, account-style numbers, e-mail addresses and passwords in the macro’s text become tokens such as [CARD 1], and your organization’s MaskPatterns become dots, as for Explain this screen.
• The lines the import listed, and why.
• What WND Terminal’s emulator objects have, generated from the objects themselves, so the model doesn’t invent members that aren’t there.
• An instruction to change only the listed lines, keep the names and what the macro does, and answer with a unified diff and a one-line reason for each change.

Each change comes back with its lines (taken out in red, put in green) and its reason, and a box to tick. Changes that only touch the listed lines are ticked already. A change that also touches other lines says so and isn’t ticked. Use the ticked changes checks the macro again: "It runs in WND Terminal with the changes you chose", or the lines that still need a person. Tokens get their real values back in your copy. A change that would need a value your organization’s masking hid can’t be used, because the model never saw it.

Nothing is sent when AllowAI is off or no model is set up. Each request is in the audit log (macro.fix, with the server, the model and how many values were masked).

From a script, wnd-automate macro check FILE lists the lines, and wnd-automate macro fix FILE --write asks for a fix, prints it as a diff with the reasons, checks the result, and saves it (the original is kept as FILE.bak). It uses the policy’s AIEndpoint and AIModel, or WND_AI_ENDPOINT and WND_AI_MODEL (and WND_AI_KEY), and sends nothing when the policy turns AI off. It ends with exit code 0 when the macro runs.

Verify with a recording

A macro that runs isn’t the same as a macro that does the job. Record yourself doing the task once in WND Terminal (Session recording), and Verify with a recording… runs the macro against that recording, played back on your computer as a pretend mainframe (see the replay host). Nothing reaches a real host. The macro is verified when it presses the same keys the recording has, in the same order, and reaches the recording’s last screen. Otherwise it says where it went another way: "at key 3 of the recording it pressed PF3 where the person pressed Enter". Questions the macro asks are answered with a stand-in, and files it writes go to a folder that’s removed afterwards.

wnd-automate macro verify FILE [RECORDING] does the same from a script (a recording with FILE’s name and .wndrec when none is given) and prints the replay’s report. The migration readiness report runs every macro that has a recording with its name next to it (Payroll.ebm and Payroll.wndrec) and says Verified, "Didn’t match its recording", or "Not verified (record a run to verify)" for each. The replay host plays mainframe (3270) recordings.

What every run follows

• Passwords. A value typed into a hidden question (PasswordBox, a question that sounds like a password, PowerTerm’s input-password) can be typed into the session and compared, but never shown in a message, written to a file or handed to another program. The macro stops at that line instead. Fields whose contents aren’t shown (password fields) read as spaces, so a macro can’t read a password off the screen, and a search never finds what’s in one.
• Masking. Card numbers and your organization’s MaskPatterns read as they show, masked.
• Files. Only in the macro folder and the folders in LegacyMacroFolders. A path that climbs out with .. is refused. With copying turned off (AllowCopy false) macros can read files but not write them, and can’t use other programs either.
• No endless loops. A run goes round its loops at most 5,000,000 times, and procedures call each other at most 64 deep. The Stop button stops a macro at once, even in a wait.
• The audit log. Each run (macro.run, with the kind of macro), each file written (macro.file), each other program’s objects used (macro.object), each program started with Shell (macro.program), each fix asked of the AI (macro.fix) and each refusal.
• What a macro types isn’t kept as your recent typing.

For IT

AllowAI (and AIEndpoint, AIModel) decide whether Suggest a fix can be used, as for Ask WND.

All of these are in the Group Policy template, the Mac configuration profile and policy.json (see the policy settings reference).

The migration readiness report checks every macro on your share the same way: each EXTRA!, Reflection, HostExplorer and PowerTerm macro, each exported .bas module and the VBA project in each Reflection session document is "Runs in WND Terminal" (with its converted WND Terminal macro, when it converts), or "Needs a person" with the exact lines and why. Rumba’s text macros and scripts are "Converts fully", or "Needs a person" with the lines. Each macro with a recording next to it is run against the recording, and the Macros sheet has a Verified column with what the replay found. The summary counts the macros that convert or run as they are, and how many were verified.