HomeStartingEnvironmentDBMSVisualPQLProceduresSQLFormsHost/APIIndex
VisualPQL homecontents start chapter top of pagebottom of pagenext page index PQLForms

PQLForms Overview

PQLForms is a set of commands that extend VisualPQL allowing you to create and run sets of linked, interactive screens for data entry, retrieval and update. A complete set of screens is a single VisualPQL routine known as a Form.

A Form can be created and maintained completely through the Forms Painter and this is the recommended way to develop forms. However, it may be necessary to use PQLForms commands and this chapter describes the various commands available.

The PQLForms commands define what variables are on each screen or page of a screen, how they are displayed and edited, how the screen is to look, and how screens are linked together. A PQLForm has built in buttons and associated logic to allow the user to navigate through a set of records and to display, edit and insert data according to the database description. A developer can use all standard VisualPQL commands as necessary and these are executed at appropriate places in the form.

A PQLform can be re-compiled every time it is used or the compiled version of the form can be saved as an executable member on the procedure file. A PQLForm can also be compiled and saved as a sub-routine and can then be executed as part of another PQLform or standard retrieval. A PQLform is run in the same way as any other VisualPQL routine either directly or from a menu.

Once a form has been developed, it can be used by many people for data entry or for querying data.

A default form can be generated for a database and can be used directly to view, create, or delete records.

Form Structure

A form definition consists of a set of commands, each of which may have various clauses. Normal VisualPQL syntax rules apply.

The form definition starts with the FORM command. This is similar to a RETRIEVAL/PROGRAM/SUBROUTINE command and can take all relevant clauses as per those commands plus PQLForms specific clauses. There are no required clauses on a FORM command. The entire form definition is terminated by the END FORM command.

The FORM command may be followed by any standard VisualPQL commands, (for example defining any local variables) and then optionally a CALL SCREEN command that transfers control to the named screen. The first SCREEN command begins definition of a screen. All further commands are in a screen definition. Definition of a screen is terminated by the END SCREEN command. Commands in the screen define the set of fields that are displayed; these can be split into a number of separately displayed pages if necessary.

A form can contain any number of screens. Screens are linked to other screens with the CALL SCREEN command so that the user or the application can pass control at appropriate points. A single screen can be called from any number of different screens.

The standard VisualPQL commands up to the first SCREEN or CALL SCREEN command are executed and then execution starts with the first screen or called screen.

This keyword MENU, RECORD or TABLE on the SCREEN command specifies the type of screen being defined:-

Within each screen, further commands are used to describe the components of the screen and their individual behaviour and appearance. The most common of these is the FIELD command. This defines an individual variable, possibly displaying it on the screen allowing the user to retrieve data and maybe update data. Default formats and edit rules from the data dictionary are applied automatically. There are clauses on this command to extend the edit rules and alter the position or format of the data.

A form has a structure similar to the following:

FORM
. SCREEN RECORD record_name
.  FIELD field_name
.  FIELD field_name
.  CALL SCREEN record__name1
. END SCREEN
. SCREEN RECORD record_name1
.  FIELD field_name
.  FIELD field_name
. END SCREEN
ENDFORM
A very simple form definition (on the example COMPANY database) might be:
form
. screen record EMPLOYEE
.  field id
.  field name
.  field currpos
.  call screen OCCUP
. end screen
. screen record OCCUP
.  field id
.  field position
.  field startsal
. end screen
end form

Position on the screen

By default, each defined element is displayed one row down and in the same column as the previous element. The display position can be explicitly specified with the AT clause on the command that specifies the element.

The visual size of the screen is determined by the maximum position taken by any display element plus space for buttons and an area to display messages. There is no absolute maximum row and column size and it is possible to create screens that are too big to view all at once. There is a default font face, color and size of characters. These can be altered and specific colors/sizes/fonts can be used.

Examples

There are a number of example forms in the family EXAMPLE on the example COMPANY database. These are named FORMnnnn and contain comments as to the various features that they illustrate.

Commands

The following commands can only be used in a PQLForm:

FORM

SCREEN PAGE FIELD GENERATE CALL SCREEN ABUTTON FBUTTON FDISPLAY END SCREEN END FORM

Specifying VisualPQL in PQLForms

There are three general places in a screen definition where standard VisualPQL can be used.

Execution Clauses

Some clauses on PQLForms commands allow standard VisualPQL commands that are then executed at specific points in the form execution. Where VisualPQL commands can specified as part of a PQLForm clause, enclose the complete set of commands in brackets () and use a semi-colon ; after a command to indicate the start of a new command. For example, the FIELD command has the EDITIN and EDITOUT clauses that allow the specification of commands to transform data as it is read from the screen or displayed. :
FIELD SALARY  EDITOUT (fieldout = pformat(salary,'$zzzz.zz'))
              EDITIN  (if (sbst(fieldin,1,1) eq '$') fieldin = sbst(fieldin,2,len(fieldin)-1);
                       salary = numbr(fieldin);
                       ifthen (salary lt 1000);
                         failmess = 'Salary too low';
                         failfld  = 1;
                       fi)

Condition Clauses

Some clauses on PQLForms commands allow the specification of conditions. Where a single, standard VisualPQL condition can specified as part of a PQLForm clause, again enclose it in brackets (). A condition must eventually resolve to true or false and cannot extend over multiple commands. For example, the FIELD command has the IF clause that determines whether the field is enabled or disabled (greyed out).
FIELD SALARY prompt 'Salary:'  IF (EDUC EQ 1)

Intermixed commands

Standard commands can also be intermixed with PQLForms FIELD commands. The commands are executed when the user presses ENTER as follows:- The VisualPQL can perform any standard VisualPQL function including record access, calling subroutines, displaying sub-dialogs, etc.

Predefined Variables

To allow easy communication between the predefined PQLForms logic and user specified standard VisualPQL, certain predefined variable names have been used:-

FAILFLD A numeric variable that can be set by commands that check a specific field as it is entered. A value of zero (0) is the default and means accept the field; a positive value means warn the user that the field has failed validity tests but they have the option to accept it; a negative value means the field has failed validity tests and is not accepted. The absolute numeric value has no specific meaning. The standard error message used if FAILFLD is not zero is number 57 'Failed Edit tests' and this can be overridden by setting a value in FAILMESS.
FAILMESS A string variable set by commands to the text of the message to display for a test that fails. If a positive FAILFLD or FAILSCR code is set, the text 'OK to save?' is appended to the message.
FAILSCR A numeric variable set by commands that check record validity. During field processing or in the WRITE clause, a zero value accepts the update and is set by default. A positive value means the user has the option to accept the update after a warning. A negative value means the update is not done. The absolute numeric value has no specific meaning. The standard error message used if FAILSCR is not zero is number 110 'Record failed write tests'.
If a SELECT clause is specified on the SCREEN command, this can set FAILSCR to a non-zero value to indicate that the record should be skipped.
FIELDIN A string variable used as the starting point for data from the screen for any EDITIN commands to check or transform when the user presses Enter on that field.
FIELDOUT A string variable used as the result of any EDITOUT commands to display the field on the screen.

Help

If the user requests help on a field (by clicking on the question mark from the top of the dialog and positioning it on a field or by pressing F1 on the field), a pop-up box is displayed with any defined help text. Define help text for a field with the HELP clause followed parentheses enclosing any standard PQL expression that resolves to a string. The expression can be a simple string constant in quotes or a concatenated string. To display multiple lines in the pop up box, concatenate char(13) as a line break character. For example:
FIELD BIRTHDAY
 PROMPT 'Date of Birth'
 HELP ('Enter as MMM DD, YYYY' + char(13) +
       'For example: May 24, 2001')

If there is no defined help text for a field, nothing is displayed i.e. no box is popped. If there is no help text for any fields, the question mark is suppressed.

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
 ERROR 47 'Social security number is in the wrong format'
In this example, error message 47 "Not a valid value", is replaced by the message "Social security number is in the wrong format" if a user makes an error.

homecontents start chapter top of pagebottom of pagenext page index

Using PQLForms

Run PQLForms as per any other VisualPQL program from the SIR/XS menus. Any database or tabfile required by a form must be connected.

Every PQLForm screen has a set of buttons that take standard actions. These buttons vary according to the type of screen but all include an Exit button to return one level. Typically screens also have various fields for the display and entry of data. Error messages are displayed at the bottom of the screen.

Each data field can have up to three visual elements: a prompt, a data area to enter or to display the data and the set of value labels displayed as a pull down choice list. When a screen is initially displayed, fields may already have data in them or the fields may be blank waiting for data to be entered or a record to be retrieved.

To enter data into a field, type in the data and press Enter. To skip over fields, use the Tab keys or position to a field with the screen cursor using a mouse or other pointing device. Shift-Tab goes back a field, Tab goes forward a field. Tab does not process the data nor execute any VisualPQL associated with the field.

Field Editing Operations

When positioned to a data entry field, edit the contents of the field if necessary. Left Arrow and Right Arrow position the cursor within the field. The data in a field may be longer than the display space and is scrolled horizontally as characters are typed or the arrow keys are used.

Keys to edit the field are the normal keys for the GUI being used. On Windows systems, Del deletes the next character, Ctrl-Del deletes the whole field; Ctrl-C cuts highlighted characters, Ctrl-V pastes cut characters, Ctrl-Z restores the previous edit, etc.

Press Enter to process the data in a field and move to the next field. If you update a field but do not press Enter, the edits have no effect.

Moving from screen to screen

 A form often consists of multiple screens, one per record type or table. A screen is a single logical entity that may be split into several pages if the data does not fit on a single display screen.

If a screen is on multiple pages, the Page Down button moves to the next page; the Page Up button moves to the previous page. The title of the screen changes to indicate the current page.

To call a screen, press the appropriate button. The Exit button returns to the calling screen. Lower level screens can call other screens and screens may be nested as deeply as necessary.

Accessing Records and Rows

Key fields identify the record or row and are usually the first fields at the top of the screen. Key fields must be specified on a screen. If the complete set of key fields is not specified, a warning is given at compile time and the missing key fields are automatically added as the last fields on the screen.

There are buttons to browse through sets of records:-

 If the screen is a top level screen, (it has not been called by another screen) then the set of records is all of the records of that type in the database or table. However, if a screen is called by other screens, then some part of the overall key may have been set by the calling screen. In this case, those key fields are read-only (cannot be modified) and the set of records is a subset with that specified part of the key. The browse buttons operate within that set of records i.e. The first button retrieves the first matching record in the subset not the first on the file.

To locate a record, enter data in all the key fields. Press Enter at the last key field and the matching record is then retrieved. If no record matches the exact key, a message that a no record has been found is displayed. This positions in the set of records even if a partial key is entered or the key does not exist and the Next or Previous buttons browse from that point.

Updating a Record

 Once a record is displayed, the data fields can be modified.
At the end of processing a screen (as the user retrieves another record or exits the screen), if the form allows updates and any of the fields have been updated, the record is written back. This can be done automatically or a message can be displayed asking the user to confirm that the record should be written.
At any point after updating some field(s), press the WRITE button to write the changed data. The WRITE button is only displayed if the form allows updates and is only enabled when some data has been updated.

Prior to writing the data back, the RESET button restores the original data "undoing" whatever changes were made.
The Clear button clears the screen data fields except for any key values preset by the CALL to this screen.

Deleting Records

 Once a record is displayed, the DELETE button deletes the record. The DELETE button is only displayed if the form allows updates and a record has been retrieved. The record is deleted after asking the user for confirmation.

homecontents start chapter top of pagebottom of pagenext page index

PQLForms General Clauses

There are a number of settings or general clauses that can be specified at different levels and, if not over-ridden at a lower level, apply to all field definitions within the level. Settings can be specified at the following levels:
FORM
 SCREEN
  PAGE
    FIELD
A setting at one level acts as the default for all lower levels. For example, the width of labels could be set on the FORM command for the whole form and would apply to every field on every screen. A setting is overridden for a particular level by specifying the clause at that level. If a particular setting is not specified at a given level, the current default applies.

These general clauses are:-

[NO]PROMPT [AT r,c] 
    [WIDTH n] 
    [FONT ([NO]BOLD|[NO]ITALIC|[NO]UNDERLINE|SIZE=N|FACE = 'fontname'|FGROUND=RRGGBB|BGROUND=RRGGBB)] 
    ['prompt-string'|VARDESC|VARLABEL|VARNAME|VARDOC]
[NO]DATA   [AT r,c] 
    [WIDTH n] 
    [FONT ([NO]BOLD|[NO]ITALIC|[NO]UNDERLINE|SIZE=N|FACE = 'fontname'|FGROUND=RRGGBB|BGROUND=RRGGBB)]
[NO]LABELS [AT r,c] 
    [WIDTH n] 
    [FONT ([NO]BOLD|[NO]ITALIC|[NO]UNDERLINE|SIZE=N|FACE = 'fontname'|FGROUND=RRGGBB|BGROUND=RRGGBB)]
ERROR number 'error text'

Field Elements

 There are three main elements to each field as displayed on the screen, from left to right, the Prompt, the Data and the Label.

Screen co-ordinates

 PQLForms uses a notional set of Row and Column co-ordinates to specify vertical rows and horizontal columns. The top row is 1 and the leftmost position is column 1.

The absolute row and column size are dependent on the font size being used. A single row is sufficient to display a field or button. A column approximates to an average character in the font. The number of rows and columns displayable on a screen depend on font size and screen resolution.

AT

AT [ row ] [, column ]

WIDTH

WIDTH n

[NO]DATA

[NO]DATA [AT r,c] [WIDTH n]

[NO]LABELS

LABELS [AT R,C] [WIDTH n] | NOLABELS

[NO]PROMPT

[NO]PROMPT [ 'prompt-string' | VARDESC | VARLABEL | VARNAME | VARDOC ] [AT r,c] [WIDTH n]]

FONT

FONT ([NO]BOLD|[NO]ITALIC|[NO]UNDERLINE|SIZE=N|FACE = 'fontname'|FGROUND=RRGGBB|BGROUND=RRGGBB) Non-standard fonts can be specified with the FONT clause wherever a DATA, PROMPT or LABEL clause is specified. Follow the FONT keyword with a set of specifications enclosed in brackets () using as many as necessary. Note that some changes alter the amount of space required to display the item and other positioning specifications may need to be adjusted accordingly. Fonts specified on higher-level commands alter the default font for all fields within that level. The various specifications are:
BOLD Display the element as bold.
ITALIC Display the element as italic.
UNDERLINE Display the element underlined.
SIZE=N Increase or decrease the size of the element. Specify a negative number to decrease size.
FACE='fontname' Display the element using a different font. Specify the name of the font enclosed in quotes.
FGROUND=RRGGBB Display the element using a different foreground color. Specify the color using exactly six characters; valid characters are 0 to 9 and A to F. These are three sets of hexadecimal specifications of the strength of the red, green and blue components of the color. Each setting has a value from 00 to FF.
FGROUND=RRGGBB Display the element using a different background color. Specify the color using exactly six characters; valid characters are 0 to 9 and A to F. These are three sets of hexadecimal specifications of the strength of the red, green and blue components of the color. Each setting has a value from 00 to FF.

For example

SCREEN RECORD EMPLOYEE PROMPT FONT (FACE='Ariel')
FIELD ID PROMPT FONT (BOLD)
Note that higher level font settings apply to FIELD definitions and do not alter defaults for buttons. If you wish to alter the font on a buttons, specify the font on a FBUTTON command. Currently buttons do not support color but any other font specification can be used.

ERROR

ERROR message_number 'error_text'

homecontents start chapter top of pagebottom of pagenext page index

FORM

FORM
  [appropriate standard RETRIEVAL/PROGRAM/SUBROUTINE clauses]
  [PQLForms general clauses]
  [AUTO]
  [CLEAR|NOCLEAR]
  [NODATABASE]
  [PAGESIZE rows]
  [PQLFILE='filename']
  [SUBROUTINE name [(input_list)]]
  [UPDATE]

General Clauses

[NO]DATA   [AT r,c] [WIDTH n]
[NO]LABELS [AT r,c] [WIDTH n]
[NO]PROMPT [AT r,c] [WIDTH n] [VARDESC|VARLABEL|VARNAME|VARDOC]
ERROR number 'error text'

The FORM command is required. All other clauses are optional. All standard RETRIEVAL clauses can be specified. The PQLForms general clauses can be specified. The following specific clauses can be specified on the FORM command:

AUTO Specifies that, if updates are allowed, any new records are written to the database without asking for confirmation. NOAUTO specifies that the user is asked to confirm that the record should be written and is the default.

CLEAR Specifies that, if updates are allowed, the data fields on the screen are cleared after writing. NOCLEAR specifies that the data is not cleared and is the default.

NODATABASE Specifies that the generated form is a PROGRAM not a RETRIEVAL and can run without being attached to a database.

PAGESIZE n Specifies the maximum number of data rows in a page of a screen. The default is 20. (See the PAGE) command.

PQLFILE Specifies that the named file is created. This contains standard VisualPQL code (i.e. all PQLForms extensions have been replaced) that performs identical functions to the specified form. This can be used as the basis for a program with other functionality if necessary.

SUBROUTINE Specifies that the routine is compiled and saved as a SUBROUTINE. The subroutine name is required and is the name of the compiled subroutine. The name of the subroutine can be qualified with procedure file and family prefixes and passwords.

A subroutine may have input parameters. These are positional parameters corresponding to the EXECUTE SUBROUTINE list of parameters. The parameters are read-only and are local variables in the subroutine. These variables must be defined explicitly within the subroutine.

To pass key variables to a SCREEN defined in a FORM SUBROUTINE you would use:

FORM SUBROUTINE name (keys)
CALL SCREEN scrname USING (keys)
. SCREEN RECORD scrname
...
UPDATE Specifies that record and table screens allow the reading and writing of records. By default, screens do not update the database or tabfile. Individual screens can be set to allow/disallow updates. Local variables can be input regardless of update status.

homecontents start chapter top of pagebottom of pagenext page index

SCREEN

SCREEN
  {MENU name |
   RECORD name [/database.record][ INDEXED BY indexname ] |
   TABLE  name [/tabfile.table]  [ INDEXED BY indexname ]}
  [AUTO|NOAUTO]
  [CLEAR|NOCLEAR]
  [DELETE  (pql code)]
  [INITIAL (pql code)]
  [NOBUTTON]
  [PAGESIZE rows]
  [READ    (pql code)]
  [SELECT  (pql code)]
  [TITLE   (pql code)]
  [UPDATE | NOUPDATE]
  [WRITE   (pql code)]

General Clauses

[NO]DATA   [AT r,c] [WIDTH n]
[NO]LABELS [AT r,c] [WIDTH n]
[NO]PROMPT [AT r,c] [WIDTH n] [VARDESC|VARLABEL|VARNAME|VARDOC]
ERROR number 'error text'

A SCREEN command starts a screen definition. The screen name must be specified and must be unique within a form. This is displayed as the title of the screen. The name must be a valid SIR/XS name.

Follow the screen command with further commands to display fields, to control the appearance of the screen or to link to other screens. The sequence of the fields within the screen definition determines the sequence for moving to the next field. If the display element positioning clauses are used, this may not necessarily be the order of fields as they appear on the screen.

End the set of commands for a screen with the END SCREEN command.

There are three screen types defined by the MENU, RECORD or TABLE keyword.

MENU

Within a menu screen, FIELD commands can only refer to local variables. Menu screens may consist simply of buttons offering choices as to which screens to go to or can display fields or allow data entry providing that these are local variables.

The AUTO, READ, SELECT and WRITE clauses do not apply to MENU screens.

RECORD

Record screens access and display one record at a time. Within a screen, commands can reference any variable from that record plus any local variables. Commands can also reference common variables in a case structured database.

Specify the screen name and, optionally, the name of the record and the name of the database. If a record name is not specified, the screen name must be the record name. If a database name is not specified, the current database is the default.

The name CIR can be used as a record name on a case structured database to refer to the common information record.

An index can be specified for a record and the index variables are treated as the key fields. Only one index can be specified for a record screen. If an index is not specified, the record is processed by any case and record keys.

The same record type can be associated with multiple screen definitions in the same form definition to allow different ways of viewing the same data. Each screen name must be unique.

When control is passed to a record screen, a record can be retrieved or a new entry created. The user can enter the key fields to locate the record, or can find the appropriate record with FIRST, LAST, NEXT or PREVIOUS buttons. The record or set of records to retrieve can be determined by clauses on the CALL SCREEN command.

TABLE

Table screens access and display one row at a time. Within a screen, commands can reference any variable from that table plus any local variables.

Specify the screen name and, optionally, the name of the table and the name of the tabfile. If a table is not specified, the screen name must be the table name. If a tabfile is not specified, the default tabfile is used.

An index can be specified for a table and the index variables are treated as the key fields. Only one index can be specified for a table screen. If an index is not specified, the table is processed sequentially.

The same table can be associated with multiple screens in the same form definition to allow different ways of viewing the same data. Each screen name must be unique.

When control is passed to a table screen, a row can be retrieved or a new entry created. The user can enter the key fields to locate the row, or can find the appropriate row with FIRST, LAST, NEXT or PREVIOUS buttons. The row or set of rows to retrieve can be determined by clauses on the CALL SCREEN command.

Clauses

AUTO|NOAUTO Specifies that any new records are written to the database without asking for confirmation. NOAUTO specifies that the user is asked to confirm that the record should be written and is the default.
CLEAR Specifies that, if updates are allowed, the data fields on the screen are cleared after writing. This is the default if not set at the FORM level. NOCLEAR specifies that the data is not cleared.

DELETE (PQL Code) Specify VisualPQL code, enclosed in brackets, that is executed when a record or row is about to be deleted. The record (row) is deleted by the user pressing the DELETE button. The VisualPQL can be any set of commands. The executed code can create and display sub-dialogs or error boxes as necessary. Separate multiple commands with a semi-colon ';'.
The DELETE commands can set a value in FAILSCR to warn the user and reject the delete.
Example: To test that when employee has a current position, tell the user and ask whether to accept the delete:
SCREEN RECORD EMPLOYEE
  DELETE (IFTHEN (EXISTS(CURRPOS));
           COMPUTE FAILSCR = 15;
           COMPUTE FAILMESS='Employee in current position';
         FI)
INITIAL (PQL Code) Specifies VisualPQL code, enclosed in brackets, that is executed when the user first initiates a screen before anything is displayed, before the first command in the screen and before a record is accessed. The set of VisualPQL to execute is any set of commands but should not display any sub-dialogs or any other graphical elements. Separate multiple commands with a semi-colon ';'.
Example: To set the local variable INTIME to the current time when the screen is accessed, specify:
SCREEN RECORD EMPLOYEE INITIAL (COMPUTE INTIME=NOW(0))
PAGESIZE n Specifies the maximum number of rows in a page of a screen. The default is 20. If the number of rows on a screen exceeds this size, then a new page is created automatically. When a screen has multiple pages, each page is displayed separately, the Page Up/Page Down buttons are displayed and the screen title contains the current page number. There is no limit to the number of pages on one single screen. All pages within a screen are the same size visually. All pages within a screen are one logical entity i.e. record and table screens access one single record or row. Page breaks can be set specifically at given points by the PAGE command.
READ (PQL Code) Specify VisualPQL code, enclosed in brackets, that is executed when the user reads a record. The code is executed when a new record is retrieved, after the record is read and before the data is displayed. The VisualPQL can be any set of commands. The executed code can create and display sub-dialogs or error boxes as necessary. Separate multiple commands with a semi-colon ';'.

(The executed code is inside the record block being read so it has access to the current case and record data).

SELECT (PQL Code) Specify VisualPQL code, enclosed in brackets, that is executed as the user moves to another record. The code is executed after a record is read and selects whether this record is wanted. The VisualPQL can be any set of commands that eventually set FAILSCR to non-zero if the record is not wanted. Records that are not wanted are skipped and the user is presented with the next wanted record. Separate multiple commands with a semi-colon ';'.

Example: To ignore records where salary is under 2500, specify:

SCREEN RECORD EMPLOYEE SELECT (IF (SALARY LT 2500) FAILSCR = -1)
TITLE (PQL Code) Specify VisualPQL code, enclosed in brackets, that is executed as each page of the dialog is displayed and constructs the title of the dialog. If this clause is specified, the default title is suppressed. The VisualPQL can be any set of commands that issue a SET DIALOG TITLE command to set the title. There are two predefined variables available. PAGENO is the current page number; PAGES is the total pages. These are both string variables so can easily be included in a title expression if required. Separate multiple commands with a semi-colon ';'.

Example: To put out a title, specify:

SCREEN RECORD EMPLOYEE TITLE (SET DIALOG TITLE 'People  Page ' + PAGENO + ' of ' + PAGES)
[NO]UPDATE UPDATE specifies that this record or table screen allows the reading and writing of records. NOUPDATE specifies that this record or table screen does not allow the reading and writing of records. By default, screens are set to the update status of the form. Local variables can be input regardless of update status.

WRITE (PQL Code) Specify VisualPQL code, enclosed in brackets, that is executed when a record or row is written. If data has been updated, the record (row) is written directly by the user pressing the WRITE button or when the user retrieves a new record (row) on this screen or exits from the screen. The code is executed after all local variables have been set to the values displayed on the screen. This VisualPQL Code could be used to implement ACCEPT/REJECT RECORD and REQUIRED field functionality from old style SIRForms.
The VisualPQL can be any set of commands. The executed code can create and display sub-dialogs or error boxes as necessary. Separate multiple commands with a semi-colon ';'.
The WRITE commands can check the validity of a record (row) and can set a value in FAILSCR to warn the user and reject the write.
Example: To compute the sum of VAR1, VAR2 and VAR3, specify:
SCREEN RECORD EMPLOYEE WRITE (COMPUTE TOTAL = VAR1 + VAR2 + VAR3)
To test that when salary is greater than 5,000, tell the user and ask whether to accept the record:
SCREEN RECORD EMPLOYEE
  WRITE (IFTHEN (SALARY GT 5000);
           COMPUTE FAILSCR = 15;
           COMPUTE FAILMESS='Salary over $5,000';
         FI)

Caution

 Since there is only one fail flag for a screen, if you want to test multiple conditions then you should ensure that you don't reset an error status to a warning. For example:
WRITE (
IFTHEN (EXISTS(NAME)   EQ 0) SET FAILSCR(-1); SET FAILMESS ("You MUST enter a name"); ENDIF;
IFTHEN (EXISTS(DOB)    EQ 0) SET FAILSCR(1) ; SET FAILMESS ("You really should enter a birthday"); ENDIF;
IFTHEN (EXISTS(GENDER) EQ 0) SET FAILSCR(1) ; SET FAILMESS ("You really should enter a gender"); ENDIF;
)
If none of the variables above is entered then only one warning about gender is displayed.

However, with:

WRITE (
SET FAILMESS ("You really should enter:")
IFTHEN (EXISTS(DOB)    EQ 0) SET FAILSCR(1) ; COMPUTE FAILMESS = FAILMESS + "Birthday; "); ENDIF;
IFTHEN (EXISTS(GENDER) EQ 0) SET FAILSCR(1) ; COMPUTE FAILMESS = FAILMESS + "Gender; "); ENDIF;
IFTHEN (EXISTS(NAME)   EQ 0) SET FAILSCR(-1); SET FAILMESS ("You MUST enter a name"); ENDIF;
)
If none of the variables above is entered then an error message on name is displayed. Then on the next write attempt the warning message about birthday and gender is displayed.

END SCREEN

 
END SCREEN
A screen must be ended with the END SCREEN command. There are no further clauses on the command.

homecontents start chapter top of pagebottom of pagenext page index

PAGE

PAGE
[PAGESIZE rows]

General Clauses:

[NO]DATA   [AT r,c] [WIDTH n]
[NO]LABELS [AT r,c] [WIDTH n]
[NO]PROMPT [AT r,c] [WIDTH n] [VARDESC|VARLABEL|VARNAME|VARDOC]
ERROR number 'error text'
The PAGE command specifies that a new page begins at this point. A new page resets the row position of the next display item to the top of the screen. When a screen has multiple pages, the Page Up/Page Down buttons are displayed and the screen title contains the current page number.

There is no limit to the number of pages on one single screen. All pages within a screen are one logical entity related to one single record or row.

If any of the general clauses are specified, these apply to the first field on the page.

Clauses

 PAGESIZE n

homecontents start chapter top of pagebottom of pagenext page index

FIELD

FIELD variable_name
[EDITIN (pql commands)]
[EDITOUT (pql commands)]
[HELP (help string expression)]
[IF (pql condition)]
[NOECHO]
[READONLY]
[TYPE [INTEGER | STRING | REAL | DATE | TIME]]

General Clauses:

[NO]DATA   [AT r,c] [WIDTH n]
[NO]LABELS [AT r,c] [WIDTH n]
[NO]PROMPT [AT r,c] [WIDTH n] ['prompt-string'|VARDESC|VARLABEL|VARNAME|VARDOC]
ERROR number 'error text'
The FIELD command displays the current value of a variable on the screen and provides the capability to invoke standard PQL for editing and validating data values.

The only required clause on the FIELD command is the name of the variable. A FIELD command without any clauses displays the data at a default position on the screen using the dictionary definitions to control the prompt, the data format and the edit rules.

The FIELD command is used in record screens for record variables, in table screens for table columns and in any screen for local variables. The same variable can be referenced by multiple FIELD commands on a screen.

The sequence of the FIELD commands determines the sequence followed by the cursor on the screen when the user presses Enter or uses the Tab keys. Field commands do not have to correspond to the sequence of variables in a row or record. All of the fields on a record or table do not have to be on a screen.

The FIELD command creates visual entries in the screen together with appropriate logic to display and modify the data.

If VisualPQL commands are interspersed with FIELD commands then:

Clauses

 EDITIN (pql commands)

EDITOUT (PQL commands)

HELP (string expression) IF (pql condition) NOECHO READONLY TYPE

homecontents start chapter top of pagebottom of pagenext page index

CALL SCREEN

CALL SCREEN screen_name

[AT r,c]
[AUTO [(pql condition)]]
[HELP (help expression)]
[IF (pql condition)]
[ONCALL FIRST | LAST]
[PROMPT 'prompt']
[USING (caseid,*| key,...)
[VIA (* | key,...)
[WIDTH n]
The CALL SCREEN command passes control from one screen to another, typically when the user presses the button generated by the command.

The only required clause on the CALL SCREEN is the called screen_name. This references another screen that is included in this form. If the name is a non-standard name, ensure that it exactly matches the screen name as specified on the called screen.

The default prompt is the called screen name.

A called screen can be blank for the user to enter any keys and retrieve any records or rows, or the key fields can be passed by this command to control the set of records or rows that the called screen is to reference.

The data fields on the called screen may be blank for the user to select the required screen (first or last in the set) or a record or row may be retrieved automatically with an ONCALL FIRST or ONCALL LAST clause.

Clauses

AT AUTO [(pql condition)] HELP (string expression) IF (PQL condition) ONCALL FIRST | LAST PROMPT 'string' USING (list,...) VIA (list, ...) WIDTH n A CALL SCREEN can appear before the first SCREEN block and is typically used to pass on keys that have been sent to the FORM routine:
FORM SUBROUTINE name (keys)
CALL SCREEN scrname USING (keys)
. SCREEN RECORD scrname
...

homecontents start chapter top of pagebottom of pagenext page index

FDISPLAY

FDISPLAY
    [AT r,c]
    [[DRAW [HEIGHT N] [IMAGE (bitmap_filename_expression) [BORDER]]]
    [TEXT (text_expression)  [FONT ([NO]BOLD|[NO]ITALIC|[NO]UNDERLINE|SIZE=N|FACE = 'fontname'|FGROUND=RRGGBB|BGROUND=RRGGBB)]]
    [WIDTH n]
The FDISPLAY command puts a line, box, image or text on the screen. Expressions are evaluated and the display updated when the screen is refreshed (e.g. when a new record is read).

AT

DRAW TEXT For example:
FDISPLAY TEXT ('Welcome to the Administration System') FONT (UNDERLINE SIZE=2) WIDTH 30
FDISPLAY TEXT ('Please contact ext. 123 for help') at +2,+5
FDISPLAY TEXT (NAME) AT 4,30 WIDTH 20    |  Displays value in variable NAME
FDISPLAY DRAW WIDTH  80                  |  Draws line for 80 columns
FDISPLAY AT 1,1 DRAW HEIGHT 10 WIDTH 50  |  Draws box
FDISPLAY DRAW HEIGHT 5 WIDTH 40 IMAGE ('LOGO.BMP') | Displays image from file

homecontents start chapter top of pagebottom of pagenext page index

ABUTTON

ABUTTON {FIRST | LAST | NEXT | PREVIOUS | EXIT | RESET | WRITE | CLEAR | DELETE | PAGEDOWN | PAGEUP}

The ABUTTON command is equivalent to the user pressing a button, except that it is done under program control. This command can be used anywhere in-line VisualPQL can be used but cannot be used in clauses on other PQLForms commands.

FIRST

LAST NEXT PREVIOUS EXIT RESET WRITE CLEAR DELETE PAGEDOWN PAGEUP

homecontents start chapter top of pagebottom of pagenext page index

FBUTTON

FBUTTON [button_name | ACTION (pql commands)]
        [AT r,c]
        [ID n]
        [IF (pql condition)]
        [PROMPT '']
        [REMOVE]
        [WIDTH w]

button_name

ACTION (pql commands) AT ID IF (pql condition) PROMPT 'string' REMOVE WIDTH

homecontents start chapter top of pagebottom of pagenext page index

GENERATE

GENERATE EXCLUDE | INCLUDE
         SCREENS (screennames, ...)
         VARS    (variable, ...)

General Clauses:

[NO]DATA   [AT r,c] [WIDTH n]
[NO]LABELS [AT r,c] [WIDTH n]
[NO]PROMPT [AT r,c] [WIDTH n] [VARDESC|VARLABEL|VARNAME|VARDOC]
ERROR number 'error text'
The GENERATE command in record or table screens uses the record or table schema to give the equivalent of default FIELD commands for every field. GENERATE in a menu screen produces the equivalent of a default CALL SCREEN to every previously defined record or table screen.

The EXCLUDE and INCLUDE clauses specify fields that are affected or not by the GENERATE and allow specific FIELD commands to be combined with a GENERATE command. When a FIELD command is specified for a variable, the variable should be EXCLUDED from the GENERATE otherwise it appears on the screen twice.

The general clauses on the GENERATE command apply to all fields generated by the command. The DATA, LABELS and PROMPT AT clause refers to the row position of the first field.

EXCLUDE

INCLUDE
SCREENS
VARS

For example, to specify particular options for three fields and then bring in all the remaining fields in the EMPLOYEE record:

SCREEN RECORD EMPLOYEE/COMPANY.EMPLOYEE
TEXT 'This is the Demographic Record' AT +2
FIELD ID PROMPT 'Employee ID:'
FIELD NAME PROMPT 'Name of Employee'
FIELD SSN EDITOUT (COMPUTE FIELDOUT = EDIT    (SSN,"^^^-^^-^^^^"))
          EDITIN  (COMPUTE SSN      = REPLACE (FIELDIN,'-','',LEN(FIELDIN),1,0))
GENERATE EXCLUDE VARS (ID NAME SSN)
END SCREEN

Old Forms

There is an existing SirForms system that is a stand-alone system that uses a character style interface. While the PQLForms commands are different in design and operation, they can resemble old Forms. If comparing the PQLForms commands with old Forms note that:-
  1. The basic syntax in PQLForms is VisualPQL and conforms to VisualPQL rules in terms of names, continuation rules, etc. For example, command continuation lines are recognised by a blank in the first position.
  2. Some old Forms command names have been used but others conflicted with existing VisualPQL commands in that the same command syntax does different things in the two systems. PQLForms commands avoid these conflicts e.g. CALL SCREEN resembles the old Forms CALL; SCREEN RECORD resembles old Forms RECORD.
  3. VisualPQL already contained commands that were equivalent to various functions in old Forms e.g. to define variables, to compute values, etc.
  4. The intention is to use standard VisualPQL wherever possible so many options on commands take standard VisualPQL replacing specific old Forms keywords e.g. the EDITOUT and EDITIN clauses on the FIELD command (instead of keywords such as DSPEDIT); the INITIAL, READ and WRITE clauses on the SCREEN command (instead of keywords such as ACCEPT).
  5. The VisualPQL LOOKUP command approximates this command in old Forms.
  6. The Help system operates for fields. If screen level help is required, use the FBUTTON ACTION to define a help button.
  7. The concept of groups of fields has been dropped.
  8. The concept of separate forms based permissions has been dropped. The same security logins/permissions as for any use of VisualPQL now apply.

homecontents start chapter top of pagebottom of pagenext page index

PQLForms Error Messages

Number  Text
 15     Text too long
 27     Record not found
 30     Record Written
 37     Case not found
 38     No more records
 47     Not a valid value
 56     Not in valid range
 57     Failed Edit tests
110     Record failed write tests
118     Record was modified - OK to save ?

homecontents start chapter top of pagebottom of pagenext page index