Using AppleScript with MacToPic Plus

Introduction

MacToPic + version 8.0 or later supports AppleScript commands. Many functions of MacToPic + can be controlled by a script (such as transferring data to and from the host, sending commands to the host and messages to the MacToPic + user.) Scripts 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

AppleScript, Script Editor, MacOS 7.0 or later, MacToPic + 8.0 or later.
AppleScript and the Script Editor are included with the MacOS.
There should be an AppleScript extension in your Extensions Folder inside of the System Folder.

Scripting Additions
There should be a folder in your Extensions Folder called Scripting Additions. The following scripting additions are used by the MacToPic + sample scripts:
Beep, Display Dialog, File Commands, Run Script, String Commands and Scripting Components.
All of these scripting additions should be included with the MacOS.

Optional Reference Material

Danny Goodman's AppleScript Handbook.
AppleScript Developer's Kit including FaceSpan interface builder.
Both are available from APDA at 800 282-2732.

Some Internet AppleScript Sites as of 1/17/02

MacScripter

ScriptWeb.

Apple's AppleScript Web site

AppleScript Sourcebook


MacToPic + Sample Scripts

Carnation Software provides many sample scripts to get you started programming your own scripts. They are located in a folder on your Sample Programs floppy disk. If you obtained MacToPic + 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 "MacToPic + "
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. These options are set in the File Sharing Control Panels (Sharing Setup & Users and Groups). MacToPic + must also be running on the remote machine and have sharing and program linking enabled (you cannot launch an application on a remote Mac with AppleScript).


tell application "MacToPic + " 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 MacToPic + understands. To see a list of the commands that are specific to
MacToPic + , run the Script Editor and select "Open Dictionary..." from the File Menu and open the MacToPic + program.

Running AppleScripts from the Special Menu in MacToPic +

Once you have created a script, you can run it directly from MacToPic + 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. Most of the sample scripts provided by Carnation Software cannot be run from this menu since they have not been compiled into an application yet (since they are waiting to be customized by you).

"Run AppleScript" looks inside of a folder called "AppleScripts" for compiled scripts to run. This folder is inside of the MacToPic + folder. Make sure you put all of your compiled scripts into this folder for easy access. Also, to make sure that this is the default folder, the option in the General Control Panel for opening documents needs to be set to "Folder that is set by the Application"

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 Map 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 5" is a script that takes data that was lassoed from the MacToPic + screen and copies it into columns and rows of an Excel spreadsheet.
This script uses another script called "CarnationToExcel" that must be located in your System Extensions folder. It will only work with Microsoft Excel version 5 or later.

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

NOTE:
All of the following clipboard commands affect the clipboard of the Mac that is running
MacToPic + (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 UseResult "Use this result string"

Reply from MacToPic + : None
Reference Sample Script: Append to Clipboard

Takes the result from the last MacToPic + AppleScript command and appends it to the clipboard without erasing the contents of the clipboard. The UseResult paramater is optional and tells MacToPic + 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 MacToPic + : 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 MacToPic + : Contains the current capture file name including the path.
Or:
Error! File is open from another application."
Reference Sample Script: Capture On/Off



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


ClipboardRecordOff : Turns clipboard recording off.
ClipboardRecordOff

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


ClipboardRecordOn : Turns clipboard recording on.
ClipboardRecordOn

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


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

Example: CopyResultToClipboard
Reply from MacToPic + : None
Reference Sample Script: Copy to Clipboard

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


CopyScreenToClipboard : Copy the entire MacToPic Plus screen to the clipboard as text.
CopyScreenToClipboard

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

Reply from MacToPic + : 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 MacToPic + : 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 MacToPic + : The row position number
Reference Sample Script: Cursor Position Test


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

Example: DeleteCaptureFile
Reply from MacToPic + : 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 MacToPic + : 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 MacToPic + : The data from row 0, from column 5 to 79
Reference Sample Script: Get Screen Data
Get 10 Rows of Data


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 MacToPic + : 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.
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.

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

Reply from MacToPic + : 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.
MacToHostTransfer string
Result: string

Example: HostToMacTransfer "MyFile"
Reply from MacToPic + : 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 MacToPic + is running on.
Paste

Example: Paste
Reply from MacToPic + : None
Reference Sample Script: None


ProcessCharacters : Gets and Processes incoming characters from the host. This is normally not necessary but if you think your script is not working because all characters expected from the host have not been processed (displayed or used to perform some function) then use this command. When in the CommToolBox mode, this command processes a maximum of 256 characters per ProcessCharacters command. When in the non-CommToolBox mode, all characters in the incoming buffer will be processed.

ProcessCharacters

Example: ProcessCharacters
Reply from MacToPic + : None
Reference Sample Script: None


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

Example: SetCaptureFile "MyCaptureFile"
Reply from MacToPic + : 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 MacToPic Plus if the data transfer is done.
TransferDone
Result: string

Example: TransferDone
Reply from MacToPic + : "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 MacToPic + : None
Reference Sample Script: Special Commands


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

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


Escape :
Escape

Example: Escape
Reply from MacToPic + : None
Reference Sample Script: Special Commands


Tab : Sends a Tab to the host
Tab

Example: Tab
Reply from MacToPic + : None
Reference Sample Script: Special Commands


CommToolBox: Commands for the CommToolBox

CloseConnection : Close the CommToolBox connection
CloseConnection

Example: CloseConnection
Reply from MacToPic + : None
Reference Sample Script: CommToolBox Tests


CommToolBoxInUse : Ask if CommToolBox is in use (UseCommToolBox is checked in
MacToPic + ).
CommToolBoxInUse
Result: string

Example: CommToolBoxInUse
Reply from MacToPic + : "Yes" or "No"
Reference Sample Script: CommToolBox Tests


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

Example: ConnectionOpen
Reply from MacToPic + : "Yes" or "No"
Reference Sample Script: CommToolBox Tests

ConnectionTool : CommToolBox connection tool in use. Result is the name of the tool.

ConnectionTool
Result: string

Example: ConnectionTool
Reply from MacToPic + : Name of the connection tool in use
Or:
CommToolBox not in use
Reference Sample Script: CommToolBox Tests

FileTransferTool : CommToolBox file transfer tool in use. Result is the name of the tool.

FileTransferTool
Result: string

Example: FileTransferTool
Reply from MacToPic + : Name of the file transfer tool in use
Or:
CommToolBox not in use
Reference Sample Script: CommToolBox Tests

OpenConnection : Open the CommToolBox Connection
If the connection is already open then command is ignored.
If the CommToolBox is not in use then the command is ignored.

OpenConnection

Example: OpenConnection
Reply from MacToPic + : None
Reference Sample Script: CommToolBox Tests

Back to the Main AppleScript Page

Back to Carnation Home Page