[Search] [txt|pdf|bibtex] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02                                                      
INTERNET DRAFT
David Manning, Richard Bennett, John Boyer,
Sonja McLellan, Michael Mansell
August 1998
Expires:  February 04, 1999


      Universal Forms Description Language Specification
                      Version 4.0.1
                <draft-gordon-ufdl-spec-02.txt>

Status of this Memo

    This document is an Internet-Draft.  Internet Drafts are
    working documents of the Internet Engineering Task Force
    (IETF), its areas, and its working groups.  Note that
    other groups may also distribute working documents as
    Internet-Drafts.

    Internet-Drafts are draft documents valid for a maximum
    of six  months and may be updated, replaced, or obsolete
    by other documents at any time.  It is inappropriate to use
    Internet-Drafts as reference materials or to cite them
    other than as "work in progress."

    To view the entire list of current Internet-Drafts, please
    check the "1id-abstracts.txt" listing contained in the
    Internet Drafts Shadow Directories on ftp.is.co.za (Africa),
    ftp.nordu.net (Europe), munnari.oz.au (Pacific Rim),
    ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast)

Abstract

    The Universal Forms Description Language (UFDL) describes complex
    business forms for use over the Internet. The objective of the UFDL
    is to enable the creation of cross-platform Internet business forms
    that (1) contain both the complex logic and precise layout that
    administrators require, (2) are simple to maintain and distribute,
    and (3) integrate easily with existing business systems. As more
    and more business is done over the Internet, the need for a form
    description language that incorporates these features grows. HTML
    is designed for Internet pages, and is severely limited as a form
    language. This document specifies the vocabulary, syntax, and
    meaning of the UFDL.

CONTENTS

1.   INTRODUCTION
   1.1   Introduction to the UFDL
   1.2   UFDL Documentation
     1.2a   How This Document is Organized
     1.2b   Other UFDL Documentation
   1.3   Requirement Levels for UFDL Elements
   1.4   Implied Semantics for UFDL Viewers
   1.5   Security Considerations
   1.6   Responding to Errors in the Form Description

Universal Forms Description Language                            [page 1]


2.   INTRODUCTION TO THE UNIVERSAL FORMS DESCRIPTION LANGUAGE
   2.1   What is UFDL?
   2.2   Features of UFDL Forms
   2.3   Description of a UFDL Form
     2.3a   What is a Page?
     2.3b   What is an Item?
     2.3c   What is an Option?
     2.3d   Including External Files
     2.3e   Unrecognized Items and Options
   2.4   Syntax of UFDL
     2.4a   Basic Syntax Rules
     2.4b   Form Definition
     2.4c   Page Definition
     2.4d   Item Definition
     2.4e   Item Size
     2.4f   Item Placement
     2.4g   Toolbar Definition
     2.4h   Option Definition
     2.4i   Literals
     2.4j   References to Other Options
     2.4k   Relative Page Tags and Item Tags
     2.4l   Operations
     2.4m   User Events and Changes of State
     2.4n   Arrays
     2.4o   Defining Tabbing and Paging
     2.4p   Including External Files
   2.5   UFDL Language Elements
     2.5a   Identifiers
     2.5b   Custom Item Types and Custom Option Names
     2.5c   Reserved Words
     2.5d   Quoted Strings
     2.5e   Binary Data
     2.5f   Comments
   2.6   Security
   2.7   Filters
   2.8   Processing Forms
     2.8a   Include Statements
     2.8b   Expressions

3.   UFDL GLOBAL AND PAGE SETTINGS
   3.1   Global Settings
   3.2   Page Settings

4.   UFDL FORM ITEMS
   4.1   action
   4.2   box
   4.3   button
   4.4   cell
   4.5   check
   4.6   combobox
   4.7   data
   4.8   field
   4.9   help
   4.10  label
   4.11  line

Universal Forms Description Language                            [page 2]


   4.12  list
   4.13  popup
   4.14  radio
   4.15  signature
   4.16  spacer
   4.17  tablet
   4.18  toolbar
   4.19  <custom item>

5.   UFDL FORM OPTIONS
   5.1   activated
   5.2   active
   5.3   bgcolor
   5.4   bordercolor
   5.5   borderwidth
   5.6   coordinates
   5.7   data
   5.8   datagroup
   5.9   delay
   5.10  editstate
   5.11  filename
   5.12  focused
   5.13  fontcolor
   5.14  fontinfo
   5.15  format
   5.16  group
   5.17  help
   5.18  image
   5.19  itemlocation
   5.20  justify
   5.21  label
   5.22  labelbgcolor
   5.23  labelbordercolor
   5.24  labelborderwidth
   5.25  labelfontcolor
   5.26  labelfontinfo
   5.27  mimedata
   5.28  mimetype
   5.29  mouseover
   5.30  next
   5.31  previous
   5.32  printsettings
   5.33  saveformat
   5.34  scrollhoriz
   5.35  scrollvert
   5.36  signature
   5.37  signdatagroups
   5.38  signer
   5.39  signformat
   5.40  signgroups
   5.41  signitemrefs
   5.42  signitems
   5.43  signoptionrefs
   5.44  signoptions
   5.45  size

Universal Forms Description Language                            [page 3]


   5.46  thickness
   5.47  transmitdatagroups
   5.48  transmitformat
   5.49  transmitgroups
   5.50  transmititemrefs
   5.51  transmititems
   5.52  transmitoptionrefs
   5.53  transmitoptions
   5.54  triggeritem
   5.55  type
   5.56  url
   5.57  value
   5.58  version
   5.59  <custom option>

6.   UFDL FORM VIEWER DIRECTIVE
   6.1   #include
   6.2   #optinclude

7.   UFDL FUNCTIONS
   7.1   String Functions
     7.1a   countLines
     7.1b   replace
     7.1c   strlen
     7.1d   strmatch
     7.1e   strpbrk
     7.1f   strrstr
     7.1g   strstr
     7.1h   substr
     7.1i   tolower
     7.1j   toupper
     7.1k   trim
     7.1l   URLDecode
     7.1m   URLEncode
   7.2   Math Functions
     7.2a   abs
     7.2b   acos
     7.2c   annuity
     7.2d   asin
     7.2e   atan
     7.2f   ceiling
     7.2g   compound
     7.2h   cos
     7.2i   deg2rad
     7.2j   exp
     7.2k   fact
     7.2l   floor
     7.2m   ln
     7.2n   log
     7.2o   mod
     7.2p   pi
     7.2q   power
     7.2r   rad2deg
     7.2s   rand
     7.2t   round

Universal Forms Description Language                            [page 4]


     7.2u   sin
     7.2v   sqrt
     7.2w   tan
   7.3   Utility Functions
     7.3a   applicationName
     7.3b   applicationVersion
     7.3c   applicationVersionNum
     7.3d   decimal
     7.3e   formatString
     7.3f   isValidFormat
     7.3g   set
     7.3h   toggle
   7.4   Time and Date Functions
     7.4a   date
     7.4b   dateToSeconds
     7.4c   day
     7.4d   dayOfWeek
     7.4e   endOfMonth
     7.4f   hour
     7.4g   minute
     7.4h   month
     7.4i   now
     7.4j   second
     7.4k   time
     7.4l   year

APPENDIX A: QUICK REFERENCE TABLES
   A.1   Table of Items and Form and Page Characteristics
   A.2   Table of Options

APPENDIX B: DEFAULT SIZES

APPENDIX C: UFDL FOR C AND C++ PROGRAMMERS
   C.1   Procedural vs. State Language
   C.2   Globals and Functions (Pages)
   C.3   References and Dynamic Option Reference
   C.4   Arrays
   C.5   Assignment

APPENDIX D: GLOSSARY

AUTHOR CONTACT INFORMATION


1.  INTRODUCTION

    1.1 Introduction to the UFDL

    This document specifies the Universal Forms Description Language
    (UFDL), which describes complex business forms for use over the
    Internet. The objective of the UFDL is to enable the creation of
    cross-platform Internet business forms that (1) contain both the
    complex logic and precise layout that administrators require, (2)
    are simple to maintain and distribute, and (3) integrate easily with
    existing business systems. This document specifies the vocabulary,

Universal Forms Description Language                            [page 5]


    syntax, and meaning of the UFDL.

    Since more and more business is being done over the Internet, the
    need for a form description language that incorporates the
    complexities of business systems is growing. Typically, an
    electronic business form is part of a process-intensive
    administration system. Users or server modules populate forms with
    data, the forms are distributed according to a work flow plan, and
    the data is stored in a database (or, in departments that have no
    complete electronic solution, the form is printed for storage). The
    forms, which can contain hundreds of input items, need to validate
    the data they receive, perform calculations and other logical
    operations, and integrate with existing data management systems.
    Today, most Internet forms are inadequate and are being created with
    HTML.

    HTML is designed for the easy display of Internet pages. As a
    result, HTML is very good at creating the layout for web sites and
    has become the standard for web pages. Web designers and IS
    organizations are now trying to push HTML beyond what it was
    intended to do. HTML forms work well for collecting basic
    information over the Internet. However, most business forms are much
    more complex than the typical HTML order form.

    HTML was not designed to collect, validate, manipulate, or store
    information. In order to build significant intelligence into an HTML
    form, a developer has to use JavaScript. Business forms also may
    need to travel through nodes in distribution chains, being viewed or
    changed by people along the way. HTML forms submit merely the data
    they've collected-the user interface and intelligence don't
    accompany it, and so make it difficult to create a workflow system
    for the form. HTML forms also have a fairly inflexible layout, and
    it's impossible to create precise, complex HTML forms and print them
    the way people are used to.

    The UFDL was designed specifically for Internet business forms. It
    describes all components of a complex form: user interface,
    intelligent features, and input data. A UFDL form can be transmitted
    whole or in part from node to node in a distribution chain. The
    UFDL's precise layout specifications allow users to create and print
    forms that replicate the paper forms they're used to. The UFDL
    includes complex business logic so that intelligent features like
    user-input checking, calculations, and in-form decisions are part of
    the form itself, rather than a separate script, and travel with the
    form to the next user. The UFDL allows developers to extend the
    language to interface with other applications by adding their own
    customized information to forms. The syntax of the UFDL is
    high-level and easy to learn, but at the same time incorporates the
    logic needed for business transactions. C and Java programmers will
    recognize many features of the syntax.


  1.2 UFDL Documentation

    This section outlines how this document is organized, and directs

Universal Forms Description Language                            [page 6]


    readers to other documents on the Universal Forms Description
    Language for further information.

  1.2a How This Document is Organized

    The UFDL Specification is intended both for an academic audience
    and for form developers and people writing applications that use
    UFDL forms.

    For an introduction to the language and its elements, see Part 2:
    Introduction to the Universal Forms Description Language. It
    explains the concepts behind the UFDL and specifies the components
    of a UFDL form. It delineates the UFDL syntax and explains the
    language elements.

    For a full description of form global settings, form items, form
    options, and directives for form viewers, see parts 2, 3, 4, and 5.

    For the Backus-Naur Form (BNF) of the UFDL, see 'Appendix A:
    Grammar of the UFDL'.  C Programmers may find it useful to review
    'Appendix C: UFDL for C and C++ Programmers'.

  1.2b Other UFDL Documentation



    Those who want to find out more about the grammar behind the UFDL
    may want to view or download the Lexical and Syntactical
    Specification for the UFDL.

    Both of these documents are available at http://www.uwi.com/UFDL

  1.3 Requirement Levels for UFDL Elements

    This specification does not contain extraneous material, and
    therefore most implementers of the UFDL will want to include all
    elements specified here. However, not all elements are required,
    though all are suggested.
    This section specifies which elements are REQUIRED, RECOMMENDED, and
    OPTIONAL in an implementation. The criterion for determining whether
    an element of the language is REQUIRED is whether the exclusion of
    the element would prevent people from filling and transmitting the
    form.
    Unless specified in the list below, all elements are REQUIRED. An
    implementation that does not include an element MUST interoperate
    with another implementation that does include the element (though
    perhaps with reduced functionality). In the same vein, an
    implementation that does include the element MUST interoperate
    with one that does not (except, of course, for the feature the
    element provides). Also, before deciding to ignore an element that
    is RECOMMENDED, an implementor must understand the implications
    of not including the element.
    RECOMMENDED Elements (Elements that implementors SHOULD include)
      - bgcolor option
      - fontcolor option

Universal Forms Description Language                            [page 7]


      - labelbgcolor option
      - labelfontcolor option
      - next option
      - previous option
      - printsettings option
    OPTIONAL Elements (Elements that implementors MAY include)
      - help item

      - bordercolor option
      - borderwidth option
      - help option
      - labelbordercolor option
      - labelborderwidth option

      - #include directive
    Note: For a definition of the words REQUIRED, RECOMMENDED, OPTIONAL,
    MUST, SHOULD, and MAY as used in this section, see RFC 2119.

  1.4 Implied Semantics for UFDL Viewers

    There are a few behaviors that are "implied" but not explicit in
   the UFDL, and that are defining features of the UFDL. This section
    outlines those behaviors, and should be considered part of the UFDL
    Specification.
    Temporary Files
      A viewer that uses UFDL forms may create temporary files in the
      following locations:
          - web browser's temp directory
          - Windows temp directory
          - viewer's temp directory
      A viewer MUST NOT create temporary files in any other location
      on a user's computer. This prevents system files or permanent
      user files from being at risk if they're not in temp directories.
      A viewer may delete files from the three temporary directories
      listed above at its discretion, but it MUST delete ONLY files that
      are older than the last reboot of the operating system, or that it
      can positively identify as one of its own temporary files.
      The following UFDL form events may cause a UFDL viewer to create
      and/or delete temporary files: Opening a form; Closing a form;
      Submitting a form (a transaction of type "submit" or "done");
      Emailing a form (if a viewer supports emailing forms); Enclosing
      files; Displaying enclosures.
    Permanent Files
      Certain UFDL form operations require a viewer to read or create
      permanent files. They are: Enclosing a File; Extracting a File;
      and Saving a form. Only button and cell items can initiate these
      operations. Automatic actions MUST NOT initiate actions that
      create permanent files on a user's computer.

      When a viewer performs an enclose, extract, or save operation, it
      MUST conform to the restrictions that follow.

      Enclosures: When the user activates an enclose button or cell, the
      viewer must prompt the user with a file browser so that the user
      can choose which file to enclose. This file browser must allow the

Universal Forms Description Language                            [page 8]


      user to cancel the enclose transaction without writing the
      enclosure into the form. Users may choose to enclose any files to
      which their operating system gives them access.

      Extractions: When the user activates an extract button or cell,
      the viewer must prompt the user with a file browser so that the
      user may choose both a location and a name for the file that's
      being extracted. Other than the usual restrictions on file names
      that the user's operating system imposes, the viewer must not
      restrict the file name the user chooses. If the user specifies a
      file name that already exists, then the viewer must warn the user
      that it exists, and ask the user whether to overwrite the existing
      file. The user must be able to cancel the extract operation before
      the viewer has written the permanent file.

      Saves: When the user activates a save button or cell, the viewer
      must prompt the user with a file browser so that the user may
      choose both a location and a name for the saved form. (Save acts
      like "Save As".) Other than the usual restrictions on file names
      that the user's operating system imposes, the viewer must not
      restrict the file name the user chooses. If there is already a
      file with the file name that the user specifies, then the viewer
      must warn the user that it exists, and ask the user whether to
      overwrite the existing file. The viewer must allow the user to
      cancel the save operation before the viewer has written the
     permanent file.

    These rules have been created in order to allow users to perform the
    enclosures, extractions, and saves necessary when completing
    business forms, while at the same time protecting their computers by
    (a) limiting temporary files to temp directories, and (b) preventing
    uploads and downloads that users are not aware of.

  1.5 Security Considerations

    The UFDL specifies the description of a form, but not the transport
    protocol for transmitting it. Any trasmission security issues that
    exist for the transport protocol submitting the form (for example,
    those used by mail programs and web browsers) exist when
    transmitting a UFDL form. (Note, however, that UFDL forms can be
    compressed using a compression algorithm before they are submitted.
    For more information, see the transmitformat option description.)

    UFDL forms cannot invoke programs on local computer drives. In
    addition, a UFDL viewer must save temporary files to standard
    temp directories only, as outlined in '1.4 Implied Semantics' above.
    A UFDL Viewer may only read and write permament files under strict
    conditions and then only with the user's knowledge (through
    presenting a file browser); see '1.4 Implied Semantics' for more
    information.

  1.6 Responding to Errors in the Form Description

    Any UFDL form interpreter must parse a UFDL form for non-compliance
    to the UFDL specification. This debugger should treat

Universal Forms Description Language                            [page 9]


    non-compliances in the following manner:

    Flag as Warnings - All item types and option types that are not part
    of the UFDL. These must be flagged as warnings and not as errors
    because the UFDL allows developers to create custom items and
    options for inserting application-specific information into forms.
    Forms containing non-compliances that generate warning messages may
    still be displayed. The non-compliances must be ignored when
    displaying the form, and the defaults used instead (if applicable).
    A UFDL Viewer may implement a mechanism that allows users to turn
    off the warning messages.

    Flag as Errors - Anything that might (but also might not) adversely
    affect the appearance or functionality of the form. Forms that
    contain non-compliances that might affect the appearance or
    functionality of the form may be displayed. The non-compliances
    must be ignored, and the defaults (if applicable) must be used
    when displaying the form.

    Flag as Fatal Errors - Anything that will adversely affect the
    appearance or functionality of the form. Forms containing
    non-compliances that generate fatal error messages must not be
    displayed.

    In addition, the UFDL debugger must check the version number of the
    form it parses. The version number denotes which version of the UFDL
    specification the form complies with. The parser must check for
    non-compliances based on the version of the UFDL that the form was
    written with. This provides backwards compatibility.
------



2.   Introduction to the Universal Forms Description Language

  2.1   What is UFDL?

   Summary

     The Universal Forms Description Language (UFDL) is a language that
     describes complex Internet business forms much the way HTML
     describes web pages. It is cross-platform, easy to learn, and its
     features are tailored to business needs.
     Note:  Because UFDL version 4.0 includes the start value element
     in an option name, any code written to work with the UFDL BNF
     version 3.3.1 or earlier will not be able to parse a version 4.0
     form.

   Details
     UFDL is a platform-independent, high-level language that
     describes Internet business forms. It was designed specifically
     for creating forms that are capable of replacing paper forms
     systems. That is, it creates forms that:
      - Create auditable records, by viewing a form as an object that

Universal Forms Description Language                           [page 10]


        includes layout instructions and data, and that can be passed
        whole from node to node in a distribution chain, archived, and
        retrieved later for verification.
      - Let users work offline or online.
      - Perform logical operations, functions, and other behavioral
        changes based on user events.
      - Give users editing and error checking tools.
      - Allow users to digitally sign the whole form or parts of the
        form.
      - Appear the same on any platform and under any screen resolution
        and system font size.
      - Interface with other applications.

   UFDL incorporates the following design concepts:

   Familiar Syntax
    UFDL is easy to pick up, because it is syntactically similar to
    two industry standard programming languages: C++ and Java. Here
    is the description of a very simple UFDL form:

     version = "3.2.0";
     bgcolor = ["ivory"];
     page_1 = new page
     {
        body_label = new label
        {
           value = "This is a UFDL form.";
        }
     }

    Essentially, the form consists of one or more pages. A page
    contains zero or more items, like the label item in the example
    above. The items can be made from item types that are part of UFDL
    (labels, buttons, fields, automatic actions and so on), or from
    item types form designers create themselves. Pages and item types
    have certain default characteristics that form developers can
    modify by specifying various options.

   Declarative Language

    Statements in a UFDL form description are always maintained as
    being true, much as formula fields in a spreadsheet are maintained
    as true. The simplest example of this is a total field that adds up
    the contents of various dollar fields in a form. If one of the
    dollar fields changes, so does the total field.

    What makes UFDL different from languages like C++ and Java in this
    respect is that the constant evaluation of dependencies is inherent
    in the language. A UFDL form requires no special procedures to be
    written in order to run evaluations; the evaluations run
    automatically whenever dependent data changes.

   Extensible Syntax

    UFDL was designed to be easily extensible for both form developers
    and the creators of UFDL.

Universal Forms Description Language                           [page 11]


     - Form developers can create their own item and option types
       within forms (although currently they cannot set up inherited
       attributes for each type they create).
     - The authors of UFDL can add new features to each new version of
       UFDL.

   Open Protocol

    UFDL is an open protocol. This gives developers the freedom to
    manipulate UFDL forms any way they want. Scripts can be written to
    dynamically create forms, modify forms, or extract specific
    information from forms. UFDL forms can themselves make requests to
    databases and populate themselves with the information returned.
    This flexibility allows developers to integrate UFDL forms into any
    application.

    People with knowledge of C or C++ may wish to refer to Appendix D:
    UFDL for C and C++ Programmers. This appendix outlines UFDL's
    similarities to those languages.
------

  2.2   Features of UFDL Forms

    A UFDL form looks and behaves just the way you imagine an
    electronic form should. It can contain graphical elements,
    modifiable fields, and action items. You can organize a UFDL form
    into pages similar to the pages in a paper form and you can include
    navigational aids such as toolbars, tabbing instructions, and
    scroll bars. In addition, you can code the form to make logical
    decisions, to interface with other applications, and to
    automatically format and check user's entries.

    A desktop form viewer application displays the forms. This UFDL
    form viewer allows users to enter input, enclose and view external
    files, and print and save forms. When it is convenient, the user
    can perform a simple action, such as pressing a button, to submit
    the completed form to an application for processing.

    Some of the features that make UFDL forms ideal for every-day
    business use are outlined here.

   Versatile Form Design

    UFDL is very versatile. It provides many features you can use to
    customize both the appearance and functionality of your form.

   Absolute and Relational Positioning Schemes

    UFDL supports both an absolute positioning scheme and a relational
    positioning scheme. The absolute positioning scheme allows a form
    designer to place visible form items in fixed locations on a form.
    This is useful for beginners and for GUI design applications that
    use a drag-and-drop method for designing forms. But an absolute
    positioning scheme is not a cross-platform solution. Used in
    conjunction with relational positioning, however, it can create
    modularized blocks of a form that can be easily moved around.

Universal Forms Description Language                           [page 12]


    UFDL's relational positioning scheme allows designers to create
    forms that appear the same on any platform. It aligns visual
    elements in relation to other visual elements on the form, ensuring
    forms look consistent on all computers and at all screen
    resolutions. If an item changes size-either to accommodate a
    dynamically created value or a system font size-items aligned to it
    will shift in relation to it. This relational positioning scheme is
    flexible, giving developers freedom to create original layouts.

   Support for User-Defined Objects

    UFDL lets designers define their own form objects. These objects
    have no visible properties and initiate no actions, which means
    that form developers can store specialized information in the form
    without harming its appearance or behavior. A form viewer
    application respects references to custom objects in the form
    definition, allowing a custom object to accumulate information and
    also allowing other elements in the form to be altered according
    to the custom object's contents.

   Input and Format Control

    UFDL permits form designers to specify an item's availability, edit
    state, and input and output formats. This means the form can
    perform much of the data checking and formatting typically
    performed by form processing applications.

   Digital Signatures

    Version 4.0 and higher of UFDL supports digital signatures, for
    secure, tamper-proof documents. Digital signatures are incorporated
    into the description of the form, and allow the developer to
    specify that a user may sign the entire form or parts of the form.
    In addition, multiple users may sign a form.

   Automatic Actions

    UFDL supports automatic timed behavior activated by the form. Forms
    can automatically cancel themselves, submit themselves to a server
    for processing, open new forms, and upload information to a server.

    The ability to perform automatic actions provides a mechanism that
    form designers can use to create stated connections with other
    applications. An application typically requiring a stated
    connection is a database management system.

   Logical Operations and Arithmetic Computations

    UFDL uses a set of options to describe a form object's appearance
    and behavior. For example, the option bgcolor describes an object's
    background color. UFDL permits form designers to use literal values
    or logically computed values (called computations) to determine the
    value of an option.

    These computations are resolved when the form appears. You can nest

Universal Forms Description Language                           [page 13]


    computations, employ complex mathematical operations, populate and
    use arrays, and make decisions.

    Computations provide designers with a very powerful and
    sophisticated tool for customizing forms to the needs of individual
    users and applications. It takes very little code (one line per
    logical computation) and it allows decisions regarding a form's
    appearance and behavior to occur at run-time.

   Functions

    UFDL functions allow forms to perform procedural logicas well as
    complex operations that would normally require complicated
    conditional statements. For details, see 7: UFDL Functions".
   Stand Alone Definitions

    All aspects of a form's appearance, behavior, and content are
    integral to the form definition. Therefore, unless you specify
    otherwise, the entire form definition and the user data travel with
    the form when a user submits it for processing. Consequently, you
    can transmit any UFDL form to any site with a UFDL-compliant form
    viewer application and the viewer will display the form correctly.

    The only exception to this rule occurs when the form design
    specifies partial submission of forms. UFDL permits form designers
    to specify partial submissions in one of two ways:

     * by specifying which parts to transmit

     * by specifying HTML format

    Partial submissions help reduce network traffic and transmission
    time.

   Context Sensitive Help

    UFDL provides a mechanism whereby form designers can define help
    messages for individual items in the form. Help messages appear in
    a window overlaying the form.

   Enclosures

    Users can enclose external files in UFDL forms. They can organize
    the files into folders, and they can display, copy, or remove the
    files. Enclosed files are encoded using the base64 encoding
    technique.

    UFDL includes a MIME type with an enclosed file's description.
    This allows form viewer applications to choose an appropriate
    viewer (for example, World Wide Web browser, word processor, etc.)
    when displaying enclosures.
------

  2.3   Description of a UFDL Form


Universal Forms Description Language                           [page 14]


    A UFDL form is a collection of items (for example, buttons, labels,
    amd fields) organized into pages. There are items to display fixed
    values, items to collect user input, items to initiate actions, and
    items to assist with form navigation. The decision about which
    items to place on a page and how many pages to include in the form
    is application dependent.

    UFDL provides a set of options for assigning characteristics to the
    form and to its pages and items. These include such things as the
    behavior, appearance, and location of an item. UFDL defines default
    settings for many of these options, or you can define your own
    settings in the form.

    The following example describes a simple two-page form:
     version = "4.0.0";
     bgcolor = ["ivory"];

     page_1 = new page
     {
        bgcolor = ["seashell"];

        next_page_button = new button
        {
           value = "Next Page";
           url = ["#page_2.global"];
        }
     }
     page_2 = new page
     {
        fontinfo = ["Helvetica", "14", "plain"];

        hello_label = new label
        {
           value = "Hello, world.";
        }
     }

    For information on the syntax rules of a form description, see
     "2.4-Syntax of UFDL"
------

  2.3a   What is a Page?

    A form page is similar to a page in a paper form. Each page
    consists of its own set of items. You can place any number and type
    of items on a page. The number of items, their sizes, and their
    locations determine the size of the page.

       See the discussions of 'Relational and Absolute Positioning'
       and 'Item Placement' for more information on this topic.

    In some senses, pages act like independent forms. They have their
    own size, appearance, toolbars, and characteristics. As well,
    relational positioning of the page's items is based solely on other
    items on the same page.


Universal Forms Description Language                           [page 15]


    The following example shows a page containing a label and a button:
     page_1 = new page
     {
        bgcolor = ["seashell"];


        hello_label = new label
        {
           value = "Hello, world.";
           fontcolor = ["blue"];
        }
        next_page_button = new button
        {
           value = "Next Page";
           url = ["#page_2.global"];
        }
     }

    For more information on the syntax rules of a page description, see
     '2.4-Syntax of UFDL'

   Relational and Absolute Positioning

    UFDL supports two positioning schemes for creating a page image:
    relational and absolute positioning. In the relational positioning
    scheme, each item's location depends on the location and size of
    one or more other items on the page. For example, a field might be
    below and slightly to the right of a label. A series of buttons
    might be placed to appear one after the other.

    In the absolute positioning scheme, each visible item is anchored
    to a particular coordinate on the page drawn on the computer
    screen. Each coordinate represents a distance in pixels from the
    top left corner of the page. In addition, a form designer using
    absolute positioning can offset items from other items.

    Absolute positioning is useful for graphic form design programs
    because it allows users to drag and drop items on a form. It is not
    a good cross-platform positioning scheme, although when used
    carefully in conjunction with relational positioning, it can be
    successful.

    Relational positioning provides cross-platform compatibility in
    UFDL form designs, because all visible items are placed relative
    to each other. Therefore, if any item's size changes because of a
    change in font size or a dynamically generated value, other items
    on the form will shift to accommodate it, while maintaining their
    positions relative to each other.

    For more information, see '2.4f-Item Placement'

   Toolbars

    The toolbar is a separate and fixed area at the top of a page.
    It functions much like a toolbar in a word processing application.

Universal Forms Description Language                           [page 16]


    Typically, you place items in the toolbar that you want users to
    see no matter what portion of the page they are viewing. Toolbars
    are optional and each page has its own toolbar.

    The toolbar and the remainder (or body) of the page operate
    independently of one another. Both are scrollable, and scrolling
    one does not scroll the other. The toolbar can also have different
    characteristics than the page body, and relational positioning of
    toolbar items is based solely on other items on the same toolbar.
------

  2.3b   What is an Item?

    Items are the basic elements of a page. Just as paper forms consist
    of items like lines, boxes, and instructions, UFDL forms consist of
    items like lines, boxes, text fields, labels, buttons, and so on.
    There are two categories of items:

     - external

     - internal or hidden

    A page can include both categories of items.

         See the section 'UFDL Form Items' in section 4.0
         for a description of each item.

    External items occupy space on the page. They can be either visible
    or invisible. Visible items are things users see like labels and
    buttons. Invisible items are things like spacers that create white
    space on the form.

    Internal items are invisible and occupy no space; instead they
    trigger form actions or store data used by other items. Action and
    data items are examples of internal items. An action item initiates
    a transmission, while a data item contains data stored in the form.

         An instance is a particular occurrence of an
         item type. For example, a form may have two
         labels. Each label is an instance of the
         item type 'label'.

    Each type of item has default characteristics. For example, all
    fields will be a certain length and color unless the form developer
    specifies otherwise. A form developer can modify an item's default
    characteristics by adding options to its definition. For example,
    the field described below on the left would have a default
    appearance of 60 characters long and one row high (as well as
    having other default characteristics). On the right, the size
    option added to its description overrides that default size.

     date_field = new field
     {
     }


Universal Forms Description Language                           [page 17]


     date_field = new field
     {
       size = ["20", "1"];
     }
     Field using default characteristics only
     Modified size overriding the default size

    There are defaults for most item characteristics. If the defaults
    meet your requirements, an item definition may include only the
    instance identifier, a unique item tag. Instance identifiers are
    mandatory. They are critical to the relational positioning scheme.
    For that reason, UFDL incorporates the identifier into the syntax
    of an item definition.

    An item's definition includes:
     - An instance identifier (an item tag that uniquely identifies
       it).
     - An open brace following the item declaration.
     - A close brace at the end of the definition (after the options,
       if there are any).
     - Optional information giving the item characteristics, including
       its position on the page, graphical characteristics and size,
       initial value and edit state, and instructions for handling the
       item when the form is submitted. Because these characteristics
       are optional, the lines that specify them are called options.

    Here is a sample of an item description:


     date_field = new field
     {
      size = ["20", "1"];
      label = "Today's Date";
      format = ["date", "long"];
      value = "*";
      itemlocation = [["after", "name_field"]];
      }

    For more information on the syntax rules of an item's description,
    see '2.4-Syntax of UFDL'
------

  2.3c   What is an Option?
         See the section 'UFDL Form Options' in section
         4.0 for a description of each option.

    An option defines one characteristic of a form, a page, or an item.
    There are options to specify each aspect of the appearance and
    behavior of your form. Some options apply to the entire form,
    others apply only to items, and still others apply to pages or
    items. The example below shows options giving characteristics to an
    entire form, to a page, and to a particular item.

     version = "3.2.0";
     bgcolor = ["ivory"];

Universal Forms Description Language                           [page 18]


     page_1 = new page
     {
     ...
     page_1 = new page
     {
     bgcolor = ["seashell"];

     bar_box = new box
     {
     ...
     bar_box = new box
     {
     bgcolor = ["black"];
     size = ["60", "5"];
     }
     ...

    Options that appear at the top of the form, like the example on the
    far left, are called global settings. They apply to the whole form.

    Options that appear at the top of a page, like the example in the
    center, are called page settings. They apply to the entire page.
    Page settings override any similar global settings-but only for the
    page on which they occur.

    Options within items, like the example on the far right, apply only
    to the item whose description they are in.
------

  2.3d   Including External Files

         See the '#include' section in section 2.8a for a
         description of the '#include' statement.

    The UFDL #include statement allows you to include external files in
    your form definition much as you would include header files in a
    C language source file. The form viewer application replaces the
    #include statement with the contents of the file you specify. The
    included file must reside in a secure include directory accessible
    to the form viewer application.
------

  2.3e   Unrecognized Items and Options

   User-Defined Items and Options and Newer UFDL Items and Options
    As a UFDL form viewer parses a form, it ignores items and options
    it does not recognize. This feature has a number of advantages.

     * It allows a form designer to include items and options for new
       form viewer applications without affecting the form's behavior
       in other viewers.

     * Form processing applications can use the custom items and
       options when processing the form. One example of a custom item
       might be an SQL query item the application uses to populate a

Universal Forms Description Language                           [page 19]


       response form.

    Unrecognized items and options include:

     * User defined (or custom) items and options.

     * Items and options from releases of UFDL that are newer than the
       user's form viewer application understands.
-----

  2.4   Syntax of UFDL

  2.4a   Basic Syntax Rules

    The basic syntax rules of UFDL are:

     * It is case sensitive.

     * It ignores white space around and within statements.

     * It permits multiple line statements.

     * It permits multiple statements per line.
------

2.4b   Form Definition

    The syntax of a UFDL form definition is as follows:

     <version definition statement>*
     <option definitions for the form characteristics>
     <page definition1>
     ...
     <page definitionn>**

     * mandatory statement. See 'version' on page 226 for the syntax of
       this statement.
     ** there is no limit placed on the number of page definitions in a
        form; however, every form must contain at least one page
        definition.

    For example,
     version = "3.2.0";
     bgcolor = ["ivory"];
     fontinfo = ["Helvetica", "10", "plain"];

     //This is page 1
     page_1 = new page
     {
        <option definitions for the page settings>
        <item definitions for items located on page 1>
     }

     //This is page 2
     page_2 = new page

Universal Forms Description Language                           [page 20]


     {
        <option definitions for the page settings>
        <item definitions for items located on page 2>
     }
     ...

     //This is page 10
     page_10 = new page
     {
        <option definitions for the page settings>
        <item definitions for items located on page 10>
     }

    Defining global settings for the form is optional. It has the
    effect of setting characteristics that apply to the entire form. In
    the previous example, version, bgcolor, and fontcolor are global
    settings. These characteristics override the defaults defined by
    UFDL. Specific pages and items will override these global settings
    if the same option has been defined differently for that page or
    item.
------

  2.4c   Page Definition

    The syntax of a page definition is as follows:
     <page tag> = new page
     {
        <option definitions for the page characteristics>
        <item definition1>
        ...
        <item definitionn>
     }
     Notes:
     i) The braces are mandatory.
     ii) A page definition must begin on a new line.
     iii) Item definitions are optional and there is no limit placed
     on the number of item definitions in a page.

    The page tag uniquely identifies a page instance. No two page tags
    in a form can be the same. See the section 'Identifiers' on page 39
    for tag naming conventions.

    Defining page characteristics is optional. It has the effect of
    setting options that are global to that page. These characteristics
    override the defaults defined by UFDL and any global options set by
    the form characteristics. Specific items will override the page
    settings if the same option has been defined differently for that
    item.

    In the following example, you can see a sample page definition.
    The page tag is Page_one and the page contains a label and a
    button. The page has a background color of cornsilk and each item
    on the page will have a font of Times 14.

     Page_one = new page
     {

Universal Forms Description Language                           [page 21]


      bgcolor = ["cornsilk"];
      fontinfo = ["Times", "14", "plain"];
      button_label = new label
      {
        <option definitions for the label characteristics>
      }
      save_button = new button
      {
        <option definitions for the button characteristics>
      }
     }
------

  2.4d   Item Definition
    The syntax of an item definition is as follows:
     <item tag> = new <item type>
     {
      <option definition1>
      ...
      <option definitionn>
     }
     Notes:
     i) The braces are mandatory.
     ii) An item definition must begin on a new line.
     iii) Option definitions are optional.
     iv) You cannot assign values to options in other item definitions.

    The item tag uniquely identifies an item instance. No two item tags
    on a page can be the same. See the section '2.5a-Identifiers'
    for tag naming conventions.

    Item type is a name that identifies the type of item. Examples of
    item types are: button, label, field, line, and check. See the
    section 'UFDL Form Items' on page 58 for a description of each item
    type.

         Tip: You can also define and use your own
         item types and options. See the '<custom>'
         item and option descriptions later in this
         manual.

    There is a finite list of UFDL-defined options applicable to each
    type of item. You can code as many or as few from the list as you
    wish. There are default settings for most options (defined by
    UFDL). You may choose to use those defaults or to define your own
    settings. Defining your own settings overrides the defaults.

    You can also create your own item types. A UFDL parser will ignore
    these custom item types, but you can use them to store information
    specific to your application, and then refer to them in other item
    descriptions in the form. For more information on how to refer to
    options in the form, see 'Referring to Other Options' later in this
    section.

    In the following example, you can see a sample button definition.

Universal Forms Description Language                           [page 22]


    The button has the following characteristics:

     * The item tag is save_button.

     * It will save the form to a file on the user's workstation.

     * The button's label is Save Form.

     * The background color is cyan.

     * The font used for the label is Helvetica 12.

     save_button = new button
     {
      bgcolor = ["cyan"];
      fontinfo = ["Helvetica", "12"];
      type = "save";
      value = "Save Form";
     }
------

  2.4e   Item Size

    Every external item has a characteristic shape. Many items also
    contain data such as text and images. This is the basic item. For
    example, the basic field is a rectangular space where users can
    input text. Buttons are rectangular objects containing a
    descriptive label.

    Items may also contain the following elements:

     * borders

     * an external label

     * scroll bars

    Borders are lines outlining an item's shape. Their use is optional
    and their thickness is variable.

    External labels are part of an item's definition but they occupy
    their own space. An example of an external label is the label you
    define for a field. This label occupies space above the field item.

    Several types of items permit users to scroll the data the item
    contains. Typically, scroll bars appear with these items. Examples
    of items permitting scrolling are fields and lists.

   Size Calculation
    There are two sizes calculated for an item. They are:

     * basic item size

     * the item's bounding box

    The basic item size is composed of the item's characteristic shape

Universal Forms Description Language                           [page 23]


    and any imbedded data. UFDL defines a set of default basic item
    sizes. You can choose to use these defaults or you can define the
    size using the size option. When deciding whether to define the
    size and what size to specify, you will want to consider any data
    imbedded in the item.

    The bounding box is an unseen rectangular area surrounding each
    item and including all elements of the item. The size of the
    bounding box depends on the sizes of the various elements. UFDL
    calculates this size, taking into account the basic item size and
    the existence and size of the various optional elements. For
    example, if the item definition contains a borderwidth setting
    (meaning the item has a border), then the bounding box size
    encompasses the basic item and the space occupied by the border.

    See 'Appendix B: Default Sizes' for the default item
    and bounding box sizes.

   Altering Size Dynamically
    You can dynamically alter the bounding box size, and thus the basic
    item size and the space available for the external label. The
    itemlocation option contains various directives permitting you to
    do this.

         An item's vertical center is halfway between
         the top and bottom edges. The horizontal
         center is halfway between the left and right
         edges.

    A bounding box has six edges: left, right, top, bottom, vertical
    center, and horizontal center. You can align any of these edges
    with the edge of another item's bounding box (called a reference
    item in this context). Once you have aligned one edge, you can
    expand the bounding box until the far edge aligns with another
    location. In this manner, you override the bounding box length in
    that direction.


     Aligning horizontal centers    Expanding right edge to right edge

    For example, you can align the left edge with the horizontal center
    of one reference item. You can then expand the right edge until it
    aligns with the right edge of the original reference item or a
    second reference item. This pair of directives sets the bounding
    box width.
------

  2.4f   Item Placement

    UFDL supports two different positioning schemes to place external
    items on a page: relational positioning and absolute positioning.

    Relational positioning means an item's location depends on the
    location and size of one or more other items on the page. This
    feature is similar to the mechanism used for dynamic sizing.

Universal Forms Description Language                           [page 24]


    Relational positioning uses the bounding boxes of the other items
    as reference points. Items align relative to these bounding boxes.
    You must define the location of the other items before you can use
    them as reference points.

    The itemlocation option provides various directives you can use to
    specify an item's location. For example, you might place an image
    before a radio and expand its bottom edge to the bottom edge of
    the radio button.


         Positioning the image before radio buttons
         Expanding the bottom of the image to the bottom of the radio
         buttons.

    The only items whose placement is not affected by relational
    positioning are the first item in the toolbar and the first item in
    the body of the page. The first item assigned to the toolbar goes
    in the top left corner of the toolbar. The first item not assigned
    to the toolbar goes in the top left corner of the body.

    Absolute positioning places an item in an absolute position on the
    page, anchoring it to a particular coordinate. This coordinate is
    a pair of pixel measurements defining the item's distance from the
    top left corner of the page.

    Absolute positioning also allows items to be offset from their
    original position, in order to make layout with an absolute
    positioning scheme more flexible. When offsetting an item, the form
    developer first places the item on the page and then specifies how
    far it should be offset from that position.

    The absolute positioning scheme's advantage is that it makes
    designing a drag-and-drop form designer easy. Absolute positioning
    is not a good cross-platform solution, however, and in order to
    ensure that forms appear consistent on all platforms, developers
    should use either strictly the relational positioning scheme, or a
    careful combination of relational and absolute positioning.

    For more information, see the itemlocation option description in
    section 5.19.
------

  2.4g   Toolbar Definition

    A toolbar is a section that stretches across the top of a page in
    which items can be placed for quick access. If a user scrolls down
    on a page, the toolbar remains visible.

    A user defines a toolbar using the toolbar item. Each page can have
    one toolbar, and the toolbar will appear on only that page. Place
    items in the toolbar by using the within modifier of the
    itemlocation option.

    The following example shows the definition of a toolbar with two

Universal Forms Description Language                           [page 25]


    items: a label and a close button.
     p1_toolbar = new toolbar
     {
      bgcolor = ["cyan"];
     }
     title_label = new label
     {
      value = "Student Registration Form";
      fontinfo = ["Helvetica", "16", "bold"];
      itemlocation = [["within", "p1_toolbar"]];
     }
     close_button = new button
     {
      type = "close";
      value = "Close Form";
      itemlocation = [["within", "p1_toolbar"], ["below", "title_label"],
                           ["alignhorizc2c", "title_label"]];
     }
------

  2.4h   Option Definition

    An option definition is an assignment statement that assigns one
    characteristic to an item, a page, or to the whole form. The
    expression on the right hand side of the equal sign contains the
    option's setting. The syntax of an option definition statement is
    as follows:

     <option identifier> = <expression>;
     Note: The semicolon is mandatory and terminates the statement.

    For example:
     value = "Submit Form";
     fontinfo = ["Helvetica", 16", "bold"];
     url = global.global.db_address

   Explanation of Syntax
    Option identifier is a name that identifies the type of option. It
    can be a UFDL-defined option or a user-defined option. Examples of
    option identifier are: bgcolor, fontinfo, itemlocation, and size.
    See the section 'UFDL Form Options' in section 5 for a description
    of each option and its possible values.

    An expression specifies a value. An expression can be any of the
    following:

     * a literal
        (for example, the right hand side of
         value = "Submit Form"; )
     * a reference to another option definition in the form
        (for example, the right hand side of
         url = global.global.db_address; )
     * an operation
        (for example, the right hand side of
         value = total_field.value + "3400"; )

Universal Forms Description Language                           [page 26]


     * an array specification
        (for example, the right hand side of
         fontinfo = ["Helvetica", "16", "bold"]; )
------

  2.4i   Literals

    Specify a literal as a quoted string. This is true even for
    operands of an operation. Examples of using literals are:
       "V3.2.0" - yields "V3.2.0"
       "1" + "2"- yields "3"
       "UFDL\\" +. "form1"- yields "UFDL\\form1"
------

  2.4j   References to Other Options

    In order to copy information from one place in the form to another,
    or to make a decision based on the contents of items in the form, a
    developer needs to refer to one or more other options in the form.

    This is done using an option reference. The referenced option
    definition can exist anywhere in the form definition, including
    after the current statement.

    For examples of option references, see the paragraphs following the
    box below.

    An option reference has several possible formats:

      1.for options in the current item definition use one of the
        following:*
        *       <option reference>
        *       <option reference>-><option reference>
      2.for options in another item definition use one of the following:*
        *       <item reference>.<option reference>
        *       <item reference>.<option reference>-><option reference>
      3.for options in page characteristics use one of the following:
        *       global.<option reference>
                - for characteristics on the current page
        *       <page tag>.global.<item reference>
                - for characteristics on another page
      4.for options in form characteristics use:
                global.global.<option reference>
        where <option reference> is one of:
        *       <option identifier>
                - for the complete option setting (it can be a single
                  value or an array)
        *       <option identifier>[<array element>]
                - for one element of an array**
        and <item reference> is one of:
        *       <item tag>
                - for items on the current page
        *       <page tag>.<item tag>
                - for items on another page

        and the indirect membership operator (->) indicates:

Universal Forms Description Language                           [page 27]


        *         a dynamic option reference

    *  The phrase '-> <option reference>' can occur any number of times
       on the right hand side of an option statement.
    ** See 'Array References' in section 2.4n for information on
       <array element>.

    In order to refer to an option that varies depending on what the
    user of a form enters, use a dynamic option reference. For example,
    a form developer cannot know what cell a user will choose in a
    popup menu. To refer to the value of whatever cell the user
    chooses, the developer must use a dynamic option reference.
    For example:

     popup_menu.value->value

    A dynamic option reference (-> <option reference>) provides a
    mechanism for determining the location of the option at run-time.
    The references preceding the indirect membership operator must
    resolve to an item reference or a reference to the form or page
    characteristics.

    Examples of option references are:

      - an item on the current page:
         list_one.value
        This identifies the value option of the item whose item
         reference is list_one.

      - a form characteristic:
         global.global.bgcolor
        This identifies the bgcolor option specified at the top of the
        form, as a form global characteristic.

      - a dynamic option reference with one level of indirection:
        The my_choice.value setting becomes the item reference for the
        bgcolor option. If, for example, my_choice.value contains
        "global", then this reference is equivalent to global.bgcolor.

      - a dynamic option reference with two levels of indirection:
         my_choice.value->value->bgcolor
        The my_choice.value setting becomes the item reference for the
        value option. If, for example, my_choice.value contains
        "your_choice", then my_choice.value->value is equivalent to
        your_choice.value.

    If your_choice.value contains "page_two.global", then the complete
    reference is equivalent to page_two.global.bgcolor.
------

  2.4k   Relative Page Tags and Item Tags

    UFDL contains a way to refer to pages and items without using
    specific identifiers: relative page tags and item tags.
    For example:

Universal Forms Description Language                           [page 28]


     value = itemnext->value;

     itemlocation = [["after", itemprevious]];

     url = ["#"+.global.pagenext->global];

     url = [global.global->pagefirst->itemfirst->url[0]];

   Refering to items and pages that don't exist yet
    Relative page tags and item tags are particularly useful if you are
    making template forms for an application that dynamically generates
    extra items and pages during run time.

    Since dynamically-generated items and pages don't exist until
    runtime, you cannot refer to them by name when you are coding the
    template form (since you don't necessarily know what name the
    generation program will use). Relative page tags and item tags
    allow you to refer to non-existent pages and items.

    For example, you might want to add a paging button that opens the
    next page of a form when the user clicks it. Normally, if your next
    page was called page_2, you'd set up the paging button's url to:
     url = ["#page_2.global"];

    But if the next page will be dynamically generated by a program,
    you don't know what page tag to put in the url. So you would use
    a relative page tag, like this:
     url = ["#"+.global.pagenext->global];

    Available relative page tags and item tags

    pagefirst

      Meaning First page in form description.
      Reference must start at Form global (global.global).
      Example
      url = [global.global->pagefirst->submitButton.url[0]];

    pagelast

      Meaning Last page in form description.
      Reference must start at Form global (global.global).
      Example
      value = global.global.pagelast->resultField.value;

    pageprevious

      Meaning Previous page in form description.
      Reference must start at Page global (global).
      Example
      url = ["#"+.global.pageprevious->global];

    pagenext

      Meaning Next page in form description. The last page points to
       the first page.

Universal Forms Description Language                           [page 29]


      Reference must start at Page global (global).
      Example
      url = ["#"+.global.pagenext->global];

    itemfirst

      Meaning First item in page description.
      Reference must start at Page global (global).
      Example
      value = global.itemfirst->value;

    itemlast

      Meaning Last item in page description.
      Reference must start at Page global (global).
      Example
      value = global.itemlast->value;

    itemprevious

      Meaning Previous item in page description. First item points to
       last item in page description.
      Reference must start at Item level.
      itemlocation = [["after", itemprevious]];

    itemnext

      Meaning Next item in page description. Last item points to first
       item in page description.
      Reference must start at Item level.
      Example
      value = itemnext->value;

   Rules for creating references using relative tags

    To create references using relative page tags and item tags:

     1. Follow the normal rules for page, item, and option references
        (see "References to Other Options" earlier in this section),
        except apply the rule in 2, below.

     2. Use the dereference symbol ( -> ) following the relative tag,
        if the tag is followed by another tag. For example:
         itemlocation = [["after", itemprevious]];
        but
         value = itemprevious->value;
        and
         value = global.global.pagefirst->itemfirst->value;

    If you do not use the dereference symbol, a UFDL parser will
    evaluate the relative tag as an option name.
------

2.4l   Operations


Universal Forms Description Language                           [page 30]


    An operation is a calculation or a decision. The syntax of a
    calculation is one of the following:
      1.<operand> <math operator> <operand>
      2.<operand>

    Operands that are numbers can have a unary minus. An operand can
    be any of the following:
        - a literal (for example, "3")
        - a reference to another option (for example, total_field.
          value)
        - a calculation (for example, "total_field.value" *"4")
        - (<decision>) - see below for the syntax of a decision

    A math operator can be any of the following:
        - additive operator
        - multiplicative operator
        - exponentiation operator
    See the table of operators below.

    The syntax of a decision is as follows:

     <comparison> ? <expression> : <expression>
     where <comparison> is:
        - <Boolean> <logical operator> <Boolean>
     and <Boolean> is:
        - <operand> <relational operator> <operand>
    Note: See the table below for the definition of logical and
          relational operators.

    In decisions:
        * An operand can have a logical NOT (!) before it.
        * An expression cannot be an array.

    Some examples of decisions are:
        * A decision based on a check box.
          male_check == "on" ? "male" : "female"
    If the check box is selected, or on, then the result will be male.
    Otherwise, the result will be female. This decision could be used
    to set an item's value.
        * A decision based on a value.
          name_field == "Smith" ? "on" : "off"
    If the name entered into the name field is Smith, then the result
    will be on.  Otherwise, the result will be off. This decision
    could be used to set an item's active status.

    UFDL recognizes the following operators:

     Type of Operator        Symbol         Operation

     Additive             +             addition
                          -(minus)      subtraction
                          +.            concatenation
     Multiplicative       *             multiplication
                          /             division
     Exponentation        ^             exponential

Universal Forms Description Language                           [page 31]


     Relational           >             greater than
                          <             less than
                          <=            less than or equal to
                          >=            greater than or equal to
                          ==            equal to
                          !=            not equal to
     Logical              &&            AND
                          ||            OR
                          !!            NOT
     Unary Minus        -(minus)        take negative
     Decision           x?y:z           Assign the value of expression
                                        y to the result if expression x
                                        evaluates to true.  Otherwise,
                                        assign the value of expression
                                        z to the result.
     Assignment           =             Assign right operand to left
                                        operand
     Membership           .(dot)        structure membership
                          []            array membership
                          ->            indirect membership




   Precedence of Operations
    Operations are evaluated in the following order:
        - membership
        - exponentiation*
        - multiplicative and unary minus*

    Universal Forms Description Language                           [page 15]


        - additive
        - relational
        - logical NOT
        - logical AND
        - logical OR
        - conditional

    Operations at the same level of precedence are evaluated from left
    to right.
    Parentheses override the precedence levels; however, operations
    within parentheses are evaluated using the normal precedence
    levels.

         - When a unary minus immediately follows an
           exponentiation symbol (^), the unary minus
           is evaluated first. For example, 10^-5 is
           evaluated as ten-to-the-minus-five.

   Concatenation
    An addition operation may imply concatenation. If either operand in
    the addition contains a non-numeric value, the operands are
    concatenated. Otherwise they are added arithmetically. You only
    need to use the concatenation operator if both operands are, or can
    be, numeric values.


Universal Forms Description Language                           [page 32]


    The following examples demonstrate this rule:
     "UFDL\\" + "form1"  -yields "UFDL\\form1"
     "UFDL\\form" + "1" - yields "UFDL\\form1"
     "1" + "2"  -yields "3"
     "1" +. "2" -yields "12"

    The last example would not have resulted in concatenation without
    using the concatenation operator.

   Separators

    There are two separators in UFDL: comma (,) and semicolon (;).
    The comma separates list entries; the semicolon terminates an
    option definition statement.
------

  2.4m   User Events and Changes of State

    An "event" is the user's act of causing the state of something in
    the form to change. For example, when the user clicks a check box,
    its state changes from being unchecked (or off), to being checked
    (or on). This act of causing the state to change from off to on is
    the event.

    Other examples of events are:
     - The user moves the mouse pointer over a button and its state
       changes from not having the mouse pointer over it to having the
       mouse pointer over it.
     - The user switches from the first page to the second page in a
       form, and the state of the first page changes from being active
       to being no longer active, while the state of the second page
       changes from not being active to being active.

   Recording Changes of State

    All states in a UFDL form are recorded in options.

    For example, in check boxes the state of "being-checked or not" is
    recorded in the value option. When a user checks a check box, its
    value changes from off to on. For all visible items, all pages,
    and for the entire form, the state of "having the mouse pointer
    over me or not" is recorded in the mouseover option.

    This provides a form developer with enormous potential for creating
    intelligent forms that set and change themselves dynamically, based
    on changes of state. Those changes can be changes of user input
    (such as checking a check box), or simply changes of user behavior
    (such as moving the mouse pointer over a button).

   Example
    The following example illustrates using an event (a change of state
    caused by the user) to trigger self-modifying behavior in the form:
     saveButton = new button
        {
         type = "save";
         value = "Save";

Universal Forms Description Language                           [page 33]


         bgcolor = [mouseover=="on" ? "white" : "gray90"];
        }
    The bgcolor option in the button above will change from gray to
    white when the user moves the mouse pointer over the button.
------

  2.4n   Arrays

    UFDL uses arrays to store values in options requiring multiple
    settings. The number of elements and the number of dimensions in an
    array depend on the option. However, the syntax of the language
    supports n-elements and n-dimensions. Moreover, UFDL supports
    arrays containing a mix of simple elements and sub-arrays.

    The syntax of an array is as follows:
     [<element1>, <element2>, ... <elementn>]
     Note: 'n' is the number of settings in the option.

    An element can be either of the following:
        - an expression
        - an element definition statement

   Element Definition Statements
    The element definition statement allows you to assign a variable
    name to an element. Variable names permit you to refer to the
    element by name rather than by its position in the array. The
    syntax of an element definition statement is:
     <variable> = <expression>

    UFDL syntax includes variable names in some arrays. In this case,
    you must use an element definition statement when assigning values
    to the element. For example, the format option syntax specifies
    names for the check option's range, length and template. To assign
    values to any of these elements, you must use the name specified
    in the syntax.

    Examples of assignment statements using element definition statements:

     using a UFDL-defined variable name
        format = ["integer", range=["1","100"]];
     using a user-defined variable name
        delay = [the_repeat = "once", the_time = "10"];
     using both UFDL-defined and user-defined variable names
        format = [the_type = "string", length = ["5", "25"]];
    Array elements for UFDL-defined option types must be coded in the
    position they are documented in this specification, unless they
    have UFDL-defined variable names listed in this specification. For
    example, the elements for the size option must always be in the
    order [width, height], but the elements for check and format types
    in the format option can be in any order, since they have
    UFDL-defined variable names.

   Decisions in Arrays

    A decision can be used to determine any element within an array, so

Universal Forms Description Language                           [page 34]


    long as that element is not itself an array.

    For example, the following format line is valid.
     format = [check_1.value == "on" ? "string" : "integer"];

    The decision sets the data type to be a string if check_1 is "on",
    or an integer if it is "off".

    This format line is not valid:
     format = ["integer", check_1 == "on" ? range = ["10","20"] :
     range = ["0","10"];

    The range is itself an array, so a decision cannot be used to
    determine which range should apply.

   Array References
    The syntax of an array reference is:
     <array name>[<array element>]
     Note: Repeat the phrase '[<array element>]' until reaching the
           desired depth.

    Array name is an option or variable identifier. Array element can
    be one of two things:
        - a number indicating the position of the element in the array
        - variable name

    Before using a variable name, you must define the name in an
    element definition statement. See the section 'Element Definition
    Statements' in section 2.4n for more information.

    UFDL array starting position is 0; therefore, a reference to the
    first element of the array is really a reference to element zero
    (0).

    The following examples show various array assignments and
    references:

     itemlocation = [["below", "field1"], ["alignl2l", "field2"],
                    ["alignr2c", "field3"]];
        itemlocation[0][1]                      - points to "field1"
        itemlocation[2][0]                      - points to "alignr2c"
     itemlocation = [the_pos= ["below", "field1"], the_align=
                    ["alignl2l", "field2"]];
        itemlocation[the_pos][1]        - points to "field1"
        itemlocation[the_align][0]      - points to "alignl2l"
     format = ["integer", range=["1","10"]];
        format[0]                       - points to "integer"
        format[range]                   - points to ["1", "10"]
     format = ["integer", range=[the_low="1", the_high="10"]];
        format[range][the_low]          - points to "1"
------

  2.4o   Defining Tabbing and Paging

    UFDL provides two mechanisms for defining the movement between
    pages and items in a form.

Universal Forms Description Language                           [page 35]


        - tabbing to the new item or page
        - linking to the new page
    You can combine these methods or you can choose to use only one.

         The item in focus is the item with the
         cursor and, often, with some form of
         highlighting.

    Tabbing permits the user to move from one item to another and from
    one page to another using a keystroke. Linking permits the user to
    select a form item whose action moves the focus to a new page.

    Note: The only items users may tab or link to are modifiable items.
    These are items users can change or select.

   Tabbing

    To use tabbing, define a tabbing sequence using the next option.
    The sequence can include items anywhere in the form. Define the
    tabbing sequence this way:
        - Define the first item in the sequence by including the next
          option in the form characteristics. When the form opens, the
          page containing this item displays with the item that is in
          focus.
        - Define each subsequent item by including the next option in
          the definition of each item in the sequence.
    The next option setting is the item reference of the next item to
    receive focus (that is, the referenced item). When the user tabs
    from the current item, the referenced item receives the focus. If
    the item is on a different page, the current page closes and the
    new page displays.

    You can use tabbing to display a new page without choosing an item
    to activate. Set the next option to the characteristics reference
    for the new page. This displays the new page and focusses on the
    first item in that page's tabbing sequence. The page
    characteristics reference is <page tag>.global.
        - Define the first item in a page's tabbing sequence by
          including the next option in the page characteristics.

    This example shows a simple tabbing sequence:

     version = "4.0.0";
     // Open the form on page 'page_one' and focus on 'title_list'.
     next = "page_one.title_list";
     page_one = new page
     {
      // Define the default first item in this page's tabbing sequence.
      next = "name_field";
      bgcolor = ["LightBlue"];
      form_title = new label
       .......
      }
      title_list = new list
      {

Universal Forms Description Language                           [page 36]


       // Tab to the 'name_field' item from here.
       next = "name_field";
       ......
      }
      name_field = new field
      {
       // Tab to the 'your_signature' item on 'page_two' from here.
       next = "page_two.your_signature";
       ......
      }
     }

     page_two = new page
     {
      bgcolor = ["PaleGreen"];
      form_title = new label
      {
       ......
      }
      your_signature = new tablet
      {
       // Tab back to page 'page_one' and focus on the first item
       // in the page_one tabbing sequence.
       next = "page_one.global";
       ......
      }
     }

   Linking

    To use linking, define action, button, or cell items for the links
    you want to include in the form, and set their type option to
    pagedone. Since each item performs only one link, you require a
    separate action, button, or cell for each link. This method is
    often best suited to defining links to new pages.

    When you link to a new page, do one of the following:
        - Specify an item on the new page for the focus to move to.
        - Specify that the focus move to the default position on the
          new page, by "linking" to the page characteristics section.
    Store the reference of the linked item or page in the url option of
    the action, button, or cell. The reference is an item reference or
    a page characteristics reference. Use an item reference when you
    want to link a specific item. Use the page characteristics
    reference when you want to link the first item in the page's
    tabbing sequence. A page characteristics reference is <page tag>
    .global.

    When the link occurs (i.e., a user selects the button), the current
    page closes and the linked page appears. Before the current page
    can close, all fields containing error checking must be correctly
    filled in.

    This example shows how you might use linking:

     version = "4.0.0";

Universal Forms Description Language                           [page 37]


     // Open the form on page 'page_one'. Allow the first item in the page's
     // tabbing sequence to receive focus.
     next = "page_one.global";
     page_one = new page
     {
      // Define the default first item in this page's tabbing sequence.
      next = "name_field";
      bgcolor = ["LightBlue"];
      form_title = new label
      {
       .......
      }
      name_field = new field
      {
       ......
      next_page = new button
      {
       value = "Page 2";
       // Link to the next page. Allow the first item in the page's
       // tabbing sequence to receive focus.
       type = "pagedone";
       url = "#page_two.global";
       ......
      }
     }

     page_two = new page
     {
      // Define the default first item in this page's tabbing sequence.
      next = "your_signature";
      bgcolor = ["PaleGreen"];
      form_title = new label
      {
       ......
      }
      your_signature = new tablet
      {
       ......
      }
      first_page = new button
      {
       value = "Page 1";
       // Link to the first page. Allow the first item in the page's
       // tabbing sequence to receive focus.
       type = "pagedone";
       url = "#page_one.global";
       ......
      }
     }

   UFDL-Defined Default Paging and Tabbing Sequence

    UFDL-defined default sequence depends on the order in which you
    define pages and items in the form. The default first page is the
    first page defined in the form. The default first item is the first

Universal Forms Description Language                           [page 38]


    item defined for the body of that page.

    The sequence progresses through the page definition moving from one
    modifiable item to the next. If a user tabs past the last
    modifiable item on the page, focus returns to the first modifiable
    item in the page's toolbar (if one exists) or the first modifiable
    item on the page. The default sequence does not permit you to move
    between pages.

    UFDL permits you to define pages and items in any order, regardless
    of when and where they display. If you define your pages and items
    in a random order, the default sequence may result in apparently
    random movement.
------

  2.4p   Including External Files

    You can code a #include statement anywhere in a form definition
    except imbedded in another statement. You can also nest #include
    statements. See the section 'UFDL Form Viewer Directive' in section
    6.1 for a syntax of the #include statement.

    In the following examples, you can see the #include statement used
    in a variety of locations.

     // Use the standard defaults for v3.2.0 forms. This include file
     // contains the 'version' option statement and the default 'url'
     // option statement.
     #include "v3form.txt"

     page_one = new page
     {
      // Page one must contain the company logo. This include file
      // contains the 'label' and 'data' item definitions.
      #include  "co_logo.txt"

      // The remaining items are specific to this form.
      ...
     }

     // The last page is standard for all company forms. Use the
     #include "lst_page.txt"
     }
------

  2.5   UFDL Language Elements

  2.5a   Identifiers
    Identifiers are the names you assign to the following entities:
        - page tags
        - item tags
        - option names
        - variable names
        - datagroup names
        - group names

Universal Forms Description Language                           [page 39]


    The naming conventions for an identifier are as follows:
        - It must begin with an alphabetic character.
        - It can contain any of the characters A-Z, a-z, 0-9, $ and
          underscore.

    An example of a valid identifier is sql_query.
------
  2.5b   Custom Item Types and Custom Option Names

    These are the names you assign to your own items and options. The naming conventions for a custom name are as follows:
        - It must begin with an alphabetic character.
        - It can contain any of the characters A-Z, a-z, 0-9, $ and underscore.
        - It must contain an underscore.
------
  2.5c   Reserved Words

    UFDL reserves the following words for its own use:
        - UFDL item, option and variable names
        - global
        - page
        - new
------
  2.5d   Quoted Strings

    The syntax of a quoted string is:
     "<character string>"

    The minimum length of the string is one (1) byte; the maximum
    length is the lesser of two gigabytes (231 - 1 bytes) and the
    amount of memory the system will allocate.

    Long quoted strings can span multiple lines. To code a multiple
    line string, break the string into segments and surround each
    segment with quotation marks. A reasonable segment length might be
    the maximum line length permitted in your text editor.

    The following example shows a multiple line quoted string in an
    assignment statement. UFDL treats the segments as contiguous,
    ignoring any white space between them.

    value = "This example demonstrates the use of quoted strings "
            "that span multiple lines.";

    Some characters, such as tabs and line delimiters, are invalid in
    a quoted string unless you use an escape sequence. All escape
    sequences begin with the escape character (\). The following table
    shows the escape sequences UFDL recognizes and the characters they
    represent.

    Escape       Character      Comments
    Sequence
    \t           tab             UFDL interprets this as an imbedded
                                 tab character.
    \n           line delimiter  UFDL interprets this as am imbedded
                                 line delimiter.

Universal Forms Description Language                           [page 40]


    \xnn         hexadecimal     UFDL interprets 'nn' as a hexadecimal
                 number          number.
    \mnn         octal number    If 'm' is 0,1,2,or 3, UFDL interprets
                                 'mnn' as an octal number
    \"           double quote    UFDL interprets this as an imbedded
                                 double quote mark.
    \\           backslash       UFDL interprets this as an imbedded
    \<any other> <any other>     UFDL ignores the escape character.
 ------

  2.5e   Binary Data

         See 'mimedata' in section 5.27 for the syntax of
                 the assignment statement.

    Images and sounds are examples of binary data. Store binary data in
    a form using the mimedata option of a data item. The mimedata
    option requires a quoted string as its setting.

    To store binary data in this manner, you must first convert it to
    base64 format, copy the converted data into the form definition,
    and insert the quotation marks. In all likelihood the data will
    span several lines. Enclose each line in quotation marks.

    Converting binary data to base64 format ensures the string contains
    no characters requiring an escape sequence.
------

  2.5f   Comments

    Comments must occur at the end of the line or on a line by
    themselves. UFDL supports two comment formats:
     // comment         - the comment ends at the end of the line
     /* comment */      - these comments can span several lines
------

  2.6   Security

    Version 4.0 and higher of UFDL supports digital signatures, for
    secure, tamper-proof documents. Digital signatures are incorporated
    into the description of the form, and allow the developer to
    specify that a user may sign the entire form or parts of the form.
    In addition, multiple users may sign a form.

   Design Goals Behind Digital Signatures in UFDL

    Standards Based Security: Due to the sensitive nature of the issues
    surrounding data security and integrity, all digital signature
    technologies used in UFDL must be based on commonly accepted
    industry standards.

    Vendor Independence: Any API used must have the ability to be
    seamlessly replaced with another, should the situation warrant it.

    Optional Implementation: The act of digitally signing a UFDL form

Universal Forms Description Language                           [page 41]


    should not alter it in any way that prevents it from being opened
    by a viewer that does not support the digital signature technology.

    Partial Content Protection: Forms must be able to be signed both in
    whole and in part to allow for sections to be approved by different
    signing authorities.

    Incremental Protection: Forms or form sections must be able to be
    signed several times to allow for layered or incremental
    authorization.

   How Digital Signatures Work in UFDL

    User-level digital signature functionality is accessible through
    one or more signature buttons, which the form developer must place
    in the form. Typically, a signature button that is associated with
    a valid digital signature will display the signer's identity. A
    signature button associated with an invalid signature will display
    the word Invalid. Finally, a signature button that is not
    associated with a signature will appear to be empty. The form
    developer can override this basic behavior.

    Subject to some constraints specified by the form, a user can
    access the following digital signature functionality: verify the
    digital signatures present in the form, view the signatures in a
    form, digitally sign all or part of a form, and delete the user's
    signature.

    Signature Verification: The signatures in a form will be verified
    automatically when the form is first displayed. The user will be
    warned if any signature verification fails (in addition to the
    invalid appearance displayed by any associated signature buttons).

    Signature Viewing: By pressing a signature button on the form,
    the user will be able to call upon a Signature Viewer dialog box
    to present the signature associated with the button. The dialog
    will include four buttons: OK, Sign, Delete, and Advanced.

    The default button is OK, so the user can hit the Enter key at any
    time to release the Signature Viewer dialog. If there is no
    signature associated with the signature button, then the Delete and
    Advanced buttons will be inactive, and text field will be empty.
    The Sign button will be active, and it will receive the focus when
    the Signature Viewer dialog is first displayed so that the user can
    simply hit the space bar to sign the form. If there is a signature
    associated with the signature button, then the Sign button will be
    inactive, the Delete button may or may not be active, and the
    Advanced button will be active. The Advanced button will also
    receive the focus so that the user can hit space to view the
    advanced information regarding the signature.

    The dialog will also use labels to display the signature status
    (No Signature, Signature Is Valid, Signature Is Invalid), the
    signer's identity (e.g., John Doe Manager, jdoe@company.com), the
    identity of the cryptographic service provider used to generate and
    verify the signature (e.g., Microsoft Base Cryptographic Provider

Universal Forms Description Language                           [page 42]


    v.1.0), and the hash algorithm used (sha1 or md5).

    Finally, the dialog will provide a readonly text field labeled
    Certificate Chain that will contain a textual description of the
    chain of certificate issuance for the signer. If there is no
    signature, then all elements will be empty except the signature
    status. If there is a signature, and the user presses the Advanced
    button, then a second dialog box will appear, containing a readonly
    text field and an OK button. The OK button will release the
    advanced dialog if pushed, and the text field will contain a UFDL
    text representation showing what the user signed.

    Digital Signature: If the user presses the Sign button, then the
    viewer will first obtain the digital signature key of the user. If
    the user has more than one digital signature identity, then a
    dialog will be presented allowing the user to select the desired
    identity. The signature will then be created in accordance with the
    specifications of the signature button, and the signature
    demographics will be placed into the labels and fields of the
    Signature Viewer dialog. The Sign button will be grayed out, and
    the Delete and Advanced buttons will be activated. The Advanced
    button will receive the focus. Thus, the user may then press the
    space bar to view the new signature's advanced information (or
    Enter to release the signature dialog via the default OK button).

    Deleting a Signature: If a valid signature is associated with the
    signature button, and it belongs to the current user, and the
    deletion of the signature will not corrupt other signatures on the
    form, then the Delete button will be activated. The user is not
    permitted to delete an invalid signature (even if it claims to
    have the user's identity because it may be lying). If the user
    presses this button, then the Signature Demographics field will be
    emptied, the Delete and Advanced buttons will be deactivated, and
    the Sign button will be activated and focused. Thus, the user can
    hit Enter to release the Signature Viewer dialog box via the OK
    button, or space to sign the form. Typically, the user will delete
    a signature, release the dialog, make some changes to the form,
    then reinstantiate the dialog to sign the changed form.

   Freezing Option References, Calculations, and Other Formulas

    Once an option has been digitally signed, it maintains the signed
    literal value and will not change, even if the option setting is a
    formula (for example, value=field1.value).

    The literal value is stored in a start value element of the option
    name, which is represented by an open angle bracket with the value
    in quotation marks and a close angle bracket on the left-hand side
    of the equal sign, like this:

     value<"Jane E. Smith"> = page1.nameField.value;

    The viewer sets this literal value when a form is signed,
    submitted, or saved (and discards any old value if necessary).
    Because a digitally signed formula never fires after being signed,
    the start value for the option is always the same-and therefore it

Universal Forms Description Language                           [page 43]


    is possible to reference the option and get the signed literal
    value.

   Non-Compliance

    In accordance with the design criterion of optional implementation,
    viewers that don't support digital signature should, for the most
    part, ignore the digital signature enhancements in a form. Viewers
    that support any UFDL versions prior to v.4.0 not be able to parse
    v.4.0 forms, because of the inclusion of the start value syntax
    starting in v.4.0 (see "Freezing Option References, Calculations,
    and Other Formulas" above). However, if a UFDL viewer v.4.0 or
    higher does not have digital signature capability, then the viewer
    should not attempt to verify the signatures. Further, if a button
    of type signature is pressed, the user should be informed that the
    digital signature feature is not supported.

    If a digital signature fails because the signer's certificate is
    out of date, the viewer will denote this as a failure even if
    everything else checks out. The principal idea behind certificate
    expiry is that keys involved in a signature cannot be trusted
    beyond the expiry date.

   Setting Up a Digital Signature Button

    To allow a form user to digitally sign a form, the form developer
    must create a digital signature button, according to the language
    specs outlined in the UFDL button item description.

    When the user signs the form, the user's digital signature is
    stored in a signature item (consisting of the signer
    identification, the encoded UFDL representation of what is being
    signed, and the filters applied). The developer does not create a
    signature item; rather, it is automatically created by the viewer
    or other form application when the user signs the form.

    Once a form or a portion of a form has been signed, it cannot be
    altered. If it becomes altered, the signature will break, and all
    users will be notified of the broken signature. In addition, some
    applications may refuse to process a form containing a broken
    signature.

    Example Signature Button and Signature Descriptions

     empSigButton = new button
     {
        type = "signature";
        value = signer;
        format = ["string", "mandatory"];
        signformat = "application/uwi_form;csp=\"Microsoft Base
     Cryptographic Provider v1.0\";csptype=rsa_full;hashalg=sha1";
        signoptions = ["omit", "triggeritem", "coordinates"];
        signitemrefs = ["omit", "PAGE1.mgrSigButton",
     "PAGE1.admSigButton",
                                "PAGE1.empSignature",
        signature = "empSignature";
     }
     ...
      empSignature = new signature
       {
        signformat = "application/uwi_form;csp=\"Microsoft Base
     Cryptographic Provider v1.0\";csptype=rsa_full;hashalg=sha1";
                signer = "Jane D Smith, jsmith@insurance.com";
                signature = "PAGE1.empSignature";
                signitemrefs = ["omit", "PAGE1.mgrSigButton",
     "PAGE1.admSigButton",
                                "PAGE1.empSignature",
     "PAGE1.mgrSignature",
                                "PAGE1.admSignature"];
        signoptions = ["omit", "triggeritem", "coordinates"];
        mimedata = "MIIFMgYJKoZIhvcNAQcCoIIFIzCCBR8CAQExDzANBgkg"
        "AQUFADALB\ngkqhkiG9w0BBwGgggQZMCA36gAwSRiADjdhfHJl"
        "6hMrc5DySSP+X5j\nANfBGSOI\n9w0BAQQdWaYDVQQHEwhJbn"
        "Rlcm5ldDEXMBUGA1UEChM\nOVmVyaVNpZ24sIEluYy4xNDAKn"
        "1ZlcmlTaWduIENsYXNzIDEgQ0Eg\nLSJbmRdWFsIFN1YnNjcmliy"
        "ZXIwHhcNOTgwMTI3MwMDAwOTgwM\M1OTU5WjCCARExETA";
     }

    For more information, see the button and signature item
    descriptions.
------

  2.7   Filters

    UFDL supplies options for filtering transmissions and digital
    signatures. The filters allow the form developer to specify the
    items and options that should be included in or omitted from a
    transmission or a signed portion of the form.

    For transmissions, filtering is a useful way to reduce file size.
    While compression reduces file size significantly, filters can be
    used to further optimize a transmission, by sending only the
    required data. Obviously, filtering needs to be done with care, as
    it is possible to destroy the layout or the original context of a
    form if it is applied without caution.

    For information on compression, see the transmitformat option
    description.

    For signatures, filtering is the method to use to allow portions of
    forms to be signed. For example, if you created a form that
    contained two sections, one for an employee to fill out and sign,
    and one for an administrative officer to fill out and sign, you
    would use filters in each signature button to specify which portion
    of a form each signature applied to. For more details, see the
    button item description.

    The filters for transmission are: transmitdatagroups,
    transmitgroups, transmititems, transmititemrefs, transmitoptions,
    and transmitoptionrefs.


Universal Forms Description Language                           [page 45]


    The filters for digital signatures are: signdatagroups, signgroups,
    signitems, signitemrefs, signoptions, and signoptionrefs.

    For example:

     submitButton = new button
     {
        type = "done";
        value = "Submit";
        url = ["http://www.server.dmn/cgi-bin/warehouse.exe"];
        transmititems = ["omit", "data"];
        transmitdatagroups = ["keep", "enclosures", "related"];
        transmititemrefs = ["omit", "page1.toolbar"];
        transmitoptions = ["omit", "bgcolor", "fontcolor"];
     }

     employeeSignatureButton = new button
     {
        type = "signature";
        value = "Sign This Section";
        signature = "empSignature";
        signitemrefs = ["keep", "page1.nameField", "page1.nameLabel",
                       "page1.dateField", "page1.dateLabel",
                       "page1.evaluationField",
                       "page1.evaluationLabel"];
     }

    For details on each filter, see the option descriptions later in
    this document.

   Order of Precedence of Filters

    Within each family of filters, there are item filters and option
    filters. In addition, there are item type filters, which filter an
    entire type of items (all fields, for example), and item instance
    filters (which filter specific instances of items). The same filter
    levels exist for option filters.

    The settings in filters are applied by a UFDL parser in the
    following manner:

 Filter            Behavior                                Notes
                   If keep flag       If omit flag
                   is used             is used
 1.Filter types    Keeps only those   Omits only those
 of items, based   types referred to; types referred
 on transmititems  throws others out, to; throws them
 / signitems       including their    out including
 setting           options            their options

 2.Filter groups    Keeps those      Omits those
 of items based on  items whose tags items whose
 transmitdatagroups are specified,   tags are specified,
 and                even if the      even if the items
 transmitgroups,    items are of a   are of a type

Universal Forms Description Language                           [page 46]


 or signdatagroups  type that should that should be kept
 and signgroups     not be kept      according to a
 settings           according to a   transmititems or
                    transmititems or signitems setting
                    signitems setting

 3.Filter specific  Keeps the items   Omits the items This option's
 items based on     whose tags are    whose tags are  settings
 transmititemrefs   specified;        specified;      override those
 or signitemrefs    overrides         overrides the   in transmititems,
 settings           previous setting  previous        transmitgroups,
                    if necessary      settings if     and
                                      necessary      transmitdatagroups
                                                     or signitems,
                                                     signgroups and
                                                     signdatagroups

 4.Filter types of  In the items      In the items
 options based on   that remain,      that remain,
 transmitoptions    keeps all         omits all
 and signoptions    option types      option types
 setting            referred to;      referred to
                    throws others
                    out

 5.Filter specific  Regardless of     Regardless of  This option's
 options based on   all other         all other      settings override
 transmitoptionrefs settings above,   settings above,all other
 and signoptionrefs keeps the         omits the      filters
 setting            specific option   specific       (transmititems,
                    instances         option         transmitdatagrou
                    referred to;      instances      ps,
                    does not keep     referred to    transmitgroups,
                    any other options;               transmititemrefs,
                    in the case of                   transmitoptions
                    items that will                  or signitems,
                    be omitted                       signdatagroups,
                    exept for a                      signgroups,
                    single option,                   signitemrefs,
                    the description                  signoptions)
                    will look like
                    this:
                    itemTag = new item
                    {
                    option = setting;
                    }

   Example

    This example uses the transmit-family of options. The order of
    precedence would be the same for the sign-family of options.

     version = "4.0.0";

     page1 = new page
     {

Universal Forms Description Language                           [page 47]


        submitButton = new button
        {
                value = "Filter Submission";
                type = "done";
                url = ["http://www.server.dmn/cgi-bin/processForm"];
                transmititems = ["omit", "data"];
                transmitdatagroups = ["keep", "enclosures", "related"];
                transmititemrefs = ["omit", "page1.data2"];
                transmitoptions = ["omit" "filename"];
        }

        encloseButton = new button
        {
                image = "encloseImageData";
                type = "enclose";
                datagroup = ["enclosures", "related"];
        }

        data1 = new data
        {
                datagroup = ["enclosures"];
                filename = "jobdescr.frm";
                mimedata = "dfksdfsdfhsdhskdljhf";
        }

        data2 = new data
        {
                datagroup = ["related"];
                filename = "resume.doc";
                mimedata = "dfhsjdfsjhfjs";
        }

        encloseImageData = new data
        {
                filename = "c:\images\enclose.jpg";
                mimedata = "aswWWW8MjfbyhsUE&LKKELFir8dfd";
                  "UUUmnskshie3mkjkkeiIIUIUOlfRlgdsoepgejgjj";
                  "1sd\35fnnII\fjkess9Wfgjgkggkll\\rgakkk2klgjgkg";
        }

     }

    As a result of the filtering, the following would happen (see
    result form description below):
     - The encloseImageData data item would be stripped from the form,
       as a result of the transmititems setting.

     - The data1 data item would remain in the form, as a result of the
       transmitdatagroups setting.

     - The data2 data item would be stripped from the form, as a result
       of the transmititemrefs setting.

     - The filename option would be stripped from data1, as a result of
       the transmitoptions setting.

Universal Forms Description Language                           [page 48]


    The form description that would be received once filtering was
    applied would look like this:

     version = "4.0.0";

     page1 = new page
     {
        submitButton = new button
        {
                value = "Filter Submission";
                type = "done";
                url = ["http://www.server.dmn/cgi-bin/processForm"];
                transmititems = ["omit", "data"];
                transmitdatagroups = ["keep", "enclosures", "related"];
                transmititemrefs = ["omit", "page1.data2"];
                transmitoptions = ["omit" "filename"];
        }

        encloseButton = new button
        {
                image = "encloseImageData";
                type = "enclose";
                datagroup = ["enclosures", "related"];
        }

        data1 = new data
        {
                datagroup = ["enclosures"];
                mimedata = "dfksdfsdfhsdhskdljhf";
        }

     }
------

  2.8   Processing Forms

    Once a user saves or submits a form, it becomes a form instance.
    In the course of a form instance's life cycle, it may be viewed by
    various users at various client sites. Also, several form
    processing applications may handle the form. To ensure consistency
    and integrity of the form's appearance and contents, there are some
    important form processing rules in UFDL.
------

    UFDL offers two types of include statements:

     - #include - Includes a file from the local drive in the form
       description, and, if the file does not exist, flags the error.

     - #optinclude - Includes a file from the local drive if the file
       exists and, if the file does not exist, ignores it gracefully.

    The rules governing handling of #include statements state:


Universal Forms Description Language                           [page 49]


     - All #include and #optinclude statements are resolved when the
       form appears. The only exception occurs when the referenced file
       cannot be found. In this instance, the #include or #optinclude
       statement remains in the form.

     - When a #include or #optinclude statement is resolved, the
       #include or #optinclude statement definition is permanently
       deleted from the form instance.

    These rules combine to ensure that the definition of a particular
    form instance remains constant from first to last viewing, and that
    no user data disappears.
------

  2.8b   Expressions

    The rule governing handling of expressions in value options states:
     - Expressions are overwritten if the item is modifiable and the
       user updates the value displayed, or if the form submission
       format is HTML.

    This rule ensures that forms submitted in UFDL format continue to
    work as originally designed even after processing.
------


3.   UFDL Global and Page Settings

    At the top of each form and each page, a form developer can specify
    options that apply to the whole form or the particular page. These
    are called global settings and page settings.

    The syntax of global settings is as follows:
     version = <version_number>;
     <option definition2>
     ...
     <option definitionn>
     Notes:
     i) The version option is mandatory. It must be the first line in
        the form.
     ii)All options other than version are optional.
     iii)Global settings must appear before the first page declaration.
     iv)A page setting can override a form global option for the
        particular page.

    The syntax of page settings is as follows:
     <page tag> = new page
     {
     <option definition1>
     ...
     <option definitionn>
     Notes:
     i) Page settings are optional.
     ii)Page settings must appear before the first item definition in
        the page.
     iii)A page will assume the characteristics specified in the global

Universal Forms Description Language                           [page 50]


         settings unless they are overridden by settings of the same
         type in the page settings.
     iv)Options within item declarations override page settings for the
        particular item they appear in.

    The following pages outline which options can be used as global
    settings and which options can be used as page settings.
------

  3.1   Global Settings

    Global settings specify particular settings for the form and
    determine its physical characteristics. For example, the version
    option defines which version of UFDL the form was written in. The
    bgcolor option determines the background color of all pages in the
    form. Global settings appear at the top of a form and apply to the
    whole form. Options defined within a page or item can override
    global settings for that particular page or item.

   Available Options

    Option              Behavior
    activated           Whether the form is displayed or
                        not. Default: off

    bgcolor             Background color of form.
                        Default: 255, 255, 255 (white)

    bordercolor         Border color of items in form.
                        Default: 0, 0, 0 (black)

    borderwid           Border width of items in form.
                        Default: Depends on item

    focused             Whether the form has the input focus
                        (generally, if it's open, it does).
                        Default: off

    fontcolor           Color of all value text in form. Does not
                        apply to the text of label options.
                        Default: black

    fontinfo            Style of all value text in form. Does not
                        apply to the text of label options.
    label               Text that appears in title bar of form.
                        Default: n/a

    next                Item the focus appears on when form opens.
                        Default: First input item in form description

    saveformat          Format in which the form is saved.
                        Default: uncompressed UFDL

    transmitformat      Format in which the form is transmitted.
                        Default: uncompressed UFDL

Universal Forms Description Language                           [page 51]


    triggeritem         Item tag of item that triggered a submit
                        or done action. Default: n/a

    version             Version of UFDL used to make the form.
                        Default: n/a

   Usage Notes

    1) Define global settings at the top of the form, before the first
       page declaration.

    2) The version option is mandatory and must be the first line in
       the form.

    3) You can give the form a title that appears in the title bar by
       setting a global label option.

    4) To specify a title to appear in the form's title bar, use the
       label option as a global setting.

   Example

    This example defines settings and characteristics for the form.
     version = "3.2.0";
     saveformat = "application/uwi_form; content-encoding=\"gzip\" ";
     label = "Time Sheet";
     bgcolor = ["ivory"];
     fontinfo = ["Helvetica", "10", "plain"];

    These global settings specify that:
        - The form is written in version 3.2.0 of UFDL.
        - All saves activated from the form should save the form as a
          compressed UFDL form, unless specified otherwise in an item
          that initiates a save.
        - The title Time Sheet should appear in the title bar of all
          pages, unless specified otherwise in a page global.
        - All pages, toolbars, boxes, labels, and tablets should have
          an ivory background, unless they contain an option specifying
          otherwise.
        - All pages and items should use a plain, Helvetica, 10-point
          font, unless they contain an option specifying otherwise.
          (Note: Labels that are parts of other items, like fields,
          are excluded from the fontinfo option. They are set using the
          labelfontinfo option.)
------

  3.2   Page Settings

    Page settings specify settings (like next and saveformat) and
    characteristics (like bgcolor) for the page they appear on. Page
    settings appear at the top of each page definition, and apply to
    the whole page. They can be overridden by option settings within
    items.

   Available Options

Universal Forms Description Language                           [page 52]


    Option              Behavior
    activated           Whether the page is being displayed or not.
                        Default: off

    bgcolor             Background color of page.
                        Default: 255, 255, 255 (white)

    bordercolor         Border color of items in page.
                        Default: 0, 0, 0 (black)

    borderwidth         Border width of items in page.
                        Default: Depends on item

    fontcolor           Color of all value text in page.
                        Does not apply to the text of label options.
                        Default: black

    focused             Whether the page has the input focus.
                        (Generally, if it's open, it does).
                        Default: off

    fontinfo            Style of all value text in page. Does not
                        apply to the text of label options.
                        Default: Helvetica, 8, plain

    label               Text that appears in title bar of page.
                        Default: n/a

    mouseover           Whether the mouse pointer is over the page.
    next                Item the focus appears on when page opens.
                        Default: First input item in form description

    saveformat          Format in which the page is saved.
                        Default: uncompressed UFDL

    transmitformat      Format in which the page is transmitted.
                        Default: uncompressed UFDL

   Usage Notes

    1) Define page settings at the top of a page, after the opening
       brace and before the first item declaration.
    2) Page settings apply only to the page they are on.

    3) Page settings are optional.

    4) To specify a title to appear in the page's title bar, use the
       label option as a page setting.

   Example

    The following example shows page global options on two pages
    within a single form.

     ...

Universal Forms Description Language                           [page 53]


     page_1 = new page
     {
        bgcolor = ["seashell"];
        next = "Name_field";

        <item declaration>
     ...
     }
     page_2 = new page
     {
        fontinfo = ["Helvetica", "14", "plain"];
        next = "Activity_popup";

        <item declaration>
     ...

    Page one would have a seashell-colored background, and would direct
    the focus to the item called Name_field as soon as it opened. It
    would assume the rest of its settings from the form's global
    settings. (If no form global settings exist, the page will assume
    the UFDL defaults.)

    On page two, the font would appear as plain, Helvetica, 14-point
    type and the focus would be directed to the item called
    Activity_popup as soon as the page opened. Page two would assume
    the rest of its settings from the page global options and UFDL
    defaults.
------


4.   UFDL Form Items

    Items are the basic elements of a page. The syntax of an item
    definition is as follows:
     <item tag> = new <item type>
     {
      <option definition1>
      ...
      <option definitionn>
     }
     Notes:
     i) The braces are mandatory.
     ii) An item definition must begin on a new line.
     iii) Option definitions are optional.
     iv) You cannot assign values to options in other item definitions.

         Tip: UFDL is case sensitive. All item type
              names are lowercase.

    The item tag uniquely identifies an item instance. No two item tags
    on a page can be the same. Item type is a name that identifies the
    type of item. This section contains information about UFDL-defined
    item types and the options available for each.

    Note: Defining an option more than once in an item's definition may
    cause unpredictable behavior.

Universal Forms Description Language                           [page 54]


    See the section 'Item Definition' in section 2.4d for more
    information on the syntax and rules regarding an item definition.
------

  4.1   action

    The action item allows you to specify form-initiated actions that
    execute automatically. The actions can be any of the following
    types:
        - link
        - submit
        - done
        - display
        - print
        - cancel
    See the type option section for a description of each of these
    actions.

    You can define action items that occur only once or repeat at
    specified time intervals. You can also define actions that occur
    after the page opens but before the page appears. See the section
    on the delay option for information on timing options.

    Action items can trigger either background actions or actions
    involving user interaction. In fact, if the form contains only
    hidden items such as action items, then the whole form operates in
    the background. Such forms are called daemon forms.

   Available Options
    Option              Behavior
    activated           Specifies whether item is currently activated.
                        Default: off

    active              Specifies whether item is active or inactive.
                        Default: on

    data                Specifies a single data item associated with
                        an action of type display. Default: n/a

    datagroup           Identifies group or folder of enclosed files.
                        Default: n/a

    delay               Delays execution of automatic action or
                        specifies automatic action repeat factor.
                        Default: repeat factor of once, interval of
                        zero seconds

    transmitdatagroups  Lists which datagroups of items should be kept
                        or omitted from a transmission.
                        Default: see "Order of Precedence of Filters"

    transmitformat      Specifies format of form data transmitted to
                        form processing application. Default:
                        uncompressed UFDL (application/uwi_form)

Universal Forms Description Language                           [page 55]


    transmitgroups      Lists which groups of items should be kept
                        or omitted from a transmission. Default:
                        see "Order of Precedence of Filters"

    transmititemrefs    Lists which specific items should be kept
                        or omitted from a transmission. Default:
                        see "Order of Precedence of Filters"

    transmititems       Lists types of items to include in or omit
                        from form data submitted to form processing
                        application. Default: see "Order of Precedence
                        of Filters"

    transmitoptionrefs  Lists which specific options should be kept
                        or omitted from form data submitted to form
                        processing application. Default:
                        see "Order of Precedence of Filters"

    transmitoptions     Lists which types of options to include in
                        or omit from form data submitted to form
                        processing application. Default:
                        see "Order of Precedence of Filters"

    type                Associates task type with item that can trigger
                        a task: action, button, or cell. Default:link

    url                 Identifies an object to access, for items with
                        type option setting of link, replace, submit,
                        done, or pagedone. Default: n/a

   Usage Notes

    1) Repeating automatic actions is one method of creating a
       sparse-stated connection. It allows the form to indicate
       periodically to a server application that it is still running.
       Use the delay option to specify repetition.

    2) Actions, by the form definition rules, reside on a page;
       therefore, actions occur only when the page is open, and
       repeating actions stop when a the page closes. Actions defined
       to occur before the page displays, occur each time the page
       opens.

   Examples

    Example 1

    The following action will send a status message to the server. The
    transaction happens automatically every 10 minutes (600 seconds).
     sendStatus_action = new action
     {
      delay = ["repeat", "600"];
      type = "submit";
      url = ["http://www.server.com/cgi-bin/recv_status"];
     }

Universal Forms Description Language                           [page 56]


    Example 2

    This action will link to a search form as soon as the current page
    displays.
     grabSearch_action = new action
     {
      type = "link";
      url = ["http://www.server.com/application/ index/search.frm"];
     }

   Example 3

    Background actions can also cancel forms, or prompt the user to
    save a form. Here is an example:
     // Automatically prompt the user to save the form after 5 minutes
     autoSave_action = new action
     {
      delay = ["once", "300"];
      type = "save";
     }
    //
    // Automatically close the form after 10 minutes
    autoCancel_action = new action
    {
     delay = ["once", "600"];
     type = "cancel";
    }
------

  4.2   box

         Sample 1: Box

    The box item creates a square box on the form. You may not place
    other items in the box; however, you may place other items on top
    of it. The purpose of box items is simply to add visual variety to
    the form.

   Available Options

    Option              Behavior
    bgcolor             Defines background color of box.
                        Default: page background color

    bordercolor         Defines color of border around box.
                        Default: black


    borderwidth         Defines width of box's border in pixels.
                        Default: zero pixels

    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of box.
                        Defaults: Helvetica, 8, plain

Universal Forms Description Language                           [page 57]


    itemlocation        Specifies location of box in page layout.
                        Default: in body of page, under previous item
                        in page definition, aligned along page's left
                        margin

    size                Specifies box's size in characters.
                        Default: width 1 character, height 1 character

   Usage Notes

    1) To make the box more visible, assign a background color that
       differs from the page background color (the default).

    2) When setting the size option of a box, the height and width of
       the box will be based on the average character size for the font
       in use (set with the fontinfo option).

   Example
    The following example shows a typical box description. The box is
    25 characters wide and 4 characters high. Notice the background
    color setting.
     blue_box = new box
     {
      bgcolor = ["blue"];
      size = ["25", "4"];
     }
------

  4.3   button

         Sample 2: Button

    The button item provides a click button to perform an action when
    selected. For example, you can use buttons to request data from a
    web server, submit or cancel the form, sign the form, save it to
    disk, or enclose external files.
   Available Options

    Option              Behavior
    activated           Specifies whether the button is currently
                        activated by user. Default: off

    active              Specifies whether button is active or
                        inactive. Default: on

    bgcolor             Defines background color of button.
                        Default: gray

    bordercolor         Defines width of button's border in pixels.
                        Default: zero pixels

    borderwidth         Defines font name, point size, and font
                        characteristics for text portion of button.
                        Defaults: Helvetica, 8, plain

Universal Forms Description Language                           [page 58]


    coordinates         Records position of mouse pointer on an image
                        which must exist in a button. Default: n/a

    data                Specifies a single data item associated with
                        a button of type enclose, display, extract,
                        or remove. Default: n/a

    datagroup           Identifies group or folder of enclosed files.
                        Default: n/a

    focused             Specifies whether button has input focus.
                        Default: off

    fontcolor           Defines font color for text or filler portion
                        of button. Default: black

    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of button.
                        Default: Helvetica, 8, plain

    format              Defines whether a button is mandatory or
                        optional, for use with signature buttons.
                        Default: optional (see also format option
                        description)

    help                Points to help message for button.
                        Default: n/a

    image               Associates an image with button.
                        Default: n/a

    itemlocation        Specifies location of button in page layout.
                        Default: in body of page, under previous item
                        in page definition, aligned along page's
                        left margin.

    justify             Aligns lines of text within space button
                        occupies. Default: center

    mouseover           Specifies whether mouse pointer is over
                        button. Default: off

    next                Identifies item to receive focus when user
                        tabs ahead from current item. Default: depends
                        on order in which page and item definitions
                        occur within form definition

    signature           Establishes UFDL item name by which a digital
                        signature is identified. Default: n/a

    signdatagroups      Specifies which datagroups are to be filtered
                        for digital signature. Default: see "Order of
                        Precedence of Filters"

    signer              Adds user's common name and email address as

Universal Forms Description Language                           [page 59]


                        they appear in user's personal certificate,
                        identifying who signed the form. Default: n/a

    signformat          Controls what system parameters are used to
                        create the signature. Default:
                        application/uwi_form

    signgroups          Specifies which groups of items are to be
                        filtered for digital signature. Default: see
                        "Order of Precedence of Filters"

    signitemrefs        Specifies which individual items are to be
                        filtered for digital signature. Default: see
                        "Order of Precedence of Filters"

    signitems           Specifies which types of items are to be
                        filtered for digital signature. Default: see
                        "Order of Precedence of Filters"

    signoptionrefs      Specifies which individual options are to be
                        filtered for digital signature. Default: see
                        "Order of Precedence of Filters"

    Universal Forms Description Language                           [page 30]


    signoptions         Specifies which types of options are to be
                        filtered for digital signature. Default: see
                        "Order of Precedence of Filters"

    size                Specifies button's size in characters.
                        Default: width of label, height of label

    transmitdatagroups  Lists which datagroups of items should be kept
                        or omitted from a transmission. Default: see
                        "Order of Precedence of Filters"

    transmitformat      Specifies format of form data transmitted to
                        form processing application.
                        Default: uncompressed UFDL

    transmitgroups      Lists which groups of items should be kept or
                        omitted from a transmission. Default: see
                        "Order of Precedence of Filters"

    transmititemrefs    Lists which specific items should be kept or
                        omitted from a transmission. Default: see
                        "Order of Precedence of Filters"

    transmititems       Lists types of items to include in or omit from
                        form data submitted to form processing
                        application. Default: see "Order of Precedence
                        of Filters"

    transmitoptionrefs  Lists which specific options should be kept or
                        omitted from form data submitted to form
                        processing application. Default: see "Order of
                        Precedence of Filters"

Universal Forms Description Language                           [page 60]


    transmitoptions     Lists which types of options to include in or
                        omit from form data submitted to form
                        processing application. Default: see "Order of
                        Precedence of Filters"

    type                Associates task type with item that can trigger
                        a task: action, button, or cell. Default:link

    url                 Identifies an object to access, for items with
                        type option setting of link, replace, submit,
                        done, or pagedone. Default: n/a

    value               Contains text of button's label. Default: n/a

   Usage Notes

    1) The button's label is defined by the value option. If no value
       option exists, the default label is blank.

    2) When setting the size option of a button, the height and width
       of the button will be based on the average character size for
       the font in use (set with the fontinfo option).

    3) If a button's image option points to a data item that
       dynamically changes its mimedata (but not its item tag), then
       the button will upate the image it displays. For information on
       how to update an image by enclosing a new one, see the data
       option description.

    4) The format option is available  in buttons so that you can force
       users to sign forms before submitting them. You do this by
       making a signature button mandatory, like this:

      empSignatureButton = new button
      {
        type = "signature";
        format = ["string", "mandatory"];
        value = signer;
        signer="";
        signature = "empSignature";
        signoptions = ["omit", "triggeritem", "coordinates"];
        signitemrefs = ["omit", "page1.empSignatureButton",
                       "page1.empSignature"];
      }

    There are two steps to making a signature button mandatory:

     - Assign a format of ["string", "mandatory"].

     - Set the button's value to equal the button's signer option
       setting.

    By setting the format to mandatory, you specify that the button
    must have a value setting that is not empty before the user submits
    the form. By then equating the value to the setting of the signer

Universal Forms Description Language                           [page 61]


    option, you make sure that the only way a button's value is set is
    if somebody uses it to sign the form. (The signer option stores the
    identity of the person who signed the form using the button.)

   Behavior of Buttons in Digital Signatures

    1) A digital signature button is the means by which the user can
       digitally sign a form. To make a button a signature button,
       set its type to signature.

    2) You can set up a signature button to sign the whole form or just
       part of it. You do this by setting up filters on the signature,
       using the signdatagroups, signgroups, signitemrefs, signitems,
       signoptionrefs, and signoptions options. To learn about
       filtering, see "Filters"in section 2.7.

       Important:You should always at a minimum filter out the
       triggeritem and coordinates options. These options change
       when a submission is triggered or when a user clicks an
       image button, respectively. You should also consider
       filtering out any parts of the form that a subsequent
       user will change, including subsequent signatures and
       signature buttons; and custom options that might change
       (like odbc_rowcount).

    3) Signature buttons allow users to do the following:

       - Sign the form or portion of the form the button specifies.

       - Delete their signatures (a signature can be deleted only by
         the user whose signature it is, and if the signature is
         currently valid and not signed by some other signature).

       - View the signature and view the UFDL text of what the
         signature applies to.

    4) All option references, calculations, and other formulas in any
       signed portion of a form are frozen once they have been signed.
       Their setting will be valued at the setting they contained at
       the moment when the signature was created. If the user deletes
       the digital signature, however, then the formulas will become
       unfrozen, and will change dynamically as normal.

    5) The usual options for other buttons (i.e. size, image, value)
       can also be used with signature buttons.

   Examples

    Example 1 - Link button

    This button links the form to a server (www.server.com) and
     getHelp_button = new button
     {
      value = "Get Help";
      type = "link";

Universal Forms Description Language                           [page 62]


      url = ["http://www.server.com/application/help/formHelp.frm"];
     }

   Example 2 - Submit button

    Buttons that trigger form processing requests must have a type
    option setting of submit or done. The definition for such a
    button might look like this:
     submit_button = new button
     {
      value = "Process Form";
      fontinfo = ["Helvetica", "18", "bold", "italic"];
      type = "done";
      url = ["http://www.server.com/cgi-bin/formProcessor"];
     }

   Example 3 - Enclosure button

    This button encloses an external file in the form. The action to
    enclose a file is enclose. The datagroup option identifies the list
    of datagroups, or folders, in which the user can store the enclosed
    file. An enclose button might take the following form:
     enclose_button = new button
     {
      value = "Enclose File";
      fontinfo = ["Helvetica", "18", "bold", "italic"];
      type = "enclose";
      datagroup = ["Images_Asia", "Images_Eur" , "Images_SAmer"];
     }

    This button will allow users to enclose files into one of three
    datagroups (folders): Images_Asia, Images_Eur, Images_SAmer.

   Example 4 - Signature button

    This example shows a signature button with the signature item it
    creates when signed. The button contains the basic settings you
    should use. Its type is designated as signature; it omits
    triggeritem and coordinates options throughout to avoid breaking
    the signature.
     empSigButton = new button
     {
        type = "signature";
        value = signer;
        format = ["string", "mandatory"];
        signformat = "application/uwi_form;csp=\"Microsoft Base
     Cryptographic Provider v1.0\";csptype=rsa_full;hashalg=sha1";
        signoptions = ["omit", "triggeritem", "coordinates"];
        signitemrefs = ["omit", "PAGE1.mgrSigButton",
     "PAGE1.admSigButton", "PAGE1.empSignature",
     "PAGE1.mgrSignature", "PAGE1.admSignature"];
        signature = "empSignature";
     }
     ...
      empSignature = new signature
     {

Universal Forms Description Language                           [page 63]


        signformat = "application/uwi_form;csp=\"Microsoft Base
     Cryptographic Provider v1.0\";csptype=rsa_full;hashalg=sha1";
                signer = "Jane D Smith, jsmith@insurance.com";
                signature = "PAGE1.empSignature";
                signitemrefs = ["omit", "PAGE1.mgrSigButton",
     "PAGE1.admSigButton", "PAGE1.empSignature",
     "PAGE1.mgrSignature", "PAGE1.admSignature"];
                signoptions = ["omit", "triggeritem", "coordinates"];
              mimedata = "MIIFMgYJKoZIhvcNAQcCoIIFIzCCBR8CAQExDzANBgkg"
                "AQUFADALB\ngkqhkiG9w0BBwGgggQZMCA36gAwSRiADjdhfHJl"
                "6hMrc5DySSP+X5j\nANfBGSOI\n9w0BAQQwDwYDVQQHEwhJbn"
                "Rlcm5ldDEXMBUGA1UEChM\nOVmVyaVNpZ24sIEluYy4xNDAKn"
                "1ZlcmlTaWduIENsYXNzIDEgQ0Eg\nLSJbmRdWFsIFN1YnNjcmliy"
                "ZXIwHhcNOTgwMTI3MwMDAwOTgwM\M1OTU5WjCCARExETA";
     }
------

  4.4   cell

    The cell item populates combobox, list and popup items. A cell
    can belong to multiple comboboxes, lists and popups. See the
    combobox, list and popup item sections for information on
    associating cells with these items.

    Cells fall into two categories according to their behavior:

      - Action cells
        These cells perform the same set of actions normally associated
        with buttons. This includes such things as cancelling, saving
        and submitting the form.

      - Select cells
        These cells provide users with a mutually exclusive set of
        values from which to choose. When chosen, these cells appear
        selected. In a list this means the cell is highlighted in some
        way. In a popup, the cell's label becomes the popup's label.

   Available Options

    Option              Behavior
    activated           Specifies whether cell is currently activated
                        by user. Default: off

    active              Specifies whether cell is active or inactive.
                        Default: on

    data                Specifies a single data item to associate
                        with a cell of type enclose, display, extract,
                        or remove. Default: n/a

    datagroup           Identifies group or folder of enclosed files.
                        Default: n/a

    group               Groups cells together. Default: n/a


Universal Forms Description Language                           [page 64]


    label               Specifies external text label for cell.
                        Default: n/a

    transmitdatagroups  Lists which datagroups of items should be
                        kept or omitted from a transmission. Default:
                        see "Order of Precedence of Filters"

    transmitformat      Specifies format of form data submitted to
                        processing application. Default:
                        uncompressed UFDL

    transmitgroups      Lists which groups of items should be kept or
                        omitted from a transmission. Default: see
                        "Order of Precedence of Filters"

    transmititemrefs    Lists which specific items should be kept or
                        omitted from a transmission. Default: see
                        "Order of Precedence of Filters"

    transmititems       Lists types of items to include in or omit
                        from form data submitted to form processing
                        application. Default: see "Order of Precedence
                        of Filters"

    transmitoptionrefs  Lists which specific options should be kept or
                        omitted from form data submitted to form
                        processing application. Default: see "Order of
                        Precedence of Filters"

    transmitoptions     Lists which options to include in or omit from
                        form data submitted to form processing
                        application. Default: see "Order of Precedence
                        of Filters"

    type                Associates task type with item that can trigger
                        a task: action, button, or cell. Default:link

    url                 Identifies an object to access, for items with
                        type option setting of link, replace, submit,
                        done, or pagedone. Default: n/a

    value               Contains identity of most recently selected
                        cell

   Example

    The following example shows a list with three cells. To learn how
    to get the value of the user's selection, see Usage Notes below.

     countryPopup = new popup
     {
        label = "Country";
        group = "country";
        format = ["string", "mandatory"];
     }
     albCell = new cell

Universal Forms Description Language                           [page 65]


     {
        value = "Albania";
        type = "select";
     }
     algCell = new cell
     {
        value = "Algeria";
        group = "country";
        type = "select";
     }
     banCell = new cell
     {
        value = "Bangladesh";
        group = "country";
        type = "select";
     }

   Usage Notes

    1) Use the type option to establish a cell's behavior. Select cells
       that have a type of select (the default type).

    2) Cells can have both value and label options. These options
       affect the form differently depending on whether the cell is
       linked to a combobox, a popup, or a list. In general, the label
       of the cell will be displayed as a choice, while the value of
       the cell will be displayed if that cell is selected.  For more
       information, refer to the appropriate item type.

    3) Cells take their color and font information from the combobox,
       list and popup items with which they are associated. In this
       way, a cell's appearance can vary according to the list the
       user is viewing.

    4) To get the value of a cell that a user has selected from a list,
       you need to dereference it, like this:
        <page_tag>.<list_tag>.value->value

    For example:
     page1.countryPopup.value->value

    When a user selects a cell from a list, the item tag of the cell is
    stored as the value of the list. Hence the dereference syntax.
------

  4.5   check

         Sample 3: Check Box

    The check item provides a simple check box to record a selected
    or not selected answer from a user. A selected check box appears
    filled while a deselected box appears empty.

    The exact appearance of the check box is platform dependent; but
    the shape is rectangular. The check box appears as a normal check

Universal Forms Description Language                           [page 66]


    box for the users of each platform.

   Available Options

    Option              Behavior
    active              Specifies whether check box is active or
                        inactive. Default: on

    bgcolor             Defines background color of check box.
                        Default: white

    bordercolor         Defines color of border around check box.
                        Default: black

    editstate           Defines one of three possible edit states
                        for modifiable items: readonly, writeonly,
                        or readwrite. Default: readwrite.

    focused             Specifies whether check box currently has input
                        focus. Default: off

    fontcolor           Defines font color for text or filler portion
                        of button. Default: black

    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of button.
                        Defaults: Helvetica, 8, plain

    help                Points to help message for button. Default: n/a

    itemlocation        Specifies location of button in page layout.
                        Default: in body of page, under previous item
                        in page definition, aligned along page's
                        left margin

    label               Specifies external text label for check box.
                        Default: n/a

    labelbgcolor        Defines background color for label specified
                        in label option. Default: in toolbar,
                        background color of toolbar; otherwise,
                        background color of page
    labelbordercolor    Defines color of border around label specified
                        in label option. Default: black

    labelborderwidth    Defines width of border around label specified
                        in label option, in pixels.
                        Default: zero pixels

    labelfontcolor      Defines font color for label specified in label
                        option. Default: black

    labelfontinfo       Defines font name, point size, and font
                        characteristics for label specified in label
                        option. Default: Helvetica, 8, plain

Universal Forms Description Language                           [page 67]


    mouseover           Specifies whether mouse pointer is over item.
                        Default: off

    next                Identifies item to receive focus when user
                        tabs ahead from current item.
                        Default: depends on order in which page and
                        item definitions occur within form definition

    size                Specifies check box's size in characters.
                        Default: width 1 character, height 1 character

    value               Indicates user answer's as to whether check box
                        is checked (on) or not (off). Default: off

   Usage Notes

    1) The value option setting indicates the user's answer. If the
       user selects or checks the check box, the value option contains
       on, otherwise it contains off. The default value is off.

    2) Check boxes do not belong to groups like radio buttons-each
       check box may be turned on or off independently of the others.

    3) The label option defines the label for the check box. The label
       appears above the check box and aligned with the boxes left
       edge. There is no default label.

    4) When setting the size option of a check box, the height and
       width of the bounding box will be based on the average character
       size for the font in use (set with the fontinfo option).

    5) The fontcolor option determines the color of the check box fill
       pattern (default is red).

   Example

    This value option setting in this check box is on, so the check
    box will appear selected when it displays. The item's label is
    Activate Health Plan, and the label will display in a Times 14
    Bold font colored blue.

     healthPlan_check = new check
     {
      value = "on";
      label = "Activate Health Plan";
      labelfontinfo = ["Times", "14", "bold"];
      labelfontcolor = ["blue"];
     }
------

  4.6   combobox

         Sample 4: Combobox

    Comboboxes act like a hybrid of a field and a popup. Unopened, a

Universal Forms Description Language                           [page 68]


    combobox with a label occupies the same space two labels, and a
    combobox without a label occupies the same space as a single label.
    After a user chooses a cell, the combobox closes (that is, returns
    to its unopened state).

    If none of the cells are appropriate, the user can type other
    information into the combobox. When information is typed in, it is
    stored in the value option of the combobox. When a cell is
    selected, the value option stores the value of that cell.

    A combobox's label appears above the combobox item.

   Available Options

    Option              Behavior
    activated           Specifies whether the pop-down list is
                        currently activated. Default: off

    active              Specifies whether combobox is active or
                        inactive. Default: on

    bgcolor             Defines background color of combobox.
                        Default: white

    bordercolor         Defines color of border around combobox.
                        Default: black

    editstate           Defines one of three possible edit states for
                        modifiable items: readonly, writeonly, or
                        readwrite. Default: readwrite.

    focused             Specifies whether the combobox currently has
                        the input focus. Default: off
    fontcolor           Defines font color for text or filler portion
                        of combobox. Default: black

    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of combobox.
                        Defaults: Helvetica, 8, plain

    format              Applies to value of each cell linked to
                        combobox, flagging or filtering cells that fail
                        check, and replacing value of cells that pass
                        with formatted value. Default: format option

    group               Groups comboboxes together. Default: n/a

    help                Points to help message for combobox.
                        Default: n/a

    itemlocation        Specifies location of combobox in page layout.
                        Default: in body of page, under previous item
                        in page definition, aligned along page's
                        left margin


Universal Forms Description Language                           [page 69]


    label               Specifies external text label for combobox.
                        Default: n/a

    labelbgcolor        Defines background color for label specified
                        in label option. Default: in toolbar,
                        background color of toolbar; otherwise,
                        background color of page

    labelbordercolor    Defines color of border around label specified
                        in label option. Default: black

    labelborderwidth    Defines width of border around label specified
                        in label option, in pixels.
                        Default: zero pixels

    labelfontcolor      Defines font color for label specified in label
                        option. Default: black

    labelfontinfo       Defines font name, point size, and font
                        characteristics for label specified in label
                        option. Default: Helvetica, 8, plain

    mouseover           Specifies whether the mouse pointer is over the
                        combobox. Default: off

    next                Identifies item to receive focus when user tabs
                        ahead from current item. Default: depends on
                        order in which page and item definitions occur
                        within form definition

    previous            Identifies the item to receive the focus when
                        the user tabs backwards from the current item.
                        Default: previous item within form definition

    size                Specifies combobox's size in characters.
                        Default: width=larger of label width and widest
                        cell, height=1 character

    value               Contains one of following: value of most
                        recently chosen selection, nothing if an action
                        was most recently chosen, or text entered if
                        something was typed in most recently

   Usage Notes

    1) Place cells in a combobox by creating a group for the combobox
       and assigning cells to the group. Create a group using the group
       option in the combobox definition. Assign cells to the group
       using the group option in the cell definition.

    2) Cells that have a label option will display that label in the
       list. Otherwise, the value of the cell will be displayed. When
       a cell is selected, the value of that cell will be displayed in
       the combobox and stored internally.

    3) To get the value of a cell that a user has selected from a list,

Universal Forms Description Language                           [page 70]


       you need to dereference it, like this:
        <page_tag>.<list_tag>.value->value
       For example:
        page1.countryPopup.value->value

      When a user selects a cell from a list, the item tag of the cell
      is stored as the value of the list. Hence the dereference syntax.

    4) Combobox, popup, and list items with the same group reference
       display the same group of cells.

    5) When first viewed, a combobox will display its value. If no
       value is set, the combobox will be empty.

    6) The value option will contain one of the following:
        - The value of the most recently chosen selection.
        - Nothing if an action was most recently chosen.
        - The text entered if something was typed in most recently.

    7) When setting the size option of a combobox, the height and width
       of the popup will be based on the average character size for
       the font in use (set with the fontinfo option).

    8) The label option sets the text displayed above the item, as with
       a field.

    9) When setting the editstate option, the combobox will behave in
       the following manner:
        - A readwrite setting will cause it to function normally.
        - A readonly setting will cause the combobox to refuse all
          input, although it will function normally otherwise and
          formulas will still be able to change the value.
        - A writeonly setting will cause the combobox to use "password"
          characters in its field contents, but the list of choices
          will still be displayed in plain text.
    10) When a format is applied to a combobox, the formatting will be
        applied to the value of each cell linked to the combobox.
        Those cells that fail the check will be flagged or filtered.
        Those cells that pass the check will have their value replaced
        with a formatted value. See the format option for more
        information.

    11) If any two comboboxes, lists, or popups use the same set of
        cells, they must apply the same formatting.

   Example
    This is an example of a combobox containing a set of selections
    allowing users to choose a color.

     CATEGORY_POPUP = new combobox
     {
      group = "combo_Group";
      label = "Choose a Color:";
     }


Universal Forms Description Language                           [page 71]


    Notice the default label is "Choose a Color:". This will display
    above the combobox.  Until the user types in something or makes a
    selection, the field area of the combobox will be blank.

    These are the cells that make up the combobox. Notice they are
    select cells and they belong to the same group as the combobox:
    combo_Group.

     RED_CELL = new cell
     {
      group = "combo_Group";
      type = "select";
      value = "Red";
     }
     WHITE_CELL = new cell
     {
      group = "combo_Group";
      type = "select";
      value = "White";
     }
     BLUE_CELL = new cell
     {
      group = "combo_Group";
      type = "select";
      value = "Blue";
     }
------

  4.7   data

    The data item stores an information object such as an image, a
    sound, or an enclosed file in a UFDL form. Data in data items must
    be encoded in base64 format.

    Data items are created automatically when you enclose files in a
    form. Enclose files using items with a type option setting of
    enclose.

   Available Options

    Option              Behavior
    datagroup           Identifies group or folder of enclosed files.
                        Default: n/a

    filename            Identifies name of enclosed file.
                        Default: n/a

    mimedata            Contains actual data associated with a data
                        item. Default: n/a

    mimetype            Defines MIME type of data stored in a data
                        item

   Usage Notes
    1) See the section 'Binary Data' on page 41 for more information on
       binary data in UFDL forms.

Universal Forms Description Language                           [page 72]


    2) Store the data in the mimedata option, and the data's MIME type
       in the mimetype option.

    3) If a button or cell of type enclose contains a data option that
       points to a data item (as opposed to using the datagroup
       option), then special rules apply to the data item's behavior.
       If a user encloses a new data item using that button, the new
       information overwrites the old. For example, if the data item
       originally contained a jpeg image of a dog, and then a user
       enclosed a png image of a house, then the data item's mimedata,
       mimetype, and filename options update themselves to contain the
       information about the house image.

   Example

    This is an example of a data item produced as the result of
    enclosing a file (the data component used here is artificial, and
    is only for demonstration purposes). Notice the quotation marks
    surrounding each segment of the data.

     Supporting_Documents_1 = new data
     {
      filename = "smithltr.doc";
      mimetype = "application/uwi_bin";
      mimedata =
     "R0lGODdhYABPAPAAAP///wAAACwAAAAAYABPAAAC/4SPqcvtD02Y"
     "Art68+Y7im7ku2KkzXnOzh9v7qNw+k+TbDoLFTvCSPzMrS2YzmTE+p"
     "yai3YUk9R6hee2JFP2stju+uG0ptvdeKptb+cX8wfY1jdYU4ehKDi3pdJw"
     "44yAJEqcW28cA5M0oEKnqKasZwydrK9Wo6JTtLG9p5iwtWi8Tbi/b7E0"
     "rvKixzbHJyrDq2uNggaXUs1NlLi36AW3AGv7VWhIPA7TzvdOGi/vvr0Of"
     "ft3Nrx89JewCQJYTirxi2PwgnRpNoMV5FIIboOnqTszFLFIMhQVI0yOz";
     }
------

  4.8   field

         Sample 5: Field

    The field item creates a text area where users can display and
    enter one or more lines of data. The field's characteristics
    determine the number of lines, the width of each line, and whether
    the field is scrollable.

    Field data can be protected from modification, made to display in
    the system password format (typically, hidden from view), and
    forced to conform to data type and formatting specifications.

   Available Options

    Option              Behavior
    active              Specifies whether field is active or inactive.
                        Default: on

    bgcolor             Defines background color of field.

Universal Forms Description Language                           [page 73]


                        Default: white

    bordercolor         Defines color of border around field.
                        Default: black

    editstate           Defines one of three possible edit
                        states for modifiable items: readonly,
                        writeonly, or readwrite. Default: readwrite.

    focused             Specifies whether the field has the input
                        focus. Default: off

    fontcolor           Defines font color for text or filler portion
                        of field. Default: black

    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of field.
                        Defaults: Helvetica, 8, plain

    format              Specifies data type of field's data, along with
                        flags allowing you to specify edit checks and
                        formatting you want applied to data.
                        Default: n/a

    help                Points to help message for field.
                        Default: n/a

    itemlocation        Specifies location of field in page layout.
                        Default: in body of page, under previous item
                        in page definition, aligned along page's
                        left margin

    justify             Aligns lines of text within the space field
                        occupies. Default: left

    label               Specifies external text label for field.
                        Default: n/a

    labelbgcolor        Defines background color for label specified in
                        label option. Default: in toolbar, background
                        color of toolbar; otherwise, background color
                        of page

    labelbordercolor    Defines color of border around label specified
                        in label option. Default: black

    labelborderwidth    Defines width of border around label specified
                        in label option, in pixels.
                        Default: zero pixels

    labelfontcolor      Defines font color for label specified in label
                        option. Default: black

    labelfontinfo       Defines font name, point size, and font
                        characteristics for label specified in label
                        option. Default: Helvetica, 8, plain

Universal Forms Description Language                           [page 74]


    mouseover           Specifies whether the mouse pointer is over the
                        field. Default: off
    next                Identifies item to receive focus when user tabs
                        ahead from current item. Default: depends on
                        order in which page and item definitions occur
                        within form definition

    size                Specifies field's size in characters. Default:
                        width 30 characters, height 1 character

    value               Reflects contents of field-numeric, alphabetic,
                        or otherwise. Default: n/a

   Usage Notes

    1) When setting the size option of a field, the height and width of
       the field will be based on the average character size for the
       font in use (set with the fontinfo option).

    2) The editstate option determines whether the field is read only,
       write only (for passwords, for example) or available for both
       reading and writing.

    3) The format option specifies the data type of the field's data.
       It also contains flags allowing you to specify edit checks and
       formatting you want applied to the data.

    4) The label option defines the field's label. The label is
       placed above the field and aligned with the field's left edge.

    5) The scrollvert and scrollhoriz options govern a field's
       scrolling characteristics. They must be set to always to permit
       scrolling. With scrolling enabled, scroll bars display along the
       bottom (horizontal scrolling) and right (vertical scrolling)
       edges of the field.

   Examples

    Example 1

    This is an example of a single line field item that allows 20
    characters of input. An initial value of 23000 has been defined
    for the field. When the form appears, the field will contain
    this value.

     income_field = new field
     {
      label = "Annual income";
      value = "23000";
      size = ["20", "1"];
      fontinfo = ["Courier", "12", "plain"];
      labelfontinfo = ["Helvetica", "12", "plain"];
      labelfontcolor = ["blue"];
     }

Universal Forms Description Language                           [page 75]


   Example 2

    To create a multiple line field, the vertical size of the field
    must be adjusted (either with size or with itemlocation modifiers).
    As well, vertical scroll bars can be added, and word wrapping
    turned on. Here is an example:

     job_field = new field
     {
      label = "Job Description";
      size = ["50", "5"];
      scrollvert = "always";
      scrollhoriz = "wordwrap";
      fontinfo = ["Times", "12", "plain]";
      labelfontinfo = ["Helvetica", "12", "plain"];
      labelfontcolor = ["blue"];
     }
------

  4.9   help

    A help item defines a help message you can use to support various
    external items in the form. You can create a separate help item
    for every item you want to support, or you can use one help item
    for several items.

   Available Options

    Option              Behavior
    active              Specifies whether field is active or inactive.
                        Default: on

    value               Reflects help item's contents

   Usage Notes

    1) The help item's value option contains the help message text.

    2) The link between the help item and the supported item is created
       by the help option in the supported item's definition. The help
       option contains the help item's item reference.

   Example

    This is an example of a button for which help information is
    available.

    First, here is the button definition. Notice the help item's item
    reference in the help option.

     fullPicture_button = new button
     {
      help = "button_help";
      fontinfo = ["Times", "14", "plain"];

Universal Forms Description Language                           [page 76]


      type = "link";
      url = ["http://www.server.com/application/fullPic.frm"];
     }

    Now, here is the help item referred to in the button definition.
    The contents of the value option are used as the help message
    when the user asks for help with the button.

     button_help = new help
     {
      value = "Pressing this button will bring a full-sized image in
               a form "
                "down to your viewer.";
     }
------

  4.10   label

         Sample 6: Label

    The label item defines a static text message or an image to display
    on the form. If both an image and a text message are defined for
    the label, the image takes precedence in viewers able to display
    images.

   Available Options

    Option              Behavior
    active              Specifies whether label is active or inactive.
                        Default: on

    bgcolor             Defines background color of label.
                        Default: transparent

    bordercolor         Defines color of border around label.
                        Default: black

    fontcolor           Defines font color for text or filler portion
                        of label. Default: black

    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of label.
                        Defaults: Helvetica, 8, plain

    format              Specifies data type of label's data, along
                        with flags allowing you to specify edit checks
                        and formatting you want applied to data

    help                Points to help message for label.

    image               Defines image for label. Default: n/a

    itemlocation        Specifies location of label in page layout.
                        Default: in body of page, under previous item
                        in page definition, aligned along page's
                        left margin

Universal Forms Description Language                           [page 77]


    justify             Aligns lines of text within space label
                        occupies

    size                Specifies label's size in characters. Default:
                        width 1 character if label empty, otherwise
                        label width; height 1 character if label empty,
                        otherwise label height

    value               Defines text for label. Default: n/a

   Usage Notes

    1) To define the text for a label, use the value option. To define
       an image for a label, use the image option.

    2) To create a multiple line text message, add line breaks to the
       message text. Use the escape sequence '\n' to indicate a line
       break.

    3) When setting the size option of a label, the height and width
       of the label will be based on the average character size for
       the font in use (set with the fontinfo option).

    4) If a label's image option points to a data item that dynamically
       changes its mimedata (but not its item tag), then the label will
       upate the image it displays. For information on how to update an
       image by enclosing a new one, see the data option description.

    5) The label's background color defaults to being transparent - and
       thus the label will take the background color of whatever item
       it is over. For example, if you wanted to place a label inside a
       colored box, in order to make a title section that stands out,
       you could do so without specifying a background color for the
       label:
     box = new box
     {
        size = ["30", "3"];
     }
     label = new label
     {
        itemlocation = [["alignhorizc2c", "box"],
                                ["alignvertc2c", "box"]];
        value = "Great Insurance";
        fontcolor = ["white"];
        fontinfo = ["Helvetica", "14", "bold"];
     // Note: you could also specify bgcolor = ["transparent"], but you
              don't
     // need to because the default is transparent.
     }

   Examples

    Example 1
    This is an example of a text label. The text is centered in the

Universal Forms Description Language                           [page 78]


    space the label occupies. The label width is 30 characters (thus
    it is bigger than the text in the label).
     MAINMENU_LABEL = new label
     {
      value = "Welcome to the Main Menu";
      fontinfo = ["Helvetica", "24", "bold", "italic"];
      size = ["30", "1"];
      justify = "center";
     }

    Example 2

    This is an example of a multiple line text label. Notice the line
    break escape sequences indicating the end of each line.
     // Specify right justification for this label.
     RHYME_LABEL = new label
     {
      value = "Little miss Muffet\n Sat on her tuffet,\n"
                "Eating her curds and whey.\n When along came a
                 spider,\n"
                "who sat down beside her,\n and frightened miss
                 Muffet away!";
      fontinfo = ["Times", "16", "italic"];
     }
------

  4.11   line

         Sample 7: Line

    The line item draws a simple vertical or horizontal line on the
    form. This is useful when you want to visually separate parts of
    a page.

   Available Options

    Option              Behavior
    fontcolor           Defines font color for text or filler portion
                        of label. Default: black

    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of label.
                        Defaults: Helvetica, 8, plain

    itemlocation        Specifies location of line in page layout.
                        Default: in body of page, under previous item
                        in page definition, aligned along page's
                        left margin

    size                Determines whether line is horizontal or
                        vertical: if horizonal dimension=0 then line is
                        vertical, if vetical dimension=0 then line is
                        horizontal; calculated in characters

    thickness           Determines how thick line will be, in pixels


Universal Forms Description Language                           [page 79]


   Usage Notes
    1) Specify the dimensions of a line using the size and thickness
       options. The size option determines whether the line is vertical
       or horizontal. If the horizontal dimension is set to zero, then
       the line is vertical. If the vertical dimension is set to zero,
       then the line is horizontal. Size is calculated in characters.
       - The thickness option determines how thick the line will be.
         Thickness is calculated in pixels.

    2) The fontinfo option information is used when calculating the
       line's size. The size option's unit of measurement is
       characters; therefore, choice of font can affect the size. See
       the size option for more information.
    3) The fontcolor option defines the color of the line.

   Example

    This is an example of a horizontal line with a thickness of five
    pixels.
     BLUE_LINE = new line
     {
      size = ["40", "0"];
      thickness = "5";
     }
------

  4.12   list

         Sample 8: List

    The list item creates a list from which users can make selections
    (as in a list of names) and trigger actions (such as enclosing
    files and submitting the form). A list can contain both selections
    and actions.

    The entries in the list are cell items. Selections are cells with
    a type option setting of select. Actions are cells with any other
    type option setting.

   Available Options

    Option              Behavior
    active              Specifies whether list is active or inactive.
                        Default: on

    bgcolor             Defines background color of list.
                        Default: white

    bordercolor         Defines color of border around list.
                        Default: black

    editstate           Defines one of three possible edit states
                        for modifiable items: readonly, writeonly,
                        or readwrite. Default: readwrite.


Universal Forms Description Language                           [page 80]


    focused             Specifies whether the list has the input focus.
                        Default: off

    fontcolor           Defines font color for text or filler portion
                        of list. Default: black

    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of list.
                        Defaults: Helvetica, 8, plain

    format              Applies to value of each cell linked to list,
                        flagging or filtering cells that fail check,
                        and replacing value of cells that pass with
                        formatted value. See format option

    help                Points to help message for list.

    itemlocation        Specifies location of list in page layout.
                        Default: in body of page, under previous item
                        in page definition, aligned along page's
                        left margin

    label               Specifies external text label for list.
                        Default: n/a

    labelbgcolor        Defines background color for label specified
                        in label option. Default: in toolbar,
                        background color of toolbar; otherwise,
                        background color of page

    labelbordercolor    Defines color of border around label specified
                        in label option. Default: black

    labelborderwidth    Defines width of border around label specified
                        in label option, in pixels.
                        Default: zero pixels

    labelfontcolor      Defines font color for label specified in label
                        option. Default: black

    labelfontinfo       Defines font name, point size, and font
                        characteristics for label specified in
                        label option. Default: Helvetica, 8, plain

    mouseover           Specifies whether the mouse pointer is over the
                        list. Default: off

    next                Identifies item to receive focus when user tabs
                        ahead from current item. Default: depends on
                        order in which page and item definitions occur
                        within form definition

    size                Specifies list's size in characters. Default:
                        width=larger of label width and widest cell,
                        height=number of cells in list
    value               Contains item reference of most recently
                        selected cell in list (if it was a select
                        cell); contains nothing if most recently
                        selected cell was not a select cell

   Usage Notes

    1) Place cells in a list by creating a group for the list and
       assigning cells to the group. Create a group using the group
       option in the list definition. Assign cells to the group using
       the group option in the cell definition.

    2) Cells that have a label option will display that label in the
       list. Otherwise, the value option of the cell will be displayed.

    3) To get the value of a cell that a user has selected from a list,
       you need to dereference it, like this:
        <page_tag>.<list_tag>.value->value
     For example:
     page1.countryPopup.value->value

    4) When a user selects a cell from a list, the item tag of the cell
       is stored as the value of the list. Hence the dereference
       syntax.

    5) List, combobox and popup items with the same group reference
       display the same group of cells.

    6) The value option will contain one of the following:
        - The item reference of the most recently chosen cell if the
          cell was of type "select".
        - Nothing if the cell most recently chosen was of any type
          other than "select".

    7) Define the list's label using the label option.

    8) When setting the size option of a list, the height and width of
       the list will be based on the average character size for the
       font in use (set with the fontinfo option).

    9) A vertical scroll bar will appear beside the list if the number
       of cells is greater than the height (defined with the size
       option) of the list.

    10) When a format is applied to a list, the formatting will be
        applied to the value of each cell linked to the list.  Those
        cells that fail the check will be flagged or filtered.  Those
        cells that pass the check will have their value replaced with a
        formatted value. See the format option for more information.

    11) If any two comboboxes, lists, or popups use the same set of
        cells, they must apply the same formatting.

   Example

    This is an example of a list containing three actions: submit form,

Universal Forms Description Language                           [page 82]


    save form, and cancel form.

    Here is the list definition.

    MAINMENU_LIST = new list
    {
     group = "list_Group";
     label = "Options Menu";
     labelfontcolor = ["blue"];
     size = ["3", "20"];
    }

    These are the cells that make up the list. Notice they are action
    cells and they belong to the same group as the list: list_Group.
     SUBMIT_CELL = new cell
     {
      group = "list_Group";
      type = "submit";
      url = ["http://www.server.com/cgi-bin/processForm"];
      value = "Submit Form";
     }
     SAVE_CELL = new cell
     {
      group = "list_Group";
      type = "save";
      value = "Save Form";
     }
     CANCEL_CELL = new cell
     {
      group = "list_Group";
      type = "cancel";
      value = "Cancel this Form";
     }
------

  4.13   popup

         Sample 9: Popup Menu

    The popup item creates a popup menu from which users can make
    selections (as in a list of names) and trigger actions (such as
    enclosing files and submitting the form). A popup can contain both
    selections and actions.

    The entries in the popup are cell items. Selections are cells with
    a type option setting of select. Actions are cells with any other
    type option setting.
    Popups act like a hybrid of a label, a button, and a list.
    Unopened, a popup occupies only the space required for its label.
    Open, the popup displays a list of selections and actions. After a
    user chooses a selection or an action, the popup closes (that is,
    returns to its unopened state). A popup's label displays inside the
    popup item.

   Available Options

Universal Forms Description Language                           [page 83]


    Option              Behavior
    activated           Specifies whether the popup list is
                        "popped up". Default: off

    active              Specifies whether popup is active or inactive.
                        Default: on

    bgcolor             Defines background color of popup.
                        Default: white

    bordercolor         Defines color of border around popup.
                        Default: black

    borderwidth         Defines width of popup's border, in pixels.
                        Default: one pixel

    editstate           Defines one of three possible edit states for
                        modifiable items: readonly, writeonly, or
                        readwrite. Default: readwrite.

    focused             Specifies whether the popup has the input
                        focus. Default: off

    fontcolor           Defines font color for text or filler portion
                        of popup. Default: black

    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of popup.
                        Defaults: Helvetica, 8, plain

    group               Groups cells in popup together.

    help                Points to help message for popup.

    itemlocation        Specifies location of popup in page layout.
                        Default: in body of page, under previous item
                        in page definition, aligned along page's
                        left margin

    justify             Aligns lines of text within the space popup
                        occupies.

    label               Specifies external text label for popup.
                        Default: n/a

    mouseover           Specifies whether the mouse pointer is over the
                        popup. Default: off

    next                Identifies item to receive focus when user tabs
                        ahead from current item. Default: depends on
                        order in which page and item definitions occur
                        within form definition

    size                Specifies popup's size in characters.
                        Default: width=larger of label width and widest

Universal Forms Description Language                           [page 84]


                        cell, height=1 character

    value               Contains item reference of most recently
                        selected cell in popup (if it was a select
                        cell); contains nothing if most recently
                        selected cell was not a select cell

   Usage Notes

    1) Place cells in a popup by creating a group for the popup and
       assigning cells to the group. Create a group using the group
       option in the popup definition. Assign cells to the group using
       the group option in the cell definition.

    2) Cells that have a label option will display that label in the
       list. Otherwise, the value of the cell will be displayed. When
       a cell is selected, the value of that cell will be displayed
       in the popup.

    For example, if cell had a value of "USA", and a label of "United
    States of America", the full version would be shown in the popup
    list.  Once the cell was selected, the popup would display
    the abbreviation.

    3) To get the value of a cell that a user has selected from a list,
       you need to dereference it, like this:
       <page_tag>.<list_tag>.value->value

     For example:
     page1.countryPopup.value->value

    When a user selects a cell from a list, the item tag of the cell is
    stored as the value of the list. Hence the dereference syntax.

    4) Popup, combobox and list items with the same group reference
       display the same group of cells.

    5) The value option will contain one of the following:
        - The item reference of the most recently chosen cell if the
          cell was of type "select".
        - Nothing if the cell most recently chosen was of any type
          other than "select".
    6) When setting the size option of a popup, the height and width
       of the popup will be based on the average character size for
       the font in use (set with the fontinfo option).

    7) The label option contains the popup's default label. When the
       value option is empty, the default label displays. Otherwise,
       the label of the cell identified in the value option appears.

    8) When a format is applied to a popup, the formatting will be
       applied to the value of each cell linked to the popup.  Those
       cells that fail the check will be flagged or filtered.  Those
       cells that pass the check will have their value replaced with
       a formatted value. See the format option for more information.

Universal Forms Description Language                           [page 85]


    9) If any two comboboxes, lists, or popups use the same set of
       cells, they must apply the same formatting.

   Example

    This is an example of a popup containing a set of selections
    allowing users to choose a category.

    Here is the popup definition. Notice the default label is "Choose
    a Category:". This will display until a user makes a selection.
    Afterwards, the cell's value will display as the label.
     CATEGORY_POPUP = new popup
     {
      group = "popup_Group";
      label = "Choose a Category:";
     }

    These are the cells that make up the popup. Notice they are select
    cells and they belong to the same group as the popup: popup_Group.

     HISTORY_CELL = new cell
     {
      group = "popup_Group";
      type = "select";
      value = "World History";
     }
     SCIENCE_CELL = new cell
     {
      group = "popup_Group";
      type = "select";
      value = "Physical Sciences";
     }
     MUSIC_CELL = new cell
     {
      group = "popup_Group";
      type = "select";
      value = "Music";
     }
------

  4.14   radio

         Sample 10: Radio Buttons
    The radio button item is intended for use with one or more other
    radio button items. A group of radio buttons presents users with a
    set of mutually exclusive choices. Each radio button represents one
    choice the user can make.

    There is always one selected radio button in the group. As well,
    since radio buttons present a mutually exclusive set of choices,
    only one radio button in a group can be selected. When a user
    chooses a radio button, that radio button becomes selected.

    A selected radio button appears filled in some way. All other radio
    buttons in the group appear empty.

Universal Forms Description Language                           [page 86]


   Available Options

    Option              Behavior
    active              Specifies whether radio button is active or
                        inactive. Default: on

    bgcolor             Defines background color of radio button.
                        Default: white

    bordercolor         Defines color of border around radio button.
                        Default: black

    borderwidth         Defines width of radio button's border, in
                        pixels. Default: 1 pixel

    editstate           Defines one of three possible edit states for
                        modifiable items: readonly, writeonly, or
                        readwrite. Default: readwrite.

    focused             Specifies whether the radio button has the
                        input focus. Default: off

    fontcolor           Determines color of radio button fill pattern.
                        Default: red
    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of radio
                        button. Defaults: Helvetica, 8, plain

    group               Groups radio buttons together.

    help                Points to help message for radio button.

    itemlocation        Specifies location of radio button in page
                        layout. Default: in body of page, under
                        previous item in page definition, aligned
                        along page's left margin

    label               Defines label to appear above radio button and
                        aligned with left edge.

    mouseover           Specifies whether the mouse pointer is over the
                        radio button. Default: off

    next                Identifies item to receive focus when user tabs
                        ahead from current item. Default: depends on
                        order in which page and item definitions occur
                        within form definition

    size                Specifies radio button's size in characters.
                        Default: width 1 character, height 1 character

    value               Indicates radio button's status: on indicates
                        chosen, off indicates not chosen.
                        Default: not chosen

Universal Forms Description Language                           [page 87]


   Usage Notes
    1) Group radio buttons by assigning them to the same group. Do this
       by including the group option in each radio button's definition,
       and using the same group reference in each case.

    2) The value option contains the status indicator. It can be either
       on or off. The value on indicates a status of chosen. The value
       off indicates a status of not chosen. The default status is
       not chosen.

    3) When the form opens, if no radio button has the status chosen,
       then the last radio button defined for the group becomes chosen.
       If multiple radio buttons are chosen, then only the last
       'chosen' radio button retains that status.

    4) The label option defines a label to appear above the radio
       button and aligned with its left edge.

    5) When setting the size option of a radio button, the height
       and width of the bounding box will be based on the average
       character size for the font in use (set with the fontinfo
       option).

    6) The fontcolor option determines the color of the radio button
       fill pattern (default is red).

   Example

    This example shows a group of three radio buttons. The first radio
    button is the initial choice: the value option setting is on.
    The buttons all belong to the group search_Group.

     NAME_RADIO = new radio
     {
      value = "on";
      group = "search_Group";
      label = "Search by Name";
     }
     NUMBER_RADIO = new radio
     {
      group = "search_Group";
      label = "Search by Number";
     }
     OCCUPATION_RADIO = new radio
     {
      group = "search_Group";
      label = "Search by Occupation";
     }

    As shown here, only the chosen radio button needs to have a value
    option setting. The remaining radio buttons will receive the
    (default) value setting of off.
------

  4.15   signature

Universal Forms Description Language                           [page 88]


    The signature item contains a digital signature and the data
    necessary to verify the authenticity of a signed form.  It is
    created by a form viewer or other program when a user signs a
    form (usually using a digital signature button). The signature
    item contains an encrypted hash value that makes it impossible
    to modify the form without changing the hash value that the
    modified form would generate. To verify, one can generate the hash
    value and then see if it matches the one in the signature.

   Available Options

    Option              Behavior
    mimedata            Contains actual data associated with signature.
                        Default: n/a

    signature           Identifies the button that created the
                        signature. Default: n/a

    signdatagroups      Identifies group or folder of enclosed files
                        to be filtered for signature. Default: "Order
                        of Precedence of Filters"
    signer              Adds text similar to user's email signature,
                        identifying who signed form. Default: n/a

    signformat          Controls what system parameters are used to
                        create the signature. Default:
                        application/uwi_form

    signgroups          Identifies groups of items to be filtered for
                        signature.  Default: "Order of Precedence of
                        Filters"

    signitemrefs        Identifies item references to be filtered for
                        signature. Default: "Order of Precedence of
                        Filters"

    signitems           Identifies type of items to be filtered for
                        signature. Default: "Order of Precedence of
                        Filters"

    signoptionrefs      Identifies option references to be filtered for
                        signature. Default: "Order of Precedence of
                        Filters"

    signoptions         Identifies type of options to be filtered for
                        signature. Default: "Order of Precedence of
                        Filters"

   Usage Notes

    1) When a user signs a form using a signature button, the viewer
       creates the signature item as specified in the button's
       signature option. The viewer also associates the signature with
       the signature button, using the signature's signature option.

Universal Forms Description Language                           [page 89]


    2) When a user signs a form, the signer, signformat, signgroups,
       signitemrefs, signitems, signoptionrefs, and signoptions options
       are copied from the button description to the
       signature description.

    3) A copy of the UFDL description of the form or portion of the
       form that is signed is included in the signature's mimedata
       option. This data is encrypted using the hash algorithm
       specified in the button's signformat option.

    4) When a program checks a signed form, it compares the data in the
       mimedata option with that of the portion of the form that is
       apparently signed. If the descriptions match, then the
       signature remains valid. If the signatures do not match, the
       signature breaks, and the user is prompted.

    5) An attempt to create a signature will fail if:
       - The item named by the signature button's signature option
         already exists.
       - The signature button is already signed by any signature in the
         form.
       - The signer's private key is unavailable for signing.

    6) Filters allow you to indicate which items and options to keep
       and to omit. The explicit and implicit settings of an existing
       filter take precedence over an implication that might be drawn
       from a non-existing filter. Set up these filters in the
       signature button description. For details on the order in which
       filters are applied, see "Order of Precedence of Filters"

    7) To use digital signatures, it is necessary for the user to
       obtain a digital signature certificate.

   Example

    This example shows a signature item below the signature button
    that created it.

     empSigButton = new button
     {
        type = "signature";
        value = signer;
        format = ["string", "mandatory"];
        signformat = "application/uwi_form;csp=\"Microsoft Base
     Cryptographic Provider v1.0\";csptype=rsa_full;hashalg=sha1";
     signoptions = ["omit", "triggeritem", "coordinates"];
        signitemrefs = ["omit", "PAGE1.mgrSigButton",
                      "PAGE1.admSigButton","PAGE1.empSignature",
                      "PAGE1.mgrSignature","PAGE1.admSignature"];
        signature = "empSignature";
     }
     ...
     empSignature = new signature
      {
                signformat = "application/uwi_form;csp=\"Microsoft Base

Universal Forms Description Language                           [page 90]


     Cryptographic Provider v1.0\";csptype=rsa_full;hashalg=sha1";
                signer = "Jane D Smith, jsmith@insurance.com";
                signature = "PAGE1.empSignature";
                signitemrefs = ["omit", "PAGE1.mgrSigButton",
                        "PAGE1.admSigButton","PAGE1.empSignature",
                        "PAGE1.mgrSignature", "PAGE1.admSignature"];
                signoptions = ["omit", "triggeritem", "coordinates"];
               mimedata ="MIIFMgYJKoZIhvcNAQcCoIIFIzCCBR8CAQExDzANBgkg"
                 "AQUFADALB\ngkqhkiG9w0BBwGgggQZMCA36gAwSRiADjdhfHJl"
                 "6hMrc5DySSP+X5j\nANfBGSOI\n9w0BAQQwDwYDVQQHEwhJbn"
                 "Rlcm5ldDEXMBUGA1UEChM\nOVmVyaVNpZ24sIEluYy4xNDAKn"
                 "1ZlcmlTaWduIENsYXNzIDEgQ0Eg\nLSJbmRdWFsIFN1YnNjcmliy"
                 "ZXIwHhcNOTgwMTI3MwMDAwOTgwM\M1OTU5WjCCARExETA";
------

  4.16   spacer

    The spacer item creates space between items on a form. It can be
    any size you specify. It is invisible.

   Available Options

    Option              Behavior
    fontinfo            Defines font name, point size, and font
                        characteristics for label of spacer.
                        Defaults: Helvetica, 8, plain

    itemlocation        Specifies location of radio button in page
                        layout. Default: in body of page, under
                        previous item in page definition, aligned along
                        page's left margin

    label               Determines size of spacer, though not visible.

    size                Specifies spacer's size in characters. Default:
                        width=1 character if label empty, otherwise
                        label width, height=1 character if label empty,
                        otherwise label height

   Usage Notes

    1) You can size a spacer either by giving it length and width
       dimensions (using size), by expanding the default size using the
       itemlocation option or by giving it a label. If you use a label,
       the spacer equals the size of the text you type into the label.
       The label does not appear; it is simply used to determine the
       spacer's size.

    2) When setting the size option of a spacer, the height and width
       of the spacer will be based on the average character size for
       the font in use (set with the fontinfo option).

   Example

    Example 1

Universal Forms Description Language                           [page 91]


    This example shows a spacer item that uses the size option to
    define the amount of space it will occupy.
     3_SPACER = new spacer
     {
      size = ["1", "3"];
     }

    Example 2

    This example shows the spacer item that uses a label to define the
    amount of space it will occupy. This sizing technique is useful if
    you want to create a spacer that is exactly the same size as a real
    label on the form.
     WELCOME_SPACER = new spacer
     {
      label = "Welcome to Information Line";
     }
------

  4.17   tablet

         Sample 11: Tablet

    The tablet item creates a rectangular space or drawing object on
    the page where users can draw or write using the mouse pointer.
    This allows users to do such things as sign the form.

    To draw on a tablet, users hold down the left mouse button while
    moving the mouse pointer over the space. To erase the marks, users
    position the mouse over the tablet, hold down CONTROL and click the
    right mouse button.

    The tablet's background may be blank or composed of an image. The
    user draws on the background.

   Available Options

    Option              Behavior
    active              Specifies whether tablet is active or inactive.
                        Default: on

    bgcolor             Defines background color of radio button.
                        Default: page background color

    bordercolor         Defines color of border around tablet.
                        Default: black

    borderwidth         Defines width of tablet's border, in pixels.
                        Default: 1 pixel

    editstate           Defines one of three possible edit states for
                        modifiable items: readonly, writeonly, or
                        readwrite. Default: readwrite.

    fontcolor           Determines pen color

Universal Forms Description Language                           [page 92]


    fontinfo            Defines font name, point size, and font
                        characteristics for text portion of tablet.
                        Defaults: Helvetica, 8, plain

    help                Points to help message for tablet.

    image               Associates tablet with data item. Default: n/a

    itemlocation        Specifies location of tablet in page layout.
                        Default: in body of page, under previous item
                        in page definition, aligned along page's
                        left margin

    justify             Aligns lines of text within space tablet
                        occupies.

    mouseover           Specifies whether the mouse pointer is over
                        the tablet. Default: off

    size                Specifies tablet's size in characters. Default:
                        width 1 character, height 1 character

    value               Used to set initial size of tablet; otherwise,
                        tablet sizes itself to size of text
                        entered in value

   Usage Notes

    1) A tablet item must contain an image option that associates it
       with a data item. The data item must also exist in the form.
       The user's drawing marks will be stored as image data in the
       data item.

    2) For example, this is the code necessary to create a blank tablet
       (that contains no image background) on a form.
     sketch_tablet = new tablet
     {
      fontcolor = ["blue"];
      size = ["30", "5"];
      image = "sketch_data";
     }
     ...
     sketch_data = new data
     {
     }

    3) To place an image in a tablet's background, store the image data
       in the data item already associated with the tablet. Note that
       when the user draws on the tablet, the user's marks will be
       stored as part of the same image.

    For example, this piece of sample form code shows a tablet that
    contains an image called sign_data.
     sign_tablet = new tablet
     {

Universal Forms Description Language                           [page 93]


        fontcolor = ["blue"];
        size = ["30", "5"];
        image = "sign_logo";
     }
     ...
     sign_data = new data
     {
        mimedata = "R0lGODdhYABPAPAAAP///wAAACwAAAAAYABA/"
     "Art68+Y7im7ku2KkzXnOzh9v7qNw+k+TbDoLFTvCSPzMrSzTE+p"
     "yai3YUk9R6hee2JFP2stju+uG0ptvdeKptb+cX8wfY1jdYU4KpdJw"
     "44yAJEqcW28cA5M0oEKnqKasZwydrK9Wo6JTt9p5iwt8bi/b7E0"
     "rvKixzbHJyrDq2uNggaXUs1NlLi36AW3AGv7VWhIPAzvdGi/vvr0Of"
     "ft3Nrx89JewCQJYTirxi2PwgnRpNoMV5FIIboOnqTszFMhVI0yOz";
     }

    4) The fontcolor option determines the pen color.

    5) The pen width is two pixels.

    6) The value can be used to set the initial size of the tablet.
       If no size is indicated, and no mimedata exists, the tablet will
       size itself to the size of the text entered in the value.

    7) If an enclosure mechanism is used to replace an image stored
       in a data item with a new image, then buttons, labels, and
       tablets whose image option is set to the identifier of the
       image data item will be updated to display the new image.
       For details, see the data option description.

   Example

    This example shows a blank tablet with a background color of pale
    green. It is 40 characters wide and 10 characters high.
     users_signature = new tablet
     {
      bgcolor = ["PaleGreen"];
      size = ["40", "10"];
      fontinfo = ["Courier", "12"];    // This governs the size.
      fontcolor = ["black"];           // This governs pen color.
      image = "signature_data";
     }
     signature_data = new data
     {
     }
------

  4.18   toolbar

         Sample 12: Toolbar

    The toolbar item allows you to define a toolbar for your page. A
    toolbar is a separate and fixed area at the top of the page. It
    functions much like a toolbar in a word processing application.
    Typically, you place items in the toolbar that you want users to
    see no matter what portion of the page they are viewing.

Universal Forms Description Language                           [page 94]


    The toolbar is visible no matter what portion of the page body is
    visible. However, if the toolbar is larger than half the form
    window, you will have to scroll to see everything it contains.

    Refer to the section 'Toolbars' for more information on toolbars.

   Available Options
    You can use the following option with toolbar:

    Option              Behavior
    bgcolor             The background color of the toolbar. Default:
                        background color of page.

    mouseover           Specifies whether the mouse pointer is over
                        the toolbar. Default: off

   Usage Notes

    1) The background color of the toolbar becomes the default
       background color for items in the toolbar.

    2) Add items to the toolbar using the within modifier of the
       itemlocation option. Code the itemlocation option in each
       included item's definition.

   Example

    This example shows a toolbar that contains a label, a spacer, and
    two buttons.

    Here is the toolbar definition:

     TOOL_BAR = new toolbar
     {
      bgcolor = ["cornsilk"];
     }

    Here are the items belonging to the toolbar.

     COMPANY_NAME = new label
     {
      value = "My Company";
      itemlocation = [["within", "TOOL_BAR"]];
     }
     TB_SPACER = new spacer
     {
      itemlocation = [["within", "TOOL_BAR"], ["below", "COMPANY_NAME"]];
     }
     SUBMIT_BUTTON  = new button
     {
      value = "Submit Form";
      type = "submit";
      url = ["http://www.server.com/cgi-bin/formProcessor"];
      itemlocation = [["within", "TOOL_BAR"], ["below", "TB_SPACER"]];
     }

Universal Forms Description Language                           [page 95]


     CANCEL_BUTTON  = new button
     {
      type = "cancel";
      itemlocation = [["within","TOOL_BAR"], ["after", "SUBMIT_BUTTON"]];
     }
------

  4.19   <custom item>
    Custom items allow form designers to add application specific
    information to the form definition. This is useful when
    submitting forms to applications requiring non-UFDL information.
    An example of non-UFDL information might be an SQL query statement.

   Available Options

    You can use all UFDL options and any custom options with custom
    items.

   Usage Notes

    1) The naming conventions for a custom item are as follows:
        - It must begin with an alphabetic character.
        - It can contain any of the characters A-Z, a-z, 0-9, $ and
          underscore.
        - It must contain an underscore.

   Example

    This is an example of a custom item definition. It includes both
    a UFDL and a custom option.

     STATUS_EVENT = new ma_event
     {
      active = "off";
      ma_id = "UF45567 \t /home/users/preferences01";
     }
------


5.   UFDL Form Options

    An option defines a characteristic of a form, a page, or an item.
    An option definition is an assignment statement. The expression
    on the right hand side of the equal sign contains the option's
    setting. The syntax of an option definition statement is
    as follows:

     <option identifier> = <expression>;
     Note: The semicolon is mandatory and terminates the statement.

    Option identifier is a name that identifies the type of option. It
    can be a UFDL-defined option or a custom option. Examples of option
    identifier are: bgcolor, fontinfo, itemlocation, and size. See the
    following pages for a description of each option and its possible
    values.

Universal Forms Description Language                           [page 96]


    An expression specifies a value. An expression can be any of the
    following:
        - a literal
        - a reference to another option definition in the form
        - an operation
        - an array specification

    Use an array specification for options requiring or permitting
    multiple values. The syntax of an array specification is as
    follows: [PD1]

     [<element1>, <element2>, ... <elementn>]
     Note: 'n' is the number of settings in the option.

    An element can be any of the following:
        - an expression
        - an element definition statement

    The brackets surrounding the array specification are mandatory even
    when there is only one element in the list.

    The evaluation of array elements is done in their order of position
    unless the elements have UFDL-defined variable names. See the
    following section for a discussion of variable names.

    Element Definition Statements

    The element definition statement allows you to assign a variable
    name to an array element. Variable names permit you to refer to the
    element by name rather than by its position in the array. The
    syntax of an element definition statement is:

     <variable> = <expression>

    See the section 'Option Definition' for more information on
    expressions and arrays.

    Characteristics

    Options set for the form or a page are called characteristics. Form
    characteristics are global to the entire form. Page characteristics
    are global to the page on which they occur.

    Defining Form Characteristics

    Defining form characteristics is optional. It has the effect of
    setting characteristics that are global to the form. These
    characteristics override the defaults defined by UFDL. Specific
    pages or items will override these global characteristics if the
    same option is set differently for that page or item.

    Use the reference global.global when referring to form
    characteristics.

    Defining Page Characteristics

Universal Forms Description Language                           [page 97]


    Defining page characteristics is also optional. It has the effect
    of setting characteristics that are global to the page. These
    settings override the defaults defined by UFDL and any form
    characteristics. Specific pages or items will override these global
    characteristics if the same option is set differently for that page
    or item..

    Use the reference global or <page tag>.global when referring to
    page characteristics.

   Item Reference

    An item reference identifies a particular item instance. The syntax
    of an item reference is as follows:
        <item tag>
        - for items on another page
        <page tag>.<item tag>

   Data Type Designators

    UFDL defines a set of data types to describe the variable data in
    option settings. Each option's description includes the necessary
    data type information.

    UFDL uses the following data type designators:

    Data Type           Description
    char                a single ASCII character

    string              a series of ASCII characters

    color               a color name or an RGB triplet representing
                        the color
                        - The syntax of an RGB triplet is: [<red>,
                          <green>, <blue>]. For example, the triplet
                          for green is: ["0", "255", "0"].
                        - See Appendix B: 'Color Table' on page 300 for
                          a list of supported colors. The list contains
                          the color names and their RGB triplets.

    coordinate          whole number in the range 0 to 1,000
                        representing one coordinate of a position

    integer             positive or negative whole number in the range
                        -32,768 to 32,767

    long int            whole number in the range 0 to 2,147,483,647

    short int           whole number in the range 0 to 255

    unsigned            whole number in the range 0 to 65,535


   Syntax Notation Conventions

Universal Forms Description Language                           [page 98]


         Tip: UFDL is case sensitive. All option
              names are lowercase.

    The following syntax notation conventions have been used in the
    sections following:
     - Names have been assigned to each expression on the right hand
       side of the assignment operator (=). The meaning and setting of
       each expression appear in a table below the syntax diagram.
       For example,
        fontinfo = [<font name>, <point size>, <weight>, <effects>,
                  <form>];
        Note: <weight>, <effects>, and <form> are optional.

    Expression     Setting        Description

    <font name>    string         the name of the font
    <point size>   short int      the size of the font
    <weight>       "plain"        use plain face
                   "bold"         use bold face
    <effects>      "underline"    underline the text
    <form>         "italics"      use the italic form

     - In the table, the Setting column indicates whether the
       expression requires variable data or a constant value. Variable
       data is represented by a data type; a constant value is
       represented by the required keyword. Data types appear in
       italics (for example, string); constants display in bold face
       (for example, underline).
     - A set of mutually exclusive choices is represented by a list of
       settings beside an expression's name in the table. For example,
       in the fontinfo statement, the <weight> expression can be one
     - The syntax of an expression can take many forms. For example,
       the following formats are all valid:
        value = "Sample expression";
        value = field_one.value;
        value = "Sample " +. field_two.value;

    As a consequence of the variation, syntax diagrams make no
    reference to an expression's format.

    See the section 'Option Definition' for a discussion of expression
    formats.
     - Repeating expressions are represented using an <opt1>, ...
      <optn> notation and an explanatory note. For example,
      datagroup = [<datagroup reference1>, ... <datagroup referencen>];
      Note: Include a <datagroup reference> entry for each datagroup
            this item accesses.

     - Optional expressions are noted in an explanatory note. For example,
       fontinfo = [<font name>, <point size>, <weight>,
                  <effects>, <form>];
       Note: <weight>, <effects> and <form> are optional.
------


Universal Forms Description Language                           [page 99]


  5.1   activated

    The activated option specifies whether an item, page, or form is
    currently activated by the user or not. This option is set by code
    outside UFDL.

   Syntax

    activated = "<status>";

    Expression     Setting        Description
    <status>       "on"           item, page, or form is currently
                                   activated by user
                   "off"          item, page, or form is not
                                   currently activated by user
                   "maybe"        button only: item might be activated,
                                   as user has pressed it, but has not
                                   yet released it

   Available In
              - action
              - button
              - cell
              - combobox
              - popup
              - page global
              - form global

   Example

    The following example shows a button that changes color based on
    whether it is currently activated.
     saveButton = new button
     {
        type = "save";
        value = "Save";
        bgcolor = [activated=="on" ? "white" : "LightPink3"];
     }

    The button will appear white when the user activates it, and gray
    otherwise.

   Usage Notes

    1) Default: off

    2) Any pre-defined setting for activated, including a formula
       setting, will be destroyed as soon as the first activated event
       appears. The activated option is not intended to be set by UFDL
       script, but rather by external forces-a form viewing program,
       for example.

    3) activated is set to on when an item is activated, and remains
       on until any transaction initiated by the item is properly under
       way. For example, in a print button, activated will be turned on
       when the user initiates the print action, and will remain on

Universal Forms Description Language                          [page 100]


       until network results indicate the print action is taking place.

    4) The activated option is not included in form descriptions that
       are saved or transmitted.

    5) Specific details on activated behavior for each item:

       *      action - actions set activated to on when they fire, and
         off when the transaction they initiate is under way.

       *      button - buttons set activated to maybe when the user
         holds the mouse pointer or SPACE bar down on the button. They
         set it to on if the user releases the pointer or SPACE bar
         while over the button, and they set activated to off when the
         transaction the button initiates is under way.

       *      cell - cells behave in the same manner as buttons. In the
         split second during which a user selects a select type of
         cell, it sets activated to on. It turns activated off as soon
         as the action of being selected is finished. Cells that
         initiate network transactions set activated to on from the
         beginning of the request to the time when the request produces
         results. Note that there is no maybe status for a cell.
       *      combobox and popup - comoboxes and popup lists set
         activated to on when their lists are popped open, and off when
         the lists are not open. Note that the "field" portion of a
         combobox does not register an activated setting.

       *      page - a page sets activated to on while it is displayed
         on screen, and off when it is not.

       *      form - a form sets activated to on while it is displayed
         on screen, and off when it is not.
------

  5.2   active

    The active option specifies whether an item is active or inactive.
    Inactive items do not respond to user input and, if possible,
    appear dimmed.

    For example, an inactive check box will be dimmed and the user will
    not be able to select or deselect the box.

   Syntax

     active = <status>;

    Expression     Setting        Description
    <status>       "on"           item is active
                   "off"          item is inactive

   Available In
              - action
              - button

Universal Forms Description Language                          [page 101]


              - cell
              - check
              - field
              - help
              - label
              - list
              - popup
              - radio
              - tablet

   Example

    This sample specifies the item is active.
     active = "on";

   Usage Notes

    1) Default: on

    2) Setting active to off would be similar to setting an edit state
       of readonly.
------

  5.3   bgcolor

    The bgcolor option defines the background color of a page or
    an item.

   Syntax

    bgcolor = [<color name>];
    bgcolor = [<RGB triplet>];
    Note: Either format is acceptable.

    Expression     Setting        Description
    <color name>   color          the color name
    <RGB triplet>  color          the RGB triplet. See 'Data Type
                                  Designators' for the syntax of an
                                  RGB triplet.

   Available In
              - button
              - check
              - field
              - list
              - popup
              - radio
              - tablet
              - toolbar
              - page global characteristics
              - form global characteristics

   Examples

    These samples both set the background color to forest green.

Universal Forms Description Language                          [page 102]


     bgcolor = ["forest green"];
     bgcolor = ["34", "139", "34"];
     bgcolor = ["transparent"];

   Usage Notes

    1) The transparent color has no RGB equivalent.

    2) Default: varies depending on the object
       Form: white
       Page: the form background color
       Item: depends on the item type-
       button items: gray (or grey)
       check, combobox field, list, popup, and radio items: white
       label items: transparent (version 4.0.1 and greater)
       all other items: the background color of the page
------

  5.4   bordercolor

    The bordercolor option defines the color of the border around the
    item.

   Syntax

     bordercolor = [<color name>];
     bordercolor = [<RGB triplet>];
     Note: Either format is acceptable.

    Expression     Setting        Description
    <color name>   color          the color name
    <RGB triplet>  color          the RGB triplet. See 'Data Type
                                  Designators' in section 5 for the
                                  syntax of an RGB triplet.

   Available In
              - box
              - button
              - check
              - field
              - list
              - popup
              - radio
              - tablet
              - page global characteristics
              - form global characteristics

   Examples

     bordercolor = ["light blue"];
     bordercolor = ["173", "216", "230"];

   Usage Notes

    1) Default: black

Universal Forms Description Language                          [page 103]


------

  5.5   borderwidth

    The borderwidth option defines the width of an item's border. The
    unit of measurement is pixels.

   Syntax

     borderwidth = <width>;

    Expression     Setting        Description
    <width>        short int      the width of the border

   Available In
              - box
              - button
              - field
              - label
              - list
              - popup
              - tablet
              - page global characteristics
              - form global characteristics

   Example

    This sample sets the border width to five pixels.
     borderwidth = "5";

   Usage Notes

    1) Default: varies depending on the item type
       - box and label items: zero pixels
       - all other visible items: one pixel
------

  5.6   coordinates

    The coordinates option records the position of the mouse pointer on
    an image. The image must exist in a button item. The recording
    occurs when a user selects (i.e. clicks) the button using the mouse
    pointer.

    The position is an intersection on an unseen grid overlaying the
    image. The points along each axis of the grid range from zero (0)
    through 1000 with position 0,0 occurring in the top, left corner.
    The coordinates map the intersection closest to the mouse
    pointer's position.

   Syntax

     coordinates = [<X_coordinate>, <Y_coordinate>];

    Expression      Setting        Description
    <X_coordinate>  coordinate     the coordinate on the X axis

Universal Forms Description Language                          [page 104]


    <Y_coordinate>  coordinate     the coordinate on the Y axis

   Available In
              - button

   Example

    When a user clicks on a button containing an image, a coordinates
    option statement is inserted into the button definition. The
    statement would look something like this. This particular setting
    indicates a position at the intersection of points 180 on the
    x-axis and 255 on the y-axis.
     coordinates = ["180", "255"];

   Usage Notes

------

  5.7   data

    The data option associates an action, button, or cell item with a
    single data item. The data option is valid only in items with a
    type setting of enclose, display, extract, or remove.

   Syntax

     data = <data_item>;

    Expression     Setting        Description
    <data_item>    string         the item tag of the data item to
                                  associate with the action, button,
                                  or cell

   Available In
              - action
              - button
              - cell

   Example

    The button below is an enclosure button associated with a single
    data item.
     encloseImageButton = new button
     {
        value = "Update Image";
        type = "enclose";
        data = "displayImage";
     }

    If a user enclosed another file, then the data item referred to in
    the button's data option would be replaced with the new data item.
    (The data item would use the same item tag-the one that's referred
    to in the data option.)

   Usage Notes

Universal Forms Description Language                          [page 105]


    1) A data option may specify only zero or one data items.

    2) If an item with a type setting of enclose and a data option is
       used to enclose a second data item, then the second data item
       will replace the first.

    3) If an enclosure mechanism is used to replace an image stored in
       a data item with a new image (see above), then buttons, labels,
       and tablets whose image option is set to the identifier of the
       image data item will be updated to display the new image.

    4) A data item referred to in a data option may also have a
       datagroup option and thus belong to the datagroups of other
       actions, buttons, or cells.
------

  5.8   datagroup

    The datagroup option identifies a group or folder of enclosed
    files. Each enclosed file can belong to several datagroups, and
    each datagroup can contain several enclosed files.

   Syntax

     datagroup = [<datagroup reference1>, ... <datagroup referencen>];
     where <datagroup reference> is one of:
     - <datagroup name> for datagroups on the current page
     - <page tag>.<datagroup name> for datagroups on other pages
     Note: Include a <datagroup reference> entry for each datagroup
           this item accesses.

    Expression             Setting        Description
    <datagroup reference>  string         identifies a datagroup

   Available In
              - action
              - button
              - cell
              - data

   Example

    If this sample were part of a data item definition, it would mean
    the data item belonged to the datagroups: Business_Letters,
    Personal_Letters, and Form_Letters.

    If this sample were part of a action, button, or cell item, it
    would mean the user could store the enclosure in one of the
    three datagroups.
     datagroup = ["Business_Letters", "Personal_Letters",
                 "Form_Letters"];
   Usage Notes

    1) Default: none

Universal Forms Description Language                          [page 106]


    2) Used with items handling enclosures, datagroup lists the
       datagroups the item can access. Used with a data item, datagroup
       lists the datagroups to which the enclosure belongs. Enclosures
       are stored in data items.

    3) Items that handle enclosed files perform enclose, extract,
       remove, and display actions. These actions types are set using
       the type option.

    4) When a user selects an item that handles enclosed files, the
       list of datagroups appears. The user chooses the datagroup
       (or folder) with which to work. If the action is enclosing, the
       enclosed file is added to that datagroup. Otherwise, a list of
       files in the datagroup appears. The user chooses a file from
       the list.

    5) The action of enclosing a file creates the data item, and stores
       the user's choice of datagroup (or folder) in the data item's
       datagroup option.
------

  5.9   delay

    The delay option delays the execution of an automatic action or
    specifies an automatic action repeat factor. Repeated actions stop
    when the page containing the action definition closes. Define
    automatic actions using an action item.

   Syntax

     delay = [<repeat factor>, <interval>];

    Expression       Setting        Description
    <repeat factor>  "repeat"       queue the action to repeat at the
                                    <interval> specified
                     "once"         perform the action once after the
                                    <interval> specified
    <interval>       integer        the frequency of repeated actions
                                    or the delay before performing
                                    single occurrence actions.
                                    The unit of measurement is seconds.
                     "-1"           perform the action before the page
                                    displays. Only valid with a repeat
                                    factor of once.

   Available In
              - action

   Example

    This sample sets the action to occur once, 15 minutes (900 seconds)
    after the page opens.
     delay = ["once", "900"];

   Usage Notes

Universal Forms Description Language                          [page 107]


    1) Defaults:
        - repeat factor: once
        - interval: zero seconds
       This means the action will occur when the page appears.

    2) Repeating automatic actions is one method of creating a
       sparse-stated connection. It allows the form to indicate
       periodically to a server application that it is still running.

    3) All actions with the same interval occur in the order they are
       defined in the page.

    4) The page does not display while actions with an interval of
       -1 are running.
------

  5.10   editstate

    The editstate option defines one of three possible edit states for
    modifiable items.

   Syntax

     editstate = <edit state>;

    Expression     Setting        Description
    <edit state>   "readonly"     users cannot change the item's
                   "writeonly"    users can change, but not see, the
                                  item's setting

                   "readwrite"    users can see and change the item's
                                  setting

   Available In
              - check
              - field
              - list
              - popup
              - radio

   Example

    This sample sets the editstate to readonly.
     editstate = "readonly";

   Usage Notes

    1) Default: readwrite.

    2) The writeonly setting applies only to fields. It causes all
       characters the user types to appear the same as the system
       password character.

    3) The readonly setting permits users to scroll an item even though

Universal Forms Description Language                          [page 108]


       they may not update the item's contents.
------

  5.11   filename

    The filename option identifies the name of an enclosed file. This
    name appears in the list of enclosed files.

   Syntax

     filename = <file name>;

    Expression     Setting        Description
    <file name>    string         the name of the enclosed file

   Available In
              - data

   Example

    This sample specifies the name of an enclosed file.
     filename = "std_logo.frm";

   Usage Notes

    1) Default: none

    2) To ensure cross-platform compatibility, you should limit
       filenames to the following set of characters: lowercase letters
       from a to z, uppercase letters from A to Z, the integers 0
       through 9, and the underscore (_).

    3) To ensure cross-platform compatibility, you should limit form
       names to a maximum of eight characters, followed by a .frm
       extension.
------

  5.12   focused

    The focused option specifies whether an item, page, or form
    currently has the input focus. This option is set by code
    outside UFDL.

   Syntax

     focused = "<status>";

    Expression     Setting        Description
    <status>       "on"           item, page, or form has input focus
                   "off"          item, page, or form does not have
                                  input focus

   Available In
              - button
              - combo

Universal Forms Description Language                          [page 109]


              - field
              - list
              - popup
              - radio
              - page global
              - form global

   Example

    The following example shows a button that changes its color to
    white if it has the input focus, and to blue if it does not.
     saveButton = new button
     {
        type = "save";
        value = "Save";
        bgcolor = [focused=="on" ? "white" : "blue"];
     }

   Usage Notes

    1) Default: off

    2) Any pre-defined setting for focused, including a formula
       setting, will be destroyed as soon as the first activated event
       appears. The focused option is not intended to be set by UFDL
       script, but rather by external forces-a form viewing program,
       for example.

    3) focused is set to on when an item, page, or form receives the
       input focus, and is set to off when it does not.

    4) An object's focus does not change when the form application
       displaying it becomes active or inactive on a desktop. For
       example, a page that is open on screen will have a focus set
       to on, even if the page is minimized or is not the currently
       active application on the desktop.

    5) In objects that are hierarchical, it is possible for more than
       one object to have the focus at one time. For example, a form,
       a page, and a field can all be focused at the same time.

    6) When a form viewing application is closing a form, it should set
       all focus options to off and then resolve all formulas before
       shutting down.

    7) focused may only be set by a desktop form viewing application.

    8) The focused option is not included in form descriptions that
       are saved or transmitted.
------

  5.13   fontcolor

    The fontcolor option defines the font color for the text or filler
    portion of an item. In radio and check items, fontcolor defines
    the color of the bullet and check, respectively. In line items,

Universal Forms Description Language                          [page 110]


    fontcolor defines the color of the line. In tablet items, fontcolor
    defines the pen color. In other items, it defines the text color.

   Syntax

     fontcolor = [<color name>];
     fontcolor = [<RGB triplet>];
     Note: Either format is acceptable.

    Expression     Setting        Description
    <color name>   color          the color name
    <RGB triplet>  color          the RGB triplet. See 'Data Type
                                  Designators' in section 5 for the
                                  syntax of an RGB triplet.

   Available In
              - button
              - check
              - field
              - label
              - line
              - list
              - popup
              - radio
              - tablet
              - page global characteristics
              - form global characteristics

   Examples

    These samples both set the background color to chocolate.
     fontcolor = ["210", "105", "30"];

   Usage Notes

    1) Default: black
------

  5.14   fontinfo

    The fontinfo option defines the font name, point size, and font
    characteristics for the text portion of an item.

    Note: The font selected for an item influences the item's size.

   Syntax

     fontinfo = [<font name>, <point size>, <weight>, <effects>,
                 <form>];
     Note: <weight>, <effects> and <form> are optional.

    Expression     Setting        Description
    <font name>    string         the name of the font
    <point size>   short int      the size of the font
    <weight>       "plain"        use a plain face

Universal Forms Description Language                          [page 111]


                   "bold"         use a bold face
    <effects>      "underline"    underline the text
    <form>         "italic"       use the italic form

   Available In
              - box
              - button
              - check
              - field
              - label
              - line
              - list
              - popup
              - radio
              - spacer
              - tablet
              - page global characteristics
              - form global characteristics

   Example

    This sample sets the font information to Times 14, bold italic.
     fontinfo = ["Times", "14", "bold", "italic"];

   Usage Notes

    1) Defaults:
        - font name: Helvetica
        - point size: 8
        - weight: plain
        - effects: not underlined
        - form: not italics
    2) If any of the fontinfo settings are invalid, then the defaults
       will be used.

    3) The size option calculates item size using the font's average
       character width. Therefore, choice of font affects item width.

    4) UFDL supports the following fonts and font sizes:
       Fonts: Courier, Times, Symbol (??????), Helvetica, and
                Palatino
       Sizes: 8, 9, 10, 11, 12, 14, 16, 18, 24, 36, 48

       You can also use other fonts and font sizes if you wish.
       However, especially for cross-platform Internet applications,
       it is best to choose from the ones cited above since they are
       guaranteed to work.
------

  5.15   format

    The format option allows you to specify edit checks and formatting
    options for field, label, list, popup, and combobox items. It also
    allows you to specify a mandatory status for signature button items
    (for details, see the button item description).

Universal Forms Description Language                          [page 112]


   Syntax

     format = [<data type>, <format flag>, <check flag>];
     Notes:
     i) Multiple flags are valid.
     ii) <data type> is mandatory and must appear first; the flags are
         optional and can appear in any order.

    Expression     Setting        Description
    <data type>    (see below)    the type of data the field should
                                  contain
    <format flag>  (see below)    the type of formatting applied to
                                  the user's input
    <check flag>   (see below)    the type of edit check performed on
                                  the formatted input

   Available In
              - button
              - combobox
              - field
              - label
              - list
              - popup

   Example

    This example specifies a field containing integer data with a range
    of values from 10 to 1,000 inclusive, and formatted with commas
    separating the thousands.
     format = ["integer", "comma_delimit", range=["10", "1000"]];

    This example specifies a field that contains dollar data that is
    mandatory. An error message appears if the data is not entered
    correctly.
     format = ["dollar", "mandatory", message= "Entry incorrect-try
              again."];

    This example specifies a field in which date data will be formatted
    as day-of-month, month, and year (i.e., 15 June 1999).
     format = ["date", "long"];

    This example contains two templates. User input must match one of
    them:
     format = ["string", template=["###-###-####",
              "###-###-####-###"] ];

    This example contains a decision: if a check box called
    allowIncompleteCheck is checked, then filling out the item is
    optional; if the check box is checked, then item is mandatory and
    the user must complete it.
     format = ["string", page1.allowIncompleteCheck=="on" ? "optional"
              : "mandatory"];

   Data Types


Universal Forms Description Language                          [page 113]


    UFDL supports the following data types:

    Data Type      Description                     Format Defaults To:
    string         free form character data up     Any Character.
                   to 32K long

    integer        a positive or negative whole    Any whole number.
                   number in the range of -2,147,

    float          a positive or negative floating Any decimal number.
                   point decimal number in the
                   range of 1.7 * 10-308 to 1.7 *
                   10308

    dollar         a fixed point decimal number    Any number.
                   with a scale of 2 and a range   Automatically adds
                   equal to the range of a float   .00 to end, if no
                                                   decimal value
                                                   specified

    date           a date including day-of-month,  This format:
                   month, and year                 3 Mar 96

    day_of_week    the name or number of a day of  This format: Thu
                   the week

    month          the name or number of a month   This format: Mar

    day_of_month   the number of a day of the      Number format.
                   month

    year           a numeric year designation      This format:
                                                   1996 | 2000 B.C.

    time           a time value containing hours   This format:
                   and minutes from the 12 hour    11:23 P.M.
                   or the 24 hour clock

    void           disable entire format option    No effects on
                   (including data type, checks,   contents of a
                   and formats)                    field


   Format Flags

    You can specify any number of format flags in a format line. To see
    which format flags apply to each data type, see the cross reference
    table at the end of this section.

    The available format flags are:

    Format Flag              Description

    comma_delimit            Delimit the thousands by commas.


Universal Forms Description Language                          [page 114]


    space_delimit            Delimit the thousands by spaces.

    bracket_negative         Indicate negative values by surrounding
                             the value with parentheses, that is ( ).

    add_ds                   Add a dollar sign to the start of the
                             value (dollar fields only).

    upper_case               Convert alphabetic characters to upper
                             case.

    lower_case               Convert alphabetic characters to lower
                             case.

    title_case               Convert first letter of each word to upper
                             case and all other letters to lower case,
                             for titles and proper names.

    short                    Display dates and times using the
                             following formats:
                             - day_of_week - numeric value in range 1
                               to 7 where 1 represents Sunday
                             - day_of_month - numeric value in range 1
                               to 31
                             - year - apostrophe followed by last two
                               digits in year ('98), 'before Christ'
                               era designator is B.C. ('98 B.C.)
                             - date - year as four digits, month as two
                               digits, and day-of-month as two digits,
                               organized in YMD order; no punctuation
                               (1998-04-29)
                             - time - 24 hour clock (as in 23:30)

    long                     Display dates and times using the
                             following formats:
                             - day_of_week - name in full as in Monday
                             - day_of_month - two digits plus suffix as
                               in 1st
                             - month - name in full as in January
                             - year - four-digit numeric format,
                               'before Christ' era designator is B.C.
                               (2000 B.C.)
                             - date - long year, long month, and long
                               day-of-month formats organized in DMY
                               order; no punctuation (29th April 1998)
                             - time - 12 hour clock with the time of
                               day suffix (A.M. or P.M., as in
                               11:30 P.M.)

    numeric                  Display dates and times using numeric
                             values and, possibly, the minus sign:
                             - day_of_week - 2 digits in range 01 to
                               07 where 01 represents Sunday
                             - day_of_month - 2 digits in range 01 to
                               31

Universal Forms Description Language                          [page 115]


                             - month - 2 digits in range 01 to 12
                             - year - 4 digits; 'before Christ' era
                               designator is minus sign as in -1995
                             - date - month and day-of-month formats
                               above,
                               * year format is 4 digits
                               * 'before Christ' era designator is
                                 minus sign
                               * organized in YMD order; no punctuation
                               * Examples: 19980429, -19980429
                             - time - 24 hour clock (as in 23.30)

    presentation="yy/mm/dd"  Available only when formatting dates, to
                             create custom template for presentation
                             of dates, using Y for year, M for month,
                             and D for day
                             - Example: "date", presentation=
                               "YY/MM/DD"
                               * this could yield 98/12/23

    void                     No formatting is applied


   Check Flag

    You can specify any number of edit checks in a format line. The
    edit checks you specify and any edit checks implied by the data
    type will be performed.

    To see which edit checks apply to each data type, see the cross
    reference table at the end of this section.


    Important: UFDL specifies that fields be formatted before an edit
    check is performed. For example, if the field's data type is dollar
    and you specify the add_ds and comma_delimit format options, then
    the input 23000 becomes $23,000.00 before edit checks are applied.
    This can affect length and template checks. In this example, the
    length before formatting was 5 but it became 10 before edit
    checking.

    The available check flags are:

    Check Flag               Description

    optional                 Input from the user is not mandatory.

    mandatory                Input from the user is mandatory.

    case_insensitive         Apply edit checks without regard to the
                             case in which the user enters the data.

    range=["low","high"]     The field's value must be in the range
                             specified. The range can be alphabetic,
                             numeric, days of the week, days of the
                             month, or months.

Universal Forms Description Language                          [page 116]


                             Ranges cannot vary from high to low. For
                             example, 10 to one, the year 2000 to 1900,
                             etc. are invalid.

    length=["min","max"]     Restrict the length of the formatted input
                             data to a minimum of "min" bytes and a
                             maximum of "max" bytes.

    template=["a","b",...]   This is a list of formats permitted for
                             the field. There is no restriction on the
                             number of formats. Field contents must
                             match one of the formats in the list. You
                             may use any of the following wild card
                             characters:
                             -?- represents any one (1) character?
                             -*- represents any number of characters
                             -#- represents any one (1) numeric
                                 character
                             -%- represents any number of numeric
                                 characters
                             -@- represents any one (1) alphabetic
                                 character
                             -!- represents any number of alphabetic
                                 characters (which can include none)
    message="help"           Sets the error message that is displayed
                             if the user input fails the type checking.
                             The default message is, "This entry is
                             invalid. Please try again."

    fail_checks              Forces failure of format statement.

    ignore_checks            Causes all type checking checks to be
                             ignored.
                             Note: only checks are ignored, not
                                   formatting or data type.


   Cross Reference of Data Types, Format Flags, and Check Flags

    Data Type    Applicable Format Flags      Applicable Check Flags

    string       lower_case, upper_case,      case_insensitive,
                 title_case                   fail_checks, length,
                                              mandatory, optional,
                                              range, template

    integer      bracket_negative,            fail_checks,
                 comma_delimit, space_delimit ignore_checks, length,
                                              mandatory, optional,
                                              range, template

    float        bracket_negative,            fail_checks,
                 comma_delimit, space_delimit ignore_checks, length,
                                              mandatory, optional,
                                              range, template

Universal Forms Description Language                          [page 117]


    dollar       add_ds, bracket_negative,    fail_checks,
                 comma_delimit, space_delimit ignore_checks, length,
                                              mandatory, optional,
                                              range, template

    date         long, short, numeric         case_insensitive,
    year                                      fail_checks,
    month                                     ignore_checks, length,
    day_of_month                              mandatory, optional,
    day_of_week                               range, template
    time

    void         No formatting or type        No checking or type
                 checking is done             checking is done


   Usage Notes

    1) If a format flag conflicts with the data type, the format flag
       will be ignored.

    2) All edit checks specified will be applied to the input data.
       This may result in a field the user cannot change. For example,
       the combination of data type integer and check flag
       template="a*" creates such a situation. Data cannot be both an
       integer and begin with a letter.

    3) Default Formatting:
        - Case remains unchanged.
        - Numeric value format contains no thousands delimiter. This
          permits easy conversion of ASCII to integer format.
        - Dollar value format uses two decimal places and no dollar
          sign.
        - Zero is always positive.
        - Day-of-week and month format is the abbreviated name with no
          punctuation. For example, the 2nd day of the week is always
          Mon; the first month is always Jan.
        - The year format is long.
        - The day_of_month is short.
        - The date format uses the default day-of-month, month, and
          year formats organized in DMY order as in 25 Dec 1995. The
          'before Christ' era designator is B.C.
        - The time format defaults to short if the input is between
          0:00 and 12:59, and to long otherwise.

    4) Default Edit Checks
        - All checking is case sensitive.
        - The default edit checks combine the requirements of the data
          type with any formatting requirements (default or specific).
        - If neither optional nor mandatory are specified, the rules
          that are specified will determine whether the user must
          enter information.

    5) When applying a format to a combobox, list, or popup, the
       formatting will be applied to the value of each cell linked to

Universal Forms Description Language                          [page 118]


       the item. Those cells that do not pass the check will be
       flagged or filtered. If a cell passes the checks, its value will
       be replaced with a formatted value before the item is displayed.
       The label option for these cells will remain unaffected.

    6) When applying a format to a combobox, list, or popup, a cell
       with an empty value will fail all format checks but will still
       be selectable, even if input is mandatory. This allows users to
       erase their previous choice (which will also reset all formulas
       based on that choice). However, users will still need to select
       a valid cell before they can submit the form.

    7) If any two comboboxes, lists, or popups use the same set of
       cells, they must apply the same formatting.

    8) The void format type disables a format line completely through
       the use of a compute. void formats never fail regardless of the
       checks in the format statement.
    9) The void format flag facilitates the modification of a format
       statement by a formula. It is ignored by the formatting system.

    10) For details on using the format option in buttons, see the
        Usage Notes in the button item description.
------

  5.16   group

    The group option provides a method of grouping items together.
    Items with the same group reference are considered members of the
    same group. Examples of grouped items are radio buttons and cells.

   Syntax

     group = <group reference>;
     where <group reference> is one of:
        - <group name> for groups on the current page
        - <page tag>.<group name> for groups on other pages

    Expression        Setting        Description
    <group reference> string         identifies the group

   Available In
              - cell
              - combobox
              - list
              - popup
              - radio

   Example

    This sample associates the item with the group coverage_type.
     group = "coverage_type";

   Usage Notes


Universal Forms Description Language                          [page 119]


    1) Default: none

    2) List and popup items are populated with cells that have the same
       group reference as the item. It is possible to have several list
       and popup items with the same group reference. In this way, the
       same group of cells can populate more than one list or popup.

    3) All radio items having the same group reference will form a
       mutually exclusive group.
------

  5.17   help

    The help option points to the help message for the item. The item
    reference identifies the help item containing the help message.
    There can be many items pointing to the same help message.

   Syntax

     help = <item reference>;

    Expression       Setting        Description
    <item reference> string         identifies the help item

   Available In
              - button
              - check
              - field
              - label
              - list
              - popup
              - radio
              - tablet

   Example

    This sample points to the help item general_help defined on the
    page called page_1.
     help = "page_1.general_help";
------


    The image option associates an image with an item. The item
    reference identifies the data item containing the image. This image
    replaces any text label if the viewer is able to display images.

   Syntax

     image = <item reference>;

    Expression       Setting        Description
    <item reference> string         identifies the data item

   Available In
              - button

Universal Forms Description Language                          [page 120]


              - label
              - tablet

   Example

    This sample points to the data item company_logo defined on the
    page called page_lst.
     image = "page_lst.company_logo";

   Usage Notes

    1) Default: none

    2) Use this option to associate images with button, label, and
       tablet items.

    3) If an enclosure mechanism is used to replace an image stored in
       a data item with a new image, then buttons, labels, and tablets
       whose image option is set to the identifier of the image data
       item will be updated to display the new image. For details, see
       the data option description.
------

  5.19   itemlocation

    The itemlocation option serves three purposes:
        - It specifies the location of an item in the page layout.
        - If you use the extent setting, it will set the size of an
          item's bounding box.
        - If you are using the relational positioning scheme, it may
          dynamically alter the size of an item.

    Each specification in the itemlocation option defines one aspect
    of an item's location or size.

    There are two different schemes you can use to position items on
    the page: an absolute positioning scheme and a relational
    positioning scheme. The absolute positioning scheme anchors the
    top left corner of an item to a particular pixel on the displayed
    page, whereas the relational positioning scheme places items on the
    page in relation to one another. Once you understand the two
    schemes you can combine them to gain the advantages of both
    schemes.

    For more information on the two schemes, see 'Absolute Positioning
    Scheme' and 'Relational Positioning Scheme', below.

    Note: You can combine the two methods of positioning, so that some
    items are positioned absolutely, and other items are positioned in
    relation to those absolute items.

   Syntax:

     itemlocation = [[<specification1>], ... [<specificationn>]];
     where:
     (absolute positioning and extent modifier)

Universal Forms Description Language                          [page 121]


        - <specification> is defined as: <modifier>,<x-coordinate>,
          <y-coordinate>
     (relational positioning)
        - <specification> is defined as: <modifier>, <item tag1>,
          <item tag2>
     Notes:
     i) There is no restriction on the number of specifications.
     ii) x-coordinate and y-coordinate may be negative only when the
     modifier is offset.
     iii) <item tag2> is valid only with the modifiers
     alignhorizbetween and alignvertbetween.

    Expression     Setting        Description

    <modifier>     (see below)    the type of modification to apply to
                                  the item's location or size

    <x-coordinate> short          - the horizontal distance in pixels
                   (must be         from the form's top left corner
                   positive if      (with the modifier absolute); or
                   modifier is
                   absolute)      - the horizontal distance in pixels
                                    from the item's top left corner in
                                    its original position to its new
                                    offset position (with the modifier
                                    offset)
    <y-coordinate> short          - the vertical distance in pixels
                   (must be         from the form's top left corner
                   positive if      (with the modifier absolute); or
                   modifier is
                   absolute)      - the vertical distance in pixels
                                    from the item's top left corner in
                                    its original position and to its
                                    new offset position (with the
                                    modifier offset)

    <item tag>     string         identifies the reference point item


   Modifiers

    There are four types of modifiers:
        - position modifiers - used to position an item
        - alignment modifiers - used to align one edge of an item
          (relational positioning only)
        - expansion modifiers - used to alter an item's size
          (relational positioning only)
        - the extent modifier - used to set a pixel based size for an
          item (both relational and absolute positioning)

    Position Modifiers

    a) For the Absolute Positioning Scheme:

    Modifier                 Description

Universal Forms Description Language                          [page 122]


    absolute                 Place top left corner of item on the pixel
                             noted in the x-coordinate and y-coordinate
                             settings.

    offset                   Place item so that it is offset from its
                             original location by the measurement
                             specified in the x-coordinate and
                             y-coordinate settings.


    The extent modifier, listed later in this section, can also be
    used with absolute positioning.

    b) For the Relational Positioning Scheme:

    Note:A specification containing the within modifier must be the
         first specification in the list.

    Modifier                 Description

    above                    Place item a small distance above
                             reference point item; align left edges.

    after                    Place item a small distance after
                             reference point item; align top edges.

    before                   Place item a small distance before
                             reference point item; align top edges.

    below                    Place item a small distance below
                             reference point item; align left edges.

    within                   Assign item to the toolbar.


    Alignment Modifiers (Relational Positioning only)

    Note: The modifiers alignvertbetween and alignhorizbetween require
          two reference items.

    Modifier                 Description

    alignb2b                 Align bottom edge of item with bottom edge
                             of reference point item.

    alignb2c                 Align bottom edge of item with vertical
                             center of reference point item.

    alignb2t                 Align bottom edge of item with top edge
                             of reference point item.

    alignc2b                 Align vertical center of item with bottom
                             edge of reference point item.

    alignc2l                 Align horizontal center of item with left

Universal Forms Description Language                          [page 123]


                             edge of reference point item.

    alignc2r                 Align horizontal center of item with right
                             edge of reference point item.

    alignc2t                 Align vertical center of item with top
    alignhorizbetween        Align horizontal center of item between
                             right edge of first reference point item
                             and left edge of second reference point
                             item.

    alignhorizc2c            Align horizontal center of item with
                             horizontal center of reference point item;
                             center below.

    alignl2c                 Align left edge of item with horizontal
                             center of reference point item.

    alignl2l                 Align left edge of item with left edge of
                             reference point item.

    alignl2r                 Align left edge of item with right edge of
                             reference point item.

    alignr2c                 Align right edge of item with horizontal
                             center of reference point item.

    alignr2l                 Align right edge of item with left edge of
                             reference point item.

    alignr2r                 Align right edge of item with right edge
                             of reference point item.

    alignt2b                 Align top edge of item with bottom edge of
                             reference point item.

    alignt2c                 Align top edge of item with vertical
                             center of reference point item.

    alignt2t                 Align top edge of item with top edge of
                             reference point item.

    alignvertbetween         Align vertical center of item between
                             bottom edge of first reference point item
                             and top edge of second reference point
                             item.

    alignvertc2c             Align vertical center of item with
                             vertical center of reference point item.


   Expansion Modifiers (Relational Positioning only)


    Modifier                 Description

Universal Forms Description Language                          [page 124]


    expandb2c                Hold top edge of item constant and expand
                             bottom edge to align with vertical center
                             of reference point item.

    expandb2t                Hold top edge of item constant and expand
                             bottom edge to align with top edge of
                             reference point item.

    expandl2c                Hold right edge of item constant and
                             expand left edge to align with horizontal
                             center of reference point item.

    expandl2l                Hold right edge of item constant and
                             expand left edge to align with left edge
                             of reference point item.

    expandl2r                Hold right edge of item constant and
                             expand left edge to align with right edge
                             of reference point item.

    expandr2c                Hold left edge of item constant and expand
                             right edge to align with horizontal center
                             of reference point item.

    expandr2l                Hold left edge of item constant and expand
                             right edge to align with left edge of
                             reference point item.

    expandr2r                Hold left edge of item constant and expand
                             right edge to align with right edge of
                             reference point item.

    expandt2b                Hold bottom edge of item constant and
                             expand top edge to align with bottom edge
                             of reference point item.

    expandt2c                Hold bottom edge of item constant and
                             expand top edge to align with vertical
                             center of reference point item.

    expandt2t                Hold bottom edge of item constant and
                             expand top edge to align with top edge of
                             reference point item.


   The Extent Modifier (Relational and Absolute Positioning)

    extent                   Hold the top left corner of the item in
                             place, and size the item so that it is
                             as many pixels wide as the x coordinate,
                             and as many pixels tall as the
                             y coordinate.

   Available In

Universal Forms Description Language                          [page 125]


              - box
              - button
              - check
              - field
              - label
              - line
              - list
              - popup
              - radio
              - spacer
              - tablet

    Absolute Positioning Scheme

    This scheme anchors an item to a particular coordinate on the
    visible page. The coordinate is a measurement in pixels of the
    distance between the top left corner of the form and the item's
    top left corner.

    The itemlocation line describing the label in the picture above
    would look like this:
     itemlocation = [["absolute", "60", "60"]];

    The absolute positioning scheme also allows you to offset an item
    from its original position, by a particular number of pixels. This
    is a quick way to create an indented layout on your form.

    It is valid to offset an item in any of these four directions:
    right, left, up, down. Since the offset is measured by a pixel
    grid and is represented with x and y coordinates, the directions
    left and up are measured as negative distances. For example, to
    outdent the Last Name field in the above diagram, so that its left
    edge is further left than the label's, the x measurement would be
    negative, as in -15.

    You can offset an item from either:
        - Its original absolute position. For example,
        itemlocation = [["absolute", "60", "100"],
             ["offset", "15", "20"]];
        - Its original relational position. For example,
        itemlocation = [["below", "persInfo_label"],
             ["offset", "15", "20"]];

    Caution

    An absolute positioning scheme is not a cross-platform
    solution-nor even a solution guaranteed to make forms appear the
    same under different video cards or in both small font and large
    font modes.

    The sizes of many UFDL form items are measured in characters. For
    example, a field that is 60 x 1 in size, is 60 characters long and
    1 character high. Because different platforms and video cards use
    differently sized fonts, even for the so-called cross-platform
    fonts, an item's actual size (in pixels) may change from one
    platform to another as the font it is measured in changes size.

Universal Forms Description Language                          [page 126]


    If you rely on spacing items on your form using absolute
    positioning, which fastens an item to a particular pixel, some
    items may appear overlapped on some platforms.

    To ensure that your forms appear the same on any platform, and
    under any video card or font mode, use relational positioning.

    Relational Positioning Scheme

    Relational positioning allows you to place an item relative to the
    location of another item. It also allows you to specify an item's
    size relative to the size and location of other items. The other
    items (called reference point items) must be defined before they
    can be used in an itemlocation statement.

    When you use the relational positioning scheme, the first external
    item you place on the form appears in the top left corner. It
    cannot be placed in relation to any other item, since no other
    items exist. All subsequent items can be placed in relation to
    items that appear before them in the form's description. If you do
    not specify any relational position for an item, it will appear
    below the previous item, with its left edge against the page's left
    edge.

    Itemlocation can only reference items on the same page as the item
    being defined. If the item being defined is in a toolbar, the
    referenced items must be in the same toolbar.

    The Extent Modifier

    The extent modifier allows you to set an absolute size for an item
    in pixels. When you specify an extent, the item's top left corner
    will stay where it is, and the item will be resized so that it is
    as many pixels wide as the x value and as many pixels in height as
    the y value.

    Note: Itemlocation uses the bounding boxes of the defined and
    referenced items to determine location and size.

   Examples

    Example 1 - Absolute Positioning

    This sample places a label on the page so that its top left corner
    is 20 pixels in from the page's left edge, and 30 pixels down from
    the top of the page.
     persInfo_label = new label
     {
        value = "Personal Information";
        itemlocation = [["absolute", "20", "30"]];
     }

    Example 2 - Offsetting an Item

    These samples show two ways in which to offset a field below the
    label in example one. The first sample shows how to do so using

Universal Forms Description Language                          [page 127]


    only the absolute positioning scheme. The second sample shows how
    to do so using both relational and absolute positioning schemes.
     lastName_field = new field
     {
     label = "Last Name";
     itemlocation = [["absolute", "20", "100"],
     }


     lastName_field = new field
     {
     label = "Last Name";
     itemlocation = [["below", "persInfo_label"],
         ["offset", "10", "10"]];
     }

    Note that the item is offset from its original position, not from
    other items. It's not a good idea to offset items using strictly
    absolute positioning (sample one). Use relational positioning if
    possible (sample two). For more information on the dangers of
    absolute positioning, see the Caution in section 5.19.

    Example 3 - Relational Positioning

    Sample 3.1

    This sample aligns the vertical center of an item between the
    bottom edge of the item label_one and the top edge of the item
    label_two.
     itemlocation = [["alignvertbetween", "label_one", "label_two"]];

    Sample 3.2

    This sample aligns the item's left edge with the center of item
    the_firm and expands the right edge to align with the right edge
    of the same reference item (the_firm).
     itemlocation = [["alignl2c", "the_firm"], ["expandr2r",
                   "the_firm"]];

    Sample 3.3

    This sample assigns an item to the toolbar main_toolbar and
    positions it under the company logo company_logo.
     itemlocation = [["within", "main_toolbar"], ["below",
                   "company_logo"]];

    Example 4 - Extent

    Sample 4.1

    This sample shows an extent setting on a field that has been placed
    using absolute positioning. The field is first placed at an x-y
    coordinate of 10, 10. It is then sized to be 300 pixels wide and
    30 pixels high.
     itemlocation = [["absolute", "10", "10"], ["extent", "300",

Universal Forms Description Language                          [page 128]


                   "30"]];

    Sample 4.2

    The second sample shows an extent setting on a label that has been
    placed using relational positioning. The label is first placed
    below a field, and is then sized to be 100 pixels wide and 20
    pixels high.
     itemlocation = [["below", "field_1"], ["extent", "100", "20"]];

   Usage Notes

    1) Default item location:
        - in the body of the page
        - under the previous item in the page definition
        - aligned along the left margin of the page
    Default bounding box size:
    See 'Appendix B: Default Sizes'

    2) Itemlocation overrides size. If the itemlocation affects the
       size of the item and the size option has also been set for the
       item, the itemlocation will determine the size.

    3) An item's vertical center is halfway between the top and bottom
       edges. The horizontal center is halfway between the left and
       right edges.

    4) See the following sections for more information on using
       itemlocation:
        - 'Item Placement'
        - 'Item Size'

    4) To offset an item by shifting it to the right or down the page,
       specify the offset distance using positive integers. To offset
       an item by shifting it to the left or up the page, specify the
       offset distance using negative integers.

    5) Use absolute positioning carefully. See the Caution
       for more information.
------

  5.20   justify

    The justify option aligns lines of text within the space an item
    occupies.

   Syntax

     justify = <alignment>;

    Expression     Setting        Description
    <alignment>    "left"         align each line's left edge along
                   "right"        align each line's right edge along
                                  the right margin
                   "center"       align the center of each line with

Universal Forms Description Language                          [page 129]


                                  the center of the item

   Available In
              - button
              - field
              - label
              - popup
              - tablet

   Example

    This sample aligns the text in the center of the item.
     justify = "center";

    If the item's text was:
     The hare and the hound
     went off to the woods to play

    It would display as follows:
     The hare and the hound
     went off to the woods to play

   Usage Notes

    1) Default: varies depending on the item
        - button and popup items: center
        - label items: left
------

  5.21   label

    The label option specifies an external text label for an item. The
    label appears above the item and aligned with its left margin. The
    only exception is popup items, where the label appears inside the
    item.

   Syntax

     label = <label text>;

    Expression     Setting        Description
    <label text>   string         the text of the label

   Available In
              - check
              - field
              - list
              - popup
              - radio
              - spacer
              - page global characteristics
              - form global characteristics

   Example

    This sample defines a typical label.

Universal Forms Description Language                          [page 130]


     label = "Student Registration Form";

   Usage Notes

    1) Default: none

    2) The label you define in a label option has a transparent
       background by default. If you wish to display a particular color
       behind the label, then set the labelbgcolor option.

    3) Multiple line labels require line breaks imbedded in the label
       text. Use the escape sequence '\n' to indicate a line break.
       For example:
         label = "This label spans\ntwo lines.";
------

  5.22   labelbgcolor

    The labelbgcolor option defines the background color for the label
    specified in the label option.
   Syntax

     labelbgcolor = [<color name>];
     labelbgcolor = [<RGB triplet>];
     Note: Either format is acceptable.

    Expression     Setting        Description
    <color name>   color          the color name
    <RGB triplet>  color          the RGB triplet. See 'Data Type
                                  Designators' on page 116 for the
                                  syntax of an RGB triplet.

   Available In
              - check
              - field
              - list
              - radio
              - page global characteristics
              - form global characteristics

   Examples

    These samples both set the background color to red.
     labelbgcolor = ["red"];
     labelbgcolor = ["255", "0", "0"];
     labelbgcolor = ["transparent"];

   Usage Notes

    1) Default for version 4.0.1 and greater forms: transparent
       This means that a label option will always be transparent unless
       you specify a color.

    2) Default for version 4.0.0 and lesser forms:
       for items in the toolbar - background color of toolbar.

Universal Forms Description Language                          [page 131]


       for items on a page - background color of the page.
------

  5.23   labelbordercolor

    The labelbordercolor option defines the color of the border around
    the label specified in the label option.

   Syntax

     labelbordercolor = [<color name>];
     labelbordercolor = [<RGB triplet>];
     Note: Either format is acceptable.

    Expression     Setting        Description
    <color name>   color          the color name
    <RGB triplet>  color          the RGB triplet. See 'Data Type
                                  Designators' in section 5 for the
                                  syntax of an RGB triplet.

   Available In
              - check
              - field
              - list
              - radio
              - page global characteristics
              - form global characteristics
   Examples

    These samples both set the border color to blue1.
     labelbordercolor = ["blue1"];
     labelbordercolor = ["0", "0", "255"];

   Usage Notes

    1) Default: black
------

  5.24   labelborderwidth

    The labelborderwidth option defines the width of the border around
    the label specified in the label option. The unit of measurement
    is pixels.

   Syntax

     labelborderwidth = <width>;

    Expression     Setting        Description
    <width>        short int      the width of the border


   Available In
              - check
              - field

Universal Forms Description Language                          [page 132]


              - list
              - radio
              - page global characteristics
              - form global characteristics

   Example
    This sample sets the border width to 15 pixels.
     labelborderwidth = "15";

   Usage Notes

    1) Default: zero pixels
------

  5.25   labelfontcolor

    The labelfontcolor option defines the font color for the label
    specified in the label option.

   Syntax

     labelfontcolor = [<color name>];
     labelfontcolor = [<RGB triplet>];
     Note: Either format is acceptable.

    Expression     Setting        Description
    <color name>   color          the color name
    <RGB triplet>  color          the RGB triplet. See 'Data Type
                                  Designators' on page 116 for the
                                  syntax of an RGB triplet.

   Available In
              - check
              - field
              - list
              - radio
              - page global characteristics
              - form global characteristics

   Examples

     labelfontcolor = ["green1"];
     labelfontcolor = ["0", "255", "0"];

   Usage Notes

    1) Default: black
------

  5.26   labelfontinfo

    The labelfontinfo option defines the font name, point size, and
    font characteristics for the label specified in the label option.

   Syntax

Universal Forms Description Language                          [page 133]


     labelfontinfo = [<font name>, <point size>, <weight>, <effects>,
                      <form>];
     Note: <weight>, <effects> and <form> are optional.

    Expression     Setting        Description
    <font name>    string         the name of the font
    <point size>   short int      the size of the font
    <weight>       "plain"        use plain face
                   "bold"         use bold face
    <effects>      "underline"    underline the text
    <form>         "italics"      use the italic form

   Available In
              - check
              - field
              - list
              - radio
              - page global characteristics
              - form global characteristics

   Example

    This sample sets the font information to Palatino 12, plain
    (the default), underlined.
     labelfontinfo = ["Palatino", "12", "underline"];

   Usage Notes

    1) See the section on fontinfo for the usage notes.
------

  5.27   mimedata

    The mimedata option contains the actual data associated with a data
    item or a signature item. It can be binary data or the contents of
    an enclosed file. The data is encoded in base64 format, so that
    even forms containing binary data can be viewed in a text editor.
    When the data is needed by the form, it is decoded automatically
    from base64 back to its native format.

    About mimedata in signature items

    The mimedata contains the contents of a signature. A UFDL generator
    should create it as follows:

    1) Using the signature filter instructions in the associated
       signature button, create a plain-text version of the form or
       portion of the form to be signed.

    2) Using the instructions in the signature button's signformat
       option, create a hash of the plain-text description.

    3) Sign the hash with the signer's private key.

    4) Include the signed hash and the signer's public key in the

Universal Forms Description Language                          [page 134]


       mimedata option.

   Syntax

     mimedata = <data>;
    Expression     Setting        Description
    <data>         string         the binary data or enclosed file
                                  contents

   Available In
              - data
              - signature

   Example

    This sample assigns some encoded data to the mimedata option.
    Notice the quotation marks surrounding each segment of the data.
     mimedata =
     "R0lGODdhYABPAPAAAP///wAAACwAAAAAYABPAAAC/4SPqcvtD02Y"
     "Art68+Y7im7ku2KkzXnOzh9v7qNw+k+TbDoLFTvCSPzMrS2YzmTE+";

    This sample shows a mimedata option in a digital signature.
     empSignature = new signature
       {
          signformat = "application/uwi_form";
          signer = "Jane D Smith, jsmith@insurance.com";
          signature = "PAGE1.empSignature";
          signitemrefs = ["omit", "PAGE1.mgrSigButton",
                 PAGE1.admSigButton",
                 "PAGE1.empSignature", "PAGE1.mgrSignature",
                 "PAGE1.admSignature"];
          signoptions = ["omit", "triggeritem", "coordinates"];
          mimedata = "MIIFMgYJKoZIhvcNACooIIFIzCCBR8CAQExDzANBgkg"
            "AQUFADALB\ngkqhkiG9w0BBwGgggQZMCA36gAwSRiADjdhfHJl"
            "6hMrc5DySSP+X5j\nANfBGSOI\n9w0BAQQwDwYDVQQHEwhJbn"
            "Rlcm5ldDEXMBUGA1UEChM\nOVmVyaVNpZ24sIEluYy4xNDAKn"
            "1ZlcmlTaWduIENsYXNzIDEgQ0Eg\nLSJbmRdWFsIFN1YnNjcmliy"
            "ZXIwHhcNOTgwMTI3MwMDAwOTgwM\M1OTU5WjCCARExETA";
       }

   Usage Notes

    1) Default: none

    2) Base64 encoding transforms the data into a format that can be
       processed easily by text editors, email applications, etc.
       Converting data to base64 format ensures the resulting string
       contains no characters requiring an escape sequence.

    3) For signatures: Because the signer's public key is included in
       the mimedata, a subsequent program can verify a signature
       without requiring that to the signer's key be previously
       installed.
------


Universal Forms Description Language                          [page 135]


  5.28   mimetype

    The mimetype option defines the MIME type of the data stored in a
    data item.

   Syntax

     mimetype = <MIME type>;

    Expression     Setting        Description
    <MIME type>    string         the MIME type of the data item

   Available In
              - data

   Example

    This sample sets the MIME type to indicate image data.
     mimetype = "image/gif";

   Usage Notes

    1) Default: application/uwi_bin

    2) Here are some examples of MIME types. For full information on
       MIME types, read the MIME rfcs (1521, 1522 and 822). You can
       find them on the World Wide Web.
    MIME type                Meaning

    application/postscript   Binary item
    application/uwi_bin      Binary item
    application/uwi_form     UFDL form item
    application/uwi_nothing  No data included
    audio/basic              Sound item
    audio/wav                Sound item
    image/jpeg               Image item
    image/rast               Image item
    image/tiff               Image item
    image/png                Image item
    image/bmp                Image item
    text/plain               ASCII text item
    text/richtext            Binary item
    video/mpeg               Video item
    video/quicktime          Video item
------

  5.29   mouseover

    The mouseover option specifies whether the mouse pointer is
    currently over an item or page. This option is set by code outside
    UFDL.

   Syntax

     mouseover = "<status>";

Universal Forms Description Language                          [page 136]


    Expression     Setting        Description
    <status>       "on"           mouse pointer is over item or page
                   "off"          mouse pointer is not over item or
                                  page

   Available In
              - button
              - check
              - combo
              - field
              - list
              - popup
              - tablet
              - toolbar
              - page settings

   Example

    The following example shows a button that changes its color to
    white if it the mouse pointer is over it, and to blue if the
    pointer is not over it.
     saveButton = new button
     {
        type = "save";
        value = "Save";
        bgcolor = [mouseover=="on" ? "white" : "blue"];
     }

   Usage Notes

    1) Default: off

    2) An object's mouseover option is set to on when the mouse pointer
       is over the object, and to off when the mouse pointer is not
       over the object.

    3) A page global mouseover option is set to on when the mouse
       pointer is over the page (even if it is also over an item on
       the page).

    4) A mouseover option in a toolbar is set to on when the mouse
       pointer is over the toolbar (even if it is also over an item
       in the toobar).

    5) The mouseover option is not included in form descriptions that
       are is saved or transmitted.
------

  5.30   next

    The next option identifies the item to receive focus when a user
    tabs ahead from the current item. If the specified item is on
    another page, the new page appears with the item in focus. Only
    modifiable items can receive focus.

Universal Forms Description Language                          [page 137]


    See the section 'Defining Tabbing and Paging' in section 2.4o for
    more information on tabbing.

   Syntax

     next = <item reference>;

    Expression        Setting        Description
    <item reference>  string         identifies the item to receive
                                     focus next
   Available In
              - button
              - check
              - field
              - list
              - popup
              - radio
              - page global
              - form global

   Example

    This sample points to the item address_field. When users tab ahead
    from the current item, the item identified as address_field will
    receive focus.
     next = "address_field";

   Usage Notes

    1) Default tabbing order: depends on the order in which page and
       item definitions occur within the form definition. The
       sequence is:
        - first page to display: first page defined in the form
        - first item to receive focus: first modifiable item defined
          for the body of the first page
        - subsequent items to receive focus: each modifiable item on
          the page in the order you define them

    When you tab past the last item on the page, the first modifiable
    item in the page's toolbar receives focus. If there is no toolbar,
    focus returns to the first item.

    2) Placing the next option in form characteristics defines the
       first page to appear, and the first item to receive focus when
       the form opens. Placing next in page characteristics defines the
       first item to receive focus when the page appears.

    3) If the next option identifies form or page characteristics,
       focus moves to the item defined to receive focus when the form
       or page appears. The form characteristics reference is
       global.global. The page characteristics reference is global for
       the current page or <page tag>.global for another page
------

  5.31   previous

Universal Forms Description Language                          [page 138]


    The previous option identifies the item to receive focus when a
    user tabs backwards, using SHIFT + TAB, from the current item. If
    the current item has a previous option, the item indicated in that
    option is next in the reverse tab order. If the current item has
    no previous option, the previous item in the build order that can
    receive the input focus is next in the reverse tab order.

    See the section 'Defining Tabbing and Paging' in section 2.4o for
    more information on tabbing.

     previous = <item reference>;

    Expression        Setting        Description
    <item reference>  string         identifies the item to receive
                                     focus next

   Available In
              - button
              - check
              - combobox
              - field
              - list
              - popup
              - radio
              - page global characteristics
              - form global characteristics

   Example

    This sample points to the item date_field. When users tab back from
    the current item, the item identified as date_field will receive
    focus.
     previous = "date_field";

   Usage Notes

    2) Default tabbing order: depends on the order in which page and
       item definitions occur within the form definition. The
       sequence is:
        - first page to display: first page defined in the form
        - first item to receive focus: first modifiable item defined
          for the body of the first page
        - subsequent items to receive focus: each modifiable item on
          the page in the reverse order you define them

       When you tab back past the first item on the page, the last
       modifiable item in the page's toolbar receives focus. If there is
       no toolbar, focus returns to the last item defined in the page.

    4) Placing the previous option in form characteristics defines the
       first page to appear, and the first item to receive focus when the
       form opens. Placing previous  in page characteristics defines the
       first item to receive focus when the page appears.


Universal Forms Description Language                          [page 139]


       If the previous option identifies form or page characteristics,
       focus moves to the item defined to receive focus when the form
       or page appears. The form characteristics reference is
       global.global. The page characteristics reference is global for
       the current page or <page tag>.global for another page.
------

  5.32   printsettings

    The printsettings option determines the settings that will be used
    when the form is printed. You can allow the user to change these
    defaults, or set the form so that it will always follow the
    defaults.

   Syntax

     printsettings = [<page list>, <dialog settings>];
     Notes:
     i) All settings are optional.

    Expression        Setting       Description
    <page list>       (see below)   the list of pages that should be
                                    printed
    <dialog settings> (see below)   determines whether the print
                                    dialog is shown, and which settings
                                    should be used when printing (for
                                    example, paper orientation and
                                    number of copies)

   Available In
              - action
              - button
              - cell
              - page global characteristics
              - form global characteristics

   Page List

    The page list uses the following syntax:
     pages=["keep"|"omit", "<page tag 1>", "<page tag 2>", ...]

    Setting                  Description
    keep                     The pages listed will be printed. Any
                             other pages will not.
    omit                     The pages listed will not be printed.
                             Any other pages will.
    <page tag>               The list of page tags indicates which
                             pages should be either kept or omitted.

   Dialog Settings

    The dialog settings use the following syntax
     dialog=[active="on"|"off", orientation="portrait"|"landscape", copies="1"]

    The settings work as follows:

Universal Forms Description Language                          [page 140]


    Setting                  Description
    active                   When "on", the print dialog will be
                             displayed before the form is printed,
                             allowing the user to change the settings.
                             When "off", the dialog will not be shown
                             and the form will be printed immediately.
    orientation              Determines whether the form will be
                             printed in "landscape" or "portrait"
                             orientation.
    copies                   Determines the number of copies that will
                             be printed.
    printpages               See below.

   Example

    This sample omits "page2" from printing, sets the form to print in
    landscape orientation, and causes two copies of the form to be
    printed. The user is able to change all of these settings.
     printsettings=[pages=["omit", "page2"], dialog=["on",
                   orientation="landscape", copies="2"]];

   Usage Notes

    1) Default Page List: the page list will default to keeping all
       pages in the form.

    2) Default Dialog Settings: the dialog will default to being "on",
       and will print one copy of all pages in the form in a portrait
       orientation. By default, the user will be able to change all of
       these settings.
------

  5.33   saveformat

    The saveformat option specifies what format a form should be saved
    in. A UFDL form can be saved in UFDL format, compressed UFDL
    format, or HTML format.

    UFDL format saves the entire form definition, including the user
    input.

    Compressed UFDL format saves the entire form description as a
    compressed file using a gzip compression algorithm.

    HTML format saves the form as a series of assignment statements for
    each modifiable item, equating the item reference with the item's
    value. The only items included in the save are custom items and the
    following modifiable items: check, field, list, popup, radio.

   Syntax

     saveformat = <MIME type>;

    Expression     Setting                             Description
    <MIME_type>    "application/uwi_form"              use UFDL format

Universal Forms Description Language                          [page 141]


                   "application/uwi_form;content-      use compressed
                                  encoding=\"gzip\""   UFDL format

                   "application/x-www-form-urlencoded" use HTML format


    Note: You cannot specify that HTML format files be compressed.

   Available In
              - button
              - cell
   Example

    Example 1 - HTML format in a button

    This example shows how to use saveformat in a save button.
     save_button = new button
     {
        type = "save";
        saveformat = "application/x-www-form-urlencoded";
     }

    When a user clicks this button, the form will be converted to HTML
    format (see Usage Note 3 below) and saved to the user's drive.

    Example 2 - Compressed UFDL format in form global characteristics

    This example shows how to use saveformat as a form global
    characteristic and to specify that the saved form be compressed.
     version = "3.2.0";
     bgcolor = ["ivory"];
     saveformat = "application/uwi_form; content-encoding = \"gzip\"";

     page_1 = new page
     {
     ...

    Any time a user saves this form, it will be saved in compressed
    UFDL format.

    A saveformat setting as a form global characteristic applies to all
    save actions for the form. You can override the global setting for
    specific save actions by coding a different saveformat option into
    the item that initiates the save action. For example,
     version = "3.2.0";
     bgcolor = ["ivory"];
     saveformat = "application/uwi_form; content-encoding = \"gzip\"";

     page_1 = new page
     {
        save_button = new button
        {
           type = "save";
           value = "Save Form";

Universal Forms Description Language                          [page 142]


           saveformat = "application/uwi_form";
        }

    When the user saves the form by clicking the Save Form button, it
    will be saved as an uncompressed UFDL form.

    Note that the quotation marks around gzip must be escaped.

   Usage Notes

    1) Default: UFDL format (not compressed)

    2) You can include this option as a form global option and in the
       definitions of items that trigger save actions. These are button
       or cell items that have a type option setting of save.

    3) HTML Format by Item Type

       The general syntax of a form saved in HTML format is:
       <item reference>=<value>&< item reference>=<value>&...
       Note: the ampersand separates form items.

    The syntax of items saved in HTML format by type:

    Item Type           HTML Format
    check               <item tag>=<value option setting>
    field               <item tag>=<value option setting>
    list                <item tag>=
                        <value option setting of selected cell>
                        Note: <item reference> identifies the list.
                        <value option setting of selected cell>
                        Note: <item reference> identifies the popup.
    radio               <group option setting>=
                        <item tag of selected radio>
    <custom>            <item tag>=<value option setting>

      Note: combo boxes cannot be saved in HTML format.


   Substitutions and Omissions:

    - Only modifiable items are saved as HTML data. You cannot save a
      form in HTML format and expect to view it as a form again. It is
      saved as a string of item tags and their associated values.
    - Spaces in the value are replaced by the plus sign (+).
        Two words' becomes 'Two+words'
    - The membership operator in item and group references is replaced
      by a minus sign.
        'page_one.age_group' becomes 'page_one-age_group'
    - Page tags are removed from item and group references in single
      page forms.
    - Check boxes and radio buttons with a value option setting of off
      are omitted.
    - Entries resulting in an empty string on the right hand side
      of the assignment statement are omitted. This occurs when

Universal Forms Description Language                          [page 143]


      the referenced option setting is empty or the option
      definition is missing.
------

  5.34   scrollhoriz

    The scrollhoriz option defines horizontal scrolling options for a
    field item.

   Syntax

     scrollhoriz = <option>;

    Expression     Setting        Description
    <option>       "never"        permit scrolling using the cursor but
                                  display no horizontal scroll bar
                   "always"       permit scrolling and display a
                                  horizontal scroll bar
                   "wordwrap"     wrap field contents from line to
                                  line, inhibit scrolling and display
                                  no horizontal scroll bar

   Available In
              - field

   Example

    This sample sets the horizontal scrolling option to permit
    scrolling and to display the horizontal scroll bar.
     scrollhoriz = "always";

   Usage Notes

    1) Default: never

    2) The scroll bar displays along the field's bottom edge.
------

  5.35   scrollvert

    The scrollvert option defines vertical scrolling options for a
    field item.

   Syntax

     scrollvert = <option>;

    <option>       "never"        permit scrolling using the cursor but
                                  display no vertical scroll bar
                   "always"       permit scrolling and display a
                                  vertical scroll bar
                   "fixed"        inhibit scrolling and display no
                                  vertical scroll bars

   Available In

Universal Forms Description Language                          [page 144]


              - field

   Example

    This sample sets the vertical scrolling option to inhibit all
    scrolling.
     scrollvert = "fixed";

   Usage Notes

    1) Default: never

    2) The scroll bar displays along the field's right edge.
------

  5.36   signature

    The signature option is used in conjunction with the button item
    to establish the UFDL item name by which a particular digital
    signature will be identified.

   Syntax

     signature = <name of signature>;

    Expression           Setting        Description
    <name of signature>  string         the name of the signature

   Available In
              - button
              - signature

   Example

    This sample identifies the signature item for a particular button
    as "mysig".
     signature = "mysig";

   Usage Notes

    1) Default: none

    2) The signature option must be included in each Signature button
       that is set up.

    3) For more information on filtering, see "Filters"
------

  5.37   signdatagroups

    The signdatagroups option specifies which datagroups are to be
    filtered for a particular digital signature. (Filtering means
    either keeping or omitting data.) Keeping a datagroup means
    keeping or omitting all items containing that datagroup name, even
    if they were added after the form was created. This is how
    enclosures are signed.

Universal Forms Description Language                          [page 145]


   Syntax

     signdatagroups = [<datagroup filter>, <datagroup reference>,
                       ... <datagroup referencen>];
     Note: The number of <datagroup reference> entries is optional.

    Expression            Setting   Description
    <datagroup filter>    "keep"    include datagroups in the
                                    <datagroup reference> list with
                                    the signature; omit those not in
                                    list
                          "omit"    omit datagroups in the
                                    <datagroup reference> list from
                                    the signature; include those not
                                    in list
    <datagroup reference> string    identifies a datagroup
   Available In
              - button
              - signature

   Example

    This example specifies a signdatagroups option that keeps the
    datagroup called "Business_Letters".
     signdatagroups = ["keep", "Business_Letters"];

   Usage Notes

    1) Default: keep

    2) Since enclosed files can belong to several datagroups, and
       datagroups can contain several enclosed files, care must be
       exercised when setting up signdatagroups options to ensure that
       only the desired datagroups are filtered.

    3) See "Order of Precedence of Filters" on page 48 for further
       information on filtering.
------

  5.38   signer

    The signer option identifies who signed a particular form.

   Syntax

     signer = <identity of user>;

    Expression          Setting      Description
    <identity of user>  string       identity of user

   Available In
              - button
              - signature


Universal Forms Description Language                          [page 146]


   Example

    In this example, signer is similar to a user's email signature,
    clearly identifying who signed the form.
     signer = "John Smith jsmith@acme.org";

   Usage Notes

    1) The setting of the signer option varies, depending on where the
       signature is from. Using different certificate authorities may
       produce different results.

    2) The signer option is automatically generated by the signature
       button when the user signs the form. It goes automatically into
       both the signature button code and the signature code. No manual
       coding is required.
------

  5.39   signformat

    The signformat option records the type of encoding that a Viewer
    should use to create the mimedata setting in a signature.
    Specifically, the parameters in signformat specify:
     - the MIME type of the data from which the mimedata setting is
       created (see below for an explanation).

     - the cryptographic service provider to use when creating a hash
       of the signed data.

     - the type of implementation of the cryptographic service provider
       (for example, full implementation, only one algorithm supported,
       etc.)

     - the algorithm to use when creating a hash of the signed data.

    About the mimedata setting:

    To create the mimedata setting, a Viewer takes the signer's
    certificate and a plaintext representation of the form or portion
    of the form that the signature applies to, and encodes them
    according to the settings in signformat. For details, see the
    mimedata option description.

   Syntax

     signformat = "<MIMEtype>;csp=\"<csp>\";csptype=<csptype>;
                   hashalg=<alg>";

    Expression     Setting        Description
    <MIMEtype>     string         the MIME type of the signed data.
                                  Must be application/uwi_form.
    <csp>          string         the cryptographic service provider
                                  to use. Must be a string enclosed in
                                  escaped double-quotation marks. The
                                  string is pre-defined by the crypto
                                  API.

Universal Forms Description Language                          [page 147]


    <csptype>      string or      the type of implementation of the
                   csp-defined    crytographic service provider.  For
                   number         allowed types, see the list in
    <alg>          string         the hash algorithm to use

   Available In
              - button
              - signature

   Example

     empSigButton = new button
     {
        type = "signature";
        value = signer;
        format = ["string", "mandatory"];
        signformat = "application/uwi_form;csp=\"Microsoft Base
     Cryptographic Provider v1.0\";csptype=rsa_full;hashalg=sha1";
        signoptions = ["omit", "triggeritem", "coordinates"];
        signitemrefs = ["omit", "PAGE1.mgrSigButton",
                        "PAGE1.admSigButton", "PAGE1.empSignature",
                        "PAGE1.mgrSignature", "PAGE1.admSignature"];
        signature = "empSignature";
     }

   Usage Notes

    1) A UFDL Viewer automatically copies the signformat option from a
       signature button to its associated signature item.

    2) You must escape the quotation marks around the name of the
       cryptographic service provider. Escape them using the
       backslash (\).

    3) The list below describes the settings you may use for the
       csptype parameter. (Note that you may also use a numeric value,
       as described below the table.)

       Setting         Meaning
       rsa_full        Full RSA implementation (this is the default)
       rsa_sig         For a CSP that supplies only RSA signature
                       algorithms
       dss             For a CSP that supplies algorithms compliant
                       with the Digital Signature Standard
       dss_dh          For a CSP that supplies DSS compliant algorithms
                       and Diffie-Hellman encryption
       fortezza        For a CSP that supplies Fortezza algorithms

    4) Instead of using one of the settings in the table above for
       csptype, you may use the numeric value that is defined for it in
       the cryptographic API. For example, csptype=dss and csptype=3
       produce the same result.
------

  5.40   signgroups

Universal Forms Description Language                          [page 148]


    The signgroups option specifies which groups of items are to be
    filtered for a particular digital signature. (Filtering means
    either keeping or omitting items.) Examples of grouped items are
    radio buttons and cells.

   Syntax

     signgroups = [<group filter>, <group reference>, ...
                   <group referencen>];
     Note: The number of <group reference> entries is optional.

    Expression        Setting     Description
    <group filter>    "keep"      include groups of items in the <group
                                  reference> list with the signature;
                                  omit those not in list
                      "omit"      omit groups of items in the <group
                                  reference> list from the signature;
                                  include those not in list
    <group reference> string      identifies a group of items
   Available In
              - button
              - signature

   Example

    This example shows a signgroups setting that omits the groups of
    items named "yesnoradiobuttons" and "monthlypaycells".
     signgroups = ["omit", "yesnoradiobuttons", "monthlypaycells"];

   Usage Notes

    1) Default: keep

    2) It is possible to have several list or popup items with the same
       group reference, as these are populated with cells that have the
       same group reference as the item which contains them. Therefore,
       when setting up signgroups options, caution must be exercised
       in making group references to list or popup items which may be
       populated by the same group of cells.

    3) See "Order of Precedence of Filters" in section 2.7 for further
       information on filtering.
------

  5.41   signitemrefs

    The signitemrefs option specifies which individual items are to be
    filtered for a particular digital signature. (Filtering means
    either keeping or omitting data.)

   Syntax

     signitemrefs = [<item filter>, <item reference>, ...
                     <item referencen>];

Universal Forms Description Language                          [page 149]


     Note: The number of <item reference> entries is optional.

    Expression        Setting     Description
    <item filter>     "keep"      include items in the <item reference>
                                  list with the signature; omit those
                                  not in list
                      "omit"      omit items in the <item reference>
                                  list from the signature; include
                                  those not in list
    <item reference>  string      specifies the item to be filtered

   Available In
              - button
              - signature

   Example

    This sample sets the signitemrefs option to omit two fields from
    the digital signature.
     signitemrefs = ["omit", "field1", "page1.field2"];

   Usage Notes

    1) Default: keep

    2) Since all items have a name and type, signitemrefs filters are
       always applicable.

    3) signitemrefs filters take precedence over signitems filters.

    4) See "Order of Precedence of Filters" for further information
       on filtering.
------

  5.42   signitems

    The signitems option specifies which types of items are to be
    filtered for a particular digital signature. (Filtering means
    either keeping or omitting data.)

   Syntax

     signitems = [<item filter>, <item type>, ... <item typen>];
     Note: The number of <item type> entries is optional.

    Expression     Setting        Description
    <item filter>  "keep"         include types of items in the <item
                                  type> list with the signature; omit
                   "omit"         omit types of items in the <item
                                  type> list from the signature;
                                  include those not in list
    <item type>    string         specifies the type of item to be
                                  filtered

   Available In

Universal Forms Description Language                          [page 150]


              - button
              - signature

   Example

    This sample sets the signitems option to keep the following types
    of items with the signature: boxes, buttons, and fields.
     signitems = ["keep", "box", "button", "field"];

   Usage Notes

    1) Default:  keep

    2) A signitems setting can be overridden by a signoptions setting,
       in terms of the order of precedence.

    3) See "Order of Precedence of Filters" in section 2.7 for further
       information on filtering.
------

  5.43   signoptionrefs

    The signoptionrefs option specifies which individual options are
    to be filtered for a particular digital signature. (Filtering
    means either keeping or omitting a piece of data.) This option
    should be used in conjunction with a signoptions option also
    appearing in the filter.

   Syntax

     signoptionrefs = [<option filter>, <option reference>, ...
                       <option referencen>];
     Note: The number of <option reference> entries is optional.

    Expression          Setting  Description
    <option filter>     "keep"   include options in the <option
                                 reference> list with the signature;
                                 omit those not in list
                        "omit"   omit options in the <option reference>
                                 list from the signature; include those
                                 not in list
    <option reference>  string   specifies the option to be filtered


   Available In
              - button
              - signature

   Example

    This example specifies a signoptionrefs setting that keeps a
    particular field with the digital signature.
     signoptionrefs = ["keep", "page1.field1.value"];

    Note: the page name can be dropped if the option in question is
    on the same page, but the item name should not be dropped.

Universal Forms Description Language                          [page 151]


   Usage Notes

    1) Default:  keep

    2) Note that unlike signoptions, the signoptionrefs filter can
       cause an item to be included even if the item filters would
       normally omit the item. This is necessary in order to ensure
       that the hashed text is in valid UFDL format.

    3) Signoptionrefs filters take precedence over signoptions filters.

    4) See "Order of Precedence of Filters" in section 2.7 for further
       information on filtering.
------

  5.44   signoptions

    The signoptions option specifies which types of options are to be
    filtered for a particular digital signature. (Filtering means
    either keeping or omitting a piece of data.)

   Syntax

     signoptions = [<option filter>, <option type>, ...
                    <option typen>];
     Note: The number of <option type> entries is optional.

    <option filter>  "keep"     include types of options in the <option
                                type> list with the signature; omit
                                those not in list
                     "omit"     omit types of options in the <option
                                type> list from the signature; include
                                those not in list
    <option type>    string     specifies the type of option to be
                                filtered


   Available In
              - button
              - signature

   Example

    This example shows a signoptions setting that omits two types of
    options from the digital signature.
     signoptions = ["omit", "url", "printsettings"];

   Usage Notes

    1) Default:  keep

    2) One signoptions setting that must always be specified is as
       follows:
       signoptions = ["omit", "triggeritem", "coordinates"];

Universal Forms Description Language                          [page 152]


       This setting ensures that the signature will not be broken due
       to an alteration to the form.

    3) signoptions can be overridden by a signoptionrefs setting.

    4) See "Order of Precedence of Filters" in section 2.7 for further
       information on filtering.
------

  5.45   size

    The size option specifies an item's size. It does not include
    external labels, borders or scroll bars. These are part of the
    bounding box size which is calculated automatically. The size unit
    of measurement is characters.

    Examples of item size are the input area in a field item or the
    height and width of the label in label and button items.

    See 'Item Size' in section 2.4e for a discussion of item and
    bounding box sizes.

   Syntax

     size = [<width>, <height>];

    Expression     Setting        Description
    <width>        short int      the horizontal dimension of the item
    <height>       short int      the vertical dimension of the item


   Available In
              - box
              - button
              - check
              - field
              - label
              - line
              - list
              - popup
              - radio
              - spacer
              - tablet

   Example

    This sample sets the item's size to 80 characters wide by five
    characters high.
     size = ["80", "5"];

   Usage Notes


    2) Size and Font:

Universal Forms Description Language                          [page 153]


       The width may not always accommodate the number of characters
       you specify. The calculation to determine actual width is:
        'average character width for the item's font' X <width>
       This will only exactly match the number of characters the item
       can display horizontally when the font is mono-spaced
       (like Courier).

    3) If either the height or the width is invalid, the default item
       size will be used. A dimension of zero (0) is invalid for all
       items except line.

    4) The item and bounding box sizes can be changed by using
       itemlocation with an expansion or extent modifier.
------

  5.46   thickness

    The thickness option specifies the thickness of a line. The unit
    of measurement is pixels.

   Syntax

     thickness = <thickness>;

    Expression     Setting        Description
    <thickness>    short int      the thickness of the line


   Available In
              - line

   Example

    Example 1

    This sample defines a horizontal line 40 characters long and five
    pixels thick.
     size = ["40", "0"];
     thickness = "5";

    Example 2

    This sample defines a vertical line 20 characters long and 10
    pixels thick.
     size = ["0", "20"];
     thickness = "10";

   Usage Notes

    1) Default: one pixel

    2) Use size to define the dimension of a line in one direction
       (height or width) and thickness to define the dimension in the
       other direction. The dimension thickness defines must be set to
       zero in size.


Universal Forms Description Language                          [page 154]


    3) The line's thickness can be changed by using itemlocation with
       an expansion modifier for the dimension that thickness
       describes.
------

  5.47   transmitdatagroups

    This is one of the transmit-family of options that allow you to
    filter form submissions. This option lists which datagroups of
    items should be kept or omitted from a transmission.

    For example, if transmitdatagroups specifies that the datagroup
    called enclosures should be kept in the transmission, then all
    items with a datagroup setting of enclosures will be transmitted
    (unless other filters of greater precedence exclude them).

    This filter applies only to items for which it is valid to have a
    datagroup option (action, button, cell, data).

    For details on the order of precedence of filters, see "Order of
    Precedence of Filters" in section 2.7.

   Syntax

     transmitdatagroups = [<transmit flag>, <datagroup identifier1>,
                       ... <datagroup identifiern>];
     Note: There may be zero or more <datagroup identifier> entries.

    Expression            Setting   Description
    <transmit flag>       "keep"    keep items with a datagroup setting
                                    specified in the <datagroup
                                    identifier> list; omit those with
                                    a datagroup setting not included in
                                    the list
                          "omit"    omit items with a datagroup setting
                                    specified in the <datagroup
                                    identifier> list; keep those with a
                                    group setting not in the list
    <datagroup            string    the name of a datagroup setting
    identifier>

   Available In
              - button
              - cell

   Examples

    This sample specifies that only the items with a datagroup setting
    of enclosures should be transmitted.
     transmitdatagroups = ["keep", "enclosures"];

    This sample specifies that all items except those with a datagroup
    setting of other should be kept in the transmission.
     transmitdatagroups = ["omit", "other"];


Universal Forms Description Language                          [page 155]


   Usage Notes

    1) The default is to keep all datagroups in the form.

    For details on the order of precedence of filters, see "Order of
    Precedence of Filters" in section 2.7.
------

  5.48   transmitformat

    The transmitformat option specifies the format of the form data
    submitted to a processing application. A UFDL form can submit data
    in UFDL format, compressed UFDL format, or in HTML format.

    UFDL format is the entire form definition, including user input,
    unless you use the options transmit, transmititems, and
    transmitoptions to omit some items and options from the form
    submission.

    HTML format is just an assignment statement for each item equating
    the item reference with the item's value. The only items included
    are modifiable items, custom items, and items with a transmit
    option setting of all.

    If you specify that a UFDL format submission should be compressed,
    it will be compressed using a gzip compression algorithm.

    Note: Form and page global characteristics are sent only if the
    format is UFDL.

   Syntax

     transmitformat = <MIME_type>;

    Expression  Setting                             Description
    <MIME_type> "application/uwi_form"              use UFDL format
                "application/uwi_form;content-      use compressed UFDL
                               encoding=\"gzip\""   format
                "application/x-www-form-urlencoded" use HTML form
                                                    format

    Note: You cannot specify that data in HTML form format be
    compressed.


   Available In
              - action
              - button
              - cell
              - form global characteristics

   Examples

    Example 1 - UFDL format

    This example shows a button which, when clicked, will submit the

Universal Forms Description Language                          [page 156]


    form in UFDL format.
     send_button = new button
     {
        type = "done";
        url = ["mailto:user@host.domain"];
        transmitformat = "application/uwi_form";
     }

    When a user clicks the button, the entire form definition will be
    submitted, unless other transmit options specify a partial
    submission.

    Example 2 - Compressed UFDL format specified in form global

    This example shows how to use the transmitformat option as a form
    global option. Here, it specifies that data should be submitted in
    compressed UFDL format.
     version = "3.2.0";
     bgcolor = ["ivory"];
     transmitformat = "application/uwi_form; content-encoding=\"gzip\"";

     page_1 = new page
     {
    When a submit or done action is activated in the form, the data
    will be sent in compressed UFDL format. When transmitformat appears
    as a form global characteristic, it applies to all submissions from
    the form. You can override it for a particular submission if you
    place a transmitformat setting in the item that initiates the
    submission.

    Note that the quotation marks around gzip must be escaped.

    Example 3 - HTML form format

    This sample shows an automatic action that submits form data in
    HTML form format.
     status_action = new action
     {
        type = "submit";
        url = ["http://www.host.domain/cgi-bin/recvStatus"];
        transmitformat = "application/x-www-form-urlencoded";
        delay = ["repeat", "180"];
     }

    Every 180 seconds, the form definition will be converted to HTML
    form format as specified in Usage Note 4. Other transmit options
    could override the choice of items to include in an HTML form
    (see Usage Notes 5 and 6).

   Usage Notes

    1) Default: UFDL format (not compressed)

    2) You can include this option as a form global option and in the
       definitions of items that trigger form submissions. These items

Universal Forms Description Language                          [page 157]


       have a type option setting of submit or done.

    3) HTML Format by Item Type
       The general syntax of a submitted HTML form is:
       <item reference>=<value>&< item reference>=<value>&...
       Note: the ampersand separates form items.

       The syntax of an HTML form entry by item type:

    Item Type           HTML Format
    check               <item tag>=<value option setting>
    field               <item tag>=<value option setting>
    list                <item tag>=
                        <value option setting of selected cell>
                        Note: <item reference> identifies the list.
    popup               <item tag>=
                        <value option setting of selected cell>
                        Note: <item reference> identifies the popup.
    radio               <group option setting>=
                        <item tag of selected radio>
    <custom>            <item tag>=<value option setting>
    all other items     <item tag>=<value option setting>

      Note: combo boxes are not supported in HTML.

    Substitutions and Omissions:
        - Spaces in the value are replaced by the plus sign (+).
          'Two words' becomes 'Two+words'
        - The membership operator in item and group references is
          replaced by a minus sign.
          'page_one.age_group' becomes 'page_one-age_group'
        - Page tags are removed from item and group references in
          single page forms.
        - Check boxes and radio buttons with a value option setting of
          off are omitted.
        - Entries resulting in an empty string on the right hand side
          of the assignment statement are omitted. This occurs when the
          referenced option setting is empty or the option definition
          is missing.

    4) Partial Submissions

       Just as you can specify partial submissions when transmitting
       data in UFDL format, you can also specify partial submissions
       when transmitting data in HTML format. Use the transmit and
       transmititems options.

       Use the transmitoptions option for HTML formatted submissions
       with caution. If you omit the options used for HTML format, then
       items requiring those options are omitted also.
       For example, if the trigger item's definition included the
       following pair of statements, the form submission would contain
       only radio item entries (all other entries use a value option
       setting).
        transmitformat = "application/x-www-form-urlencoded";

Universal Forms Description Language                          [page 158]


        transmitoptions = ["omit", "value"];

    5) HTML Considerations

       The functionality of UFDL forms differs somewhat from HTML
       forms. Those differences are:
        - Enclosures
          HTML does not support enclosures. To submit enclosed form
          data, use UFDL format.
        - Item tags
          UFDL allows a smaller set of characters in item tags than
          HTML does. UFDL item tags support the following characters:
          a-z, A-Z, 0-9, and the underscore ( _ ).
        - Check boxes
          UFDL check boxes vary slightly from HTML check boxes. UFDL
          check boxes are independent items; HTML check boxes are
          grouped together using the same format as radio items. When
          a UFDL form is submitted in HTML format, the submission will
          contain an entry for each check box.
------

  5.49   transmitgroups

    This is one of the transmit-family of options that allow you to
    filter form submissions. This option lists which groups of items
    should be kept or omitted from a transmission.

    For example, if transmitgroups specifies that the group called
    countries should be kept in the transmission, then all items with
    a group setting of countries will be transmitted (unless other
    filters of greater precedence exclude them).

    This filter applies only to items for which it is valid to have a
    group option (cell, combobox, list, popup, radio).

    For details on the order of precedence of filters, see "Order of
    Precedence of Filters"

   Syntax

     transmitgroups = [<transmit flag>, <group identifier1>,
                   ... <group identifiern>];
     Note: There may be zero or more <group identifier> entries.

    Expression         Setting   Description
    <transmit flag>    "keep"    keep items with a group setting
                                 specified in the <group identifier>
                                 list; omit those with a group setting
                                 not included in the list
                       "omit"    omit items with a group setting
                                 specified in the <group identifier>
                                 list; keep those with a group setting
                                 not in the list
    <group identifier> string    the name of a group setting



Universal Forms Description Language                          [page 159]


   Available In
              - action
              - button
              - cell

   Examples

    This sample specifies that only the items in the countries and
    departments groups should be kept in the transmission.
     transmitgroups = ["keep", "countries", "departments"];

    This sample specifies that all groups should be kept in the
    transmission except the fillType group.
     transmitgroups = ["omit", "fillType"];

   Usage Notes

    1) The default is to keep all groups in the form.

    2) This option is handy for keeping the user's selection in lists
       and popups. Since the value setting of a popup or list is not
       the value of the cell the user chose, but is rather the item
       tag of the cell containing the value, you might want to make
       sure you keep the selected cell in the transmission so that you
       can dynamic option reference its value. To do this, you would
       keep the group of cells associated with the popup's group.

       For details on the order of precedence of filters, see "Order
       of Precedence of Filters"
------

  5.50   transmititemrefs

    This is one of the transmit-family of options that allow you to
    filter form submissions. This option lists which specific items
    should be kept or omitted from a transmission. It differs from
    transmititems in that transmititems specifies particular types of
    items to filter, whereas transmititemrefs refers to one or more
    specific items.

    For example, if transmititemrefs specifies that the item
    page1.MgrSignButton should be kept in the transmission, then even
    if a transmititems filter says all buttons should be omitted from
    the form, the particular button on page 1 named MgrSignButton would
    be kept.

    For details on the order of precedence of filters, see "Order of
    Precedence of Filters"

   Syntax

     transmititemrefs = [<transmit flag>, <item identifier1>,
                     ... <item identifiern>];
     Note: There may be zero or more <item identifier> entries.
    Expression         Setting   Description

Universal Forms Description Language                          [page 160]


    <transmit flag>    "keep"    keep the specific items referred to in
                                 the <item identifier> list; omit all
                                 other items
                       "omit"    omit the specific items referred to in
                                 the <item identifier> list; keep all
                                 others
    <item identifier>  string    the item reference of an item,
                                 starting with the page tag

   Available In
              - action
              - button
              - cell

   Examples

    This sample specifies that only the item on page 1 called
    MgrSignButton should be transmitted, and that all other items
    should be omitted.
     transmititemrefs = ["keep", "page1.MgrSignButton"];

    This sample shows how you would use transmititemrefs in
    conjunction with transmititems: although all items that are
    buttons are omitted, the button on page 1 called MgrSignButton will
    be kept.
     transmititems = ["omit", "button"];
     transmititemrefs = ["keep", "page1.MgrSignButton"];

   Usage Notes

    2) The default is to keep all items in the form.

    3) The setting of a transmititemrefs always overrides a
       transmititems setting.

    4) The setting of a transmitoptionrefs always overrides a
       transmititemrefs setting.

       For full details on the order of precedence of filters, see
       "Order of Precedence of filters" in section 2.7.
------

  5.51   transmititems

    This option lists the types of items to include in or omit from the
    form data submitted to a form processing application. Include this
    option in the definitions of items that trigger form submissions.
    These trigger items have a type option setting of submit or done.

   Syntax

     transmititems = [<transmit flag>, <item type1>, ... <item typen>];
     Note: The number of <item type> entries is optional.

    Expression        Setting     Description
    <transmit flag>   "keep"      include items with an item type from

Universal Forms Description Language                          [page 161]


                                  the <item type> list; omit those not
                                  in list
                      "omit"      omit items with an item type from the
                                  <item type> list; include those not
                                  in list
    <item type>       string      a type of item


   Available In
              - action
              - button
              - cell

   Example

    This sample specifies that box, help, label, spacer, and toolbar
    items should be omitted from the form data submitted to the form
    processing application.
     transmititems = ["omit", "box", "help", "spacer", "toolbar"];

   Usage Notes

    1) The default is to keep all items.

    2) See the transmititemsrefs description for information on how to
       keep or omit a specific item (as opposed to a type of item).
  5.52   transmitoptionrefs

    This is one of the transmit-family of options that allow you to
    filter form submissions. This option lists which specific options
    should be kept or omitted from a transmission. It differs from
    transmitoptions in that transmitoptions specifies particular types
    of options to filter, whereas transmitoptionrefs refers to one or
    more specific options.

    For example, if transmitoptionrefs specifies that the option
    page1.NameField.value should be kept in the transmission, then even
    if a transmitoptions filter says all value options should be
    omitted from the form, the particular value option in the field on
    page 1 called NameField will be kept.

    For details on the order of precedence of filters, see "Order of
    Precedence of Filters" in section 2.7.

   Syntax

     transmitoptionrefs = [<transmit flag>, <option identifier1>,
                       ... <option identifiern>];
     Note: There may be zero or more <option identifier> entries.

    Expression          Setting   Description
    <transmit flag>     "keep"    keep the specific options referred to
                                  in the <option identifier> list; omit
                                  all other options
                        "omit"    omit the specific options referred to

Universal Forms Description Language                          [page 162]


                                  in the <option identifier> list; keep
                                  all others
    <option identifier> string    the option reference of an option,
                                  starting with the page tag


   Available In
              - action
              - button
              - cell

   Examples

    This sample shows how you would use transmitoptionrefs in
    conjunction with transmitoptions: although all options that are
    values are omitted, the value in the NameField on page 1 will be
    kept.
     transmitoptions = ["omit", "value"];
     transmitoptionrefs = ["keep", "page1.NameField.value"];

    This sample shows how you would use transmitoptionrefs in
    conjunction with transmititemrefs: although the item called
    MgrSignButton on page 1 is omitted, its signer option is kept
     transmititemrefs = ["omit", "MgrSignButton"];
     transmitoptionrefs = ["keep", "page1.MgrSignButton.signature"];

   Usage Notes

    5) The default is to keep all options in the form.

       For details on the order of precedence of filters, see "Order
       of Precedence of Filters" in section 2.7.
------

  5.53    transmitoptions

    This option lists which options to include in or omit from the
    form data submitted to a form processing application. Include this
    option in the definitions of items that trigger form submissions.
    These trigger items have a type option setting of submit or done.

    Only options meeting the following standard are affected by
    transmitoptions:
     - The option definition occurs in an item already included in the
       form submission.

    Note: The version option is always included in the submission
    unless the format is HTML.

   Syntax

     transmitoptions = [<transmit flag>, <option identifier1>,
                    ... <option identifiern>];
     Note: The number of <option identifier> entries is optional.

    Expression            Setting  Description

Universal Forms Description Language                          [page 163]


    <transmit flag>       "keep"   include options with an option type
                                   in the <option identifier> list;
                                   omit those not in list
                          "omit"   omit options with an option
                                   identifier in the <option
                                   identifier> list; include those not
                                   in list
    Tip: Transmitoptions does not affect options in items omitted by
         the transmititems option.

   Available In
              - action
              - button
              - cell

   Example

    This sample specifies that only the active, mimedata, and value
    options should be included in the form data submitted to the form
    processing application.
     transmitoptions = ["keep", "active", "mimedata", "value"];

   Usage Notes

    6) The default is to keep items.

    7) See the transmitoptionrefs description for details on how to
       keep or omit a specific option (as opposed to a type of option).
------

  5.54   triggeritem

    The triggeritem option identifies the item that triggered a form
    submission. Items triggering form submissions have a type option
    setting of submit or done.

    When a user selects an item that triggers a form submission, the
    triggeritem option is added to the form global characteristics and
    assigned the item reference of the selected item.

   Syntax

     triggeritem = <item reference>;

    Expression         Setting   Description
    <item reference>   string    identifies the trigger item


   Available In
              - form global characteristics

   Example

    This sample indicates that the item triggering the request is on
    the page called Page_one and has an item tag of submit_button.

Universal Forms Description Language                          [page 164]


     triggeritem = "Page_one.submit_button";
------

  5.55   type

    The type option associates a task type with an item that can
    trigger a task: action, button, or cell.

   Syntax

     type = <task type>;

    Expression     Setting        Description
    <task type>    (see below)    the task to perform


   Task Types

    The <task type> can be any of the following:

    Task Type  Description of Task                     Use With
    link       Perform all requests specified by the   action
               url options in the current item. See    button
               the section 'url' for more details.     cell

    replace    Perform a link followed by a cancel.    action
                                                       cell

    submit     Initiate the form processing            action
               applications identified in the url      button
               options of the current item.            cell

    done       Perform a submit followed by a cancel.  action
                                                       button
                                                       cell

    pagedone   Move to the page specified in the url   action
               option. This closes the current page    button
               and replaces it with the new page.      cell
               All fields containing error checking
               on the current page must be correctly
               filled out before it can be closed.

    cancel     Close the form; if any changes were     action
               made to the form since the last save    button
               or submit, then the user is informed    cell
               that the form has changed and is
               allowed to choose whether the
               cancellation should proceed. Note that
               the value options of many items, as
               well as the contents of data items,
               can change in response to an enclose
               or remove action.

    save       Save the form in a file specified by    action

Universal Forms Description Language                          [page 165]


               the user.                               button
                                                       cell

    select     With cell items: flag the cell as       button
               selected when a user chooses the cell.  cell
               This means the item reference of the
               cell is copied to the value option of
               the parent list or popup.
               With button items containing images:
               store coordinates of the mouse click
               position in the image into the
               coordinates option

    enclose    Allows the user to place one or more    button
               files into one or more of the           cell
               datagroups defined for the form. The
               files will be encoded using base64
               encoding format.

    extract    Allows a user to copy the contents of   button
               an enclosed file into a file on the     cell
               local disk.

    remove     Allows the user to remove an item from  button
               a datagroup; the underlying data item   cell
               will only be deleted if it belongs to
               no other datagroups.

    display    Display an enclosed file. Your web      action
               browser will choose the appropriate     button
               viewer according to the file's MIME     cell
               type.

    print      Print the form on a local printer.      action
                                                       button
                                                       cell

    signature  Create a digital signature.             button

 Universal Forms Description Language                           [page 96]


   Available In
              - action
              - button
              - cell

   Example

    This sample specifies that this item saves the form to a local file.
     type = "save";

   Usage Notes

    1) Default: link
------


Universal Forms Description Language                          [page 166]


  5.56   url

    The url option identifies an object to access. Items containing
    this option must have a type option setting of link, replace,
    submit, done, or pagedone.

    The object identified can be any of the following:
        * File - used with a type option setting of link or replace
          The file identified is downloaded, and either displayed or
          saved. Examples of such files are images, word processing
          documents, and UFDL forms.
        * Application - used with a type option setting of submit or
          done
          The application identified is initiated. A form processing
          application is an example of such an application.
        * Item - used with a type option setting of pagedone
          The item identified, on the page identified, receives focus.
          The item must be on another page.
        * Form or Page Characteristics - used with a type option
          setting of pagedone
          The focus moves to the item defined to receive focus when the
          form or page appears. The form characteristics reference is
          global.global. The page characteristics reference is
          <page tag>.global for another page.

   Syntax

     url = [<the URL1>, <the URL2>, ... <the URLn>];
     where <the URL> is one of:
        - a URL with the format <scheme://host.domain[:port]
          /path/filename> for files and applications
        - #<item reference> for the next item in the form to receive
          focus
     Notes:
     I) <the URL> can occur 1-n times.
     ii) <item reference> can be a form or page characteristics
     reference.

    Expression     Setting        Description
    <the URL>      string         identifies the object to link


   Available In
              - action
              - button
              - cell

   Example

    This sample identifies a form processing application.
     url = ["http://www.host.domain/cgi-bin/recv_status"];
    This sample identifies a page to display and an item on it to
    direct the focus to.
     url = ["#page_2.expense_field"];

   Usage Notes

Universal Forms Description Language                          [page 167]


    1) Default: none

    2) When a form communicates with a server, the information sent
       may be URL-encoded. This means all non alpha-numeric characters
       are replaced by a character triplet consisting of the %
       character followed by two hexadecimal digits that form the
       hexadecimal value of the original character. The hexadecimal
       digits are "0123456789ABCDEF". For example,

       Character      ASCII Number              URL-encoded triplet
       \r             13                        %0D


    Applications receiving form data must check the content type of the
    incoming data to see whether it is url-encoded.
------

  5.57   value

    The value option reflects the contents of an item. Visually, this
    can take several forms, depending on the item to which it applies.
    For example, the value option in label items contains the label
    text; the value option in radio items contains the status
    indicator; and the value option in list items contains the identity
    of the most recently selected cell (if it was a select cell).

    An item's contents will be stored in the form whenever a user saves
    the form or submits it for processing. This is true even for
    inactive items and items using the default value option setting
    (in this case, a value option containing the default setting is
    added to the item's definition).

   Syntax

     value = <setting>;

    Expression     Setting        Description
    <setting>      string         the item's contents


   Available In
              - button
              - cell
              - check
              - field
              - help
              - label
              - list
              - popup
              - radio
              - tablet

   Example


Universal Forms Description Language                          [page 168]


    This sample identifies the text of a label item.
     value = "My Form Title";

   Usage Notes

    1) Default: varies by item. See the documentation for each item.

    2) Multiple line values require line breaks imbedded in the value
       text. Use the escape sequence '\n' to indicate a line break.
       For example:
        value = "This value spans\ntwo lines.";

    3) To get the value of a cell that a user has selected from a list,
       you need to dereference it, like this:
        <page_tag>.<list_tag>.value->value
       For example:
        page1.countryPopup.value->value

       When a user selects a cell from a list, the item tag of the cell
       is stored as the value of the list. Hence the dereference
       syntax.
------

  5.58   version

    The version option specifies the Universal Forms Description
    Language version used to code the form definition.

    Note: This option must be the first statement in the form. It is
    invalid in any other location.

   Syntax

     version = <version>;

    Expression     Setting        Description
    <version>      string         the UFDL version number.

    Note: The version number must be coded as a quoted string. Other
    expression formats are invalid in this statement.


   Available In
              - form global characteristics (mandatory)

    This sample indicates the language in this form definition conforms
    to UFDL version 3.2.0 specification.
     version = "3.2.0";

   Usage Notes

    1) Important: Do not increase the version number of old forms
       unless they have been modified to conform to the new version.

    2) The format of a version number is m.n.r where:

Universal Forms Description Language                          [page 169]


       i) m is the major version number
       ii) n is the minor version number
       iii) r is the maintenance release number
------

  5.59   <custom option>

    Custom options allow form designers to add application specific
    information to the form definition. This is useful when submitting
    forms to applications requiring non-UFDL information. An example of
    non-UFDL information might be an SQL query statement.

   Syntax

     <custom> = [<expression1>, ... <expressionn>];
     Note: <expression> can occur 1-n times.

    Expression     Setting        Description
    <expression>   string         an expression that assigns a value
                                  to the option

   Example

    This sample shows a custom option containing an SQL query.
     sql_query = ["SELECT NAME FROM EMPLOYEE WHERE ID = "];

    This statement could be included in the definition of an item that
    triggers a form submission. The form processing application might
    then complete the statement with a value option setting from
    another item, and use the statement results to populate a response
    form.

   Usage Notes

    1) The naming conventions for a custom option are as follows:
        - It must begin with an alphabetic character.
        - It can contain any of the characters A-Z, a-z, 0-9, $ and
          underscore.
        - It must contain an underscore.
------


6.   UFDL Form Viewer Directive

    UFDL contains the following viewer directive statement:
        - the #include statement for including external files
        - the #optinclude statement for optionally including external
          files

    The syntax of a viewer directive statement is as follows:
     #<directive> "<value>"

    Do not terminate viewer directive statements with a semicolon.

    See the section "UFDL Form Options" for syntax notation
    conventions in section 5.0.

Universal Forms Description Language                          [page 170]


------

  6.1   #include

    The #include statement allows you to include external files in your
    form definition much as you would include header files in a C
    language source file. The form viewer application replaces the
    #include statement with the contents of the include file before the
    form appears.

   Syntax

     #include "<filename>"

    Value          Setting        Description
    <filename>     string         name of the include file


   Example

    This is an example of using an include file to add image data to
    a form.

     ?
     // Create a label to display the image.
     LOGO_IMAGE = new label
     {
       image = "LOGO_DATA";
     }
     //
     // Now include the image in the form.
     #include "logo.frm"
     ?

    This is the external file:

     LOGO_DATA = new data
     {
      mimedata = "<image data>";
     }

    The form after resolution of the include:
     ?
     // Create a label to display the image.
     LOGO_IMAGE = new label
     {
       image = "LOGO_DATA";
     }
     //
     // Now include the image in the form.

     LOGO_DATA = new data
     {
      mimedata = "<image data>";
     }

Universal Forms Description Language                          [page 171]


     ?

   Usage Notes

    1) You can code a #include statement anywhere in a form definition
       except imbedded in another statement. You can also nest #include
       statements.

    2) The include file must reside in a secure include directory
       accessible to the form viewer application.

    3) Use include files to reduce form file size, and ensure
       standardization of form definitions. Smaller files occupy less
       space on the server and download more quickly
------

  6.2   #optinclude

    The #optinclude statement is a variation on the #include statement.
    It allows you to include external files in your form definition
    much as you would include header files in a C language source
    file-without crashing your program if a file you attempt to include
    is not available. The form viewer application replaces the
    #optinclude statement with the contents of the optinclude file
    before the form appears.

   Syntax

     #optinclude "<filename>"

    Value          Setting        Description
    <filename>     string         name of the optinclude file


   Example

    This is an example of using an optinclude file to add image data
    to a form.

    Here is the original form definition:
     ?
     // Create a label to display the image.
     {
       image = "LOGO_DATA";
     }
     //
     // Now include the image in the form.
     #optinclude "logo.frm"
     ?

    This is the external file:

     LOGO_DATA = new data
     {

Universal Forms Description Language                          [page 172]


      mimedata = "<image data>";
     }


    The form after resolution of the include:
     ?
     // Create a label to display the image.
     LOGO_IMAGE = new label
     {
       image = "LOGO_DATA";
     }
     //
     // Now include the image in the form.

     LOGO_DATA = new data
     {
      mimedata = "<image data>";
     }

     ?


   Usage Notes

    1) Employing the same syntax as #include, #optinclude is a
       convenient alternative to #include, because:

       - In a given pool of users, everyone can be sent the same form,
         but certain users can have access to all its components while
         others do not-but there is no risk of crashing for anyone.

       - #optinclude saves server resources by making decisions on the
          client side about which files are to be included.

    2) The files to be included must reside in a secure directory on
       the user's computer.
------


7.   UFDL Functions

    UFDL functions allow forms to perform procedural logic, and also
    to perform complex operations that would normally require
    complicated conditional statements to achieve.

    Using functions in conjunction with conditional statements and user
    events provides a means for creating extremely powerful Internet
    form applications in a fairly simple and elegant manner.

    Below is a simple example of using a UFDL function (in the
    status_option line):
     version = "4.0.0";

     page1 = new page
     {
        field1 = new field

Universal Forms Description Language                          [page 173]


        {
                label = "Field 1";
                format = ["string", "mandatory"];
                value = "high";
        }

        {
                label = "Field 2";
                format = ["string", "mandatory"];
                status_option = toggle(field1.value, "high", "low");
                value = status_option=="1"?"Declined":"";
        }

     }

    Explanation: The toggle function (used in the status_option option
    line) returns a "1" if the value in field1 changes from high to
    low. As a result, the value of field 2 will change to Declined, if
    the toggle function returns a "1". Otherwise the value of the
    second field will be empty.

   Function Definition

    Call a UFDL function much in the same way you would call a C or
    Java function. The formal definition of a UFDL function is:

     returnValue package.functionName([parameter])


    Expression               Description

    returnValue              a string or an array
    package                  the name of the package that the function
                             belongs to; UFDL functions from this
                             specification are part of the system
                             package. All custom-made packages must
                             contain an underscore in their names.
    functionName             the name of the function
    parameter                a string or an array

   Notes on the Functions

    Position in Strings

    When referring to the position of a character in a string, note
    that the position of the first character in a string is at
    position zero. For example:
     This is a string

    The capital T in the string above is at position zero.

    Passing Literals and Option References

    1) To pass a literal value into a function, surround it in
       double-quotatation marks. For example:

Universal Forms Description Language                          [page 174]


        str_length = strlen("This is a literal string");

    2) To evaluate an option reference and pass its evaluated value
       into a function, do not surround the option reference in
       quotation marks. For example:
        str_length = strlen(surnameField.value);

    3) To pass an option reference into a function (without evaluating
       it), surround the option reference in double-quotation marks.
       For example:
        auto_set = set("statusField.value", "Confirmed.");

    A UFDL form will evaluate option references before a function runs,
    unless the references are surrounded by quotation marks.

   About Functions and Packages

    Functions are compiled into packages, which must reside on the
    desktop computer. The UFDL functions that are documented in this
    specification must be compiled into a package called system. No
    functions other than those documented here may be part of the
    system package.

    Form developers are free to develop their own packages of functions
    to extend UFDL. Packages of custom-developed functions must contain
    an underscore in their names. For example:

    - extr_fun.ifx

   About UFDL Functions

    UFDL functions are divided into the following sections:

     - String Functions
     - Math Functions
     - Utility Functions
     - Time and Date Functions
------

 7.1   String Functions

  7.1a   countLines

   Description

    Counts the number of lines that a string <string> would take up
    over a given width <width>, and returns the number of lines. The
    count assumes that the font is a monospaced font, and that the
    line will be wrapped at the ends of words, and not in the middle of
    words.
    This function is useful if you need to dynamically size items into
    which you want to insert a string. For example, if you want to
    insert an entry from a database into a field on a form, you can
    dynamically size the height of the field so that all of the text is
    visible.

Universal Forms Description Language                          [page 175]


    Note:  The <width> must be a character-based width and not a
    pixel-based width.

   Call

     countLines(<string>, <width>)

   Parameters

    Expression     Setting          Description
    <string>       literal string   the string to base the measurement
                   or option        on
                   reference
    <width>        positive int     the width, in monospaced
                                    characters, to base the measurement
                                    on

   Returns

    The number of lines, or "" (empty) if an error occurs.

   Example

     commentField = new field
     {
        label = "Comments";
        itemlocation = [["below", "deptField"]];
        size = ["50", countLines(value, "50")];
     }

    In the example above, the field's height will be set by the number
    that countLines returns. The calculation is based on a
    dynamically-generated value, and the field's set width (50).
------

  7.1b   replace

   Description

    Takes a string <string> and replaces a substring in it (marked by
    <start> and <end>) with <newString>. Returns the resulting string.

    If <start> is less than 0 then the substring will begin on the
    first character of <string>.  If <end> is greater than or equal to
    the length of <string> then the substring will end on the last
    character of <string>.  If <newString> is not long enough (i.e.,
    does not reach position <end>), replacement will end with the last
    character of <newString>.  If <newString> is too long (i.e.,
    extends past position <end>), replacement will end on position
    <end>.

    An error occurs if <start> is greater than <end>, if either of
    <start> and <end> is not a valid integer, or if <string> is empty.

   Call

Universal Forms Description Language                          [page 176]


     replace(<string>, <start>, <end>, <newString>)

   Parameters

    Expression     Setting          Description
    <string>       literal string   the original string (enclose
                   or option        literal strings in double
                   reference        quotation marks, do not enclose
                                    option references in quotation
                                    marks)
    <start>        int              position of character at the start
                                    of the substring (the first
                                    character in <string> is zero)
    <end>          int              position of character at the end of
                                    the substring (the first character
                                    in <string> is zero)
    <newString>    literal string   the replacement string (enclose
                   or option        literal strings in double
                   reference        quotation marks, do not enclose
                                    option references in quotation
                                    marks)

   Returns

    The modified string, or "" (empty) if an error occurs.

   Example

     replaceField = new field
     {
        label = "Test replace()";
        format = ["string", "mandatory"];
        id_value = replace(value, "3", "6", "east");
     }

    The result of replace in the above example would be "Go east,
    young man!".
------

  7.1c   strlen

   Description

    Returns the length of <string>.

   Call

     strlen(<string>)

   Parameters

    Expression     Setting          Description
    <string>       literal string   the string (enclose literal strings
                   or option        in double quotation marks, do not

Universal Forms Description Language                          [page 177]


                   reference        enclose option references in
                                    quotation marks)


   Returns

    A string containing the length.

   Example

     stringLengthField = new field
     {
        label = "The length of this label is:";
        format = ["string", "mandatory"];
        value = strlen(label);
     }

    The result of strlen in the above example would be "28".
------

  7.1d   strmatch

   Description

    Determines if the wildcard string <wild> matches the non-wildcard
    string <real> and returns the boolean result.  See the format
    forms option for a description of valid wildcards.

   Call

     strmatch(<wild>, <real>)

   Parameters

    Expression     Setting          Description
    <wild>         literal string   the wildcard string to match
                   or option        (enclose literal strings in double
                   reference        quotation marks, do not enclose
                                    option references in quotation
                                    marks)
    <real>         literal string   the non-wildcard match string
                   or option        (enclose literal strings in double
                   reference        quotation marks, do not enclose
                                    option references in quotation
                                    marks)


   Returns

    A string containing "1" if a match occurs, "0" if no match occurs.

   Example

     testStrmatch = new field
     {
        label = "Test strmatch()";

Universal Forms Description Language                          [page 178]


        format = ["string", "mandatory"];
        value = "To be or not to be, etc.";
        id_value = strmatch("?o be* ?o be*", value);
     }

    The result of strmatch in the above example would be "1".
------

  7.1e   strpbrk

   Description
    Returns the position of the first character from <string2> that is
    found in <string1>.

   Call

     strpbrk(<string1>, <string2>)

   Parameters

    Expression     Setting          Description
    <string1>      literal string   the string (enclose literal strings
                   or option        in double quotation marks, do not
                   reference        enclose option references in
                                    quotation marks)
    <string2>      literal string   the string of characters (enclose
                   or option        literal strings in double quotation
                   reference        marks, do not enclose option
                                    references in quotation marks)


   Returns

    A string containing the position, or "-1" if no matching
    characters are found.

   Example

     testStrpbrk = new field
     {
        label = "testField";
        format = ["string", "mandatory"];
        value = "To be or not to be, etc.";
        id_value = strpbrk(value, "lLmMnNoOpP");
     }

    The result of strpbrk in the above example would be "9".
------

  7.1f   strrstr

   Description

    Returns the position of the first character of the last
    occurrence of <string2> in <string1>.

Universal Forms Description Language                          [page 179]


   Call

     strrstr(<string1>, <string2>)

   Parameters

    Expression     Setting          Description
    <string1>      literal string   the string (enclose literal strings
                   or option        in double quotation marks, do not
                   reference        enclose option references in
                                    quotation marks)
    <string2>      literal string   the substring (enclose literal
                   or option        strings in double quotation marks,
                   reference        do not enclose option references
                                    in quotation marks)


   Returns

    A string containing the position, or "-1" if no substring is found.

   Example

     testStrrstr = new field
     {
        label = "testField";
        format = ["string", "mandatory"];
        value = "To be or not to be, etc.";
        id_value = strrstr(value, "be");
     }

    The result of strrstr in the above example would be "16".
------

  7.1g   strstr

   Description

    Returns the position of the first character of the first occurrence
    of <string2> in <string1>.

   Call
     strstr(<string1>, <string2>)

   Parameters

    Expression     Setting          Description
    <string1>      literal string   the string (enclose literal strings
                   or option        in double quotation marks, do not
                   reference        enclose option references in
                                    quotation marks)
    <string2>      literal string   the substring (enclose literal
                   or option        strings in double quotation marks,
                   reference        do not enclose option references

Universal Forms Description Language                          [page 180]


                                    in quotation marks)


   Returns

    A string containing the position, or "-1" if no occurrence is
    found.

   Example

     testStrstr = new field
     {
        label = "testField";
        format = ["string", "mandatory"];
        value = "To be or not to be, etc.";
        id_value = strstr(value, "be");
     }

    The result of strstr in the above example would be "3".
------

  7.1h   substr

   Description

    Returns the substring of <string> from the position indicated in
    <start> through the position indicated in <end>.  If <start> is
    less than zero then the substring will begin on the first
    character of <string>.  If <end> is greater than or equal to the
    length of <string> then the substring will end on the last
    character of <string>.

    An error occurs if <start> is greater than <end>, if either of
    <start> and <end> is not a valid integer, or if <string> is empty.

   Call

     substr(<string>, <start>, <end>)

   Parameters

    Expression     Setting          Description
    <string>       literal string   the string (enclose literal strings
                   or option        in double quotation marks, do not
                   reference        enclose option references in
                                    quotation marks)
    <start>        int              position of character at the start
                                    of the substring (the first
                                    character in <string> is zero)
    <end>          int              position of character at the end of
                                    the substring (the first character
                                    in <string> is zero)


   Returns


Universal Forms Description Language                          [page 181]


    The substring, or "" (empty) if an error occurs.

   Example

     surnameField = new field
     {
        label = "Surname";
        format = ["string", "mandatory"];
        value = "Watson";
        id_value = substr(value, "0", "4");
     }

    The result of substr in the above example would be "Watso".
------

  7.1i   tolower

   Description
    Returns the lower case of <string>.

   Call

     tolower(<string>)

   Parameters

    Expression     Setting          Description
    <string>       literal string   the original string (enclose
                   or option        literal strings in double quotation
                   reference        marks, do not enclose option
                                    references in quotation marks)


   Returns

    The lower case string.

   Example

     tolowerField = new field
     {
        label = "Type in Here";
        format = ["string", "mandatory"];
        value = "Hello!";
        id_value = tolower(value);
     }

    The result of tolower in the above example would be "hello!".
------

  7.1j   toupper

   Description

    Returns the upper case of <string>.

Universal Forms Description Language                          [page 182]


   Call

     toupper(<string>)

   Parameters

    Expression     Setting          Description
    <string>       literal string   the original string (enclose
                   or option        literal strings in double quotation
                   reference        marks, do not enclose option
                                    references in quotation marks)


   Returns

    The upper case string.

   Example

     toupperField = new field
     {
        label = "Type in Here";
        format = ["string", "mandatory"];
        value = "Hello!";
        id_value = toupper(value);
     }

    The result of toupper in the above example would be "HELLO!".
------

  7.1k   trim

   Description

    Returns a copy of <string> with all leading and trailing white
    space (blanks, tabs, newlines, carriage returns) removed.

   Call

     trim(<string>)

   Parameters

    <string>       literal string   the original string (enclose
                   or option        literal strings in double quotation
                   reference        marks, do not enclose option
                                    references in quotation marks)


   Returns

    The string with leading and trailing whitespace removed.

   Example

Universal Forms Description Language                          [page 183]


     trimField = new field
     {
        label = "     Test trim()  ";
        format = ["string", "mandatory"];
        value = trim(label);
     }

    The result of trim in the above example would be "Test trim()".
------

  7.1l   URLDecode

   Description

    Returns a URL-decoded version of <string>.

   Call

     URLDecode(<string>)

   Parameters

    Expression     Setting          Description
    <string>       literal string   the original string (enclose
                   or option        literal strings in double quotation
                   reference        marks, do not enclose option
                                    references in quotation marks)


   Returns

    The URL-decoded string.

   Example

     URLDecodeField = new field
     {
        label = " Test URLDecode";
        format = ["string", "mandatory"];
        value = URLDecode("This%20is%20a%20line%0D");
     }

    The result of URLDecode in the above example would be "This is a
    line\r".
------

  7.1m   URLEncode

   Description

    Returns a URL-encoded version of <string>.

   Call

     URLEncode(<string>)

Universal Forms Description Language                          [page 184]


   Parameters

    Expression     Setting          Description
    <string>       literal string   the original string (enclose
                   or option        literal strings in double quotation
                   reference        marks, do not enclose option
                                    references in quotation marks)


   Returns

    The URL-encoded string.

   Example

     URLEncodeField = new field
     {
        label = " Test URLEncode";
        format = ["string", "mandatory"];
     }

    The result of URLEncode in the above example would be
    "This%20is%20a%20line%0D".
------


 7.2   Math Functions

  7.2a   abs
   Description

    Returns the absolute value of the number represented in <number>.
    An error occurs if <number> is not a valid number.

   Call

     abs(<number>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number


   Returns

    A string containing the absolute of the number, or "" if an
    error occurs.

   Example

     absTest = new field
     {
        label = "Test abs";

Universal Forms Description Language                          [page 185]


        format = ["string", "mandatory"];
        value = abs("-2341.23");
     }

    The result of abs in the above example would be "2341.23".
------

  7.2b   acos

   Description

    Returns the arc cosine of a number stored in <number>.
    An error occurs if <number> is not a valid number or has absolute
    value greater than 1.

   Call

     acos(<number>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number


   Returns

    A string containing the arc cosine, or "" if an error occurs.

   Example

     arccosineField = new field
     {
        label = " Test acos";
        format = ["string", "mandatory"];
        value = acos("0.5");
     }

------

  7.2c   annuity

   Description

    Returns the present value annuity factor for an ordinary annuity,
    at a periodic interest rate indicated by <rate> over a number of
    periods specified in <periods>. (Present value is the lump sum to
    invest at <rate> in order to produce a set payment over <periods>.
    An ordinary annuity provides the payment at the end of each period
    specified in <periods>.)

    You might use this function to figure out either:
    - P, the present value (lump sum to invest)
    - R, the periodic payment amount that you will receive


Universal Forms Description Language                          [page 186]


    For your reference:

    P = R * annuity_factor          R = P / annuity_factor

    An error occurs if <periods> is not a valid integer, or if
    <rate> is 0.

   Call

     annuity(<rate>, <periods>)

   Parameters

    Expression     Setting          Description
    <rate>         decimal number   the rate of interest in decimal
                                    form compounded each period
    <periods>      integer          the number of periods


   Returns

    A string containing the present value annuity factor, or ""
    if an error occurs.

   Example

     presentValueInv = new field
     {
        label = "The present value to invest is:";
        format = ["string", "mandatory"];
        value = paymentField.value * annuity(".05", "7");
     }

    In the example above, annuity would return "5.786373", and, if the
    desired payment entered into paymentField were $1, then the value
    of presentValueInv would be $5.78. (That is, a person would have
    to invest $5.78 at 5% for seven payments.)
------

  7.2d   asin

    Description

    Returns the arc sine of a number stored in <number>.

    An error occurs if <number> is not a valid number or has an
    absolute value greater than 1.

   Call

     asin(<number>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number

Universal Forms Description Language                          [page 187]


   Returns

    A string containing the arc sine, or "" if an error occurs.

   Example

     arcsineField = new field
     {
        label = " Test asin";
        value = asin("0.5");
     }

    The result of asin in the above example would be "0.523599".
------

  7.2e   atan

   Description

    Returns the arc tangent of a number stored in <number>.

    An error occurs if <number> is not a valid number.

   Call

     atan(<number>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number


   Returns

    A string containing the arc tangent, or "" if an error occurs.

   Example

     arctangentField = new field
     {
        label = " Test atan";
        format = ["string", "mandatory"];
        value = atan("0.5");
     }

    The result of atan in the above example would be "0.463648".
------

  7.2f   ceiling

   Description


Universal Forms Description Language                          [page 188]


    Returns the ceiling of the number represented in <number>.

    An error occurs if <number> is not a valid number.

   Call

     ceiling(<number>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number


   Returns

    A string containing the ceiling of the number, or "" if an error
    occurs.

   Example

     ceilingTest = new field
     {
        label = "Test ceiling";
        format = ["string", "mandatory"];
        value = ceiling("-19.6");
     }

    The result of ceiling in the above example would be "-19".
------

  7.2g   compound

   Description

    Returns the compound interest factor at a rate indicated by <rate>
    over a number of periods specified in <periods>.

    You might use this to calculate the total amount of a loan, by
    multiplying an original principle by the result of compund. See
    below for an example.
    An error occurs if <periods> is not a valid integer.

   Call

     compound(<rate>, <periods>)

   Parameters

    Expression     Setting          Description
    <rate>         decimal number   the rate of interest in decimal
                                    form compounded each period
    <periods>      integer          the number of periods



Universal Forms Description Language                          [page 189]


   Returns

    A string containing the compound interest factor, or "" if an error
    occurs.

   Example

     totalAmountField = new field
     {
        label = "Total Amount of Loan";
        format = ["string", "mandatory"];
        value = principleField.value * compound(".1", "7");
     }

    The result of compound in the above example would be "1.948717".
    The value of the field would then be 1.948717 x the amount in the
    field called principleField.
------

  7.2h   cos

   Description

    Returns the cosine of an angle stored in <angle> and expressed
    in radians.

    An error occurs if <angle> does not contain a valid angle.

   Call

     cos(<angle>)

   Parameters

    Expression     Setting          Description
    <angle>        decimal number   the angle in radians


   Returns

    A string containing the cosine, or "" if an error occurs.

   Example

     cosineField = new field
     {
        label = " Test cos";
        format = ["string", "mandatory"];
        value = cos("2");
     }

    The result of cos in the above example would be "-0.416147".
------

  7.2i   deg2rad


Universal Forms Description Language                          [page 190]


   Description

    Returns the number of radians in an angle expressed in degrees
    stored in <angle>.

    An error occurs if <angle> does not contain a valid angle.

   Call

     deg2rad(<angle>)

   Parameters
    Expression     Setting          Description
    <angle>        decimal number   the angle in degrees


   Returns

    A string containing the number of radians, or "" if an error
    occurs.

   Example

     deg2radField = new field
     {
        label = " Test deg2rad";
        format = ["string", "mandatory"];
        value = deg2rad("114.591559");
     }

    The result of deg2rad in the above example would be "2.00000".
------

  7.2j   exp

   Description

    Returns the exponentiation of the number represented in <number>
    (i.e., e<number>).

    An error occurs if <number> is not a valid number.

   Call

     exp(<number>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number


   Returns

    A string containing the exponentiation of the number, or "" if an

Universal Forms Description Language                          [page 191]


    error occurs.

   Example

     expTest = new field
     {
        label = "Test exp";
        format = ["string", "mandatory"];
        value = exp("3");
     }

    The result of exp in the above example would be "1.098612".
------

  7.2k   fact

   Description

    Returns the factorial value of the integer represented in
    <integer>.

    An error occurs if <integer> is negative.

   Call

     fact(<number>)

   Parameters

    Expression     Setting          Description
    <integer>      integer          a non-negative integer


   Returns

    A string containing the factorial of the integer, or "" if an error
    occurs.

   Example
     factTest = new field
     {
        label = "Test fact";
        format = ["string", "mandatory"];
        value = fact("8");
     }

    The result of fact in the above example would be "40320".
------

  7.2l   floor

   Description

    Returns the floor of the number represented in <number>.


Universal Forms Description Language                          [page 192]


    An error occurs if <number> is not a valid number.

   Call

     floor(<number>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number


   Returns

    A string containing the floor of the number, or "" if an error
    occurs.

   Example

     floorTest = new field
     {
        label = "Test floor";
        format = ["string", "mandatory"];
        value = floor("-19.6");
     }

    The result of floor in the above example would be "-20".
------

  7.2m   ln

   Description

    Returns the natural logarithm of the number represented in
    <number>.

    An error occurs if <number> is not a decimal number greater
    than zero.

   Call

     ln(<number>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number


   Returns

    A string containing the natural log of the number, or "" if an
    error occurs.

   Example


Universal Forms Description Language                          [page 193]


     lnTest = new field
     {
        label = "Test ln";
        format = ["string", "mandatory"];
        value = ln("1");
     }

    The result of ln in the above example would be "0".
------
  7.2n   log

   Description

    Returns the logarithm of the number represented in <number> to the
    base indicated by <base>.  If <base> is empty or absent, then base
    10 is used.

    An error occurs if either of <number> or <base> is not a valid
    number, or <base> is negative.

   Call

    log(<number>)
    log(<number>, <base>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number
    <base>         decimal number   a number representing the base for
                                    which the logarithm will be
                                    computed

   Returns

    A string containing the log of the number to the base, or "" if an
    error occurs.

   Example

     logTest = new field
     {
        label = "Test log";
        format = ["string", "mandatory"];
        value = log("100", "10");
     }

    The result of log in the above example would be "2".
------

  7.2o   mod

   Description

    Returns the modulus of the number represented in <number> using the

Universal Forms Description Language                          [page 194]


    divisor indicated by <divisor>.

    An error occurs if either of <number> or <divisor> is not a valid
    number, or <divisor> is 0.

   Call

     mod(<number>, <divisor>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number
    <divisor>      decimal number   a number representing the divisor
                                    for which the modulus will be
                                    computed


   Returns

    A string containing the modulus, or "" if an error occurs.

   Example

     modTest = new field
     {
        label = "Test mod";
        format = ["string", "mandatory"];
        value = mod("-3.5", ".3");
     }

    The result of mod in the above example would be "-0.200000".
------

  7.2p   pi
   Description

    Returns the value of PI to the best available accuracy.

   Call

     pi()

   Parameters

    Expression     Setting          Description
    (none)


   Returns

    A string containing the value of PI.

   Example


Universal Forms Description Language                          [page 195]


     piTest = new field
     {
        label = "Test pi";
        format = ["string", "mandatory"];
        value = pi();
     }

    The result of pi in the above example would be "3.14159265359"
    (precision is machine-dependent).
------

  7.2q   power

   Description

    Returns the number represented in <number> raised to the power
    indicated by <power>.

    An error occurs if either of <number> or <power> is not a valid
    number.

   Call

     power(<number>, <power>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a number
    <power>        decimal number   a number representing the power
                                    by which the number will be
                                    raised


   Returns

    A string containing the number raised to the power, or "" if an
    error occurs.

   Example

     powerTest = new field
     {
        label = "Test power";
        format = ["string", "mandatory"];
        value = power("0.1", "-2");
     }

    The result of power in the above example would be "100.00000".
------

  7.2r   rad2deg

   Description

    Returns the number of degrees in an angle expressed in radians

Universal Forms Description Language                          [page 196]


    stored in <angle>.

    An error occurs if <angle> does not contain a valid angle.

   Call

     rad2deg(<angle>)

   Parameters
    Expression     Setting          Description
    <angle>        decimal number   the angle in radians


   Returns

    A string containing the number of degrees, or "" if an error
    occurs.

   Example

     rad2degField = new field
     {
        label = " Test rad2deg";
        format = ["string", "mandatory"];
        value = rad2deg("2");
     }

    The result of rad2deg in the above example would be "114.591559".
------

  7.2s   rand

   Description

    Returns a random integer from the range of integers indicated by
    <lowerlimit> and <upperlimit>. (The range includes <lowerlimit>
    and <upperlimit>).

    An error occurs if either of <lowerlimit> or <upperlimit> is not a
    valid integer, or <upperlimit> is less than <lowerlimit>.

   Call

     rand(<lowerlimit>, <upperlimit>)

   Parameters

    Expression     Setting          Description
    <lowerlimit>   integer          the lower limit of the random
                                    number's range
    <upperlimit>   integer          the upper limit of the random
                                    number's range


   Returns

Universal Forms Description Language                          [page 197]


    A string containing the random integer, or "" if an error occurs.

   Example

     randTest = new field
     {
        label = "Test rand";
        format = ["string", "mandatory"];
        value = rand("45", "90");
     }

    The result of rand in the above example would be an integer in the
    range [45,90].
------

  7.2t   round

   Description

    Returns the number represented in <number> rounded to the nearest
    decimal position indicated by <place> (e.g., 100, 10, 1, 0.1, ...).

    An error occurs if <number> is not a valid number or <place> is not
    a power of 10.

   Call

     round(<number>, <place>)

   Parameters

    Expression     Setting          Description
    <place>        decimal number   a number representing the decimal
                                    place where <number> is to be
                                    rounded


   Returns

    A string containing the rounded number, or "" if an error occurs.

   Example

     roundTest = new field
     {
        label = "Test round";
        format = ["string", "mandatory"];
        value = round("-323.235", ".01");
     }

    The result of round in the above example would be "-323.2400".
------

  7.2u   sin

Universal Forms Description Language                          [page 198]


   Description

    Returns the sine of an angle stored in <angle> and expressed in
    radians.

    An error occurs if <angle> does not contain a valid angle.

   Call

     sin(<angle>)

   Parameters

    Expression     Setting          Description
    <angle>        decimal number   the angle in radians

   Returns

    A string containing the sine, or "" if an error occurs.

   Example

     sineField = new field
     {
        label = " Test sin";
        format = ["string", "mandatory"];
        value = sin("2");
     }

    The result of sin in the above example would be "0.909297".
------

  7.2v   sqrt

   Description

    Returns the square root of the number represented in <number>.

    An error occurs if <number> is a negative number.

   Call

     sqrt(<number>)

   Parameters

    Expression     Setting          Description
    <number>       decimal number   a non-negative number

   Returns

    A string containing the square root, or "" if an error occurs.

   Example


Universal Forms Description Language                          [page 199]


     {
        label = "Test sqrt";
        format = ["string", "mandatory"];
        value = sqrt("19.5");
     }

    The result of sqrt in the above example would be "4.415880".
------

  7.2w   tan

   Description

    Returns the tangent of an angle expressed in radians stored in
    <angle>.

    An error occurs if <angle> does not contain a valid angle (for
    example, (/2, 3(/2, 5(/2, and so on).

   Call

     tan(<angle>)

   Parameters

    Expression     Setting          Description
    <angle>        decimal number   the angle in radians


   Returns

    A string containing the tangent, or "" if an error occurs.

   Example

     tanField = new field
     {
        label = " Test tan";
        format = ["string", "mandatory"];
        value = tan("2");
     }

    The result of tan in the above example would be "-2.185040".
------

 7.3   Utility Functions

  7.3a   applicationName

   Description

    Returns the name of the currently running application.

   Call


Universal Forms Description Language                          [page 200]


     applicationName()

   Parameters

    Expression     Setting          Description
    (none)

   Returns

    A string containing the application name.

   Example

     anTest = new field
     {
        label = "Test applicationName";
        value = applicationName();
     }

    The result of applicationName in the above example, if the form
    were running in an application named "Viewer", would be "Viewer".
------

  7.3b   applicationVersion

   Description

    Returns the version of the currently running application in the
    format "MM.mm.TT".

   Call

     applicationVersion()

   Parameters

    Expression     Setting          Description
    (none)

   Returns

    A string containing the application version.

   Example

     avTest = new field
     {
        label = "Test applicationVersion";
        format = ["string", "mandatory"];
        value = applicationVersion();
     }

    The result of applicationVersion in the above example, if running
    in an application at version 3.2.4, would be "03.02.04".
------

Universal Forms Description Language                          [page 201]


  7.3c   applicationVersionNum

   Description

    Returns the decimal form of the version of the currently running
    application.  This number is obtained from the hexadecimal format
    0xMMmmTTPP, where MM is the Major version number, mm is the minor
    version number, TT is the maintenance number, and PP is the patch
    number.  At this point, individual patches are not recognized in
    version numbers and so will always be 0.

   Call

     applicationVersionNum()

   Parameters

    Expression     Setting          Description
    (none)

   Returns

    A string containing the application version number.

   Example

     avnTest = new field
     {
        label = "Test applicationVersionNum";
        format = ["string", "mandatory"];
        value = applicationVersionNum();
     }

    The result of applicationVersionNum in the above example, if
    running in an application at version v3.2.4, would be "50463744",
    which is the decimal representation of 0x03020400.
------

  7.3d   decimal

   Description

    Returns the decimal representation of the number represented by
    <number> with base indicated by <base>.

    An error occurs if <number> is not a valid number, if <base> is
    not a valid positive integer base, or <number> cannot be resolved
    under the specified <base>.

   Call

     decimal(<number>, <base>)
   Parameters


Universal Forms Description Language                          [page 202]


    Expression     Setting          Description
    <number>       number           a number
    <base>         positive integer an integer that is the base of
                                    the provided number


   Returns

    A string containing the decimal representation of the number,
    or "" if an error occurs.

   Example

     decimalTest = new field
     {
        label = "Test decimal";
        format = ["string", "mandatory"];
        value = decimal("-4a", "16");
     }

    The result of decimal in the above example would be "-74".
------

  7.3e   formatString

   Description

    Returns a string <string> formatted according to the rules set out
    in the referenced format option <formatOptionReference>.

    An error occurs if an invalid format is specified.

   Call

     formatString(<string>, <itemtagOfFormat>)

   Parameters

    Expression              Setting          Description
    <string>                a string         a string to format
                                             according to the
                                             referenced option
    <formatOptionReference> an option        the option reference of
                            reference,       the format line to use
                            including the    when in formatting the
                            page tag, if     string
                            necessary


   Returns

    The formatted string.

   Example
     Field1 = new field
     {

Universal Forms Description Language                          [page 203]


        label = "Field 1";
        format = ["dollar", "add_ds", "comma_delimit"];
        value = "";
     }
     Field2 = new field
     {
        label = "Field 2";
        format = ["string", "mandatory"];
        value = formatString(Field3.value, "Field1.format");
     }
     Field3 = new field
     {
        label = "Field 3";
     ]

    The result of formatString in Field2 would be $30,095.60.

     //Example 2
     Field4 = new field
     {
        value = "$1.00";
        format = ["dollar"];
        backend_value = formatString(value,"backend_format");
        backend_format = ["integer"];
        }

    In the example above, formatString is used to reformat a value as
    an integer and insert it into a custom option (presumably for a
    back-end application to use).
------

  7.3f   isValidFormat

   Description

    Returns the boolean result of whether a string <string> is valid
    according to the setting of the format option referred to in
    <formatOptionReference>.

    An error occurs if a non-existent format is specified.

   Call

     isValidFormat(<string>, <formatOptionReference>)

   Parameters

    Expression              Setting         Description
    <string>                a string        a string to be checked
                                            against the format
    <formatOptionReference> an option       the option reference of the
                            reference,      format to check the string
                            including the   against
                            page tag, if
                            necessary

Universal Forms Description Language                          [page 204]


   Returns

    "1" if the string follows the format, "0" if not, or "" if an
    error occurs.

   Example

     Field1 = new field
     {
        label = "Test isValidFormat1";
        format = ["integer", "mandatory"];
        value = "45";
     }
     Field2 = new field
     {
        label = "Test isValidFormat2";
        format = ["string", "mandatory"];
        value = isValidFormat("23.2", "Field1.format");
     }

    The result of isValidFormat in the above example would be "0"
    because the string to check contains a non-integer number
    representation and the specified format to check is of type
    integer.
------

  7.3g   set

   Description

    Sets the value of a form option described by <reference> to the
    value described by <value> and returns an indication of the success
    of the operation. The option will be created if it does not exist.
    If a compute existed on the option, it will be destroyed. Items
    and pages will not be created.

    An error occurs if the specified form option could not be set to
    the specified value.

   Call

     set(<reference>, <value>)

   Parameters

    <reference>    form option      an adequately qualified reference
                   reference        to a form option
    <value>        form value       a string containing the option's
                                    new value


   Returns


Universal Forms Description Language                          [page 205]


    "1" if the operation completed successfully, "0" if an error
    occurred.

   Example

     field1 = new field
     {
        label = "Test set 1";
        format = ["string", "mandatory"];
        value = "gold";
     }
     field2 = new field
     {
        label = "Test set 2";
        format = ["string", "mandatory"];
        value = set("field1.value", "silver");
     }

    The result of set in the above example would be "1" and the value
    of field1 would be set to "silver".
------

  7.3h   toggle


   Description

    Detects transitions in a form option specified by <reference>, and
    returns a result. If toggle contains just a <reference> parameter,
    then toggle returns "1" every time the referenced setting changes.
    If toggle contains the <reference> parameter and the <from> and
    <to> parameters, then toggle returns "1" when the setting changes
    from the from state to the to state, and "0" at other times.

    An error occurs if the specified form option does not exist.

   Call

     toggle(<reference>)
     toggle(<reference>, <from>, <to>)

   Parameters

    Expression     Setting          Description
    <reference>    form option      an adequately qualified reference
                   reference        to a form option
    <from>         form value       a string containing a possible
                                    option value
    <to>           form value       a string containing a possible
                                    option value


   Returns

    "1" if the specified change occurs in the specified option, or "0"
    if another change occurs.

Universal Forms Description Language                          [page 206]


   Example

     timeStampField = new field
     {
        value = toggle(nameField.value)=="1"?now():"";
        label = "Time Stamp";
        editstate = "readonly";
     }

     nameField = new field
     {
        value = "";
     }

    In the example above, toggle has just a <reference> parameter.
    Every time the nameField's value changes, toggle will return "1",
    and then a new time will be entered into timeStampField, using
    the now function.

     noChoiceAllowed = new check
     {
        label = "Simple Application - No Choices";
        value = "off";
        logic_1 = toggle(noChoiceAllowed.value, "off", "on")
                        == "1" ? set("option1.value", "off") +
                        set("option2.value", "off") +
                        set("option3.value", "off") : "";
     }

    In the example above, toggle is used to change form behavior based
    on whether the noChoiceAllowed check box is checked. When the
    check's value changes from off to on, toggle will return a "1".
    That will trigger the decision set up in the logic_1 option - thus
    the items called option1, option2, and option3 will become
    deselected (their values will be off). Normally, you would also set
    their active options to be off, but to save room, this example
    omits that step.
------

 7.4   Time and Date Functions

  7.4a   date

   Description

    Returns the current date in "yyyymmdd" format.

   Call

     date()

   Parameters

    Expression     Setting          Description

Universal Forms Description Language                          [page 207]


    (none)

   Returns

    A string containing the current date.

   Example

     dateTest = new field
     {
        label = "Test date";
        format = ["string", "mandatory"];
        value = date();
     }

    The result of date in the above example, if run on January 18th,
    1998, would be "19980118".
------

  7.4b   dateToSeconds

   Description

    Returns the number of seconds from the GMT date and time
    represented in <date> and <time> respectively since 00:00:00 GMT,
    January 1st, 1970.

    An error occurs if either of <date> or <time> is not well-formed.

   Call

     dateToSeconds(<date>, <time>)

   Parameters

    Expression     Setting          Description
    <time>         time string      a time in a recognized format


   Returns

    A string containing the number of seconds, or "" if an error
    occurs.

   Example

     dtsTest = new field
     {
        label = "Test dts";
        format = ["string", "mandatory"];
        value = dateToSeconds("980319", "09:39:16");
     }

    The result of dateToSeconds in the above example would be
    "89030056"

Universal Forms Description Language                          [page 208]


------

  7.4c   day

   Description

    Returns the numeric day of the month for the provided date in
    <dateSecs> or the current date if one is not provided.  The
    provided date is a string representing the number of seconds
    since 00:00:00 GMT, January 1st, 1970.

    An error occurs if <dateSecs> is not well-formed.

   Call

     day(<dateSecs>|"")

   Parameters

    Expression     Setting          Description
    <dateSecs>     number           a date represented by the number
                                    of seconds since 00:00:00 GMT,
                                    January 1st, 1970


   Returns

    A string containing the day, or "" if an error occurs.

   Example

     dayTest = new field
     {
        label = "Test day";
        format = ["string", "mandatory"];
        value = day("890300356");
     }

    The result of day in the above example would be "19".
------

  7.4d   dayOfWeek

   Description

    Returns the numeric day of the week (Sunday=1, etc.) for the
    provided date in <dateSecs> or the current date if one is not
    provided.  The provided date is a string representing the number of
    seconds since 00:00:00 GMT, January 1st, 1970.

    An error occurs if <dateSecs> is not well-formed.

   Call

     dayOfWeek(<dateSecs>|"")


Universal Forms Description Language                          [page 209]


   Parameters

    Expression     Setting          Description
    <dateSecs>     number           a date represented by the number of
                                    seconds since 00:00:00 GMT,
                                    January 1st, 1970


   Returns

    A string containing the day of the week, or "" if an error occurs.

   Example

     {
        label = "Test dayOfWeek";
        format = ["string", "mandatory"];
        value = dayOfWeek("890300356");
     }

    The result of dayOfWeek in the above example would be "5".
------

  7.4e   endOfMonth

   Description

    Returns the number of seconds since 00:00:00 GMT, January 1st, 1970
    to the current time on the last day of the month in the date
    provided in <dateSecs> or the current date if one is not provided.
    The provided date is a string representing the number of seconds
    since 00:00:00 GMT, January 1st, 1970.

    An error occurs if <dateSecs> is not well-formed.

   Call

     endOfMonth(<dateSecs>|"")

   Parameters

    Expression     Setting          Description
    <dateSecs>     number           a date represented by the number of
                                    seconds since 00:00:00 GMT,
                                    January 1st, 1970


   Returns

    A string containing the number of seconds, or "" if an error
    occurs.

   Example

     eomTest = new field

Universal Forms Description Language                          [page 210]


     {
        label = "Test endOfMonth";
        format = ["string", "mandatory"];
        value = endOfMonth("890300356");
     }

    The result of endOfMonth in the above example would be "891337156".
------

  7.4f   hour

   Description

    Returns the numeric hour for the provided date in <dateSecs> or the
    current date if one is not provided. The provided date is a string
    representing the number of seconds since 00:00:00 GMT, January 1st,
    1970.

    An error occurs if <dateSecs> is not well-formed.

   Call

     hour(<dateSecs>|"")

   Parameters

    Expression     Setting          Description
    <dateSecs>     number           a date represented by the number of
                                    seconds since 00:00:00 GMT, January
                                    1st, 1970


   Returns

    A string containing the hour, or "" if an error occurs.

   Example

     hourTest = new field
     {
        label = "Test hour";
        format = ["string", "mandatory"];
        value = hour("890300356");
     }

    The result of hour in the above example would be "9".
------

  7.4g   minute
   Description

    Returns the numeric minute for the provided date in <dateSecs> or
    the current date if one is not provided.  The provided date is a
    string representing the number of seconds since 00:00:00 GMT,
    January 1st, 1970.

Universal Forms Description Language                          [page 211]


    An error occurs if <dateSecs> is not well-formed.

   Call

     minute(<dateSecs>|"")

   Parameters

    Expression     Setting          Description
    <dateSecs>     number           a date represented by the number of
                                    seconds since 00:00:00 GMT, January
                                    1st, 1970


   Returns

    A string containing the minute, or "" if an error occurs.

   Example

     minuteTest = new field
     {
        label = "Test minute";
        format = ["string", "mandatory"];
        value = minute("890300356");
     }

    The result of minute in the above example would be "39".
------

  7.4h   month

   Description

    Returns the numeric month of the year for the provided date in
    <dateSecs> or the current date if one is not provided.  The
    provided date is a string representing the number of seconds since
    00:00:00 GMT, January 1st, 1970.

    An error occurs if <dateSecs> is not well-formed.

   Call

     month(<dateSecs>|"")

   Parameters

    Expression     Setting          Description
    <dateSecs>     number           a date represented by the number of
                                    seconds since 00:00:00 GMT, January
                                    1st, 1970

   Returns

    A string containing the month, or "" if an error occurs.

Universal Forms Description Language                          [page 212]


   Example

     monthTest = new field
     {
        label = "Test month";
        format = ["string", "mandatory"];
        value = month("890300356");
     }

    The result of month in the above example would be "3".
------

  7.4i   now

   Description

    Returns the number of seconds since 00:00:00 GMT, January 1st,
    1970.

   Call

     now()

   Parameters

    (none)

   Returns

    A string containing the number of seconds.

   Example

     nowTest = new field
     {
        label = "Test now";
        format = ["string", "mandatory"];
        value = now();
     }

    The result of now in the above example, if run at 09:39:16 GMT on
    Thursday, March 19th, 1998 would be "890300356".
------

  7.4j   second

   Description

    Returns the numeric second for the provided date in <dateSecs> or
    the current date if one is not provided.  The provided date is a
    string representing the number of seconds since 00:00:00 GMT,
    January 1st, 1970.

    An error occurs if <dateSecs> is not well-formed.

Universal Forms Description Language                          [page 213]


   Call

     second(<dateSecs>|"")

   Parameters

    Expression     Setting          Description
    <dateSecs>     number           a date represented by the number
                                    of seconds since 00:00:00 GMT,
                                    January 1st, 1970


   Returns

    A string containing the second, or "" if an error occurs.

   Example

     secondTest = new field
     {
        label = "Test second";
        format = ["string", "mandatory"];
        value = second("890300356");
     }

    The result of second in the above example would be "16".
------

  7.4k   time

   Description

    Returns the current time in "hh:mm:AM" format.

   Call

     time()

   Parameters

    Expression     Setting          Description
    (none)

   Returns

    A string containing the current time.

   Example

     timeTest = new field
     {
        format = ["string", "mandatory"];
        value = time();
     }

Universal Forms Description Language                          [page 214]


    The result of time in the above example, if run at 3:22 in the
    afternoon, would be "3:22:PM".
------

  7.4l   year

   Description

    Returns the numeric year for the provided date in <dateSecs> or the
    current date if one is not provided.  The provided date is a string
    representing the number of seconds since 00:00:00 GMT, January 1st,
    1970.

    An error occurs if <dateSecs> is not well-formed.

   Call

     year(<dateSecs>|"")

   Parameters

    Expression     Setting          Description
    <dateSecs>     number           a date represented by the number of
                                    seconds since 00:00:00 GMT, January
                                    1st, 1970


   Returns

    A string containing the year, or "" if an error occurs.

   Example

     yearTest = new field
     {
        label = "Test year";
        format = ["string", "mandatory"];
        value = year("890300356");
     }

    The result of year in the above example would be "1998".
------


Appendix A: Quick Reference Tables

  A.1   Table of Items and Form and Page Characteristics

    Item           Available Options

    action         activated; active; data; datagroup; delay;
                   transmitdatagroups; transmitformat; transmitgroups;
                   transmititemrefs; transmititems; transmitoptionrefs;
                   transmitoptions; type; url


Universal Forms Description Language                          [page 215]


    box            bgcolor; bordercolor; borderwidth; fontinfo;
                   itemlocation; size

    button         activated; active; bgcolor; bordercolor;
                   borderwidth; coordinates; data; datagroup;
                   editstate; focused; fontcolor; fontinfo; format;
                   help; image; itemlocation; justify; mouseover; next;
                   previous; saveformat; signature; signdatagroups;
                   signer; signformat; signgroups; signitemrefs;
                   signitems; signoptionrefs; signoptions; size;
                   transmitdatagroups; transmitformat; transmitgroups;
                   transmititemrefs; transmititems;
                   transmitoptionrefs; transmitoptions; type; url;
                   value

    cell           activated; active; data; datagroup; editstate;
                   group; saveformat; transmitdatagroups;
                   transmitformat; transmitgroups; transmititemrefs;
                   transmititems; transmitoptionrefs; transmitoptions;
                   type; url; value

    check          active; bgcolor; bordercolor; editstate; focused;
                   fontcolor; fontinfo; help; itemlocation; label;
                   labelbgcolor; labelbordercolor; labelborderwidth;
                   labelfontcolor; labelfontinfo; mouseover; next;
                   previous; size; value

    combobox       activated; active; bgcolor; bordercolor;
                   borderwidth; editstate; focused; fontcolor;
                   fontinfo; format; group; help; itemlocation; label;
                   labelbgcolor; labelbordercolor; labelborderwidth;
                   labelfontcolor; labelfontinfo; mouseover; next;
                   previous; size; value

    data           datagroup; filename; mimedata; mimetype

    field          active; bgcolor; bordercolor; borderwidth;
                   editstate; focused; fontcolor; fontinfo; format;
                   help; itemlocation; justify; label; labelbgcolor;
                   labelbordercolor; labelborderwidth; labelfontcolor;
                   labelfontinfo; mouseover; next; previous;
                   scrollhoriz; scrollvert; size; value

    help           active; value

    label          active; bgcolor; bordercolor; borderwidth;
                   fontcolor; fontinfo; help; image; itemlocation;
                   justify; size; value

    line           fontcolor; fontinfo; itemlocation; size; thickness
    list           active; bgcolor; bordercolor; borderwidth;
                   editstate; focused; fontcolor; fontinfo; group;
                   help; itemlocation; label; labelbgcolor;
                   labelbordercolor; labelborderwidth; labelfontcolor;
                   labelfontinfo; mouseover; next; previous; size;

Universal Forms Description Language                          [page 216]


                   value

    popup          activated; active; bgcolor; bordercolor;
                   borderwidth; editstate; focused; fontcolor;
                   fontinfo; group; help; itemlocation; justify; label;
                   mouseover; next; previous; size; value

    radio          active; bgcolor; bordercolor; editstate; focused;
                   fontcolor; fontinfo; group; help; itemlocation;
                   label; labelbgcolor; labelbordercolor;
                   labelborderwidth; labelfontcolor; labelfontinfo;
                   mouseover; next; previous; size; value

    signature      mimedata, signature, signdatagroups, signer,
                   signformat, signitems, signgroups, signoptions,
                   signoptionrefs

    spacer         fontinfo; itemlocation; label; size

    tablet         active; bgcolor; bordercolor; borderwidth;
                   fontcolor; help; image; itemlocation; justify;
                   mouseover; size; value

    toolbar        bgcolor; mouseover

    page globals   activated; bgcolor; bordercolor; borderwidth;
                   focused; fontcolor; fontinfo; label; mouseover; next

    form globals   activated; bgcolor; bordercolor; borderwidth;
                   focused; fontcolor; fontinfo; label; next;
                   saveformat; transmitformat; triggeritem; version
------

  A.2   Table of Options

    Option         Details

    activated      Syntax: activated = "on" | "maybe" | "off";
                   Default:off
                   Items:  action; button; cell; combobox; popup; page
                           global; form global

    active         Syntax: active = "on" | "off";
                   Default:on
                   Items:  action; button; cell; check; combobox;
                           field; help; label; list; popup; radio;
                           tablet. To prevent user input in a field,
                           use the editstate "readonly".

    bgcolor        Syntax: bgcolor = ["<color name>"];
                           bgcolor = ["<R value>","<G value>",
                                      "<B value>"];
                   Default:for button - "gray"
                           for check, field, list, popup, radio -
                           "white" all other items - the background #
                           color of the form

Universal Forms Description Language                          [page 217]


                   Items:  box; button; check; combobox; field; label;
                           list; popup; radio; tablet; toolbar; page
                           characteristics; form characteristics

    bordercolor    Syntax: bordercolor = ["<color name>"];
                           bordercolor = ["<R value>","<G value>",
                                          "<B value>"];
                   Default:the bordercolor set in the global
                           characteristics, or "black" if no
                           characteristics set
                   Items:  box; button; check; combobox; field; label;
                           list; popup; radio; tablet; page
                           characteristics; form characteristics

    borderwidth    Syntax: borderwidth = "<width>";
                   Default:for label - 0
                           for all other items - the borderwidth set
                           in characteristics, or 1 if no
                           characteristics set
                   Items:  box; button; combobox; field; label; list;
                           popup; tablet; page characteristics; form
                           characteristics

    coordinates    Syntax: coordinates = ["<X_coordinate>",
                           "<Y_coordinate>"];
                   Default:none
                   Items:  button

    data           Syntax: data = "<data_item>";
                   Default:none
                   Items:  action; button; cell
    datagroup      Syntax: datagroup = ["<datagroup_reference>",
                           "<datagroup reference>"...];
                   Default:none
                   Items:  action; button; cell; data

    delay          Syntax: delay = ["repeat" | "once","interval"];
                   Default:once with an interval of 0 seconds
                   Items:  action

    editstate      Syntax: editstate = "readonly | writeonly |
                           readwrite";
                   Default:readwrite
                   Items:  button; cell; check; combobox; field; list;
                           popup; radio

    filename       Syntax: filename = "<file name>";
                   Default:None
                   Items:  data

    focused        Syntax: focused = "on" | "off";
                   Default:off
                   Items:  button; check; combo; field; list; popup;
                           radio; page global; form global


Universal Forms Description Language                          [page 218]


    fontcolor      Syntax: fontcolor = ["<color name>"];
                           fontcolor = ["<R value>","<G value>",
                           "<B value>"];
                   Default:for check and radio - red
                           for all other items, the fontcolor set in
                           global characteristics, or "black" if no
                           preference set
                   Items:  button; check; combobox; field; label; line;
                           list; popup; radio; tablet; page
                           characteristics; form characteristics

    fontinfo       Syntax: fontinfo = ["<font name>","<point size>",
                           "<weight>","<effects>","<form>"];
                           * weight, effects, and form are optional
                   Default:the fontinfo set in global characteristics,
                           or "Helvetica 8 plain" if no characteristics
                           set
                   Items:  box; button; check; combobox; field; label;
                           line; list; popup; radio; spacer; tablet;
                           page characteristics; form characteristics

    format         Syntax: format = [<data type>,<format flag>,
                           <check flag>];
                           * format and check flags are optional, and
                             multiple flags are valid
                   Default:for data type - none
                           for format flag - depends on data type
                           for check option - depends on data type
                   Items:  button; combobox; field; label; list; popup

    group          Syntax: group = "<group name | group reference>";
                   Default:none
                   Items:  cell; combobox; list; popup; radio

    help           Syntax: help = "<item reference>";
                   Default:none
                   Items:  button; check; combobox; field; label; list;
                           popup; radio; tablet

    image          Syntax: image = "<item reference>";
                   Default:none
                   Items:  button; label; tablet

    itemlocation   Syntax: itemlocation = [[<specification>],
                           [<specification>]...];<specification> =
                           "<modifier>","<itemtag>","<itemtag>"
                           * the second itemtag only to align between
                             modifiers
                   Default:for the first item - the top left corner of
                           the form
                           for all other items - vertically below the
                           previously created item and horizontally at
                           the left margin
                   Items:  box; button; check; combobox; field; label;
                           line; list; popup; radio; spacer; tablet
    justify        Syntax: justify = "<left | right | center>";
                   Default:for button and popup - center
                           for label - left
                   Items:  button; field; label; popup; tablet

    label          Syntax: label = "<label text>";
                   Default:none
                   Items:  check; combobox; field; list; popup; radio;
                           spacer; page characteristics; form
                           characteristics

    labelbgcolor   Syntax: labelbgcolor = ["<color name>"];
                           labelbgcolor = ["<R value>","<G value>",
                           "<B value>"];
                   Default:for items in the toolbar - the background
                           color of the toolbar
                           for other items - the background color of
                           the form
                   Items:  check; combobox; field; list; radio

    labelbordercolorSyntax:labelbordercolor = ["<color name>"];
                           labelbordercolor = ["<R value>","<G value>",
                           "<B value>"];
                   Default:black
                   Items:  check; combobox; field; list; radio

    labelborderwidthSyntax:labelborderwidth = "<width>";
                   Default:0 pixels
                   Items:  check; combobox; field; list; radio

    labelfontcolor Syntax: labelfontcolor = ["<color name>"];
                           labelfontcolor = ["<R value>","<G value>",
                           "<B value>"];
                   Default:black
                   Items:  check; combobox; field; list; radio; page
                           characteristics; form characteristics

    labelfontinfo  Syntax: labelfontinfo = ["<font name>",
                           "<point size>","<weight>","<effects>",
                           "<form>"];
                           * weight, effects, and form are optional
                   Default:Helvetica, 8 plain
                   Items:  check; combobox; field; list; radio

    mimedata       Syntax: mimedata = "<data>";
                   Default:none
                   Items:  button, data, signature

    mouseover      Syntax: mouseover = "on" | "off";
                   Default:off
                   Items:  button; check; combo; field; list; popup;
                   radio; tablet; toolbar; page global

    next           Syntax: next = "<item reference>";
                   Default:when the form opens - the first non-toolbar
                           item in the form's description that users

Universal Forms Description Language                          [page 220]


                           can modify
                           when tabbing to subsequent items - the next
                           item in the form's description that users
                           can modify
                           when tabbing from the last item - the first
                           item in the form's description that users
                           can modify (can be a toolbar item)
                   Items:  button; combobox; check; field; list; popup;
                           radio; page globals; form globals

    previous       Syntax: previous = "<item_reference>";
                   Default:the previous item in the form description
                   Items:  button; combobox; check; field; list; popup;
                           radio;

    printsettings  Syntax: printsettings = [<page list>,
                           <dialog settings>];
                   Default:the page list defaults to include all pages
                           in the form the dialog defaults to "on", has
                           the following settings:
                           orientation = portrait
                           copies = 1
                           printpages active = on
                   Items:  action, button, cell, page global
                           characteristics, form global characteristics

    saveformat     Syntax: saveformat = "<mimetype>";
                   Default:application/uwi_form
                   Items:  button; cell; form characteristics

    scrollhoriz    Syntax: scrollhoriz = "<never | always | wordwrap>";
                   Default:never

    scrollvert     Syntax: scrollvert = "<never | always | fixed>";
                   Default:never
                   Items:  field

    signature      Syntax: signature = "<string>";
                   Default:none
                   Items:button, signature

    signdatagroups Syntax: signdatagroups = ["<keep | omit>",
                           "<datagroup reference>","<datagroup
                           reference>"...];
                   Default:keep
                   Items:  button, signature

    signer         Syntax: signer= "<string>";
                   Default:depends on where signature is from
                   Items:  button, signature

    signformat     Syntax: signformat = "<MIME type>";
                   Default:application/uwi_form
                   Items:  button, signature


Universal Forms Description Language                          [page 221]


    signgroups     Syntax: signgroups = ["<keep | omit>","<group
                           reference>","<group reference>"...];
                   Default:keep
                   Items:  button, signature

    signitems      Syntax: signitems = ["<keep | omit>", "<item type>",
                           "<item type>"...];
                   Default:keep
                   Items:  button, signature

    signitemrefs   Syntax: signitemrefs = ["<keep | omit>", "<item
                           reference>","<item reference>"...];
                   Default:keep
                   Items:  button, signature

    signoptionrefs Syntax: signoptionrefs = transmitoptions = ["<keep
                           | omit>","<option reference>","<option
                           reference>"...];
                   Default:keep
                   Items:  button, signature

    signoptions    Syntax: signoptions = ["<keep | omit>","<option
                           type>","<option type>"...];
                   Default:keep
                   Items:  button, signature

    size           Syntax: size = ["<width>","<height>"];
                           The unit of measurement is characters.
                   Default:see below (defaults are also used in place
                           of invalid and missing arguments)

         Items       Width        Height      Default bounding box size

         box         1            1           same as item
         (smaller than one not allowed in either dimension)

         button
         (with text) label width  label height same as item
         (with image)image width  image height same as item

         check       1            1           max (1, label width)
                                              x  label height  + 1

         combobox    max of       1           same as item
                    (label width,
                    widest cell)

         field       60           1           max (field width, label
                                              width)x field height +
                                              label height

         label
         (label empty)1           1           same as item
         (label given)label width label heightsame as item


Universal Forms Description Language                          [page 222]


         line         1           1 pixel     same as item
         (one dimension must be 0)


         list         max of       number of  same as item
                      (label       cells, +1
                      width,       if label
                      widest
                      cell)

         popup        max of      1           same as item
                    (label width,
                    widest cell)

         radio        1           1           max (radio width, label
                                              width)x radio height +
                                              label height

         spacer
         (no label)   1           1           same as item
         (label given)label width label heightsame as item

         tablet
         (no image)   1           1           same as item
         (image)      image width image heightsame as item


    thickness      Syntax: thickness = "<thickness>";
                   Default:1 pixel
                   Items:  line
    transmitdatagroupsSyntax:transmitdatagroups = [<transmit flag>,
                             <datagroup identifier>, ...
                   Default:keep
                   Items:  action; button; cell

    transmitformat Syntax: transmitformat = "<MIME type>";
                   Default:application/uwi_form
                   Items:  action; button; cell; form characteristics

    transmitgroups Syntax: transmitgroups = [<transmit flag>, <group
                           identifier>,...<group identifier>];
                   Default:keep
                   Items:  action; button; cell

    transmititemrefsSyntax:transmititemrefs = [<transmit flag>, <item
                           identifier>,...<item identifier>];
                   Default:keep
                   Items:  action; button; cell

    transmititems  Syntax: transmititems = ["<keep | omit>", "<item
                           type>","<item type>"...];
                   Default:keep
                   Items:  action; button; cell

    transmitoptionrefsSyntax:transmitoptionrefs = [<transmit flag>,

Universal Forms Description Language                          [page 223]


                             <option identifier>,...<option
                             identifier>];
                   Default:keep
                   Items:  action; button; cell

    transmitoptionsSyntax: transmitoptions = ["<keep | omit>","<option
                           type>","<option type>"...];
                   Default:keep
                   Items:  action; button; cell

    triggeritem    Syntax: triggeritem = "<item reference>";
                   Default:the item reference of the item that
                           triggered the "submit" or "done"
                   Items:  in form global characteristics

    type           Syntax: type = "<task type>";
                   Default:link
                   Items:  action; button; cell

    url            Syntax: url = ["<URL | item reference>",
                           ["<URL>"],...];
                   Default:none
                   Items:  action; button; cell

    value          Syntax: value = "<setting>";
                   Default:depends on item
                   Items:  button; cell; check; combobox; field; help;
                           label; list; popup; radio; tablet

    version        Syntax: version = <version number>;
                   Default:none
                   Items:in form global characteristics
------


Appendix B: Default Sizes

    The following table shows the default basic item and bounding box
    sizes.


    box            width:1 character        Same as default item size
                   height:1 character
                   Smaller than 1 not
                   allowed in either
                   dimension

    button         width:width of label     same as default item size
                   height:height of label
                   (label is in the value
                   option)
                   or size of embedded image
                   if it exists

    check          width:1 character        width:larger of 1 character

Universal Forms Description Language                          [page 224]


                   height:1 character             and label width
                                            height:label height plus
                                                   1 character
                                            (label is in the label
                                             option)

    combobox       width:larger of label    Same as default item size
                         width and widest   (ii)
                         cell (iii)
                   height:1 character
                   (label is in the label
                    option)

    field          width:30 characters      width:larger of item width
                   height:1 character             and label width (ii)
                                            height:height of item plus
                                                   height of label (ii)
                                            (label is in the label
                                             option)

    label          width:1 character if     Same as default item size
                         label empty,
                         otherwise label
                         width
                   height:1 character if
                          label empty,
                          otherwise label
                          height
                   or size of embedded image
                   if it exists

    line           width:30 character       Same as default item size
                   height:1 pixel
                   One dimension must be 0
                   (i)

    list           width:larger of label    width:larger of item width
                         width and widest         and widest cell (ii)
                         cell (iii)         height:height of item plus
                   height:number of cells          height of label
                          in list           (label is in the label
                   (label is in the label    option)
    popup          width:larger of label    Same as default item size
                         width and widest   (ii)
                         cell (iii)
                   height:1 character
                   (label is in the label
                    option)


    radio          width:1 character        width:larger of 1 character
                   height:1 character             and label width
                                            height:label height plus
                                                   1 character
                                            (label is in the label

Universal Forms Description Language                          [page 225]


                                             option)

    spacer          width:1 character if    Same as default item size
                         label empty,
                         otherwise label
                         width
                   height:1 character if
                          label empty,
                          otherwise label
                          height
                   (label is in the label
                    option)

    tablet         width:1 character if     Same as default item size
                         tablet empty,
                         otherwise value
                         width
                   height:1 character if
                          label empty,
                          otherwise value
                          height
                   or size of embedded image
                   if it exists


   Notes

    i) For line items, either height or width must be set to zero. The
       thickness option specifies the thickness (in pixels) of the line
       in the dimension containing zero (0). If both settings are
       non-zero, the line size will default to one character wide by
       one pixel thick.

    ii) This includes a scroll bar if one appears.

    iii) The cell's width comes from the cell's value option setting.
------


Appendix C: UFDL for C and C++ Programmers

    This document is intended to introduce programmers to the syntax
    of UFDL. To do so, we will compare UFDL to the C programming
    language, and point out many of the similarities in syntax and
    structure that exist between the two languages, as well as some of
    the differences.

    Be aware that this document outlines one way of modelling these
    similarities and differences, and that a number of other approaches
    could be used.
------

  C.1   Procedural vs. State Language

    Unlike C, UFDL is a state language. Where C describes a procedure
    that is followed, UFDL describes a state that is maintained. All of

Universal Forms Description Language                          [page 226]


    the statements in a UFDL form are always maintained as being true.

    As a result, computations are constantly updated throughout the
    form. For instance, imagine a form with a field called total, the
    value of which is based on adding the values of five other fields.
    Whenever a value is entered (or changed) in one of those five
    fields, the total field will be instantly updated to reflect that
    change. In this, UFDL acts much like a spreadsheet.
------

  C.2   Globals and Functions (Pages)

    When coding a form, the first statements define the global
    characteristics and includes. These are much like global variables
    and includes in C. The next thing defined is the first page of the
    form, which parallels a function in a C program. The table below
    demonstrates these similarities:

         C                      UFDL

     int version=3;             version="3.2.0";
     char *bgColor="blue";      bgcolor=["blue"];

     #include "header.h"        #include "header.frm"

     void page_1()              page_1=new page
     <code>                     <code>
     }                          }


    Notice the similarities in syntax as well. Statements are ended
    with a semi-colon. New pages (or functions) do not end with a
    semi-colon, and the code for each begins and ends with braces.

    Within each page, UFDL allows the definition of page-specific
    characteristics similar to function specific variables. You can
    also define items, which can be thought of as instances of
    predefined structures or cases. Within each instance, there are a
    number of options that can be set. The following table illustrates
    this:

         C                                       UFDL

         struct label{
          char *value;
          char *fontcolor;
          char *bgcolor;
          };

         void page_1()
         {                                      page_1=new page
         struct label *label_1=NULL;            {
         char *bgcolor = "papayawhip";          bgcolor=["papayawhip"];

          label_1=(struct label*)malloc

Universal Forms Description Language                          [page 227]


          (sizeof(struct label));                   label 1_1=new label
          label_1->value=strdup("This is a label"); {
          label_1->fontcolor=strdup("white");  value="This is a label";
          label_1->transmit=strdup("none");    fontcolor=["white"];
          label_1->bgcolor=strdup(bgcolor);    transmit="none";
         }                                     }

    In this example, value and fontcolor are options for the item
    label_1. Notice that they are contained within an opening and a
    closing brace, which makes it clear, without dereferencing, which
    item they belong to (this is similar to the with statement in
    Pascal). Also note that bgcolor is a page characteristic that is
    automatically assigned to label_1.

    Additional pages can be defined just like additional functions, and
    there is no limit to the number of pages you can have, nor to the
    number of items you can have within a page. Additionally, it is
    possible to create custom items and options, allowing for greater
    flexibility.
------

  C.3   References and Dynamic Option Reference

    Specific items or option can be referenced through the use of a
    reference string. Additionally, the values of options can be
    dynamic option reference in a manner similar to C.

         C                      UFDL

    Structure Declaration               Item declaration
    struct label{                       label_1=new label
        struct label *value;            {
        char *fontcolor;                   value="label_2";
        };                                 fontcolor=["white"];
                                        }
    struct label *label_1;              label_2=new label
    struct label *label_2;              {
                                           fontcolor=["blue"];
    label_1->value=label_2;             }
    label_1->fontcolor=strdup("white");
    label_2->fontcolor=strdup("blue");

    References                          References
    label_1->fontcolor is white        label_1.fontcolor is white
    label_1->value->fontcolor is blue  label_1.value->fontcolor is blue

    no equivalent                      page1.label_1.fontcolor is white



    Note that the inclusion of page1 is optional. Including it allows
    the item or option to be referenced from a different page. Where C
    requires you to pass values between functions by using parameters,
    UFDL allows you to access any value from any page on the form by
    using a direct reference.

Universal Forms Description Language                          [page 228]


------

  C.4   Arrays

    Many of the options in UFDL are set using array structures.
    Specific elements in these arrays are referenced just as they
    would be in C.

    Array Declaration                Option Declaration
    char *format[2][2];              format=["integer",range=["1","10"]];

    format[0][0]=strdup("integer");
    format[0][1]=NULL;
    format[1][0]=strdup("1");
    format[1][1]=strdup("10");

    Element Reference                Element Reference
    format[1][0]                     format[1][0]  or
                                     format[range][0]


    Note the second Element Reference in UFDL. This reference is based
    on assigning a name to an element or set of elements within the
    array. In this case, the name range was given to the second set of
    elements. This allows you to access the elements of an array
    without having to know the order of those elements.

    There is no limit to the depth allowed an array in UFDL-you can
    have infinitely nested arrays. Additionally, UFDL does not create
    unnecessary blocks in memory. For instance, in the above example
    format[0][1] was assigned to be NULL in the C code. This is
    because this portion of the array is not used. In UFDL, that
    portion of the array is never created. This means that UFDL uses
    significantly less memory to store multi-dimensional arrays.
------

  C.5   Assignment

    UFDL has a single data type: the string. All values, be they
    integer, character, or float, are stored as literal strings. In
    order to assign literal strings, quotes are used just as in C.
    For example:

         C                                       UFDL

    value=strdup("This is a          value="This is a literal string";
    literal string");

    size[0]=strdup("10");            size=["10","10"];
    size[1]=strdup("10");


    Note that you do not need to use any of the string functions such
    as strdup. Memory management is handled automatically. Assigning a
    string to an option automatically copies the string and disposes of

Universal Forms Description Language                          [page 229]


    any previous value for that option. Additionally, the full list of
    elements can be assigned to an array at any time in UFDL code. In
    C, this is only possible when you first declare your arrays (see
Appendix D:  Glossary

Absolute Positioning

    Absolute positioning places items in set locations on the form. This
    form of positioning uses an x-y coordinate system to specify where,
    in relation to the upper-left corner of the form, the item should be
    placed. Absolute positioning allows for drag-and-drop form designer
    functionality. See Also: Relative Positioning

Automatic Action

    Automatic actions are background actions that you can set your form
    to carry out without user prompting. These actions can be set to
    occur after a specific amount of time, or to repeat periodically.
    Use automatic actions to create effects such as periodic interfacing
    with databases. For example:

    ping_action = new action
    {
            delay = ["repeat", "120"];
            type = "submit";
            url = ["http://www.server.domain/cgi-bin/status"];
    }

Alignment Modifiers

    This is a group of modifiers used in relative positioning. They are
    used to set locators that align items in relation to each other. See
    Also: Relative Positioning, Locators

Bounding Box

    An unseen rectangular area surrounding each item and including all
    elements of the item (including built-in labels and borders). Used
    in the relative ositioning scheme for determiniing the "edge" of an
    item.

Build Order

    When you create items on a form, the order in which they are created
    forms a sequence. The first item you create is the first item in the
    sequence, the second item is second in the sequence, and so on. This
    sequence is called the build order. The build order can affect
    relative positioning.

Compression

    You can set up forms to submit and save as compressed files. See the
    descriptions or the saveformat and transmitformat options.


Universal Forms Description Language                          [page 230]


Computation

    See: Formulas

Custom Item

    Custom items are items that are not part of the standard UFDL. You
    define these items yourself. Custom items are ignored by the a UFDL
    parser, and are never visible on the form. Use custom items to
    integrate the form with other applications. See Also: Custom
    Options, Hidden Items

Custom Option

    Custom options are options that are not part of the standard UFDL.
    You create these options yourself.  Custom options are ignored by a
    UFDL parser, and ever affect the appearance of an item. Use custom
    options to integrate your form with other applications. See Also:
    Custom Items

Expansion Modifiers

    This is a group of modifiers used in relative sizing. They are used
    to set locators that adjust the size of items in relation to other
    items on the form. See Also: Extent Modifier, Locators

Extent Modifier
    This modifier is used in both normal and relative positioning.  It
    is used to set locators that set the size of items in pixels. See
    Also: Expand Modifiers, Locators

Filtering

    You can set up forms to filter out specific item types, option
    types, or items when they are transmitted. This can be useful for
    eliminating unnecessary information when the form is being
    transmitted to another application. See the descriptions for the
    transmit, transmititems, and ransmitoptions options. See Also:
    Compression

Formulas

    Formulas allow you to add math or logic to your form. You can use
    them to add values or make decisions based on user input. Also
    referred to as computations or logical operations.

Global Settings

    Global settings are used to set options for the whole form. Each
    item in the form will reflect that option setting, unless the same
    option is also set for that page or item.

Hidden Items

    Hidden items are not independently visible on the form. However, in

Universal Forms Description Language                          [page 231]


    some cases they may contribute to the appearance of other form
    items. The hidden items are: data items, cells, action items, help
    items, and custom items.

Identifiers

    Identifiers are used to uniquely identify a page, item, option, or
    option element in the form. For a discussion of the character set
    you may use when creating identifiers, see the section called
    Identifiers in '2. The Universal Forms Description Language'.

Include

    The #include statement allows you to "include" external files in a
    form. These files must be in a UFDL format that is compatible with
    the form. A UFDL parser must insert include files into forms at the
    place marked by an #include statement.

Input Focus

    When a user views a form, the input focus is the focus that moves
    from item to item in the form when the user presses the TAB key.

Item Tag

    Each item has a unique item tag, or name, which is used to identify
    that item.

Locators

    Locators are used to set both the locations of an item on the page
    and any relative or extent sizing that should apply to the item.

Modifier

    Modifiers are combined with item tags to create locators. Modifiers
    describe how an item should be positioned in relation to its
    reference items. For example, after, below, left-to-left, and so on.
    See Also: Locators, Reference Items

Page

    Each form can be composed of any number of pages, just like a paper
    form. Each page is identified with a page tag, begins with an open
    brace ({) and ends with a close brace (}). All forms must have at
    least one page.

Page Settings

    These settings set global option settings for all items on the page
    (unless an individual item description overrides the setting). Page
    settings override global settings, but are overridden by options set
    for individual items.

Page Tag

Universal Forms Description Language                          [page 232]


    Each page has a unique page tag, or name, which is used to identify
    that page.

Reference

    References allow you to identify a specific option by providing a
    "path" to it. This means that you can refer directly to a specific
    option anywhere in the form. A reference is constructed by combining
    the page tag, item tag, and option name that will point to the
    option you want. For example, page1.title_label.value points to the
    value option of the title_label on page one.

Reference Items

    When using relative positioning or sizing, you will need to use some
    items as reference points. These reference points will be used as
    anchors that set either where an item is positioned on the form or
    how large the item is. If the reference items are moved or change
    size, the item using them as anchors may also move or change size.
    See Also: Relative Positioning, Relative Sizing

Relative Positioning

    Relative positioning places items on the form in relation to other
    items. This means that items will move on the form if their
    reference item moves. Relative positioning is useful for ensuring
    cross-platform compatability. See Also: Absolute Positioning,
    Reference Items

Relative Sizing

    Relative sizing adjusts the size of items on the form in relation to
    other items. This means that items will change size on the form if
    their reference item moves or changes size. Relative sizing is
    useful for ensuring that the edges of your items line up on the
    form. See Also: Reference Items

Required Status

    The required status is part of the format option. It determines
    whether the user of a form is required to enter information into an
    item.  The required status can be set to "optional" or "mandatory".

Start Value

    The start value is an element of the option name that contains the
    literal resolution of an option reference or other formula. The
    start value element is represented as an open angle bracket, the
    value in quotation marks, and a close angle bracket on the left-hand
    side of the equal sign, like this:

        value<"Jane E. Smith"> = page1.nameField.value;

    The viewer sets this literal value when a form is signed, submitted,

Universal Forms Description Language                          [page 233]


    or saved (and discards any old value if necessary). Because a digitally
    signed formula never fires after being signed, the start value for the
    option is always the same--and therefore it is possible to reference the
    option and get the signed literal value.


Tab Order

    This is the order in which the user will move through the item on
    the form by pressing the TAB key.  The tab order only includes those
    items that take user input, such as fields, buttons, and so on.  You
    can set the tab order yourself.

Version Number

    This option records the version number of the UFDL that was used to
    create the form. It is only available in the global settings.


Author Contact Information

David Manning
dmanning@uwi.com

voice. 250-479-8334
fax.   250-479-3772
post.  David Manning
       UWI.Com
       1095 McKenzie Avenue, 4th Floor
       Victoria, B.C., Canada
       V8P 2L5



Expires:  February 04, 1999



















Universal Forms Description Language                          [page 234]