Code

Programs are written in code. This topic explains the basics of the language that Panorama uses for programming code.

#### Statements

A program is simply a series of steps or actions. Panorama has a special name for these steps: statements. Each statement is simply a single step to be performed by the computer. Most statements start with a special word (sometimes called a command or keyword) that tells Panorama what the statement should do. Here are some examples of commonly used statements:

    SortUp
    Select
    Print
    Open

Panorama understands several hundred different keywords that perform a wide variety of operations. (By the way, Panorama statement keywords are case insensitive, so `sortup`, `SortUp` and `SORTUP` can be used interchangeably.)

#### Parameters

A statement may consist of a keyword all by itself, but many keywords also require additional options. These additional options are called parameters. For example, the `openfile` statement requires one additional parameter, the name of the database to be opened.

    openfile "My Database"

If a statement uses two or more parameters, each parameter is separated from the next by a comma. The `copyfile` statement has two parameters, the original path to a file and the destination path to which it is to be copied.

    copyfile "~/Documents/logo.png","~/Dropbox/newlogo.png"

Parameters don’t have to be simple values – any formula can used to calculate the parameter value. In some cases, the formula itself is the parameter. For example the `select` statement uses one parameter, the formula to be used to select data.

    select Price>200 and Item contains "chair"

#### Assignment

An assignment statement computes a value (text or numeric) and stores that value somewhere. Unlike every other statement, an assignment statement has no specific keyword that identifies the statement, instead, it is identified by the `=` symbol. Assignment statements always have the format shown below:

    <data storage location> = <formula>

The first part of the assignment statement is the data storage location. This is the final destination for the data that is being moved. In fact, usually the data storage location is simply called the destination of the assignment. The data storage location may be a variable, a field in the currently active record, or the clipboard.

The next part of the assignment statement is the equals symbol. This identifies this statement as an assignment statement.

After the equals symbol is the formula. The formula produces the data that will be stored in the data storage location. The formula may simply take a variable or field and pass it along, or it may process, calculate or filter the data before it passes it along to be stored in the data storage location.

Here‘s a simple assignment statement that takes the contents of B and moves it into A. After this statement is finished both A and B will contain the same value.

    A = B

More complicated assignment statements may combine multiple fields or variables, and they may process the data in some way. An assignment statement may also take a constant value and store it. Here are some examples:

    A=B*C
    Name=upper(myName)
    City="San Francisco"

In each case, the process is the same. First Panorama calculates the formula to produce a data value. Then it stores the data value in a data storage location.

#### Code Layout

Panorama is very flexible about how code is arranged. Each statement is separated from the next by whitespace. Whitespace is one or more blanks, carriage returns or comments. Unlike many other programming languages, there is no need for for a special separator between statements (no `;` or carriage return is needed between each step). You can also put whitespace between parameters (and also between tokens in formulas).

Here is an example of a simple program with seven steps:

    select Debit>0
    field Category
    groupup
    field Debit
    total
    outlinelevel 1

In the example above, each step is on a separate line. But that’s not necessary. If all of the steps are on a single line, the program is harder to read but will work exactly the same.

    select Debit>0 field Category groupup field Debit total outlinelevel 1

You can even split individual statements across multiple lines, as long as you don’t split a single word or constant in the middle. Here’s another version of this same program but split across 12 lines.

    select
    Debit
    >
    0
    field
    Category
    groupup
    field
    Debit
    total
    outlinelevel
    1

In general, we recommend using one statement per line for readability, but that is only a recommendation, not a requirement.

#### Statement Blocks

Some programming languages have a concept of a “statement block” where curly braces around multiple statements essentially combine them into a single statement. Here’s how this would work in the “C” programming language.

    if (Balance<0)
    {
        status="BLOCK";
        message("Warning, negative balance");
    }

Panorama doesn’t have statement blocks. Instead, Panorama requires a special statement at the end of each “block” of code. (You can also see that unlike “C”, Panorama doesn’t require `(` and `)` around conditional expressions, but it will ignore them if they are included.)

    if Balance<0
        status="BLOCK"
        message "Warning, negative balance"
    endif

This topic is discussed in more detail in Control Flow. (By the way, the indentation in the above example is optional. The entire block could even be put on one line if you want, as long as there is an `endif` statement at the end.)

#### Statements vs. Functions

In some programming languages, all actions are functions that can return a value and be used in formulas. In Panorama, however, statements and functions are distinct. In Panorama, a statement performs an action. A function, on the other hand, returns a value. You can’t use a function where Panorama is expecting a statement, and you can’t use a statement in a formula, where Panorama needs a value.

To illustrate this, consider the `message` statement.

    message "Warning, negative balance"

When used in a program, this statement displays an alert, like this.

But since `message` is a statement, not a function, it doesn’t return a value and you cannot use it in a formula. So this code will not work:

    x = message "Warning, negative balance"

and neither will this:

    x = message("Warning, negative balance")

On the other hand, consider the `sqr(` function, which calculates a square root. Since this is a function and returns a value, it’s perfectly fine to use it in a formula, for example with this assignment.

    x = sqr(7)

But the `sqr(` function cannot be used by itself. It’s not an action, so Panorama doesn’t know what to do with this:

    sqr(7)

The basic rule is, if a keyword ends with a (, it’s a function and returns a value, and can be used in formulas. If a keyword doesn’t end with a (, it’s a statement and it performs an action.

#### Debugging with Instrumentation

Code doesn’t always work the first time, and sometimes it can be difficult to understand what your code is actually doing. To assist with this, Panorama includes an instrumentation system that you can use to help understand what is really happening with your code and variables, and diagnose tricky problems. See Debug Instrumentation to learn more about this system.

See Also

- Accessing the Clipboard -- reading from and writing to the system's clipboard.
- Action Menu -- simple way to create your own menu items.
- Alerts -- displaying a variety of standard modal alerts.
- Automatic Field Code -- running a short program when data is entered into a field.
- Channels -- provide a standard way to interface with external resources (email servers, phones, web sites etc.)
- Coding with Debug Instrumentation -- modifying your code to generate debug instrumentation output.
- Control Flow -- making decisions about what code should be executed in response to changing conditions.
- copyindentedcode -- copies the selected code with 4 space indent (for pasting into the Panorama forum).
- Crash Proof Debug Instrumentation Monitoring -- real time crash-proof instrumentation monitoring
- Custom Dialogs -- creating custom dialogs using forms.
- Custom Menus -- creating custom menus, menu bars and pop-up menus (and customizing standard menus).
- Custom Statements -- creating your own custom statements that can be used in your code.
- Customizing Debug Instrumentation Coverage -- specifying what code is being debugged at the moment.
- Database Navigation & Editing -- using program code to navigate within a database, and to add and remove database records.
- Debug Instrumentation -- conditional logging of the internal state of Panorama program code.
- Debug Instrumentation Log Window -- dynamically monitor debug instrumentation output as your program runs.
- Debug Instrumentation Monitoring using an External Program -- monitoring debug instrumentation with an external program (Terminal.app, BBEdit.app).
- Debug Instrumentation Text File -- configuring and accessing the debug instrumentation log (text) file.
- Drag and Drop -- dragging data to and from a Panorama form.
- Generating & Analyzing HTML -- generating HTML code from data, and extracting data from structured HTML.
- Internet Access -- accessing information from web servers.
- Procedure Editor -- editing named procedures.
- Procedure Recorder -- recording database actions as code.
- Procedures -- basics of procedures for automation.
- Program Access to Databases -- using a program to create, open, import or export databases.
- Program Error Handling -- handling errors and exceptions that occur when a program is running.
- Programmable Database Administration -- using a program to access and/or modify the structure of a database.
- Programmable Form Management -- using a program to work with forms.
- Programmable Graphics -- using program code to create and modify graphic objects in a form.
- Programmable Outlines -- using a program to create and manipulate data outlines.
- Programmable Printing -- using program code to print reports, mailing labels, etc.
- Programmable Searching -- using program code to search and select data.
- Programmable Sorting -- using program code to sort a database.
- Programmable Text Export -- using a program to export text from a database.
- Programmable Window Management -- using a program to arrange windows.
- Programming Database Fields -- using a program to add and remove database fields.
- Recompiling Code -- recompiling code & formulas
- Recording Code Triggers in Debug Instrumentation -- the code triggers option automatically tracks whenever any code is triggered, whether from a menu, a button, or implicitly (for example when data is entered).
- Recording Control Flow in Debug Instrumentation -- configure debug instrumentation to automatically log when control flow is non-linear, for example a call, return, goto, etc.
- Scripting -- embedding scripting languages (AppleScript, shell scripts, Python, Ruby, PHP, Perl, etc.) into Panorama program code.
- Speech Programming -- using program code to convert data to speech (voice).
- Statements -- index of all statements available for use in Panorama procedures.
- Subroutines -- writing code that can be called from other code.
- Suppressing Display -- temporarily disabling display of changes in a program (to reduce "flickering" and increase performance).
- Timer Workshop -- provides a tool for monitoring timers and testing timer configurations.
- Timers -- executing recurring periodic background code at fixed intervals.
- Transforming Data -- using program code to modify data in bulk.
- Triggers -- finding out what event triggered the execution of program code.

History

Version | Status | Notes
10.0 | Updated | Carried over from Panorama 6.0.