Variables

A variable is a place in the computer where an item of data can be stored, kind of like a storage bin for a value. Variables may be explicitly created by procedure code, and they can also be automatically created by graphic objects. Most procedures will use one or more variables to hold and transfer data as the program runs. Use a variable whenever you need to store a single data item so that you can use it later. Unlike a field, the value variable doesn’t change as you move from record to record, or, in the case of a global variable, even when you move from database to database.

#### Variable Names

Just as a house is identified by its address, a variable is identified by its name. A street address tells you exactly how to find a house or business. It doesn’t tell you who or what is inside the house, however. Families may come and go, but the street address remains the same. In a similar way, a variable name identifies a place where data can be stored. The data may change, but the variable name remains the same.

Panorama allows any sequence of characters to be used as a variable name. However, if the variable name contains spaces or punctuation, or begins with any character except a letter or underscore, it must be surrounded by the chevron characters « and ». (Press Option-\ to create the « chevron character and Shift-Option-\ to create the » chevron character.) Here are some examples of typical variable names:

    X
    birthDay
    Counter
    «Tax Rate»
    «PrimeRate%»

A variable name must be spelled exactly the same way every time, including upper and lower case. The variable name birthDay is not the same as Birthday or birthday. In fact, you could create three different variables using these three different names (although this is not recommended because it would be very confusing).

By the way, it’s always ok to use chevrons around a variable name, even if the name doesn’t have any punctuation. «Counter» is exactly the same as Counter, and they can be used interchangeably. So if you have any doubts about whether or not chevrons are necessary, go ahead and use them. No harm, no foul.

#### What’s Inside A Variable?

By itself, a variable has no meaning, no value…until you put some data in it. When you use a variable in a formula or procedure, you are actually telling Panorama to use the contents of the variable.

A variable is sort of like a cup that you can pour anything into. A cup may contain water, soda, tea, or coffee. If you tell a person to drink the blue cup, what you really mean is to drink whatever liquid is in the blue cup. Each time they drink they may get a different liquid, depending on what the blue cup has been filled with.

Using a variable is similar. If you tell Panorama to calculate X+Y (where X and Y are variable names), what you really mean is “take whatever value is in X and whatever value is in Y and add them together.”

It’s important to remember that a variable name simply identifies the variable, but the name is not the variable itself. The name is like a placeholder for the real contents of the variable.

#### The Life Cycle of a Variable

A variable doesn’t just appear by magic. It must be created, just as you have to build a house before you can move in. Once the variable has been created it can be used for storing a data item. However, variables don’t last forever. Most variables eventually disappear without a trace. (You can also explicitly force a variable to disappear at any time — see the undefine statement.)

Panorama has five kinds of variables: local, window, fileglobal, global and permanent. The only difference between these types of variables is how long they last before disappearing and when the variables are available.

Local variables are the most short-lived. A local variable disappears when the procedure that created the variable is finished. In addition, a local variable can only be used by the procedure that created it. If proce- dure A calls procedure B as a subroutine, procedure B cannot access the local variables created by procedure A. In fact, procedure B could create its own local variables with the same names as the local variables created by procedure A. Panorama keeps the local variables for each procedure completely separate from each other. (Note: Local variables should never be used in a form.)

Window variables are associated with a particular window. A window variable is only accessible when the window it is associated with is on top, and the variable disappears completely when the window is closed. It is possible for several different windows to have window variables with the same name. In that case, each window variable may have a different value.

FileGlobal variables are associated with a particular database (file). A fileglobal variable is only accessible when the database it is associated with is the current database (on top), and the variable disappears completely when the file is closed. It is possible for several different files to have fileglobal variables with the same name. In that case, each fileglobal variable may have a different value. For many applications fileglobal variables are the best choice because there is no chance of an accidental conflict with a variable of the same name in another database.

Global variables are relatively long-lived. A global variable doesn’t disappear until you quit from Panorama. Even if you close the database, the global variable remains. Once a global variable has been created it can be accessed in any procedure, in any database or window, at any time. You should avoid using global variables unless you absolutely need universal access across databases for the value stored in the variable. If the value is only needed in one database it is much better to use a fileglobal variable to avoid the chance of an accidental conflict with another database using the same global variable name.

Permanent variables are almost immortal. When the database is saved, all permanent variables in that database are also saved. Like a fileglobal variable, a permanent variable is only accessible when the database it is created in is the current database, and a permanent variable disappears when you close the database. However, unlike a fileglobal variable, a permanent variable will re-appear like a phoenix from the ashes when you re-open the database. In fact, there are only two ways a permanent variable can permanently disappear. First, you can explicitly kill a permanent variable with the unpermanent statement. Secondly, you can create a permanent variable but never save the database.

#### Creating Variables in a Procedure

To create a local variable, use the let statement. This statement defines the name and initial value of the variable. (The spaces around the = symbol are optional.)

    let count = 1
    let myName = "Robert"

If the variable name contains punctuation, it must be surrounded by chevrons « and » like this:

    let «Home Timeouts» = 0
    let «Visitor Timeouts» = 0

There are four additional variations of the let statement: letwindowglobal, letfileglobal, letglobal, and letpermanent. Each of these statements is exactly the same except for the type of variable created.

    letfileglobal nextEvent = "Vuelta a Espana Stage 21"
    letpermanent raceLeader = "Chris Froome"

Each let statement creates a single variable. There is no limit to the number of local, global, and permanent statements you use in your programs, and no limit to the total number of variables.

The let statement (and the other four variations) can be used at any point in your program. Some programming languages require that all variables be defined at the top of the program, but Panorama allows variables to be defined anywhere.

#### Modifying the Value of a Variable

The let statement assigns an initial value for a variable, but that value can be modified at any time with an assignment statement:

    count = 5
    myName = "Maren"

You can also use another let statement to change the value of a variable. If you do, however, make sure that you use the same type of let statement each time. Don’t use more than one type, like this:

    let discountRate = 0.25
    letfileglobal discountRate = 0.1

This code actually creates two separate variables, a local variable and a fileglobal variable, both named discountRate. While the current procedure is running, the local variable has precedence, so the apparent discount rate will be 0.25. When the current procedure finishes, the local variable will vanish, so then the apparent discount rate will be 0.1. See Variable Name Conflicts below to learn more.

#### Creating Empty Variables

Sometimes you may want to create one or more variables without immediately assigning a value. This can be done with the local, windowglobal, fileglobal, global, and permanent statements. Each of these statements is exactly the same except for the type of variable created. The statement must be followed by a list of one or more variables to create, with each variable name separated from the next by a comma. (Remember: if a variable name contains punctuation, it must be surrounded by chevrons « and ».)

Here are a few examples of typical statements for creating empty variables:

    local counter,myName,beans
    fileglobal DNA,Channel,«Home Timeouts».«Visitor Timeouts»
    permanent myAreaCode

Creating a variable with these statements creates a place to store data, but it doesn’t actually put any data in the variable. It’s kind of like a new house that no one has moved into yet. If you try to access the variable before any data has been put into it, an error occurs. To use any of these variables, you must use an assignment statement to set the value, like this:

    local Count
    Count=0

(Of course in this example, it would be simpler to simply say `let Count=0`).

#### Re-Initializing a Variable Value

Sometimes you may not be sure if a variable has been initialized with a value yet. If it has not been, you want to initialize it. But if it has already been initialized, you don’t want to disturb the value that is already there. You can get around this problem with the define statement, as shown in this example.

    global AreaCode
    define AreaCode,"714"

If some other procedure has already defined a value for the AreaCode variable, the define statement does nothing. But if that hasn’t happened, define will set the value of the AreaCode variable to 714.

#### Variables and Data Types

A variable can hold any kind of data: text, numbers, and secondary data types like dates, times, points, rectangles, etc. In addition, you can change the type of data in a variable at any time. One minute the AreaCode variable can contain text, moments later it can contain a number. The variable takes on the data type of whatever data you assign to it.

#### Graphic Object Variables

Many graphic objects have the option of linking to a variable or a field. These include the Text Editor Object, Data Button Object, Popup Menu Button Object, Text List Object, Matrix Object Slider Object and Tab Panel Object. If one of these objects is linked to a variable and the variable does not exist, Panorama will automatically create a fileglobal variable when it opens the form, and initialize the variable to empty text. Except for how it was created, this fileglobal variable is just like any other fileglobal variable and can be used freely in procedures and formulas.

#### Variable Name Conflicts

If two database files define a global variable with the same name, you’ve got a conflict. It’s kind of like two families trying to share the same house. This can work if the two families have an arrangement, but if they don’t the result is chaos.

The best solution to this problem is to avoid it. If you can, use a fileglobal variable instead of a global variable. If this is not possible, stay away from simple global variable names like X, Payment, Count, etc. If possible, choose names that incorporate the database name (or an abbreviation of the name), for example Invoice, TaxRate, ReceivablesTotal, or APLastReconcileDate.

Variable names (even for local variables) can also conflict with fields in a database. In this battle, the variable always wins. Panorama will use the data in the variable instead of the data in the field. Avoid variable names that are the same as field names.

#### Permanent Variable Tips

When the permanent statement creates a permanent variable, it really creates two variables: one in memory and one in the current database. The one in memory is an ordinary fileglobal variable. Whenever the database is saved, Panorama copies the contents of the fileglobal variable into the copy of the variable in the database itself, then saves the database. Just like any other data, the contents of the permanent variable are not saved unless the database itself is saved. However, if you have not made any other changes to the database, Panorama will not warn you if you attempt to close a database without saving changes to the permanent variable.

Whenever a database is opened, Panorama automatically creates fileglobal variables for any permanent variables associated with that database. Next it copies the values from the database into the fileglobal variables. The variables are now ready to use.

If you ever want to make a permanent variable un-permanent, use the unpermanent statement, which is followed by a list of variables you want to make unpermanent. This statement doesn’t make the variables go away, but they will no longer be permanent. The unpermanent statement only affects variables that are permanent in the current database. The example below changes two permanent variables back into regular (non- permanent) fileglobal variables.

    unpermanent myAreaCode,myZipCode

See Also

- Arithmetic Formulas -- mathematical operators and functions.
- Characters and Unicode Values -- working with individual characters of text.
- Constants -- values embedded into a formula.
- convertvariablestoconstants -- converts all of the variables in a formula into constant values.
- Date Arithmetic Formulas -- performing calculations on dates, and converting between dates and text.
- Formula Workshop -- formula workshop wizard for testing and experimenting with formulas.
- formulacalc -- allows you to evaluate a formula that you were not able to code into the procedure when it was being written.
- formulafields( -- returns a list of fields used in a formula.
- formulaidentfiers( -- returns a list of identifiers (fields and variables) used in a formula.
- Formulas -- basics of formulas: components and grammar.
- formulavalue -- calculates the result of a formula. Usually this is done with an assignment statement (for example `x=2 * y` ), but the *formulavalue* statement gives you more flexibility. You can specify what database is to be used for the calculation (an assignment statement always uses the current database) and you can specify the formula using a variable, making it easy to change on the fly. This statement also gives you more control over how errors are handled.
- formulavariables( -- returns a list of variables used in a formula.
- Functions -- index of all functions available for use in Panorama formulas.
- Linking with Another Database -- techniques for relating multiple database files so that they work together.
- makemergeformula( -- builds a formula from an “auto-wrap" style merge template.
- Non Decimal Numbers -- working with numbers in alternative (non-decimal) bases, including binary, octal and hexadecimal.
- Numbers -- Working with numeric values in a formula, and converting between numbers and text.
- Operators -- index of all operators available for use in Panorama formulas.
- Quotes -- text constants embedded into a formula
- Recompiling Code -- recompiling code & formulas
- Statements -- index of all statements available for use in Panorama procedures.
- SuperDates -- date and time combined into a single value.
- Tag Parsing -- Panorama functions for working with text that contains data delimited by tags, including HTML.
- Text Formulas -- manipulating text with a formula (concatenation, extraction, rearranging, etc.)
- Time Arithmetic Formulas -- performing calculations on times, and converting between times and text.
- True/False Formulas -- logical boolean calculations.
- Using Fields in a Formula -- accessing database fields within a formula.
- Values -- the raw material that formulas work with -- numbers and text.

History

Version | Status | Notes
10.0 | No Change | Carried over from Panorama 6.0