5. AppleScript ________________________________________________________________ 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 AppleScript with dataComet Sample AppleScript Copy and Paste Executing an AppleScript dataComet's AppleScript Suites Required Suite URL Suite dataComet Custom Suite Mandarin Suite "status" report format ___________________________________________________ Using AppleScript with dataComet ___________________________________________________ dataComet supports AppleScript commands which allow the user to control dataComet through scripts. All dataComet macro functions are accessible through the "execute" event, which submits a macro string to dataComet for execution by the target window. Currently AppleScript recording is not supported by dataComet. You can, however, record a dataComet macro using "Record macro..." and then use the results in an execute command. Note that '\' characters in the macro commands must be doubled ("\\") in order to prevent your AppleScript Script Editor application from interpreting them as special characters. If you want to your script to cause dataComet to quit, use the AppleScript "quit" command rather than a dataComet macro, so that dataComet can handle the Quit case properly by returning a value to the calling script indicating the command has been completed prior to actually executing the Quit command. See "Sample AppleScript" in the Extras folder for an example script which opens a session with a UNIX host, executes a command, copies the command output, and closes the window. This example includes a number of useful script routines. ___________________________________________________ Sample AppleScript Copy and Paste ___________________________________________________ global copyresult set copyresult to "" tell application "dataComet" execute "!WSYourWindowName\\000!Ce" -- Select a window by name; -- "!Ce" guarantees the emulator is in front, -- rather than the session's .edit window. execute "!S\\000!T\\000!U\\003!V\\000" -- Select the first 3 lines in the emulator screen. copy end tell set copyresult to the result -- copy the result of the dataComet copy; -- NOTE: this must be immediately after the "copy" command -- in the "tell" statement to work correctly in the -- background! doedit(copyresult) return -- paste text into a new Scriptable Text Editor window on doedit(edittext) tell application "Scriptable Text Editor" activate set the clipboard to edittext make window paste end tell end doedit ___________________________________________________ The AppleScript dataComet "copy" command waits for up to 45 seconds for dataComet macros executing in the frontmost session to be completed before copying the window selection to try to guarantee that select/copy macro scripts will work smoothly. NOTE that during this wait all applications on your Macintosh will have to wait for the loop to complete; if you're using a complicated macro to display and select text, it's best to check whether the "status" of a session contains "Executing" before performing a copy; this way you can be absolutely certain that complex selection macros will copy the selection you really want. (See "Sample AppleScript" for an example using the "status" command.) More sample script snippets which might be useful... ___________________________________________________ -- note that some Applescript variables may need to be -- coerced to "text"; otherwise it will abort the script -- with the error message "incorrect data type" send (thisorderedlist as text) -- This is a sample prompt line. -- Note that in an "execute" command you need to use -- a "!!" to sends a "!" to the host. execute "!qzThis is a 25th line prompt!!!qz" -- This clears the prompt line. execute "!qz!qz" -- uploadtext(copyresult, "uploadtext.txt") -- uploads an AppleScript text object via a UNIX cat -- command. -- Note that 8-bit characters won't pass unless the host -- is set to read them (see "UNIX connections" in -- "1. Emulators"). on uploadtext(thetext, filename) tell application "dataComet" send "cat >" & filename & " <<'###EOF###'" & return send thetext send return & "'###EOF###'" & return end tell end cat ___________________________________________________ ___________________________________________________ Executing an AppleScript ___________________________________________________ Save the script as an "Application" with "Never show startup screen" checked. To easily execute the script from dataComet, first place the script (called, say, "PrintBarcode") in the System "Apple Menu Items" folder. You can then set a dataComet button or key to execute a dataComet macro of the form "!m\000\127\127PrintBarcode\000". ___________________________________________________ dataComet's AppleScript Suites ___________________________________________________ _____________________________________________ Required Suite Events that every application should support _____________________________________________ open: Open the specified object(s) open alias -- list of objects to open print: Print the specified object(s) print alias -- list of objects to print quit: Quit application quit run: Sent to an application when it is double-clicked run _____________________________________________ URL Suite Standard Suite for Uniform Resource Locators _____________________________________________ geturl: opens a Telnet connection specified by a URL geturl string -- a Telnet URL Result: small integer -- result code _____________________________________________ dataComet Custom Suite Suite of AppleEvents for interfacing to dataComet _____________________________________________ targetwindow: sets the window to use as a target targetwindow string -- optional window name, -- default front Result: small integer -- result code If the targetwindow is not specified in a script, the frontmost window is used as the target for the following commands. You can use the argument "frontwindow" to reset the target window for a script to whichever window happens to be frontmost. status: returns status for the target window status Result: string -- text description of status send: sends text to the target window send string -- text to send Result: small integer -- result code execute: executes a string as a dataComet macro execute string -- a dataComet macro Result: small integer -- result code cut: cuts the selection in the target window cut Result: string -- the cut text copy: copies the selection in the target window copy string -- optional string overrides selection Result: string -- copied text paste: pastes into the target window at the cursor position paste string -- optional string sets clipboard -- before paste Result: small integer -- result code ___________________________________________________ ___________________________________________________ "status" report format ___________________________________________________ The status inquiry returns a string containing a list of tab-delimited strings which can help in monitoring the status of the frontmost session. The string may contain the following names and status indications: "WindowName LineCount CharCount SessionType TermType NewData ConnectionStatus 3270Status MacroStatus". You can use the MacroStatus returned by the "status" call to synchronize scripts by using a '!Z' or '!z' macro at the end of an "execute" call to guarantee that the host has sent an indication that its output is complete (this is application-dependent, since you must rely how the host application draws its screens). E.g., you might receive the following status reports: "\"fedworld.gov\"85768560 TelnetANSI.SYS NewDataClosed" or "\"Scratch Pad\"22186EditOnly". _____________________________________________ WindowName: Window name: ".edit" will be appended if a session's .edit window is in front. LineCount: Count of lines in window CharCount: Count of characters in window SessionType: Session type: "EditOnly" "Telnet" "Serial" TermType: Session terminal type: "VT100" "VT102" "VT220" "H19" "ANSI.SYS" "IBM-3278-" NewData: Session has received new data: "" "NoData" "NewData" ConnectionStatus: Session connection status: "" "Opening" "Connected" "Closing" "Closed" 3270Status: Session status for IBM 3270 session: "" "Running" "MORE" "VM Read" "CP Read", "Holding" MacroStatus: Macro execution status "Waiting" "Executing" _____________________________________________ ___________________________________________________ ________________________________________________________________