Scripting Panorama X with AppleScript

Using the `run code` command, Panorama code can be embedded into AppleScript code, allowing Panorama to be automated from other applications. Here is an AppleScript that makes Panorama the frontmost application, opens the Checkbook database in the Documents folder, and adds a new record.

    tell application "PanoramaX"
        activate
        run code "openfile {~/Documents/Checkbook} addrecord"
    end tell

This short example illustrates several important points. First of all, if you want Panorama to be the frontmost application, you must use the `activate` command. Otherwise Panorama will remain in the background.

Secondly, the Panorama code you want to run must be enclosed in double quote characters. This means that you cannot use the double quote characters for text constants in this code. Instead you can use { and } characters (as shown above), pipe characters, or smart quotes. See Quotes to learn how to use these different types of quotes. Or, you can prefix the quote characters with a backslash, like this:

    tell application "PanoramaX"
        activate
        run code "openfile "~/Documents/Checkbook" addrecord"
    end tell

The final point that this example illustrates is that you generally can’t make any assumptions about what state Panorama is in when the AppleScript code runs. Is the database you want to use the frontmost window, or even open? You can’t rely on that. To avoid unpleasant surprises, or errors, your code should usually start with statements that make sure that Panorama is in the state you want – that the database you need is open, the form you want is open, etc. Here’s an example of code that does not do that.

    tell application "PanoramaX"
        activate
        run code "deleterecord"
    end tell

This AppleScript will delete the current record of whatever database happens to be on top. Don’t write code like this!

#### Returning a Value to AppleScript

Use the SetAppleEventValue statement to return a value from Panorama to the AppleScript. This AppleScript finds out the number of selected records in the current database and displays that in a dialog.

    tell application "PanoramaX"
        set recordCount to run code "setappleeventvalue info({selected})"
    end tell
    display dialog recordCount

Working with Lists

One of AppleScript’s powerful features is the List data type. Panorama does not directly support the list data type, but you can easily convert between Panorama text arrays and lists, and back again.

Here is an example that transfers a text array to an AppleScript variable and then converts that variable into a list.

    tell application "PanoramaX"
        set databaseFields to run code "setappleeventvalue dbinfo({fields},{})"
    end tell
    set AppleScript's text item delimiters to return
    set databaseFields to every text item of databaseFields

This can be rearranged into a simpler version:

    tell application "PanoramaX"
        set AppleScript's text item delimiters to return
        set databaseFields to every text item of (run code "setappleeventvalue dbinfo({fields},{})")
    end tell

#### Error Handling

Usually when an error occurs in a Panorama program, Panorama stops and displays an alert. If the program is embedded in an AppleScript, however, this does not happen. Instead, the error is returned back to AppleScript.

If you don’t want the error to propagate back to AppleScript, use if error, try/catch or onerror to trap and handle the error in Panorama. See Error Handling to learn more about these techniques.

#### Calling a Subroutine

You don’t need to include all of the code you need to run in the AppleScript itself, instead you can use the call or farcall statements to invoke procedures you have already put in the database. This example opens a checkbook database (or brings it to the front if it is already open) and calls the ExportLastMonth procedure.

    tell application "PanoramaX"
        activate
        run code "openfile "~/Documents/Checkbook" call ExportLastMonth"
    end tell

If you know a database is already open, you can use the farcall statement to invoke subroutines in that database without first bringing that database to the front, like this:

    tell application "PanoramaX"
        run code "farcall {Checkbook},ExportLastMonth"
    end tell

A potential problem with this technique is that the ExportLastMonth subroutine may rely on the Checkbook database being the topmost database – in fact it probably does rely on that. If it is not currently the topmost database, errors will occur (since the correct fields are not available, etc.) You can fix this by adding the topdatawindow statement to the top of any procedure that is called by farcall, as shown here:

    topdatawindow info("proceduredatabase")
    ...
    ... rest of procedure
    ...

Or, if you need the database to be active but not necessarily visible, you can use the setactivedatabase statement.

    setactivedatabase info("proceduredatabase")
    ...
    ... rest of procedure
    ...

By the way, the info(“proceduredatabase”) function returns the name of the database that contains the procedure code, even if that isn’t currently the active database.

See Also

- applescriptconstant( -- converts an expression into an AppleScript literal.
- applescriptstring( -- converts text into an AppleScript string literal.
- arraytopythonlist( -- converts a Panorama array into a Python list.
- hideotherapplications -- hides all other applications, leaving only Panorama visible.
- javascriptconstant( -- converts an expression into a JavaScript literal.
- javascriptstring( -- converts a text string into a JavaScript string
- jsonscriptstring( -- converts text into a JSON string literal
- loadcustomfunctions -- reloads all ProVUE defined custom functions.
- openanything -- opens a document or application.
- openurl -- opens a URL (usually a web page or to create an e-mail message).
- openurlinbackground -- opens a URL (usually a web page or to create an e-mail message) without bringing forward the app that handles the URL (in other words, Panorama remains the frontmost application).
- openwith -- opens a document with a specific application.
- openwithterminal -- opens an application in a new Terminal.app window (useful for debugging).
- perlconstant( -- encodes text for use as a constant in a Perl program.
- perlscriptstring( -- converts text into a Perl string literal.
- phpconstant( -- encodes text for use as a contant in a php program.
- posixpath( -- converts a path and filename into a POSIX path that can be used as a parameter to a shell command.
- pythonconstant( -- encodes text for use as a constant in a python program.
- registercustomfunction -- defines a new custom function.
- revealinfinder -- reveals a file or folder in the Finder.
- revealmultipleinfinder -- reveals one or more files or folders in the Finder.
- rubyconstant( -- encodes a value for use as a constant in a Ruby program.
- runningappinfo( -- returns information about applications that are currently running on this computer.
- setappleeventvalue -- may be used in a procedure that responds to an AppleEvent (this includes AppleScript programs), the statement specifies the value to be returned by the event.
- shellscriptwithterminal -- runs a shell script in a new Terminal.app window (useful for debugging).
- unixshellpath( -- converts a path and filename into a POSIX path that can be embedded within the shellscript statement.
- unixshellstring( -- encodes text for use as a parameter to a unix shell command.

History

Version | Status | Notes
10.1 | New | New in this version.