4. Macros ________________________________________________________________ dataComet documentation. (Rev. 1/27/08) Copyright 1995 databeast, Inc. All Rights Reserved. This document has information on (select and use "FindÉ" to go to the section): Using Macros Using the Macro menu(see 2. Menus) Using the "Define Macros..." dialog Entering text and macro commands Entering Escape and other ASCII control characters Macro commands Moving the Host Cursor Finding a string or setting the selection Sending Function keys Controlling the emulator Display Literal mode Selecting National Character Sets Keymap command Menu commands File and Print commands File Transfer commands Edit commands Window selection and output redirection commands Telnet commands Scripting commands Delay Loop Loop break Query the user to enter a string Inform the user using the prompt line or an alert Match String Match case Triggers Scripted login example with user prompt for password Menu numbers (table) ___________________________________________________ Using Macros ___________________________________________________ dataComet allows you to record macros to perform functions such as moving the cursor, making a selection, or appending the selection to a file. Dialogs in the Macro menu allow you to paste in or enter a sequence of macro commands; macros can also be entered and executed in the .edit window. Pressing the "Shift-Enter" key while an edit window is the frontmost window causes the current line or selection to be executed as a macro (pressing the Enter key alone sends the selection as plain text). You can execute the examples below in the frontmost emulator session by selecting them and pressing "Shift-Enter". There are many other ways in which you can trigger dataComet macros: * With key-combinations you enter on the keyboard (such as Control Option A, set using "Define macros..." in the Macro menu); * With a mouse single- or double-click (set using "Set single-click macro..." or "Set double-click macro..."); * You can also define a macro to execute when a connection with a host is complete ("Set Connection macro...") or when the user closes the connection ("Set Close macro..."); * You can define macros as menu items in the "Macro" menu. * Command-clicking on button controls brings up a dialog which allows you to rename the control and set it to execute a macro when clicked. The Key Macro on/off switch is in the Macro menu; when macros are on, an M appears in a box on the top left hand side of the screen. When a key macro is currently executing, the M appears in reverse video; the reverse M also appears if keystrokes are pending execution in the key queue. If you wish to cancel the execution of a macro or pending keystrokes, use Command-'.'. ___________________________________________________ Macros... Using the "Define Macros..." dialog ___________________________________________________ When the dialog for entering key macros comes up, you have three options: select a key by pressing it, select a macro button or menu by command-clicking on it, or show a list of macros currently associated with keys and buttons. "Press the key-combination you want to remap...": When this prompt appears, you can press a key-combination (or command-click on a button or menu macro); the dialog will show you the name of the key, and will allow you to enter actions (text and commands) you want the key-combination to produce. If there is a key macro associated with that key, the actions associated with the key will be displayed, and the Delete button will be enabled. Note that holding down the mouse button when you press the key-combination will identify the key as an "Alt-key," and such a macro will only be matched if the "ALT" state is set using the "!CA" command documented below (this allows you to switch keyboard configurations with a keystroke, and is used with library keymapping). When the "ALT" state is on, the boxed "M" which shows that key macros are on changes to an "m". There are several check boxes in the dialog: "Global": This check box shows whether a key macro is a global macro which can be used by all sessions (saved in the "Comet Default" document). Setting it on allows you to set a key macro as a global macro. "Ignore Caps Lock": Ignore the caps lock key when matching key macros. "Use Command Font": Use the "Comet Chicago" font, which displays common macro commands as buttons. If this option is off, the frontmost window's font is used. If you want to enter international characters, this option needs to be off. You can modify the macro text by entering new text or using copy and paste with the Command-C and Command-V keys. Command-. cancels your modifications to the key macro. When you are finished, you must press the Set button if you want the changes to take effect. The program will then alert you if your entry has errors in the length of the codes. (PLEASE NOTE that the codes are not checked for validity until you execute a key macro by typing the key when you have quit the dialog and Key Macros are set on! Alerts will then inform you of any errors.) If there is no error, the macros are updated immediately; there is no need to save the configuration to save the key macros in the document. If you decide not to change the text, you should press the Cancel button. You can then quit if you wish, or add, remove, or modify other keys. Entering text and macro commands Text which you enter in the key macro window can be interpreted as either plain text or commands. Individual characters stand for themselves--except for '!' & '\', which can be entered by using '!!' and '\\'. These two characters are special: '!' is used to introduce a command; '\' is used to enter a number, specified using three decimal digits, such as "\010". This numeric entry can be used either in place of a character, or to enter a decimal numeric value. Ordinary text can be entered directly in the text-editing field of the dialog. Commands are entered as a '!' (exclamation point) followed by a pair of characters; the first character selects a class of action, and the second the particular type of this action. In IBM mode, the macro dialogs present buttons to perform input of all the IBM function keys. (PLEASE NOTE that dataComet does not automatically map the Return key to produce an "Enter," so you need to press the "Enter" button to send an Enter command to the host using a macro.) Entering Escape and other ASCII control characters ASCII control characters can be entered by pressing the Control key and the character ('a' through 'z', Space, '[', ']', '\', '@', '^', '_', or '?'). Note that you can enter the Escape control character (which sometimes appears in host application documentation as "^[" or ) by pressing the "esc" key or Control-[. The action classes and associated characters available in both ASCII and the "IBM Keymapping" modes are as follows: ___________________________________________________ Moving the Host Cursor ___________________________________________________ Move to X-coordinate: (X) followed by a decimal number specifying the column number (0-255). !X\000 Move to Y-coordinate: (Y) followed by a decimal number specifying the row number (0-32). The Y command always positions the cursor in column 0. !Y\000 !Y\002!X\049 position the cursor on 50th column of the 3rd line Move the cursor: (M), and a code: !ML Move the cursor to the left; !MD Move the cursor down; !MU Move the cursor up; !MR Move the cursor right. The IBM 3270 also supports: !M0 Move the cursor home; !M< Move the cursor backwards one field; !M> Move the cursor forward one field; !MN Do a Newline. ___________________________________________________ Finding a string or setting the selection ___________________________________________________ Search forward or backward for a string: ('!/>' or '!/<'), followed by a string terminated with another macro or null ASCII character. !/>make!D\001 To make a selection: you must use four commands to set a selection range, each of which uses a number to specify the position on the screen numbered from 0; when all four codes have been received, the selection will be made. (Note also the "!Ea" macro above which selects the current screen only, and "!EA" which selects the screen and the entire scrollback buffer.) !S\000 selection start Y position, followed by the position number; !T\000 selection start X position, followed by the position number; !U\023 selection end Y position, followed by the position number; !V\080 selection end X position, followed by the position number. !S\000!T\000!U\002!V\080 Shift selection left: (<) followed by the number of spaces to shift the selection. !<\005 Shift selection right: (>) followed by the number of spaces to shift the selection. !>\080 Set selection length: (#) followed by the new length. !#\004 ___________________________________________________ Sending Function keys ___________________________________________________ !P\001 through !P\036 map to PF keys 1 through 36 for both ASCII and IBM emulations. Send VT220 keys: !P\128 Find !P\129 Insert !P\130 Remove !P\131 Select !P\132 Previous Screen !P\133 Next Screen Send 3270 PF action keys: !P\000 Sys Request !P1 PA1 !P2 PA2 !P3 PA3 !PC Clear !PE Enter Send 3270 local keys: !A Backspace blank (that's a space there!) !AB Backspace delete !AD Delete character to right (x->) !AE Erase to end of field !AI Toggle insert mode !AR Reset !AS Light pen select at the mouse position !As Light pen select at the cursor position !AX Erase Input !AA Display attribute bytes !AC Toggle Base Color attribute mapping Setting 3270 extended attributes: !aZ Reset the color attribute to the default color !aR Red !aG Green !aY Yellow !aB Blue !aP Pink !aT Turquoise !aW White !aX Reset the character attribute to the default !aA Blink !aS Reverse !aD Underline If a selection has been made, the selection is set; otherwise succeeding characters are set to the attribute. ___________________________________________________ Controlling the emulator ___________________________________________________ Perform an emulator action: (C) followed by a code: !CA Set the ALT (mousedown state) modifier bit for all keypresses. This allows you to have an Alternate macro set. !Ca Set ALT off. !CB Hide the Desktop from the user (for kiosk security). !CC Close the session without a dialog. !CE Show the .edit window. !Ce Show the terminal emulator window. !CD Show MacTCP smoothed round-trip time and time-out in the upper right corner of the screen. !Cd Show MacTCP packets sent and received in the upper right corner of the screen. This is the default. The send counter becomes inverted when a resend is performed. !CF Close the copyright/help textwindow. !CH Don't update the display. !CS Update the display as usual. !Cs Display the mouse cursor position in the emulator window status bar. !CI Draw each character promptly as it is processed (ASCII only). !Ci Wait to update the screen: draw characters en masse. !CM Set the top bit (meta-bit) of the next ASCII character. !CN Makes a bell sound and sets the Apple Task menu to flash if dataComet is in the background. !Cp Set an IBM PF key to page when pasting text (default is Enter). !CR Restore line 25. !CT Turn on cursor positioning using the mouse. !Ct Turn off cursor positioning. !CUstring\000 Interpret a string as a URL and open it. !CV Turn on VT100 auto-print (i.e., print line on CR, LF, FF). !Cv Turn off VT100 auto-print. !CZ Toggle fast drawing mode (useful for library data entry checking). !C>string\000 send a string, usually a VT100 parameter, directly to the emulator. Display Literal mode !CL Display all characters sent and received as literals in the .edit window. In IBM mode, the streams are presented in an intelligible format; ASCII mode is presented raw. This mode is very useful for debugging or analyzing host application output to the emulator. !Cl Display Telnet layer transmissions also. Selecting National Character Sets For VT100 emulators you can select a National Character Set which is mapped into ISO-Latin-1, or the Macintosh character set if a "Control Translation" menu mapping is selected (for this mapping to work correctly, you must select a Macintosh font such as Monaco). The '!N\000' and '!n\000' macros set the G0 and G1 fonts, respectively. The character sets are selected using a numeric argument: \000 US-ASCII \001 ISO-Latin 1 \002 British \003 Dutch \004 Finnish \005 French \006 French Canadian \007 German \008 Italian \009 Norwegian/Danish \010 Spanish \011 Swedish \012 Swiss \013 Portugese \014 DEC Supplementary \128 VT Graphic Symbols ___________________________________________________ Keymap command ___________________________________________________ !K\nnn Select the keymap (000-nnn). \000 Automatic \001 IBM 3270 \002 IBM 5250 (AS/400) \003 ncsa (NCSA Telnet) \004 linux \005 scoansi \006 xterm / VT420f \007 386at (Intel SysV) \008 wyse-60 \009 UNIX tn3270 ___________________________________________________ Menu commands ___________________________________________________ Macros from !\000 to !\031 correspond to the menu items from left to right, with the items numbered from 1 (i.e., "!\<3-digit menunum>\<3-digit itemnum>"). Adding 64 to the item number sets the shift key for the menu item execution; adding 128 to the item number sets the Option key for the menu item execution; adding 160 to the item number sets the Shift-Option keys for the menu item execution; adding 192 to the item number disables it. (Macro recording provides an easy way to get an item's macro equivalent, since menu items selected are included in the macro.) Menu number 31 corresponds to the Finder menu at the far right (these items can only be disabled, not executed). !\001\001 Execute the "File New" menu item to open a new session. !\001\065 Execute the "File New" menu item to open a new text document. !\001\129 Disable the "File New" menu item. !\031\192 Disable the Finder menu. !\031\193 Disable the "Hide Comet" Finder menu item. See "Menu numbers (table)" below for a complete list of the available menus. ___________________________________________________ File and Print commands ___________________________________________________ Perform a file action: (F) followed by a code: !FA Append the selection to a file. !FB Append the selection to a file selected through a Standard Put File dialog. !FD Print the window selection using dataComet's serial print routine. !Fd Perform a print page eject. !FF Bring the Finder or application launchpad to the front, closing sessions which are not configured to stay open on Mandarin sleep events. !Ff Bring the Finder or application launchpad to the front without closing any sessions. !FP Print the emulator screen using Apple's standard Print Manager routines. !Fp Print the .edit window. !Fq Print selection in the .edit window. !FS Save the selection in a file; if a file has not been opened, a Put File dialog will be performed. !FT Save the selection in a file; always present the Put File dialog. !FV Toggle VT100 auto-print mode (the "Local Print" key). !Fv Set VT100 auto-print off. Opening Documents and Sessions: Note that the following commands for opening files need to have path names specified with colons ':' rather than slashes '/': !FOfilename\000 Open a document by name relative to dataComet's home application folder, e.g., !FO::Resources:Help:0.1. Shortcuts\000 !Fofilename\000 Open relative to the dataComet/ folder (in the user's ~/Documents/ folder) !FWfilename\000 Open relative to the home Documents folder !Fwfilename\000 Open relative to the dataComet/Documents/ folder !FXfilename\000 Open relative to the home Sessions folder !Fxfilename\000 Open relative to the dataComet/Sessions/ folder ___________________________________________________ File Transfer commands ___________________________________________________ The following commands work with IND$FILE and X-, Y-, and Z-Modem. Perform a file transfer action: (f) followed by a code: !fUfilename\000 Upload a file using the default serial transfer method. When using IBM IND$FILE, this sets the local file name; the appropriate local option settings (below) and text of the IND$FILE command specifying the host file name and host options should follow (with an ENTER command to execute it). !fFfoldername Set the download folder, e.g., !fF:Downloads:\000 IND$FILE options: !fA ASCII mode. !fa Binary mode. !fC CR/LF translation. !fc No CR/LF translation. !fP Protect local file. !fp Don't protect local file. !f+ Append to local file. !f- Overwrite local file. Dump/Trace options: !fT Trace packets. !ft Don't trace packets. !fD Dump packets. !fd Don't dump packets. ___________________________________________________ Edit commands ___________________________________________________ Perform an editing action: (E) followed by a code: !ES Use the standard text mode when copying the selection. !ET Use the Table mode when copying the selection. !EA Select the whole screen buffer or text. !Ea Select the current emulator screen. !EL Select the line where the mouse cursor is located. !El Select the line where the emulator cursor is located. !EW Select the word where the mouse cursor is located (the default double-click action). !Ew Select the word where the emulator cursor is located !EB Append the selection to the session's .edit window. !Eb Append the selection to the session's .edit window without returns. !EC Copy the selection to the Clipboard. !Ec Copy the selection to the Clipboard without returns. !EM Execute the selection range from the .edit window. !Em Send the selection range from the .edit window to the host. !EX Cut the selection range (works only with the .edit window). !Ex Clear the Clipboard. !EV Paste the selection into the emulator screen or the .edit window. !B\000 Append the emulator screen to the logs & scrollback buffer. !B\nnn Append a line (001-nnn) to the logs & scrollback buffer. ___________________________________________________ Window selection and output redirection commands ___________________________________________________ Bring a window to the front (w) followed by the number associated with it in the Window menu: !w\001 Perform a window action (W) followed by a code: !WSwindowname\000 Bring a window to the front; WS followed by the window name and terminated with another macro or null ASCII character. !W>windowname\000 Make a window the output window, so that typed characters, PF keys, macro characters, and pastes will appear in the named window. !W>\000 Make the emulator window the output window, so that typed characters, PF keys, macro characters, and pastes will appear in the emulator window, even though the .edit window is on top. !W} Reset the output window to the standard output. NOTE: All keys and macros are routed to a session's .edit window if it is the front window. ___________________________________________________ Telnet commands ___________________________________________________ !tA send Are You There; !tB send Telnet Break. !tC send Interrupt; !tU send Abort; !tx send Erase Character; !tX send Erase Line. !ta Type IP address at cursor. !tM disable Return key remapping !tm allow Return key remapping (i.e., the following items) !tR Return sends Carriage Return !tr Return does not send Carriage Return !tL Return sends Line Feed !tl Return does not send Line Feed !tN VT100 newline mode on !tn VT100 newline mode off !tu Type username at cursor The username set in the "Reconfigure SessionÉ" dialog can be sent to the host using this command. ___________________________________________________ Scripting commands ___________________________________________________ Record user input as macro commands: (R) followed by a code: !RB begin recording; !RE end recording and place the recording in the scrap for pasting into the .edit window or key macro dialog. Delay: (D) followed by the number of seconds to wait specified as \nnn, e.g. "!D\001". Delay Ticks: (d) followed by the number of ticks (1/60 seconds) to wait specified as \nnn, e.g. "!d\001". Loop: (L) followed by the number of times to repeat the sequence of macro commands which follows; this sequence must be terminated by an entry containing "!L\000" (loop zero). Using '\255' for the count will cause the loop to continue until the Command-. "cancel" key is pressed. !L\001echo hello !L\000 Loop break: (l) followed by a level, \001 or \002. !l\001 break out of a match case. !l\002 break out of a match case and any enclosing Loop. Query the user to enter a string: (Q) followed by P, followed by the prompt, followed by a "!Q". macro command to terminate the prompt string. The user's response will be sent out to the host. To enter a password, use "!QS" to replace the characters with dots. Both the query and the response must be under 256 characters. !QPEnter ID:!QQ Inform the user using the prompt line or an alert: (q) followed by 'a' if you wish an alert, or 'b' if you want to sound the bell; otherwise the prompt line in the button bar is set. !qaThis is an alert!!\000 or !qb!qzThis is a 25th line prompt!!\000 or, finally !qz\000 will clear the prompt line. Match String: Delay session macro processing until host output matches string: (Z) followed by a number indicating the number of seconds to wait before aborting; if the number is '\255', it waits forever if the string is not matched. This entry is followed by a list of characters to match, terminated by any non-character macro command (usually a Delay entry). You might use this in a login as follows... Match case: Execute a macro when host output matches a string: (z) followed by a number indicating the number of seconds to wait before aborting (if the number is '\255', it continues waiting until a "!l\001" breaks out of the match case loop or a "!l\002" breaks out of a repeat loop containing the match case macro; Note: match case macros cannot contain a loop), AND THEN followed by a string terminated by a macro, ANOTHER !z\000 (the numeric argument is ignored for following cases), string, macro, ..., TERMINATED by a !Z\000. Processing of macro commands on the macro queue and new keystrokes is delayed until the match is found. Triggers: If you use "!Z\001", the match case macro is interpreted as a trigger, and the processing of macro commands and new keystrokes continues while the match case waits for matches and handles them. Here's an example of a match case macro with paused input: cat shoplist !z\030dog!D\000echo food !z\255cat!D\000echo litter !z\255frog!D\000echo flies !l\001!Z\000 produces litter food litter litter food flies when shoplist is a file containing dogcatcatdogfrogcatdog Note that matching "flies" breaks out of the loop, and that the "cat" in "cat shoplist" is also matched! ___________________________________________________ Scripted login example with user prompt for password: !Z\030login:!D\000myloginname!Z\030password:!D\000!QSEnter password:!QQ Scripted login example with user prompts for userid and password: !Z\030login:!D\000!QPEnter User ID:!QQ!Z\030password:!D\000!QSEnter password:!QQ Scripted login example with userid and password from configuration: !Z\030ogin:!D\000!tu\013!Z\030assword:!D\000!tp\013 ___________________________________________________ Menu numbers (table) A list of the menu numbers which are used in macros to select (or disable) menu items. ___________________________________________________ Menu # Name Submenu <- of ... \000 dataComet-Secure \001 File \002 Edit \003 Window \004 Control \005 Macros \006 Telnet \007 Serial \008 ASCII \009 Transfer <- File \010 IBM \011 3270 \012 Help \013 Cursor <- Edit \014 Send Telnet Command <- Telnet \015 Font <- Control \016 Size <- Control \017 Leading <- Control \018 Width <- Control \019 Bold Font <- Control \020 Control Font <- Control \021 Translation <- Control \022 National <- Control \023 Sessions <- File \024 5250 \025 Documents <- File \026 Set Attributes <- IBM \027 SSH \028 New <- File ___________________________________________________ ________________________________________________________________