Represents the value of the current field.

Example 1: answer = 10 puts the number 10 in the current field.

Example 2: answer = $7 puts the value in field 7 into the current field.

Example 3: answer = result puts the value that is currently in the result variable into the current field.

Used as a temporary variable for storing intermediate calculations.

Several scripting statements also place values into the result variable.

Example 1: result = 6 + 19 stores the number 25 in the result variable.

Example 2: result = $5 + $6 adds up the values in fields 5 and 6, and places the sum of the two fields in the result variable.

Example 3: result = result + $15 adds the existing value in result to the value in field 15, and stores the sum of the two values back in the result variable.

$ is a field reference, used to refer to the value in the specified field.

Example 1: $5 means the value in field 5.

Example 2: $[OrderTotal] means the value in a field with the field label of OrderTotal.

temp is a "free" variable that can be used to store data. Whereas scripting statements place values into the result variable, the value in the temp variable can be set in a script and will be preserved until you change this value in a script yourself, or until Pendragon Forms is no longer the active application on the mobile device.

null is a constant which is equivalent to an empty string.

Example 1: $10 = null sets the value of field 10 to null.

Example 2: calculate:
         if $4 <> null then
                  answer = $3 / $4
         endif

In this example, if field 4 is not null, then a calculation is performed.

buffer is another "free" variable that can be used to store data, similar to the temp variable. The buffer variable can be set in a script and will be preserved until you change this value in a script yourself, or until Pendragon Forms is no longer the active application on the mobile device.

lookupname is a variable that can be used to determine the name of the Lookup List that will be displayed when a user taps in a Lookup List field. Lookupname is set with a setlookupname statement - see page 301.

lookuplocale is another variable that can be used to determine the name of the Lookup List that will be displayed when a user taps in a Lookup List field. Lookuplocale is set with a setlookuplocale statement - see page 301.

The enterscreen: event runs as soon as the user arrives on a screen. The enterscreen: event can be used to pre-fill certain fields on a screen as the user gets to that screen.

The exitscreen: event runs as soon as the user leaves a screen to go to another screen. The user must tap the Next button or End button. The exitscreen: event can be used to pre-fill certain fields on the next screen based on values entered in the current screen. A goto statement in an exitscreen: event lets the user branch to a specified screen.

The enter: event runs only when the cursor enters a Text, Numeric or Currency field. If the first field on a screen is a Text, Numeric or Currency field with an enter: event, the script will run as the mobile device user gets to that screen. If the field with the script is not the first field on the screen, the script will run when the user taps in that field.

The exit: event runs only when the user exits a Text, Numeric or Currency field. This means that the exit: event will run when the user taps in the next field after a Text, Numeric or Currency field, or if the user taps the Next arrow button to move to the next screen. The exit: script is only run when the user is moving 'forward', for example from field 8 to field 9, and not "backward" from field 9 to field 8.

The select: event occurs when the user selects an option or accepts a dialog associated with a field. The select: event is typically used in branching, so that when the user selects an option, he/she branches to a field depending on the selection made. A select: event is only triggered in fields that allow a selection, such as a Popup List, Lookup List or a checkbox. Leaving a selection field blank will cause the select: script not to run.

Text, Numeric and Currency fields do not trigger a select: event.

The initialize: event runs only once when a new record is created. The initialize: event is often used to set values in Date and Date&Time fields, so that when the user creates a new record, these fields are already filled in.

The open: event runs only once whenever a record is entered. The open: event is used instead of an initialize: event if you need a script to run every time a record is accessed.

A calculate: event is used to place the result of a calculation into a field. Typically, the calculated result depends on the values in other fields. The calculate: event is triggered when any field is updated manually or updated via a script. As you exit the updated field, any calculate: script in Field 1 is run, followed by a calculate: script in Field 2, then Field 3, etc.

There is a performance penalty if there are a lot of fields on the form. For example, if you have a form with 100 fields and the form contains one calculate: script, then that script will be run 100 times as you enter data and then exit each field.

A click: event is primarily used in Button fields. The click: event allows a script to run when the mobile device user taps on the button in the Button field. See page 297.

A click: event can also run when you tap in a Lookup List field, before the list is displayed. This is useful if you are performing a Lookup to Another Form, and you want to filter the records that are displayed in the list. See pages 312-313.

A click: event can be run in a Section field, if you tap the question area or graphic in a Section field.

A click: event can run in a Subform field.

A click: event can run in a Custom Control field, provided that the creator of the Custom Control application allows it.

A validate: event runs when the mobile device user leaves a record. The script in a validate: event can be used to perform additional validation on various fields.

If a record is selected with the select statement (see page 266-268), the column function returns the value of the specified column number in the record.

The function now is used to store the current date and time. For an example, see page 287.

Returns the creation date and time of the record.

Returns 0 if the record is not modified, or returns 1 of the record has been modified.

Stores the value of a bar code that has just been scanned. Used in a scan: event script, the value of scandata can be placed into a Text field.

Stores an X-coordinate (horizontal coordinate) when a user taps in a Section field. On a mobile device (even a high resolution device), the screen has X-coordinates ranging from 0 - 159. The tapx function can be used to determine where on a picture in a Section field a user has tapped horizontally.

Stores a Y-coordinate (vertical coordinate) when a user taps in a Section field. On a mobile device (even a high resolution device), the screen has Y-coordinates ranging from 0 - 159. Pendragon Forms reserves Y-coordinates 0-15 for the title bar, and Y-coordinates 145-159 for the buttons at the bottom of the Layout View screen. Valid values for tapy are therefore in the range 16-144. The tapy function can be used to determine where on a picture in a Section field a user has tapped vertically.

Username stores user name of the mobile device.

Stores the HTML data returned by a server after the transmit web statement in a script has sent an HTTP request to the server. If the returned data is in XML format, the extract statement can be used to extract components of the data into different fields on the form.

Returns the sine of the angle value, expressed in radians.

To convert degrees to radians, multiply by pi / 180.

Pi is a constant representing the number Π.

In this example, an angle in radians is entered into field 5. The sine of the angle is then placed into field 6.

calculate:
   $6 = sin $5

In this example, an angle in degrees is entered into field 5. The angle is first converted to radians for use with the sin function, and the sine of the angle in radians is placed into field 6.

calculate:
   result = $5 * pi
   result = result / 180
   $6 = sin result

Returns the cosine of the angle value, expressed in radians. In this example, an angle in radians is entered into field 7. The cosine of the angle is placed in the current field.

calculate:
   answer = cos $7

Returns the tangent of the angle value, expressed in radians.

Returns the arcsine of the number value. The resulting angle is expressed in radians.

To convert radians to degrees, multiply by 180 / pi.

Pi is a constant representing the number Π.

In this example, clicking a button calculates the arcsine of a number in field 24, and places the result in field 25. The angle in field 25 is expressed in radians, and so the script then converts the radians to degrees and places the angle in degrees in field 26.

click:
   $25 = asin $24
   result = $25 * 180
   $26 = result / pi

Returns the arccosine of the number value. The resulting angle is expressed in radians.

To convert radians to degrees, multiply by 180 / pi.

Pi is a constant representing the number Π.

Returns the arctangent of the number value. The resulting angle is ex- pressed in radians.

To convert radians to degrees, multiply by 180 / pi.

Pi is a constant representing the number Π.

Returns the hyperbolic sine of the number value.

Returns the hyperbolic cosine of the number value.

Returns the hyperbolic tangent of the number value.

Returns the square root of the number value.

In this example, a number is entered in field 12. The square root of the number is placed in the current field.

calculate:
   answer = sqr $12

Pow is a binary operator that calculates the number value1 raised to the power of value2.

For example, the answer in this script would be 10 * 10 * 10 = 1000.

calculate:
   answer = 10 pow 3

In this example, a number in field 4 is squared.

calculate:
   answer = $4 pow 2

In this example, a number in field 6 is raised to the power specified in field 7, and the calculated result is placed in field 8.

click:
   $8 = $6 pow $7

Exp calculates the number e raised to the power value.

e is an irrational number that begins with: e = 2.7182818284590...

In this example, e is squared.

calculate:
   answer = exp 2

In this example, e is calculated to the power specified in field 3. The calculated answer is placed in field 4.

calculate:
   $4 = exp $3

Returns the log base e of the number value.

In this example, the current field calculates the log base e of the number in field 5.

calculate:
   answer = log $5

Returns the log base 10 of the number value. In this example, the log base 10 of the number in field 3 is placed into field 4.

calculate:
   $4 = log10 $3

Rounds the number value to the nearest whole number.

For example, 20.5 rounds up to the nearest integer, namely 21.

20.49 rounds down to 20.

In this example, field 7 is rounded to the nearest whole number, and the answer is placed in field 9.

calculate:
   $9 = round $7

In this example, fields 10 and 11 are multiplied together, and then rounded to the nearest whole number.

calculate:
   result = $10 * $11
   answer = round result

Truncates the number value, discarding any decimal places and leav- ing the integer part of the number. No rounding occurs, so truncating the number 29.9 returns the number 29.

In this example, the number in field 23 is truncated and the integer part of the number is stored in the current field.

calculate:
   answer = trunc $23

Adds two values.
Example: answer = $4 + $5 adds the value in field 4 to the value in field 5.

Subtracts one value from another.
Example: result = $18 - 20 subtracts the number 20 from the value in field 18.

Multiplies two values.
Example: $6 = $5 * $4 multiplies the values in fields 5 and 4, and places the result in field 6.

Divides one value by another.
Example: answer = $12 / $13 divides the value in field 12 by the value in field 13.

Looks for a character string.
Example: if answer # Red then goto 4 endif looks for the string Red in the answer. Quotation marks are used if the string has spaces, example:
if answer # "Critical condition" then require 5 endif

Returns the remainder of a division.
Example: result = $4 % 12 returns the remainder after dividing field 4 by the number 12.

Concatenates two strings. Example: If field 2 contained the word Red, then answer = $2 & "apples" would put the string "Red apples" into the current field.

Performs a bitwise AND operation on a binary number. Used to extract information from Multi-Selection fields. See page 299.

Performs a bitwise OR operation. Used to assign a value to a Multi-Selection field.

Converts a number to its integer part.

For instance, 10.6 is converted to 10.

In this example, the answer in the current field is given the value of the integer part of field 5.

answer = integer $5

Converts a number to a negative number.

Example: answer = -$8

Returns the number of characters in a value.

This example returns the number of characters in field 5.

calculate:
   answer = length $5

Places the result of a calculation into the current field. Note that only simple expressions, involving not more than two values and one operator (+ - * /) can be used. In the following example, the value in field 4 is multiplied by the value in field 5, and the calculated result is placed in the current field.

calculate:
   answer = $4 * $5

In this example, the value in field 8 is divided by the number 10, and the result is placed in the current field.

calculate:
   answer = $8 / 10

The Answer statement can be used with field labels.

In this example, one field has a field label called ItemTotal and another field has a label called TaxRate. Clicking a button calculates the tax and places the calculated result into the current field.

click:
   answer = $[ItemTotal] * $[TaxRate]

Result is a temporary variable. Since not more than two values can be calculated at a time, result is used as extra "storage space" for intermediate calculations. Several scripting statements also use the Result variable to store the result of a calculation.

In the following example, the values in fields 4, 5, 6 and 7 are being added, and the final calculated result is placed in the current field.

calculate:
   result = $4 + $5
   result = result + $6
   answer = result + $7

To calculate an expression like 8*(9+7), the script would be:

calculate:
   result = 9 + 7
   answer = 8 * result

The Result statement can be used with field labels.

In this example, fields are given labels of Discount, RetailPrice and DiscountedPrice. If the mobile device user selects to give a discount, the discount amount is calculated by multiplying the discount by the price. The discounted price is then calculated by subtracting the discount from the retail price.

select:
   if answer == Y then
      result = $[Discount] * $[RetailPrice]
      $[DiscountedPrice] = $[RetailPrice] - result
   endif

This assignment statement is used to assign a value to a field from another field.

In the following example if the mobile device user selects Yes, then field 15 is set to the number 10; if the user selects No or leaves the field blank, then field 15 is set to the number 5.

select:
   if answer == Y then
      $15 = 10
   else
      $15 = 5
   endif

Field labels can be used when assigning a value to a field.

In this example a field with the label Daily Total is assigned the value of the sum of a field with the label Total and a field with the label Surcharge.

calculate:
   $[Daily Total] = $[Total] + $[Surcharge]

Temp is a temporary variable, similar to Result. However, whereas the Result variable is used by various scripting statements to store a value, the Temp variable is reserved for use by you, the form designer. This means that if you assign a value to the Temp variable, that value will remain until you change that value or until the handheld user exits the Pendragon Forms application on the mobile device.

Buffer is another temporary variable. Similar to temp, if you assign a value to buffer, that value is retained until you change the value or until the user exits the Pendragon Forms application on the mobile device.

Assigns a value to the current field. Functions in the same way as answer =. However, answer = is preferred because an answer statement is less ambiguous and easier to read.

The following script creates a default value of 100 for a numeric field:

calculate:
   if answer = null then
      assign 100
   endif

Aborts the form, deleting the current record from the mobile device.

Can be used in Click, Select, Exit and Scan events only.

In the following example, the record is deleted and the form is aborted if the value in field 5 is less than zero.

exit:
   if $5 < 0 then
      abortform
   endif

Used to combine select statements for the same form, to narrow the selection of records that are displayed when performing a lookup to another form.

Typically, select statements only work one at a time, meaning that if one select statement is followed by another, the second select statement will cause the first select statement to be discarded. The use of the also statement between two select statements causes the first selection to be kept, and the second selection to be performed on the subset of records from the first selection.

Note: The also statement only works if the select statements are referencing the same form.

As with any lookup to another form, the current form must have a Lookup List field that references the name of the reference form. Also, fields that you want to copy from the reference form to the current form must have the same field name and field type in both the reference form and the current form.

In this example, imagine that Field 2 of the current form contains a State and Field 3 contains a City. The "Employee List" reference form also contains a State and City. The click: event script is placed in the Lookup List of the current form that is doing the lookup to the reference form. The first select statement selects all employees in the specified State. The also statement retains that selection, and the second select statement then selects all employees within the selected State who are in the selected City.

click:
   select "Employee List" where field 1 is $2
   also
   select "Employee List" where field 2 is $3

The call statement allows you to call custom Javascript code.

The Javascript code can utilize and modify the value of the result variable. The script continues after the call statement with the updated value of the result variable. Typically, the call statement is used to call Javascript functions that perform computations or access Javascript features that are not available directly through Pendragon Forms.

For use with custom controls that provide methods for you to call from a script.

A method is a term for a callable function that is built-in to a custom control. The callmethod statement calls the named method in the custom control that is located in the specified field.

A custom control is a separate program from Pendragon Forms. If the custom control is not loaded or visible on the current screen of your form design on the mobile device, then you cannot use callmethod (it will have no effect).

The result variable is passed to the custom control, and the result variable may be modified by the call.

Each custom control will have its own documentation that specifies what methods are available to be called. See page 137 for information on Custom Controls.

In this example, the GPS Custom Control in field 5 has a method called GPSINFO. The GPS Custom Control runs the click: event script written in field 5. The GPSINFO method puts GPS data into the result variable. This data is copied to the temp variable, and then extract statements are used to extract the GPS Latitude and put the value in field 6, the GPS Longitude is put in field 7, etc. (Refer to the GPS Custom Control documentation starting on page 137 for more information.)

click:
   result = ""
   callmethod 5 "GPSINFO"
   if result <> null then
      temp = result
      extract "GPS.LAT" from temp
      $6 = result
      extract "GPS.LONG" from temp
      $7 = result
      extract "GPS.ACCURACY" from temp
      $8 = result
      extract "GPS.ALTITUDE" from temp
      $9 = result
   endif

Checkflag is used in conjunction with clearflag, to enable you to modify a record with a script without marking the record as modified. This is useful when you want to have your form update some fields for cosmetic purposes without causing the changes to be synchronized back to the server.

For instance, the following script:

open:
   lookup $5 within "Expense Category"

might be used to lookup a value in a reference table every time the form is opened. Such a script is typically used when some of the fields on the form are not synchronized from the desktop to the mobile device, but must be calculated or looked up instead. (Database developers call thisde-normalization.)

While this technique enables the mobile device user to see related values on the screen, it has the side effect of modifying the record. This would mean that the simple act of viewing a record marks that record as modified, and causes it to be sent back to the desktop, overwriting the original record.

To prevent this side effect from occurring, use the checkflag statement to "memorize" the modification state of the record before any unintended modifications are made. After performing the script statements that you do not want changing the record, use the clearflag statement. Clearflag sets the modified flag back to the memorized value that it had when checkflag was called.

Using checkflag and clearflag, the script above would now be:

open:
   checkflag
   lookup $5 within "Expense Category"
   clearflag

NOTE: Any scripting actions that are supposed to modify the record should be made before checkflag or after clearflag. Otherwise the record will not properly be marked as changed , and will not synchronize.

The clone statement saves the current record, then creates a new record with identical values in all the fields as the original record. Scripting statements that occur after the clone statement are applied to the new record.

Clone statements can reduce the need for manual data entry. See page 298 for an example of using a clone statement in a click: event script to make a Clone Button.

When you use the clone statement, no validation is done on the record that you are leaving nor on the new record created by the clone statement. If you are using your own primary key, the combination of the primary key fields has to be unique for every record. You can use the keyunique statement before the clone statement, to check if the record that you are leaving has a unique primary key. If the record that you are leaving does not have a unique primary key, you can display a message to alert the user, and abandon cloning the record.

In this example, if you have a form in which fields 1, 2 and 3 basically remain the same, but fields 4 and 5 vary every time you record data, you might make Field 6 a Yes/No checkbox that asks the user "Do you need to make another reading?" If the user selects Yes in the following script, the record will be cloned and the values in fields 4 - 6 will be made null so that the user can enter the new values for these fields while retaining the existing values in fields 1 - 3.

select:
   if answer == Y then
      clone
      $4 = null
      $5 = null
      $6 = null
   endif

Column is a function that is used with a select statement to retrieve the value in a specified field of a selected record in a reference form.

The number is the column number (i.e. the field number) of the reference form.

In this example, a bar code is placed into field 1 of a form, and then a select statement is used to lookup that barcode in a reference form called Inventory. If a match is found, field 2 of the current form is populated with data from column 3 of the reference form. Field 3 of the current form is populated with data from column 5 of the reference form.

scan:
   $1 = scandata
   select "Inventory" where field 2 is $1
   $2 = column 3
   $3 = column 5

Checks the current record against all the other records in the database, to see how many records have the same value in the specified field. The number of records that match is placed into the Result variable.

Note: For performance reasons, the count statement should not be used in events.

If you need to check for uniqueness in a primary key, use the keyunique statement instead of count, because keyunique can check for uniqueness even if the primary key is comprised of more than one field.

This example checks to see if field 6 is unique.

validate:
   count 6
   if result > 0 then
      msgbox "This is a duplicate barcode"
   endif

Used in conjuction with select statements to delete all the selected records in a reference form.

WARNING: Should only be used with extreme caution to avoid accidentally deleting records from a reference form.

Records are selected with a select, select matching or select where statement.

Not recommended for use with select all statement, due to the possibility of deleting all records in a reference form.

Note: It may be easier to switch off the use of these options via Advanced Form Properties - see page 181.

In some form designs, you may want to hide certain buttons and menu options that are usually available to the mobile device user. The disable statement will hide the specified button, and the enable statement will display the specified button. Disable can be used in an open: event if you want the button or menu to be hidden in both new and existing records.

The endbutton specifier will hide the End button. You may want to hide the End button to prevent a mobile device user from exiting a form before viewing all the fields on the form. Warning: if you hide the End button on a form, you will have to give the user a way to exit the form, such as a Button field that when tapped, runs a script to end the form.

The nextbutton specifier will hide the Next button or the right arrow button. You may want to hide the Next button on a form that is being used as a 'main menu' from which the user jumps to other forms.

The backbutton specifier will hide the Back button or the left arrow button. You may want to hide the Back button on a form that is being used as a 'main menu' from which the user jumps to other forms. Or you may want to hide this button if your form requires users to answer a question and not go back to view or change answers.

The menus specifier will hide certain options that normally appear if the user taps the handheld Menu button. The menus that are disabled include: Delete and Mark All Changed. You may want to hide these menu options if your form design does not use them and you do not want to allow the user access to these menu options.

In this example, the End button, Navigation buttons and menu options are all disabled in an open: script in Field 1 of a form:

open:
   disable endbutton
   disable navbuttons
   disable menus

Since the End button is disabled in the above script, a Button field is added to the end of the form to give the mobile device user a way to exit the form. The script in the Button field is:

click:
   endform

Note: It may be easier to switch off the use of these options via Advanced Form Properties - see pages 181.

In some form designs, you may want to hide certain buttons and menu options that are usually available to the mobile device user. The disable statement will hide the specified button, and the enable statement will display the specified button. Disable should be used in an open: event to ensure that the button or menu is hidden in both new and existing record. Enable can be used in a scripting event where it makes sense to do so. For example, if you use the disable statement or Advanced Form Properties to hide an End button, you can have a button field with a click: event that allows the user to tap the button to end the form. Or you can have a Yes/No Checkbox field and use a select: event script that ends the form is the user selects Yes.

The endbutton specifier refers to the End button that allows the user to end a form at any time.

The nextbutton specifier refers to the Next button or the right arrow button.

The backbutton specifier refers to the Back button or the left arrow button.

The menus specifier refers to certain options that normally appear if the user taps the mobile device Menu button . The menus include: Delete and Mark All Changed.

If you disable the menus via a disable script or Advanced Form Properties, and you want to use a script to enable the menus, you will turn on all the menus. You cannot select a particular menu to enable.

In this example, the End button, Navigation buttons and menu options are all disabled in an open: script in Field 1 of a form:

open:
   disable endbutton
   disable menus

Since the End button is disabled in the above script, a Yes/No Checkbox field is added to the end of the form to give the mobile device user a way to exit the form. If the user selects yes to end the form, the endbutton appears. The script in the Yes/No field is:

select:
   if answer == Y then
      enable endbutton
   endif

Also, see the use of endform as a means of exiting a form that does not have an End button.

Equivalent to pressing the End button. Saves relevant data, then exits the form. This statement is only available in click:, select:, exitscreen:, exit: and scan: events.

In the following example, if the answer in the current field contains the word Finished, then the record is saved and the form is exited.

exitscreen:
   if answer # Finished then
      endform
   endif

In this example, a Button field is used to exit a form.

click:
   endform

Extracts XML formatted data from the specified value. The XML formatted data can originate from a transmit web statement, or a call to an external method.

Extracted data is placed into the result variable.

The entity parameter defines the XML tags that delimit the data.

The value parameter depends on where the XML data originates from.

When the transmit web statement is used, data returned from a Web server is stored in the webdata function. The Extract...From statement can be used to extract XML from webdata. In this case the value parameter in the extract statement is the webdata function.

In this example, clicking a button on a form sends a part number stored in Field 6 to a Web URL. The data returned by the Web server is stored in the webdata function, and the Extract statement is used to place a sale price into Field 8 and the quantity in stock in Field 9.

click:
   transmit web "http://www.site.com/cgi-bin/inventory.cgi?partnum=$6$"
   extract "saleprice" from webdata
   $8 = result
   extract "qtyinstock" from webdata
   $9 = result

Used to check uniqueness within a subform. In a subform, records are filtered to display only those which match the parent record. A filtercount statement should be placed in a script in the subform, to check the current record against currently filtered records, to determine how many filtered records match in the specified field. The number of records that match is placed into the Result variable.

Note: For performance reasons, filtercount should not be used in a calculate: event.

This example checks to see if field 13 in a subform is unique:

validate:
   filtercount 13
   if result > 0 then
      msgbox "A record already has this value."
   endif

Internally, Pendragon Forms stores dates and times as a number - the number of seconds since 01/01/1904. Currency fields are stored internally as a number of cents. No special formatting is required if these types of fields are stored in the appropriate field type - for instance, if a currency amount is stored and displayed in a Currency field, no formatting is required.

However, if a Date, Time, Date&Time or Currency field needs to be displayed in a Text field, the format statement can be used to display the field in a way that is readable to the mobile deviceuser. The formatted value is placed in the result variable.

The following example causes the date in Field 1 to be formatted, and the formatted date to be placed in Field 8.

calculate:
   format $1 date
   $8 = result

The fixed specifier displays a currency without a currency symbol, and the currency specifier displays a currency with a currency symbol. In this example, if Field 7 contains the value of $15.95, then Field 8 will contain 15.95 and Field 9 will contain $15.95.

calculate:
   format $7 fixed
   $8 = result
   format $7 currency
   $9 = result

The month, day and year specifiers can be used to extract the month, day and year from a date.

Adds up the values across all records for the specified form and the specified field, and places the calculated result in the Result variable.

In the following example, clicking a button adds up all the values of field 17 across all records in the form "Daily Sales". The result is then put in field 8 of the current form.

click:
   formsum "Daily Sales" 17
   $8 = result

Moves to the specified field on the form and then exits the current script.

Can be used in the following scripting events:

select: event

click: event

scan: event

exitscreen: event

In the following example, when the mobile device user exits the current screen, the script checks the response in field 6. If the response contains the word Red, the scripts jumps to field 7; if the response contains the word Blue, the script jumps to field 12; if the response contains neither Red nor Blue, the script jumps to field 20.

exitscreen:
   if $6 # Red then
   goto 7
   endif
   if $6 # Blue then
   goto 12
   else
   goto 20
   endif

With a goto statement, a field must be visible for the script to be able to execute. If a field is hidden, the goto statement will go to the next visible field. For instance, if a script says goto 5, but field 5 is hidden, the goto statement will go to field 6. If there are no more visible fields after the specified field, the goto statement will do nothing.

Generally, if you use a goto statement to go to a specific field, you should also include a goto statement for the case in which you do not want to go to that field. Normally, Forms will move you to the next field automatically. However, if you use a script Forms may not move to the next field in the normal way, unless you add another goto statement. In this example, selecting Yes in a Yes/No checkbox jumps you to Field 5. Selecting No or not making a selection at all, jumps you to Field 4.

select:
   if answer == Y then
   goto 5
   else
   goto 4
   endif

The Gotosubform statement allows programmatic jumps to subform records without the use of a Subform List field on the parent form. The Gotosubform statement can be used to make the transition from a parent form to a subform transparent to the mobile device user.

The normal specifier causes the Gotosubform statement to behave just like a regular Subform List field, meaning that a review screen of existing subform records is displayed and the mobile device user can review an existing subform record or to create a new record. In this example, a button field is used to allow the user to access a subform:

click:
   gotosubform "Customer Contacts" normal

The new specifier causes a new subform record to be created, without the mobile device user seeing a list of existing subform records.

In this example, clicking a button creates a new subform record.

click:
   gotosubform "Item Ordered" new

The review specifier is similar to using a Single Subform field on the parent form, and provides a way to create a form with more than 250 fields by linking together more than one form design. Using the review specifier displays the most recently created subform record, or if none exists, a new subform record will be created. In this example, clicking a button jumps to the next form.

click:
   gotosubform "Survey2" review

With gotosubform normal, new and review, when the user ends the subform, he/she returns to the parent form. The oneway specifier, however, allows you to return to any form: a parent or a grandparent form. Normally if you go from form A --> B --> C --> D, when you end form D you have to return from D --> C --> B --> A. With gotosubform oneway, you can choose, for example, to go from form A --> B --> C --> D -->A or from form A --> B --> C --> D --> B . The destination form retains any parent-child association (if any) that it had previously, so if you jump from Form D --> B, and B is a subform of A, then when you end form B you would return to form A. In this example, the script is placed in a Button field in Form D.

click:
   gotosubform "Form B" oneway

The Hide statement is used to hide a single field on a form.

Hide From...To is used to hide multiple fields.

In this example, as the user exits the current screen, field 51 is hidden if the answer in the current field is Y:

exitscreen:
   if answer == Y then
      hide 51
   endif

This example hides fields 4 - 20 if the value in the current field is 1.

exitscreen:
   if answer = 1 then
      hide from 4 to 20
   endif

Creates a new record in the specified form and selects the new record. The user cannot see the record, and the only means for filling in the fields of this record is via the use of the update field statement .

In this example, when the user taps a button, the select statement checks if field 2 on the current form matches field 1 on the "Inventory" reference form. If not, a new record is created in the "Inventory" form, and fields 2 and 3 of the current form are copied into fields 1 and 2 of the new record.

click:
   select "Inventory" where field 1 is $2
   if result = 0 then
   insert into "Inventory"
      update field 1 = $2
      update field 2 = $3
   endif

Only used with the validate: event. The invalidate statement flags the record as having an invalid value, and the mobile device user cannot exit the record until the invalid value is corrected. A message is displayed on the screen, with buttons for the user to Edit or Delete the record.

Note that a validate: script only runs when the user exits the form. If the form has a lot of fields, it may be easier to use an exitscreen: script to check that fields contain valid data before the user moves to the next screen.

In this example, when the user tries to exit a record, if field 25 has a value greater than 100, an error message is displayed and the record is invalidated. The user has to edit field 25 or delete the record.

validate:
   if $25 > 100 then
      invalidate "Grade cannot exceed 100 points"
   endif

Normally, the lookup value within formname statement (page 258) finds a record in the form formname by matching the specified value to contents of the Display Key field of the form formname. (If no Display Key is specified, field 1 of the form is the Display Key field by default.)

The keycolumn statement allows you to perform a lookup to another form using a field other than the Display Key field of the reference form. The specified number is the alternate column of the reference form that the lookup...within statement will use to search for a matching record. After the lookup...within statement is run, the keycolumn is reset to the Display Key field once more.

In this example, the lookup...within script searches field 5 of a form called "Inventory Form".

click:
   keycolumn 5
   lookup $3 within "Inventory Form"

Determines whether the primary key of the current record is unique on the mobile device.

Keyunique places the value 1 in the Result variable if the primary key of the current record is unique on the mobile device, or places the value 0 in the Result variable if the primary key is not unique.

Keyunique is typically used before a clone statement. For instance, if you have a barcode as a primary key field, and you are using the clone statement to create new records automatically, before you clone a record you can use keyunique to check that the record has a unique primary key. If the record does not have a unique primary key, the user can be prompted to correct the error before making a new record.

In the example below, field 1 is used to store an inventory ID number or barcode. When the user enters an ID number and clicks a button to check that number, if there is already a value in field 1, the keyunique statement is used to check that the existing ID number (primary key) is unique. If it is not unique, a message is displayed to the user and field 1 is erased. If the primary key is unique then the record is cloned and the new ID number is placed in field 1 of the new record. Keyunique is used again to check that the new ID number is unique, and if it is not, then the ID number is erased from field 1.

click:
   if $1 <> null then
      keyunique
      if result = 1 then
         clone
      else
         msgbox "ID Number has already been entered."
         $1 = null
      return
      endif
   $1 = scandata
   keyunique
   if result = 0 then
      msgbox "ID Number has already been entered."
      $1 = null
   endif

The Launch statement can launch a new Web browser window that goes to the specified URL (Web address). Mobile device users would need to manually return to the Pendragon Forms Universal window when they wish to resume entering data in Pendragon Forms.

Extracts the left-most characters and places the extracted characters into the Result variable.

The value specifier is the value from which the left-most characters are to be extracted. The value can be a text string in double quotation marks, or it can be a field number such as $46 for field 46.

The length specifier is the number of characters to be extracted. The following example puts the value MXP in the current field.

enter:
   left "MXP53802" 3
   answer = result

This example puts the first 4 characters from field 16 into the Result variable, and then into the current field.

enter:
   left $16 4
   answer = result

Used to lookup a value in a Lookup List or in another form.

The value specifier is the display entry to search for.

If a lookup-list-name is specified, this is the name of the Lookup List to search. The Lookup List that you use should be set to Store Lookup Values in the Lookup field (see page 108). The value that is found (if any) is put into the result variable. Your script can then place the value in the result variable into a field on the form.

Imagine that you want to create a form with a field called Item Name and a field called Price. When you select the Item Name in field 1, you want to see the correspond Price appear in field 2. To create this requires two Lookup Lists on your form. One Lookup List contains the item names. The second Lookup List, called ‘Prices’, contains the item names and prices, and is set to Store Lookup Values in the Lookup field. The script in field 1 should be as follows:

select:
   lookup $1 within "Prices"
   $2 = result

If a form-name is specified instead of a Lookup List name, the lookup...within script will perform a lookup to the specified form. The field that is being looked up must be the Display Key on the reference form. If a match is found in the reference form, all fields that are named the same on both forms will be copied from the reference form into the current form.

You can use the keycolumn statement to look up a field other than the Display Key field when doing a lookup...within another form.

Note: You do not need to use a lookup...within script to perform a manual lookup to another form - see page 116.

This function copies length characters from value, starting at position start, and places the characters into the Result variable.

The following example places "123" into the Result variable, and then into the current field.

calculate:
   mid "012345678A" 2 3
   answer = result

In this example, 10 characters are extracted from field 5, starting from the 7th character position in field 5. The extracted characters are placed in field 6.

calculate:
   mid $5 7 10
   $6 = result

Displays a dialog box on the mobile device. An individual string cannot exceed 512 characters.

This example displays a message if the user enters a value greater than 100 in the current field.

exitscreen:
   if answer > 100 then
      msgbox "The temperature is very high"
   endif

If you just use a string, the message box dialog will contain an OK button that the user can tap to clear the dialog window.

Alternatively, you can use a special prefix at the start of the text of the string, to add a series of buttons to the message box dialog. The result variable stores a character depending on the button that the user taps.

You can write a script to take action depending on which button the handheld user taps in the message box dialog.

In this example, if the answer in field 8 is less than zero, a dialog will appear asking if the user wants to continue. The dialog will have two buttons, OK and cancel. If the user taps the OK button, the user will jump to field 12. If the user taps the Cancel button, he/she will jump to field 20.

exitscreen:
   if $8 < 0 then
      msgbox "?OC?Would you like to continue?"
      if result == O then
         goto 12
      else
         goto 20
      endif
   endif

Allows a range of fields to be set to NULL.

Field-number1 is the first field in the range and field-number2 is the last field in the range. A field name can be an actual field number, such as 5, or a field label such as [AccountName].

In this example, if the user selects Y in the current field, the record is cloned and fields 5 to 20 are set to null.

select:
   if answer == Y then
      clone
      nullfrom 5 to 20
   endif

The words NEXTFIELD and LASTFIELD can be used instead of field numbers. NEXTFIELD means the field immediately after the field containing the script. LASTFIELD means the last field on the form.

In this example, if the user selects to erase information, then fields will be erased starting from the field with the field label [CustomerName] and ending with the last field on the form.

exitscreen:
   if $12 == "Erase" then
      msgbox "?OC?Are you sure you want to erase this info?"
      if result == O then
         nullfrom [CustomerName] to LASTFIELD
      endif
   endif

Makes the specified field optional. Used to override setting the field as Required in the Advanced Field Properties screen. (Note that all fields are optional by default, unless made Required either by setting the Advanced Field Property of Required (page 150), or by making the field Required in a script - page 263.)

In this example, if the answer in the current field is Y, then field 7 is optional.

exitscreen:
   if answer == Y then
      optional 7
   endif

In this example, if the response in field 8 is "Never", fields 9 to 15 are optional.

exitscreen:
   if $8 == "Never" then
      optional from 9 to 15
   endif

Used to make a field or a range of fields read-only.

Instead of using a script, you can also make a field read-only in the Form Designer window (see page 167).

In this example, if the value in field 15 is greater than 100, field 16 and fields 20 - 25 are made read-only.

exit:
   if $15 > 100 then
      readonly 16
      readonly from 20 to 25
   endif

Used to make a read-only field updatable.

In this example, field 27 is made writable:

enter:
   readwrite 27

Makes the specified field(s) required, meaning that the field(s) cannot be left blank.

Instead of using a script, you can also make a field required in the Form Designer window (see page 150).

In this example, if the response in the current field is Y, then field 45 is a required field:

select:
   if answer == Y then
      require 45
   endif

In this example, if the response in the current field is "Critical", then fields 18 to 22 are required.

exitscreen:
   if answer == "Critical" then
      require from 18 to 22
   endif

Extracts the right-most characters and places the extracted characters into the Result variable.

The value specifier is the value from which the right-most characters are to be extracted. The value can be a text string, or a field, e.g. $50 means the value in field 50.

The length specifier is the number of characters to be extracted. In this example, the value "129" is placed into the current field.

enterscreen:
   right "Procedure Code 129" 3
   answer = result

Here the last five characters from field 35 are placed into the current field.

exitscreen:
   right $35 5
   answer = result

Returns from the current script without executing any more instructions. Useful if you want to prevent default instructions from being executed after an IF statement.

In this example, a field with the field label Quantity is to be multiplied by a field labeled Price, and stored in a field labeled Total. However, if the Quantity field is left blank, a message is displayed to the user and the return statement stops the script before the multiplication takes place.

calculate:
   if $[Quantity] is null then
      msgbox "Please fill in the quantity"
      return
   endif

$[Total] = $[Price] * $[Quantity]

Reverselookup...Within is the opposite of Lookup...Within. Reverselookup takes the lookup value of a Lookup List and returns the corresponding lookup display item, and places the result in the Result variable.

The value specifier is the Lookup List value for which you are searching in the Lookup List. The value can reference a field number, e.g. $15 is the value in field 15.

In this example, imagine that a Lookup List named "Airports" contains the full names of airports as the lookup display items, and the corresponding 3-letter airport codes as the lookup value items. If the user selects an airport code in field 5, making that selection will run the script and place the full airport name in field 6.

select:
   reverselookup $5 within "Airports"
   $6 = result

Used primarily in a click: event or in a scan: event.

Used to go to the Review screen for the specified form, so that the user can select and edit a record.

The review statement can be used in conjunction with making your own custom 'Main Menu' that users see when they launch the Forms application. See Chapter 15, Creating a Custom Main Menu, page 326.

The review statement can be used with select statements.

A select where statement can select records based on a certain criteria, and then the review statement allows the user to see and edit the filtered records. See page 334.

In this example, tapping a picture in a Section field that is part of a custom 'Main Menu' displays a list of records in a form called Customer Log.

click:
   review "Customer Log"

Selects all records in the specified form. Might be used to undo a select matching statement or a select where statement, or to show all records in a reference form if a matching criteria was not specified.

The formname is the name of a reference form.

If you are performing a lookup to another form, the current form must have a Lookup List field that references the name of the reference form. If you want to copy records from the reference form into the current form automatically, the field names and field types have to match in both the reference form and the current form.

In this example, the script is written in a Lookup List field that references a reference form. If field 5 of the current form is null (blank), then the select all statement selects all records of the Parts List reference form. If field 5 of the current form is filled in, then the select where statement selects only those records that match field 2 of the Parts List form to field 5 of the current form.

click:
   if $5 = null then
      select all "Parts List"
   else
      select "Parts List" where field 2 is $5
   endif

Used to perform cascading updates or deletes from a parent form to a subform.

Selects all records in the subform called formname that match the current record of the current (parent) form. The first 10 fields of the current form are used, and the field names and values in those fields must match in the current form and the subform for a record to be selected. The Result variable stores the number of matching records.

Once selected, the subform records can be updated with the update field statement. Alternatively, the selected subform records can be deleted with the delete statement.

WARNING: If you change the values in any fields that are used to match the parent record to the subform records, you will lose the link from parent form to subform and the parent form will appear not to have any subform records.

In this example, a parent form has a Yes/No checkbox field with a field name such as "Do you want to delete this equipment log and all related equipment readings?". Choosing Yes runs a select: script to delete all the corresponding records on the "Equipment Readings" subform.

select:
   if answer == Y then
      select matching "Equipment Readings"
      delete
   endif

NOTE: This type of subform record deletion will only work in the case where you are not storing records on the mobile device after synchronization. If you are choosing to keep records on the handheld, deleting subform records only works if the record is a newly created record that has not been backed up to the PC. If records have been backed up to the PC, then those records will be re-sent to the mobile device during the next synchronization. The solution in this case is to either use a Completion Checkbox field within the first 10 fields of the parent and subform, or to have a field for storing the status of the field (e.g.: Active or Deleted), and then use Additional Download Criteria (see page 184) to send only Active records to the mobile device.

The select where statement is used to select records from a reference form. This has the effect of performing a filter on the reference form, and is useful if you want to limit the list of records that the mobile device user sees when performing a lookup to another form. See pages 312 and 314 for examples.

Only one form can be selected at a time.

The formname is the name of the reference form.

The field-number is a field number (or column number) in the reference form.

The expression is the criteria for finding a matching record in the reference form. The expression can be:

A text string (e.g.: "Cherry Street"). For example:
select "Addresses" where field 4 is "Cherry Street"

A numeric value (e.g. 15 ). For example:
select "Inventory" where field 3 is 15

A value in a field (e.g. $8 means the value in field 8). For example:
select "Parts List" where field 1 is $8

A function that takes no arguments (e.g. username). For example:
select "Customers" where field 1 is username

The expression in a select where statement can also contain a range, such as:

Greater than (> numeric comparison). For example:
select "Student Scores" where field 6 > 90

Less than (< numeric comparison). For example:
select "Sale Items" where field 2 < 995
(Note that if field 2 is a Currency field, 995 means $9.95)

Equal ( = numeric comparison). For example:
select "Items to Re-Stock" where field 5 = 0

Contains a character sequence (e.g.: contains "Ave"). For example:
select "Addresses" where field 2 contains "Ave"

Starts with a character sequence (e.g.: startswith "Tr"). For example:
select "Countries" where field 1 startswith "Tr"

The number of records that match the select where criteria is stored in the result variable.

The also statement can be used to combine selection criteria for the same form.

If a lookup to another form is being performed, then one field on the current form has to be a Lookup List field type that references the name of the reference form. A click: event script in the Lookup List field causes the select where statement to be run when the mobile device user taps in the Lookup List field, so that the user sees the filtered list of records. Fields that are named the same on both the reference form and the current form will automatically copy from the reference form into the current form when the user selects a record from the list.

In this example, the user enters a value in field 2 of the current form. Tapping in a Lookup List displays all the records in the Customers reference form, where field 4 of the reference form matches field 2 of the current form. When the user taps on a record, all the fields named the same in both forms are copied from the reference form into the current form.

click:
   select "Customers" where field 4 is $2

If you are looking up records automatically via a script, fields can be copied from the reference form to the current form using the column function, or fields on the reference form can be updated or deleted.

In this example, the ID Number on a student badge is entered into field 2 of the current form. The select statement selects the record where field 1 in a form called StudentID matches field 2 in the current form. After the match is found, the value in field 3 of StudentID is copied into field 4 of the current form.

click:
   select "StudentID" where field 1 is $2
   $4 = column 3

Setlookuplocale is used to set the lookuplocale variable to the specified value. This is used to create a cascading lookup list, that is, a lookup list in which the list that is displayed depends on a selection in another field on the form. (Note: You can also use setlookupname with the variable lookupname to do a cascading lookup.)

The value can be the value in a field, such as $3, or a constant value such as "Car" or "Plane".

setlookuplocale is usually run in a click: event script in a Lookup List field. The value that the lookuplocale variable is set to, is then used to help determine which Lookup List to display.

In the form design, the name of the Lookup List is a keyword followed by the caret (^) character. For example, if the keyword is Transport, then the Lookup List to display is written as Transport^ . When the user taps in the Lookup List field, the ^ character is replaced by the value in the lookuplocale variable. So if lookuplocale has been set to "Car", the Lookup List that will be displayed is called TransportCar.

In this example, the user makes a selection in field 8 of the form, and that value is assigned to the lookuplocale variable in the following script in a Lookup List field:

click:
   setlookuplocale $8

See page 301 for an example of using setlookuplocale.

Setlookupname is used to set the lookupname variable to the specified value. This is used to create a cascading lookup list, that is, a lookup list in which the list that is displayed depends on a selection in another field on the form. (Note: You can also use setlookuplocale with the variable lookuplocale to do a cascading lookup.)

The value can be the value in a field, such as $4, or a constant value such as "Male" or "Female".

setlookupname is usually run in a click: event script in a Lookup List field. The value that the lookupname variable is set to, is then used to help determine which Lookup List to display.

In the form design, the name of the Lookup List is a keyword followed by the tilde (~) character. For example, if the keyword is Adult, then the Lookup List to display is written as Adult~ . When the user taps in the Lookup List field, the ~ character is replaced by the value in the lookupname variable. So if lookupname has been set to "Female", the Lookup List that will be displayed is called AdultFemale.

In this example, the user makes a selection in field 12 of the form, and that value is assigned to the lookupname variable in the following script in a Lookup List field:

click:
   setlookupname $12

See page 301 for an example of using setlookupname.

Makes a hidden field or range of hidden fields visible.

In this example, if the answer in the current field is N, then field 4 is made visible.

select:
   if answer == N then
      show 4
   endif

In this example, several hidden fields are displayed.

exit:
   if $3 # "More" then
      show from 8 to 30
   endif

Used to add all values in a specific field across all subform records associated with a given parent record. The Subformsum statement is placed in a script on the parent form, typically a click: event.

The calculated sum is placed in the Result variable.

The name-of-subform is the name of the subform.

The field-number is the field on the subform which is to be added across all subform records for that parent.

In this example, clicking a button on the parent form adds up the values in Field 6 of the Items Ordered subform. The calculated result is placed in Field 12 of the parent record.

click:
   subformsum "Item Ordered" 6
   $12 = result

See page 300 for an example.

The synchronize statement is typically placed in a click: event script in a Section field or a Button field on a Custom Main Menu form, to provide users with a menu option for initiating a synchronization of Pendragon Forms. (See page 327.)

For example:

click:
   synchronize

The Transmit Web statement transmits the URL to a Web server and returns data in the webdata function.

To send the value of a field to the Web server, you can reference the field number in the URL by using the field number between $ signs.

For instance, $16$ means the value in Field 16.

In this example, clicking a button sends the value in Fields 2 and 7 to the Web server.

click:
   transmit web "http://www.mycorp.com/cgi-bin/premium.cgi?age=$2$&smoke=$7$"

Updates selected records in a reference form by setting the value of the field number to the specified expression.

See pages 317-322 for an example.

Records in the reference form are selected using one of the following statements: select where, select matching, select all or insert into.

The number is the field number of the reference form.

The expression is the value that will be assigned to the specified field.

The expression can be:

A text string (e.g.: "Active Customer"). For example:
update field 2 = "Active Customer"

A numeric value (e.g. 42 ). For example:
update field 4 = 42

A value in a field (e.g. $16 means the value in field 16) on the current form. For example:
update field 7 = $16

A function that takes no arguments (e.g. scandata). For example:
update field 1 = scandata

In this example, the current form is used to scan a product barcode in field 1, and the user counts the number of an item in thewarehouse, and enters the quantity in stock in field 2. The user then taps a button to update the "Inventory Items" form. A select statement matches the barcode in field 1 with the corresponding record in the Inventory Items form. Field 3 of the Inventory Items form is updated with the quantity that the handheld user entered in field 2 of the current form. If the quantity is less than 3, field 4 of the Inventory Items form is updated to read "Time to re-order".

click:
   select "Inventory Items" where field 1 is $1
   update field 3 = $2
   if $2 <= 3 then
      update field 4 = "Time to re-order"
   endif