Forms

Home	Starting	Environment	DBMS	VisualPQL	Procedures	SQL	Forms	Host/API	Index

Forms

Introduction

Overview

SirForms allows you to create and run sets of linked, interactive screens for data entry, retrieval and update. A complete set of screens, known as a form, is defined using commands. There are commands for defining what variables are on each screen, how they are displayed and edited, how the screen is to look, and for linking screens together.

A form can be re-compiled every time it is used or the compiled version of the form can be saved as a .frm file.

Once a form has been developed, it can be used by many people for data entry or for querying data. (See Using an existing form.)

SirForms can be run as an independent module or from the main SIR/XS menu.

When SirForms is run, a number of parameters can be specified. At a minimum, the name of the input file containing the form must be specified. The input can be either a text file to be compiled (.cmp) or a pre-compiled form (.frm). If the input file is not specified, you are prompted for an input file to be compiled.

SirForms commands are created with a standard text editor. A Default Form can be generated for a database and can be used without any modifications to create new records, to modify or delete any existing records and to search the database for records meeting particular criteria.

When SirForms compiles the commands, if there are any errors, a message is displayed and errors are listed either to the specified listing file or to the default SirForms.err. If any changes are made to the database that affect a compiled form, a warning is issued that the form is out of revision and must be re-compiled.

If 'journalling' is set on for a database, SIR/XS take copies of any database updates as they happen through SirForms. If the database becomes corrupted or damaged, then a backed up version can be restored and the journal updates applied to bring the database or tabfile back to the current level without re-entering data. See Check Database for a further discussion of recovery.

Form Structure

A form definition consists of a set of commands, each of which has numerous clauses. Each command may continue on as many lines as necessary and it is usual practice to specify each clause of a command as a continuation line. To continue a command to the next line, put the continuation character "-", at the end of a line.

A Form Definition starts with the FORM command. This specifies the name of the form, the name(s) of any database(s) or tabfile(s) to be used, any defaults that apply to the entire form, security specifications and defines any temporary variables for use in the form. The entire Form Definition is terminated by the ENDFORM command.

The FORM command is followed by commands defining one or more screens. A screen is a display on the execution window which is a fixed 30 rows by 80 characters text style screen window. The window is cleared between each screen.

A form can contain any number of screens; it must contain at least one screen definition.

Definition of a screen starts with one of the commands MENU,RECORD,TABLE. Menu screens are independent of any database record or table. They can act as a table of contents with a choice as to where to go next. Menu Screens can also be used to display or enter data into temporary variables. Record and Table screens relate to database records or tables. These screens can be used to display data and can be used to enter new data and modify existing data.

Within each screen, further commands are used to describe the screen. The most common of these is the FIELD command. This displays individual variables and allows the user to enter new data. Default formats and edit rules from the data dictionary are applied automatically. There are numerous clauses on this command to extend the edit rules and alter the position or format of the data.

Definition of a screen is terminated by the appropriate END command (ENDMENU, ENDRECORD or ENDTABLE).

Screens are linked together with the CALL command which passes control from one screen to another. This can be done under user control or automatically at given points in the form.

All the data quality control and schema information defined in the data dictionary (such as Valid Values, Variable Ranges, data type, data size) is applied automatically within a form; this information does not have to be specified again.

Comments can be added to a form definition. Comment lines begin with an asterisk "*". The whole line is treated as a comment.

If the same commands or partial commands are used repeatedly, synonyms for these can be defined, which can simplify maintenance and development. Synonyms are frequently used for video attributes which are common to many fields, edit checks across fields and standard CALL keywords.

Parts of forms can be held on separate files and included into other forms definitions. This technique can be used where the same screen or menu occurs in many forms, or can be used with a standard set of synonyms to ensure consistency of usage across all forms.

A form has a structure similar to the following (The indentation is for readability only) :

FORM form_name
  MENU menu_screen_name
     CALL record_screen_name
     CALL table_screen_name
  ENDMENU
  RECORD record_screen_name
     FIELD field_name
     FIELD field_name
  ENDRECORD
  TABLE table_screen_name
     FIELD field_name
     FIELD field_name
  ENDTABLE
ENDFORM

A very simple form definition might be:

form COMPANY -
     database COMPANY -
     password COMPANY -
     security HIGH,HIGH -
     labels 20 -
     root MAINMENU
  menu MAINMENU
    call EMPLOYEE
    call OCCUP
    call REVIEW
  endmenu
  record EMPLOYEE
    generate
  endrecord
  record OCCUP
    generate
  endrecord
  record REVIEW
    generate
  endrecord
endform

Specification Levels

There are levels within a form for specification of common field attributes and specifications concerning fields can be set at any level and apply to all of the fields within that level. These levels are:

FORM
  SCREEN (RECORD, TABLE or MENU)
     PAGE
       GROUP
         FIELD

For example, to highlight data on all of the fields for one particular record, specify the DATA HILITE clause at the RECORD level.

Higher level specifications act as defaults for all lower levels. These can be overridden for a particular field or group of fields by specifying the clause at that level.

Names

Names are normal SIR/XS names. Standard names are 1 to 32 characters long with no spaces. The first character must be alphabetic. Characters can be letters, digits or four characters ($, #, @,_). Names are translated to upper case so uppercase and lowercase letters are equal.

If you wish to use a name which does not conform to these rules, enclose the name in curly braces {} as per other SIR/XS references to non-standard names. (Note: for compatability with previous versions the SIR/XS FORMS module also supports the use of double quotes "" as delimiters on input for non-standard names.)

A non-standard name can contain blanks or use lowercase letters.

Expressions can be used at many points in commands, typically in IF or COMPUTE clauses. An expression is a set of named variables, constants or functions which eventually resolves to a single value. For example, SALARY*1.1 is an expression which multiplies salary by 1.1. see COMPUTE commands.

Default form

It is very easy to create a default form from within the main SIR/XS menu. (See Default Form.)

To create a default form, start SIR/XS and log on to the database. For the example COMPANY database, the name of the database is COMPANY, password COMPANY, read security is HIGH, write security is HIGH. When you have logged on:

Select the Database menu option

Select Write schema
Enter a file name, for example, COMPANY.cmp and turn on the Forms Definition option. Execute the dialogue.

The default form is now in the specified file. You can run the default form immediately without making any changes or you can edit the file.

Commands

The following commands can be used:

FORM

Begins the definition of a form. Defines databases, tabfiles, local variables and security. Local variables can be referenced at any point in the form. RECORD

Begins a record screen set of commands which can reference database variables from one record type. TABLE

Begins a table screen set of commands which can reference variables from one table. MENU

Begins a menu screen that contains only calls to other screens and temporary variables. It cannot reference a record or table. HELP

Begins a help screen containing text. This is a display only screen. PAGE

Defines a page of fields within a screen. A page refers to a physical screen of data. GROUP

Defines a group of fields within a page. FIELD

Defines a field. Fields are always in a screen and may be in pages and/or groups. GENERATE

Defines a default set of fields from the schema. CALL

Passes control from one screen to another. COMPUTE

Calculates a variable. IF

Conditionally calculates a variable. LOOKUP

Finds a record from which to retrieve data or to verify a value or expression. AT

Sets the cursor position on the screen. TEXT

Displays a text string. DRAW

Draws a line or box. ENDxxxxxx

ENDFORM, ENDRECORD, ENDTABLE, ENDMENU, ENDHELP, ENDPAGE

ENDGROUP

Security

The security levels defined in the database schema are applied in SirForms for access to the database, record types or variables that have security levels defined. The database password and security passwords must be specified before access to the database is permitted.

Further security control can be defined to regulate the activities or functions a user may perform while using the form. You can restrict the ability of a particular form to read existing data, write new data, delete data, etc. By default, virtually all activities are allowed. Permission is denied for an activity on a form or screen by adding the prefix NO to the name of the activity. For example, to disallow all changes to the database, add the NO prefix to the WRITE activity.

FORM COMPANY .... ACTIVITIES NOWRITE ....

The ACTIVITIES clause on the FORM command sets the permissions for all the screens in the form. Activities can be specified at a screen and further restrict what can be done at that screen. If USERS GROUP ACTIVITIES are specified on the FORM command, the specifications are in effect for the entire form. Permissions that have been denied at a higher level cannot be granted to a user group at a lower level of the Form Definition.

The MODIFY/NOMODIFY applies to fields and can be specified at the individual FIELD, GROUP and PAGE levels. The ACTIVITIES clause specifies the restrictions which apply to anyone using the form.

If several people use the same form, activities can be allowed or disallowed for different users or groups of users. The various users of a form can be split into user groups. Each group has a name and optional password and a set of permitted and prohibited activities. These are specified as clauses on the FORM command. For example:

FORM COMPANY  -
      DATABASE COMPANY PASSWORD COMPANY SECURITY HIGH, HIGH -
      LABELS 20 ROOT MAINMENU -
      USERS -
       GROUP SUPER / DOALOT ACTIVITIES NONEWCASES -
       GROUP CLERK / DOSOME ACTIVITIES NOMODIFY

When a user accesses this form, they are prompted for a group name and password. The NONEWCASES on the ACTIVITIES clause for SUPER means that this group cannot create new cases, however all other activities are allowed. The CLERK group cannot modify existing data.

Help

Help is provided from the schema for users who need information about a particular field. The default help text consists of the variable name, label, input format, value labels, storage requirements and missing value(s).

Additional help can be provided as part of the form as a separate screen of text or as a line displayed in the Status area. A line of help text for a field can be displayed in the Status Area with the HELP clause on a FIELD command:

FIELD BIRTHDAY -
  PROMPT 'Date of Birth (Enter as MMM DD, YYYY)' -
  TYPE DATE 'Mmm DD, YYYY' -
  HELP 'For example: May 24, 1997'

If a longer description is required, a separate screen can be defined as an alternative to the default Help screen. Specify the name of the Help screen on the HELP clause. Define a help screen with the text of the help to be displayed. Help screens can contain DRAW, TEXT and other visual enhancement commands. For example, to specify a Help screen for the Social Security Number field:

FIELD SSN -
  PICTURE 'DDD-DD-DDDD' -
  HELP HELPSSN

The standard Help scripts from SIR/XS give extensive information on how to use SIR/XS and may be inappropriate for forms users. Help scripts are simply HTML text files and can be edited or altered as necessary for particular projects. The index.htm file in the Forms sub-directory in the help system is the starting point for SirForms help.

Error Messages

Error messages are displayed on the status line with a number in parentheses following the message. A full listing of the error messages is contained in Messages. Error messages can be altered to reflect the needs of specific projects by specifying an ERROR clause for the error message number at any level (form, screen, field). This replaces the default error message for everything within that level. For example:

FIELD SSN-
   PICTURE 'DDD-DD-DDDD' -
   HELP HELPSSN -
   ERROR 16 'Social security number is in the wrong format'

In this example, error message 16 "Input does not match picture", is replaced by the message "Social security number is in the wrong format" when a user makes an error.

This does not alter the html help page for message 16.