adjustservervariable(
DATABASE
,
VARIABLE
,
CHANGE
)

The adjustservervariable( function adjusts the value of a server variable. This is an “atomic” operation, so it is multi-user friendly.


Parameters

This function has three parameters:

database – name of the shared database that contains the server variable. If this parameter is missing or empty, the current database is assumed.

variable – name of the shared variable to be adjusted. The name must either be quoted, or calculated by a formula.

change – the value to be used to change the server variable. If the server variable contains a numeric value, this parameter should be a number that will be added (or subtracted if negative) to the server variable value. If the server variable contains text, this value will be appended to the server variable.


Description

This function adjusts the value of a server variable. This is an “atomic” operation, so it is multi-user friendly (in other words, it will work correctly even if multiple users adjust the same value at the same time). If you need to increment or decrement a server variable, you should use this function instead of using the letservervariable statement and servervariable( function.

To illustrate this, suppose you want to keep track of how many times invoices have been printed to a PDF file – keeping track of the count no matter what computer was used to do the printing. This example shows how this can be done.

letfileglobal currentInvoicePrintCount = adjustservervariable("InvoicePrintCount",1)
printtopdf "invoices.pdf","Form","Invoice Template"

Each time this code runs, the InvoicePrintCount server variable is incremented by one (1, 2, 3, 4, etc.). The count is copied into the fileglobal variable currentInvoicePrintCount on the local computer. If you wish, you could embed the variable into the Invoice Template form, so that it will be printed.

You might wonder why a special function is needed. You might think – why can’t I just use the letservervariable statement and servervariable( function, and do the math with the + operator, something like this:

let count = servervariable("InvoicePrintCount")
letservervariable "InvoicePrintCount",count+1

This two step code will work fine when only one user is using the database. But if multiple people are using the database at the same time, there is always the chance that they will run this code at exactly the same time. Suppose the count is set to 2, and Bob and Frank both run this code at the exact same time. Both with get a count value of 2. Then both will add 1 and the new count will be 3. But that’s wrong, the count should be 4, since both Bob and Frank have printed.

By using the adjustservervariable( function, you make sure that each user get their own unique number (in this case one gets 3, the other 4), and that the final count is correct (in this case 4). Since the math is actually happening on the server, accesses is gated so that only one user can actually get access at a time. This is called an “atomic” operation because it can’t be split.

In addition to the adjustservervariable( function, there is also an adjustservervariable statement. It works just the same, however, it does not return the new, updated value of the server variable. If you don’t care what the new value is, only that is updated, the adjustservervariable statement will work fine for you.

The adjustservervariable statement normally modifies a server variable belonging to the current database, but you can specify a different database if you want. The specified database must be a shared database, and it must be currently open. Here is a revised version of the previous example that modifies the server InvoicePrintCount variable in the Invoices database instead of the current database.

letfileglobal currentInvoicePrintCount =
    adjustservervariable("Invoices","InvoicePrintCount",1)

All of the examples have used a change value of 1, so that the value increments by one each time the code runs. But you can use any numeric value, positive or negative, even fractional. But don’t assume that you’ll see iteration on your computer. Other computers on the network may also be incrementing this value, so you might see a sequence like 1, 2, 3, 4, 7, 9, 12. If you are running a loop you’ll want to avoid checking for absolute values like 5 – 5 might be skipped on this computer. Look for greater than or equal to 5 instead.


See Also


History

VersionStatusNotes
10.2UpdatedCarried over from Panorama 6.0.