Variables

The purpose of variables is to allow you to pass information back and forth between you and the computer. You can pass information from one command to another, for example.

Variables can be interrogated (IF), moved around (SET), used to calculate (CALC), or substituted into downstream commands ({ } "value of").

Variables are created with the SET, CALC, PROMPT, MENU, CHOOSE, LISTPICK, FETCH, CALENDAR, MOVE and TIMING commands. There are also five special variables, the "command answer cells," which are discussed further below.

Variable names are determined by you. The first character of a variable name must be a % (percent sign), the second character must be a letter. Names can be up to 12 characters in length.

You may not name a variable with any of the following "command answer cell" names as the commands themselves put data directly into them. Here we will list these special variable names, further below we will discuss them:

                Ctl.Ans1                                (this one can also be called %answer1)
                %answer2
                %answer3
                %status
                %level                                    (the first four names in this list are the command
                %usn                                      cells, these last two are special system variables)

Once a variable exists, it is global. It can be used in commands, Procedures, Reports, etc. Variables stay in existence when a database is closed, but are erased when you QUIT the session and return to the operating system. They can also be erased with the UNSET and UNCALC commands. Some examples of creating variables:

                set %name='Sue' 
                                -The variable %name is assigned the value Sue
                calc %nn=5
                                -The variable %nn is assigned the value 5
                calc %aa=%nn*2
                                -The variable %aa is assigned the value 10
                prompt %v Please enter name
                                -The value of %v becomes whatever the response was
                                to the prompt: "Please enter name"

The "value of"
Variables are used directly in CALC, SET and IF commands. The value of a variable can be substituted into any downstream command or statement. The notation to specify "the value of" a variable is to surround its name with braces { }. For example, the value of the variable %xx is indicated by {%xx}.

                set %name='Sue'
                                -Assigns the value Sue to %name

                message Hi There! My name is {%name}!
                                -Displays the message: Hi There! My name is Sue!

                find a where name={%name}
                                -Executes the command: Find a where name=Sue

                If %name='Mary'
                message YesYesYes
                else
                message NoNoNo
                endif      
                                -Displays the message: NoNoNo

                set %xx=%name!' Jones'
                                -Uses the connect operator (!) to attach the literal ' Jones'
                                to the existing %name and assign that to %xx

                find a where name="{%xx}"
                                -Executes: Find a where name="Sue Jones"


String and Numeric variables

The CALC command creates numeric variables and all of the other commands that create variables create string variables.

String variables can consist of anything and can be up to 4096 characters in length.

Numeric variables consist of numbers only and are kept internally as double precision floating point, allowing for 17 significant digits of precision. All calculations are done at full precision, how much of that precision that you see when it is time to display the value of a numeric variable is up to you. You can see more about this below in "viewing variables."

All variables in the variable pool are uniquely named, that is, you cannot have a string variable and a numeric variable with the same name. If the variable
%xx already exists as a string variable you cannot use it as the result of a CALC statement (you will get a diagnostic if you do). Note that is OK to use it as a term or a factor in a calculation, it just cannot be the result as the result of a CALC statement is always a numeric variable.


Viewing variables

All variables, both numeric and string, are kept in the variable pool. The content of the variable pool can be inspected with:

                The VLIST command

                By pressing the button on the tool bar

                Or, you can see the value of a specific variable: TYPE {%xx}

The VLIST command and the "View" button show the value of numeric variables out to 4 decimal places. The default for PRINT or TYPE statements will show the value with two decimal places when you do not specify a format
override.

For example, if %xx contains the value 12.1234567

                type {%xx}            -uses the default format of (9.2) so displays 12.12
                type {%xx(9.3)}    -displays 12.123
                type {%xx(9.5)}    -displays 12.12346 (note the rounding)
                type {%xx(9.7)}    -displays 12.1234567

                and VLIST will display 12.1235 (note the rounding)

When you use the "View" button the display is in a separate window. In this display all the string variables are delimited with a little x. The "x" is not part of the content of the variable, it is showing you where the variable ends so that you will know when your variable has low-order spaces in it. For example, if the little x is right after the final visible character you know that there are no low-order spaces in the content of your variable, but if you see some white space before you see the x you will know that there is trailing spaces.


Command answer cells

There are five special variables. They are the "command answer cells." These five have special names that you may not use when assigning your own variable names.

You cannot set values into them. The commands do that. But you may use them as you would use any other variable in SET, CALC, and IF statements.
And you can use the "value of" notation to substitute their value into the next command. They are:

                Ctl.Ans1                -The primary command answer (also known as %answer1)
                Ctl.Ans2                -Second answer for commands that have two answers
                Ctl.Ans3                -Third answer for commands that have three answers . Error messages also occur.
                %level                    -This cell is used and maintained by the report writer.
                                                When a report is active, %LEVEL always contains the
                                                hierarchical level number of the record just read.

The content of the answer cells depend on the command. For example, in a FIND command %answer always contains the number of records found. Each command description documents its own answers.

All commands put something into the answer cells unless told not to via the use of the Y option.

Since every command puts something into the answer cells this means that if you want to save this information for later use, you need to move it to a less volatile spot. To save more than one answer you must use the Y option:

                some command                     -Some command is executed and we desire to
                set/y %xx=Ctl.Ans1             save two of its answers for later use. The Y
                set/y %yy=Ctl.Ans2            option is used on the SET command in order to suppress SET from storing its own answers.
                                                                Thus %answer2 is still there by the time you get to it.

Here is a handy procedure that you might want to put into your own catalog. It consists of four TYPE statements:

                type/y ANSWER ={%answer}
                type/y ANSWER2={%answer2}
                type/y ANSWER3={%answer3}
                type/y STATUS ={%status}

Suppose, that when you define it, you name this procedure ANSWERS. Then anytime you want to inspect the current values in the answer cells just type ANSWERS.

To see an example of how command answers are used in your procedures, see "An Example of Creating a Procedure."


Super global variables

No program would be complete without at least one "Super" something.

There are times when you want to create a variable that is used in many places throughout your application so you don't want it easily erased with an
UNSET or UNCALC command.

For example, lets say every report in your system displays your company name, address, and so on. You set up some super global variables in your begin procedure (named APPLICATION) and all reports refer to those variables for the display of company information. These variables are permanently there, that is, they are not erased with simple usage of UNSET and/or UNCALC. So it will be easy for your application to maintain the variable pool, keeping it clean via the use of UNSET and UNCALC, and it will also be easy to change the setup if your company ever moves to a new location and all your reports will automatically adapt.

A super global variable name starts with two percent signs (%%), such as:

                set %%aa = 'super global'

You can have current variables named %%AA and %AA as these are different variable names. All variable names that start with two percent signs are "permanent." If you want to erase these, you must be explicit. See UNSET and UNCALC for more information.


The System Variable %USN

There is a system variable named %USN. This variable already exists - you do not define it. Its value is always the User Number assigned to you in this session when you OPENed the database.

An important use for this variable follows: Suppose that you do not have a local printer attached to your PC. Instead, you are routing reports to files and subsequently sending the files to system spooled printers.

The techniques to send a report to a file is either to use the "filename" argument on the REPORT command, or to use the "filename" argument on the PON command. In either case, what we are discussing here is the "filename" argument itself.

The problem in a multi-user environment is: What if several users who are all operating from the same directory are all executing the same procedure (which produces a given report) at the same time?

You want to make sure that each user's output filename is different. The thing to do is to append the %USN to the filename so that it can act to make the filenames unique. For example, the filename argument in the procedure would look like:
                filename{%usn}

So if the output file were named JACK, and you were user number 3, your output file would be named JACK3. And the output file name for user number 70 who is getting this report at the same time would be JACK70.