How To Use Variables

Variables provide complete flexibility in gathering information from your database for calculations and printing in reports. Variables are used to add, subtract, multiply, and divide numeric database information. Conditionals may be used when accumulating variables. Variables can also be assigned strings.

There are two parts to using variables:

Storing a value in the variable through declaring the variable, initializing it and assigning a value to it.

Printing the value stored in the variable.

What Is A Variable?

A variable is a "holding place" for a value. This value can be taken from a single field. It can be a calculation based on that field. It can be taken from a combination of fields or calculations. By making a variable to hold this information, it is easier to use in your reports.

For example, a variable called @varTotal can store the value of a Debtor Payment and Debtor Fees calculation.

@varTotal = @(de.pa+de.fe)

Now let's say that you need to divide this amount into four payments and put that in your report. The @varTotal can be used.

@varTotal = @(de.pa+de.fe)

@varTotal/4

@varTotal/4 means the same as @((de.pa+de.fe)/4).

You can also do this all in one line:

@varTotal =@((de.pa+de.fe)/4)

Now @varTotal means the same as @((de.pa+de.fe)/4).

Also, once you have assigned a value to a variable, you can use it in other places in your report.

As you can see, using variables can make complicated calculations easier to describe and manipulate with less chance for error.

Declaring And Initializing Variables

In the example above, the variable that is declared is @varTotal. To declare it, write @varTotal on a line by itself at the beginning of your Report Body. Collect! recognizes as variables, all print codes that start with @var. Variables must be declared and initialized before they are used.

Always start variable declarations or assignments on the first character position in a line. Only one declaration is permitted per line.

When you use a variable in your report, Collect! has to know what type of value you have stored in that variable. If you have forgotten to store a value in a variable that you declare, your use of it in your report calculations will not produce correct results. To insure against this, always set your variable's value to 0 when you declare it and assign a type to it. This is called "initializing the variable."

It is also possible to initialize your variable to an actual value when you declare it. When Collect! first attempts to use the variable, it will assign a type to it that matches the field it encounters. This can present a problem if Collect! encounters an empty field when it first attempts to use the variable. So it is best to assign a type to your variable.

A variable may be retained across report printouts, and its value may be indeterminate if you don't set it to zero.

Assigning A Type To Your Variable

When variables are declared, a type specifier should be added to set the type of data the variable will hold, unless the variable is initialized to a field.

When Collect! prints a variable in your reports, it needs to know what type of data the variable is holding. Otherwise, it will not print anything, even though the variable contains a value. However, when you initialize a variable to a field, Collect! can determine the data type of the variable because it is given the data type of the field itself.

Report Variable Specifiers

The specifiers are # % $ ! * and they are used as described in the following examples. Additional examples of their use can be found in sample reports that ship with Collect!.

Integer

This is a whole number. For example: 1, 6780, 45

@varName#

@varFile# = 0
@varFile = @de.fi

Floating Point

This is a number with a decimal. For example: 1.5, 67.80, 45.878 Floating point is precise to 3 decimal places.

@varName%

@varInterest% = 0.000
@varInterest = @de.in

Dollar

This is a currency value. For example: 2.88, 7.90, 4.56 Dollar is precise to 2 decimal places.

@varName$

@varOwing$ = 0.00
@varOwing = @de.ow

Date

This is a date. For example: 4/5/2011

@varName!

@varListed! = "01/01/2011"
@varListed = @de.li

Put the date in quotes if specified as 01/01/2011. You don't need quotes if specified as 1110101. (This is year/111 - month/ 01 - day/ 01. 101 is 2011.)

String

This is a string of characters. For example: abcdefg, Sam Jones

@varName*

@varName* = " "
@varName = @de.na

The variable specifier is applied when the variable is assigned a field or value rather than when it is initialized or declared.

Time

To declare a variable as a Time type, simply initialize your variable to a time field.

Example:

@varTime = @de.wt

Then you can do time assignments and calculations with this variable. Current time is stored in @t. You may add or subtract from this to use in calculations, along with time variables.

@varTime = @de.wt
@varFlag = 1 if (@varTime < @t+020000)

One use of this is timezones. For an example of setting the color of the phone field depending on timezones please refer to Help topic Timezone Alerts.

Assignment Of Values To Variables

After variables are declared, values may be assigned to them. Whenever they are used in your report calculations, Collect! will substitute that value when it sees the variable name.

Variables will not print unless previously assigned a type or field value! For example, if you set @var1 = 10, you will be able to use @var1 in conditionals and calculations. However, because the system does not know the format of the value, it will not print out anything if you try to print @var1. If you assign an integer data type to it, for instance, then it will be able to be printed.

For example:

@var1# = 10

Printing var1: @var1

The output of this code is:

Printing var1: 10

Because Collect! knows that the variable is an integer, it can print it.

Additional Examples

These variables are initialized correctly:

@varOwing$ = @de.ow
@varListed! = @de.li
@varDate! = @d-30
@varMyVariable# = 0
@varTotalOwing$ = 10.00
@varTotalDirect% = 20.00

Printing Variables In Reports

Printing variables is easy. If you created one called @varPaid, for instance, to print it, you would just type @varPaid where you want it printed.

At least one of the assignments to a variable must be a database field, or a variable that has previously been assigned a database field. Otherwise, the report system doesn't know how to format the variable for printing, and it won't print anything. You can also give the variable a data type when you initialize it.

One complete statement should be printed on a single line. In the following code, if long statements have wrapped around, in your browser, when you use them in your own reports, please put the entire statement on a single line.

Example 1

@varTotalPrincipal$ = 0.00
@varTotalPaid$ = 0.00
@varTotalOwing$ = 0.00
@de WHERE (@de.li = ?)
@varTotalPrincipal = @(varTotalPrincipal+de.pr)
@varTotalPaid = @(varTotalPaid+de.pa)
@de.li @de.na
@de
@varTotalOwing = @(varTotalPrincipal-varTotalPaid)

Principal ...... $@varTotalPrincipal
Paid ...........$@varTotalPaid
Owing .......... $@varTotalOwing

Example 2

//--- String variable example
String test report

@varString1* = " "

//--- Scan through a few Debtors
@de max = 10 no total

//--- Assign string based on Debtor conditions
@varString1 = owes less than $100.00 if (@de.ow < 100)
@varString1 = owes between $100.00 and $200.00 if (@de.ow = 100 .. 200)
@varString1 = owes more than $200.00 if (@de.ow > 200)

//--- Print the data
@de.na<30> $@de.ow<13.2> @varString1
@de

These examples demonstrate the use of WHERE clauses, 'if' conditionals and loops. See How-to topics on these concepts for details and additional examples.

Summary

Many reports that ship with Collect! use variables. Review them for additional examples. Also, you may use the Index to look up the topic, "Variables."