MacWise - Macintosh Terminal Emulation - telnet / serial for OS X - Wyse, Viewpoint, VT100, VT220


Using AppleScript with MacWise

Introduction

MacWise version 10.5 or later supports AppleScript commands. Many functions of MacWise can be controlled by a script (such as transferring data to and from the host, sending commands to the host and messages to the MacWise user.) Scripts compiled as applications can be run from "Run AppleScript" under the Special Menu. For instance, you can write a script to transfer data from the host to a file on your Macintosh and then tell another application to open that file.

What You Need

Mac OS X which includes AppleScript and Script Editor

Optional Reference Material

Danny Goodman's AppleScript Handbook.

AppleScript Studio - Write applications with sophisticated user interfaces. (Included with the developer's CD that comes with OS X).

Some Internet AppleScript Sites...

http://www.applescript.apple.com/
http://www.scriptweb.com/

MacWise Sample Scripts

Carnation Software provides many sample scripts to get you started programming your own scripts. They are located in a folder called MacWise Sample AppleScripts. If you obtained MacWise from the Internet, the Script Samples will also be included.
These scripts have been created with Apple's Script Editor. You can modify them to suit your needs.

Apple's Script Editor

The Script Editor is included with the MacOS. Carnation Software does not provide any documentation for the editor. The best thing to do first is load in one of the sample scripts provided by Carnation Software and see how it works. It is very logical and easy to learn. A script looks like this:

tell application "MacWise"
activate
SendUserMessage "Hello from AppleScript"
end tell

Remote Scripts

If you are running your script from a remote Macintosh, you must specify the Macintosh that you want to send the command to. You must also have file sharing and program linking turned on. Also, the user must have program linking enabled. MacWise must also be running on the remote machine and have sharing and program linking enabled (you cannot launch MacWise on a remote Mac with an AppleScript command because it loads the program into the Mac you are running the script from). The remote Mac needs to be running MacWise version 10.5 or later.

tell application "MacWise" of machine "Linda's Mac"
activate
SendUserMessage "Hello from AppleScript"
end tell

Commands inside of the tell loop can be a combination of commands that AppleScript understands and commands that only MacWise understands. To see a list of the commands that are specific to
MacWise, run the Script Editor and select "Open Dictionary..." from the File Menu and open the MacWise program.

Running AppleScripts from the Special Menu in MacWise

Once you have created a script, you can run it directly from MacWise by selecting "Run AppleScript" from the Special Menu. Only scripts that have been saved from the Script Editor as an Application can be run from this menu. The sample scripts provided by Carnation Software cannot be run from this menu until you save them as a an application using the Script Editor.
"Run AppleScript" looks inside of a folder called "AppleScripts" for compiled scripts to run. This folder is inside of the MacWise folder. Make sure you put all of your compiled scripts into this folder for easy access.

There are some scripts provided that have been compiled into an application:

The "Carnation Time Zone" script. is a handy script that tells you the difference in time between your location and Carnation Software. Good to know if you want to make a call early in the morning and we are not open yet. Your Date & Time Control Panel has to be set correctly to your location for this to work properly. The source code for the script is also provided.

"Screen Selection to Excel" is a script that takes data that was lassoed from the MacWise screen and copies it into columns and rows of an Excel spreadsheet.
This script uses another script called "MacWiseToExcel" that must be located in your MacWise Prefs folder. It will only work with Microsoft Excel version 5 or later.

The "Copy Screen to Clipboard" script copies the entire contents of your MacWise screen to the clipboard.

Running AppleScripts from a Host Basic Program

You can send an escape sequence from the host computer to MacWise to run an AppleScript.
A compiled AppleScript must be in the AppleScripts folder inside of the MacWise folder.
The sequence is "ESC tilde a tilde AppleScriptName"
The following example shows how to do it from a host Basic program:

PRINT CHAR(27):"~a~Carnation Time Zone"

 

The MacWise AppleScript Dictionary

The AppleScript commands below are special commands that MacWise understands. You can use "Open Dictionary..." in the Script Editor to see these commands. However, a more detailed description of the commands follows:

Each dictionary description has the dictionary terminology and an example of how to use the command. A Reference to a sample script is also included. The sample scripts are included
with MacWise.

Messages: Send Message to MacWise

SendHostMessage: Send a Message to the host Computer.
SendHostMessage string
Result: string

Example: SendHostMessage "LIST BP"
Reply from MacWise : "Message sent to host"
Reference Sample Script: Send host Message

SendUserMessage: Send a message to the user on the message line.
SendUserMessage string

Example: SendUserMessage "Hello"
Reply from MacWise : None
Reference Sample Script: Send User Message

Dialing: Commands for Dialing a Modem

Hangup: Hangup the modem connection
Hangup

Example: Hangup
Reply from MacWise : None
Reference Sample Script: None

QuickDial: Dial the QuickDial number
QuickDial

Example: QuickDial
Reply from MacWise : None
Reference Sample Script: QuickDial

 

Required Events: Required Apple Events

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

Data Transfer: Transfer data to and from MacWise

NOTE:
All of the following clipboard commands affect the clipboard of the Mac that is running
MacWise (not the clipboard of a remote Mac the script is being run from)

AppendResultToClipboard: Append the AppleScript result to the clipboard without clearing it.
AppendResultToClipboard
[UseResult]

Example: AppendResultToClipboard or
AppendResultToClipboard "Use this result string"

Reply from MacWise : None
Reference Sample Script: Append to Clipboard

Takes the result from the last MacWise AppleScript command and appends it to the clipboard without erasing the contents of the clipboard. The UseResult paramater is optional and tells
MacWise to use this text to append to the clipboard instead of the last result.

CaptureOff: Turn off capture mode and close the capture file.
CaptureOff

Example: CaptureOff
Reply from MacWise : None
Reference Sample Script: Capture On/Off

 

CaptureOn: Turn on capture mode to send data to the capture file. Reply with capture file name.
CaptureOn
Result: string

Example: CaptureOn
Reply from MacWise : Contains the current capture file name including the path.

Reference Sample Script: Capture On/Off

 

ClearClipboard: Clear the Clipboard.
Example: ClearClipboard
Reply from MacWise : None
Reference Sample Script: None

ClipboardRecordOff: Turns clipboard recording off.
ClipboardRecordOff

Example: ClipboardRecordOff
Reply from MacWise : None
Reference Sample Script: Record to Clipboard

ClipboardRecordOn: Turns clipboard recording on.
ClipboardRecordOn

Example: ClipboardRecordOn
Reply from MacWise : None
Reference Sample Script: Record to Clipboard

CopyResultToClipboard: Copies the AppleScript result to the Clipboard, clearing the clipboard first.
CopyResultToClipboard
[UseResult]

Example: CopyResultToClipboard
or
CopyResultToClipboard UseResult "Use this result string"

Reply from MacWise : None
Reference Sample Script: Copy to Clipboard

Takes the result from the last MacWise AppleScript command and copies it to the clipboard, erasing the contents of the clipboard first. The UseResult paramater is optional and tells MacWise to use this text to append to the clipboard instead of the last result.

 

CopyScreenToClipboard: Copy the entire MacWise screen to the clipboard as text.
CopyScreenToClipboard

Example: CopyScreenToClipboard
Reply from MacWise : None
Reference Sample Script: Copy Screen to Clipboard

CursorColPosition:Get the current column position of the cursor. Note: Columns start at zero ( 0-204 )
CursorColPosition
Result: small integer

Example: CursorColPosition
Reply from MacWise : The column position number
Reference Sample Script: Cursor Position Test

CursorRowPosition: Get the current row position of the cursor. Note: Rows start at zero ( 0-70 )
CursorRowPosition
Result: small integer

Example: CursorRowPosition
Reply from MacWise : The row position number
Reference Sample Script: Cursor Position Test

DataReceivedFromHost: Asks MacWise if any data has been received from the host since the last time we asked.
DataReceivedFromHost
Result: string

Example: DataReceivedFromHost
Reply from MacWise : Yes (when data has been received)
Or:
No (when data has not been received)
Reference Sample Script: Business Card Reader

DeleteCaptureFile: Deletes the current capture file. Use SetCaptureFile to create a new one.
DeleteCaptureFile
Result: string

Example: DeleteCaptureFile
Reply from MacWise : The name and path of the file deleted
Or:
Cannot Delete file when capture is on
Reference Sample Script: Delete Capture File

 

GetCaptureFile: Gets the name of the current capture file.
GetCaptureFile
Result: string

Example: GetCaptureFile
Reply from MacWise : The name and path of the capture file.
Reference Sample Script: None

GetScreenData: Get data from the screen, specifying the row, starting column and ending column. Note: Rows start at zero ( 0-70 )
GetScreenData
Row small integer
ColStart small integer
ColEnd small integer
Result: string

Example: GetScreenData
Row 0
ColStart 5
ColEnd 79

Reply from MacWise : The data from row 0, from column 5 to 79
Reference Sample Script: Get Screen Data
Get 10 Rows of Data

line: Get a line from the screen, specifying the line. Note that lines start with line 1.
line
Result: string

Example: line 1
Or
Word 1 of (line 1)

Reply from MacWise : The data from the line on the screen
Reference Sample Script: Get a line

HostToMacTransfer: Starts a Host To Mac data transfer with operator intervention. You provide the host command.
HostToMacTransfer string
Result: string

Example: HostToMacTransfer "LIST-CUSTOMERS"
Reply from MacWise : The file name selected by the user.
Or:
User Canceled
Reference Sample Script: HostToMac Transfer

HostToMacXfer: Starts a Host To Mac data transfer without operator intervention.
(this command has not yet been implemented in MacWise. Let us know if you need it).
You provide the host command, filename and other options that the user would normally enter into the Host-To-Mac Transfer window. Commands that are in [brackets] are optional and are set to a default setting if not specified.

HostToMacXfer

HostCommand string -- The command to send to the host to start the data transfer. If Convert is Yes then HostCommand needs to bring data to the Mac in a Labels format. Usually the HostCommand is a PROC name and the PROC uses LIST-LABEL.

FileName string -- The file name on the Mac where the data will be transferred to.

Convert string -- If Convert = Yes then tabs will be inserted (Convert to Spreadsheet/Database format)

[FieldsPerRecord small integer] -- The number of fields in each record being transferred.
Default: 0

[OverWrite string] -- If OverWrite = Yes then FileName will write over the existing file.
Default: "No"

[LinesToSkip small integer] -- Number of lines to skip before recording data (1 minimum)
Default: 1

[TimeOut small integer] -- Time in seconds to wait and end of transfer.
Default: 5

[NoPage string] -- If NoPage = Yes then (N is sent after HostCommand to the host.
Default: "Yes"

Result: string -- Result will be the name of the capture file including path. Any problems will be reported as Error! followed by a description of the error.

Example:
Note: This script has to be all on one line or a continuation character ¬ must be used.

HostToMacXfer HostCommand "CUSTOMERS" FileName "MyFirstXfer" Convert "Yes"
FieldsPerRecord 5 OverWrite "Yes" LinesToSkip 1 TimeOut 5 NoPage "No"

Reply from MacWise : The file name provided by the script and the path
Or:
Error! Host Command required
Error! File name required
Error! File Exists and OverWrite = No
Error! Must specify FieldsPerRecord when Convert = Yes
Error! Must enable Xon/Xoff or lower baud rate to 1200
Error! Connection is not open

Reference Sample Script: HostToMacXfer

 

MacToHostTransfer: Transfer a file from the Mac to the host computer.
(This command has not been implemented yet. Let Carnation Software know if you need it)

If the file name is supplied in "theFile" then it will be used. If theFile is blank then MacWise will
prompt the user for a file name.
MacToHostTransfer string
Result: string

Example: HostToMacTransfer "theFile"
Reply from MacWise : The file name selected by the user.
Or:
Invalid file name supplied by AppleScript
Reference Sample Script: MacToHost Transfer

Paste: Paste the contents of the clipboard to the host computer. This is the clipboard on the computer that MacWise is running on.
Paste

Example: Paste
Reply from MacWise : None
Reference Sample Script: None

 

SetCaptureFile: Sets the capture file to the name specified The file will be created in the MacWise Prefs folder unless a full path is specified.
SetCaptureFile string
Result: string

Example: SetCaptureFile "MyCaptureFile"
Reply from MacWise : The file name and path of the new capture file.
Or:
Error! Incorrect path name supplied from AppleScript.
Or:
Error! Cannot use this file for a capture file.
Reference Sample Script: Set Capture File Name

TransferDone: Asks MacWise if the data transfer is done.
TransferDone
Result: string

Example: TransferDone
Reply from MacWise : "Yes" or "No"
Reference Sample Script: HostToMac Transfer

Special Commands: Send Special Commands to the Host such as Break, Escape etc...

Break:
Break

Example: Break
Reply from MacWise : None
Reference Sample Script: Special Commands

Control: Send a control character to the host. Example: Control "X"
Control string

Example: Control "X"
Reply from MacWise : None
Reference Sample Script: Special Commands

Escape:
Escape

Example: Escape
Reply from MacWise : None
Reference Sample Script: Special Commands

Tab: Sends a Tab to the host
Tab

Example: Tab
Reply from MacWise : None
Reference Sample Script: Special Commands

Wait: MacWise will wait for n seconds before processing the next command.
Wait small Integer

Example: Wait 1
Reply from MacWise : None
Reference Sample Script: None

Note: You can also use the "delay" command. Delay is built into AppleScript and will pause
the script. (the "Wait" command tells MacWise to pause).

Connection Commands:

CloseConnection: Close the connection
CloseConnection

Example: CloseConnection
Reply from MacWise : None

ConnectionOpen: Is the Connection open? Result is "Yes" if open and "No" if closed.
ConnectionOpen
Result: string

Example: ConnectionOpen
Reply from MacWise : "Yes" or "No"

ConnectionMethod: Connection method in use. Result is the name of the method

ConnectionMethod
Result: string

Example: ConnectionMethod
Reply from MacWise : telnet
Or:
modem
Reference Sample Script: Connection Tests

 

OpenConnection: Open the Connection
If the connection is already open then command is ignored.

OpenConnection

Example: OpenConnection
Reply from MacWise : None