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

Field

FIELD

The FIELD command displays the current value of variables on the screen and provides extensive capabilities for editing and validating data values.

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.

When defining custom screens and additional edits, much of the work done by the screen designer is in specifying the various clauses to do with this command. Clauses specified at the Form, Screen, Page and Group levels to apply to all fields within that level.

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

The command is executed when the flow of control moves to it. The sequence of the commands determines the flow of control and this is the sequence followed by the cursor on the screen. The key fields for a record, or the index fields for a table, must be the first fields referenced on a screen. 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.

Syntax

Clauses:

The only required clause on the FIELD command is the name of the variable.

FIELD variableBOOLEAN ( expression ) [OPTIONAL] [NO]DATA [AT r , c] [HILITE | VIDEO video_options] DEFAULT expression DISPLAY ['prompt' | VARDESC | VARLABEL | VARNAME] [VIDEO video_options] DSPEDIT options DSPTYPE options FINAL COMPUTE variable=expression, ... HELP helpscreen | 'help_string' IF ( expression ) INITIAL COMPUTE variable=expression, ... INSERT | OVERSTRIKE LEFT | RIGHT LENGTH min, max LOOKUP options NOECHO PATTERN 'pattern' PICTURE 'picture' PMTEDIT options PMTTYPE options [NO]PROMPT {'string' | VARDESC | VARLABEL | VARNAME } HILITE | VIDEO video_options RANGE (n,m) ['error message'] .... [OPTIONAL] REQUIRED TYPE options VALUELABELS (n [,m]) 'string' WIDTH d,w

`General Clauses:`


ACTIVITIES permissions

AT [r][,c]

[NO]AUTOTAB

CLEAR  'c'

ERROR  message_number  [ VIDEO video_options ]
'error message'

LABELS n

PAD [n][,m]

BOOLEAN

BOOLEAN ( expression ) [OPTIONAL]
Specifies a logical expression that must be true for data to be accepted into the field. After the field has been entered, the expression is evaluated and, if false, an error message (Error 57) is issued and the cursor remains at the field.

If OPTIONAL is specified, and the logical expression is false, an error message is displayed to alert the user. The user can modify or accept the field before moving to the next field. If OPTIONAL is not specified, the user cannot accept a field which fails the test.

Example: To specify that an entry for BIRTHDAY is acceptable only if it falls within the last week, specify:

FIELD BIRTHDAY BOOLEAN  -
      (BIRTHDAY GE (TODAY(0)-7) AND BIRTHDAY LE TODAY(0))

DATA

[NO]DATA [ AT r,c] [ HILITE | VIDEO video_options ]
Specifies attributes for the data area of a field. NODATA suppresses the data area of the field. If NODATA and NOPROMPT are specified nothing is displayed and the cursor position remains unchanged.

AT

specifies the starting position (row and column) of data area of field. See

HILITE

specifies the video treatment when cursor is in field. VIDEO

specifies the video treatment of field at other times. See

video treatment

Example: Highlight the field with bold video when the cursor is positioned in the field. Position the data area below the prompt area.
FIELD BIRTHDAY DATA HILITE BOLD AT +1

The "AT + 1" option on the DATA clause positions the data area only. The data area is positioned on the next line, and the column position is not changed. If the "AT + 1" was specified as a clause on the FIELD instead of as a sub-clause on DATA, it would position both the prompt and the data.

DEFAULT

DEFAULT expression
Specifies the default value for a field on a new record if the user skips the field. Any arithmetic expression, function or constant can be used.

Example: Set the default for BIRTHDAY to today's date.
FIELD BIRTHDAY DEFAULT TODAY(0)

DISPLAY

DISPLAY  ['prompt string' | VARDESC | VARLABEL | VARNAME]
         [VIDEO video_options]

Specifies that the field is display only. It cannot be modified nor can new data be entered. The options on DISPLAY control the prompt and are the same as the PROMPT clause.

prompt string

Specifies a string that is used as the prompt. VARDESC

Specifies that the variable name and label are used as the prompt string. VARLABEL

Specifies that the variable label is used as the prompt string. This is the default. VARNAME

Specifies that the variable name is used as the prompt string. VIDEO

Specifies the video treatment of the prompt field. Because the cursor never goes to a display field, only the VIDEO clause is applicable. See

video treatment

DSPEDIT

DSPEDIT
   CAPITALIZE
   EDIT 'edit_template'
   LEADING 'leading_string'
   LEFT | RIGHT [FILL 'fill_character']
   LOWERCASE
   MASK {COMMA | DOLLAR | PERCENT}
   MONEY
   SCALE n
   STRIP 'string'
   TRAILING 'trailing_string'
   TRUNCATE n
   UPPERCASE

Specifies display edits. DSPEDIT alters the way the field is displayed. If an error occurs in the execution of the DSPEDIT, an error message is issued and the field is filled with X's. Use the TYPE clause to increase the field length to accommodate extra characters.

If the user edits the field, the displayed field, including any characters added or taken out by the display edit, become the input. This must be dealt with, either by the user clearing the field when editing or by an appropriate PMTEDIT clause.

CAPITALIZE

Specifies that the first character and every character following a blank, is changed to upper case. Other characters are unchanged. EDIT

Specifies an "edit template". Specify characters to display and use the circumflex (^) to represent a character of data to achieve the desired format. Characters are displayed as they appear in the template intermixed with data. Strings are left-justified, numerics are right-justified.

FILL

LEADING

Specifies a character string prefixed to the data. LEFT

FILL

RIGHT

FILL

Specifies a single "fill" character. Enclose the character in quotes. Blank is the default. LOWERCASE

MASK

COMMA

DOLLAR

PERCENT

MONEY

DOLLAR

COMMA

SCALE

Specifies a constant "n" by which the data value is multiplied.

Note:

SCALE 1

STRIP

Specifies a set of characters removed from a field before it is displayed. Each character is stripped out as a single character. Enclose the list of characters or each individual character in single quotes. TRAILING

Specifies a character string appended to the data before it is displayed. Enclose the characters in single quotes. TRUNCATE

Specifies that the field is truncated to "n" characters. UPPERCASE

Specifies that all characters are converted to uppercase. Example: The following template can be used to display a social security number in the format ddd-dd-dddd:

FIELD SSN -
      DSPEDIT EDIT '^^^-^^-^^^^'

DSPTYPE

DSPTYPE
   DATE      'date_format'
   EREAL     n  ,m
   INTEGER   n [,m]
   REAL      n  ,m
   STRING    n
   TIME      'time_map'
   ZINTEGER  n  [,m]

Specifies the type of a field for display. Specify one of the following:

DATE

FIELD BIRTH DSPTYPE DATE 'MM/DD/YY'

EREAL

TYPE

INTEGER

Integer number n columns wide, zero filled to m columns wide. REAL

Real number n columns wide with m decimal places. STRING

String variable n characters wide. TIME

DECLARE

FORM

ZINTEGER

INTEGER

ZINTEGER

FINAL

FINAL  COMPUTE           variable = expression, ...
       IF ( expression ) variable = expression, ...

Specifies one or more variables computed when the user leaves the field.

Specify multiple COMPUTE and IF statements if required; only specify the keyword FINAL once. If multiple COMPUTE and IF clauses are used, use commas as delimiters between clauses.

Use COMPUTE to compute a variable.

Use IF to compute a variable under particular conditions. When the IF clause is used, variables are computed only when the expression following the IF clause is true. The expression can be enclosed in parentheses if desired.

HELP

HELP screen_name | 'help_string'
Specifies a text string or the name of a help screen to display when help for a specific field is requested by the user.

When the user requests help, if a screen name is specified, that help screen is displayed; if a text string is specified, the string is displayed on the status line at the bottom of the screen.

IF

IF ( logical_expression )
Specify an IF clause to control whether the cursor moves to the field for data entry. If the expression is true, the cursor moves into the field and data can be entered. If the expression is false, the cursor skips over the field and data cannot be entered.

Example: Allow monthly rent to be entered if OWNHOME is not equal to 1.
FIELD MONRENT IF (OWNHOME NE 1)

INITIAL

INITIAL COMPUTE           variable = expression, ...
        IF ( expression)  variable = expression, ...

Specifies one or more variables computed when the cursor moves to the field.

Specify multiple COMPUTE and IF statements if required; only specify the keyword INITIAL once. If more than one clause is used, use commas as delimiters between clauses.

Variables can be computed using the COMPUTE clause or conditionally computed using the IF clause. When the IF clause is used, variables are computed only when the expression following the IF clause is true.

INSERT | OVERSTRIKE

Specifies that insert or overstrike mode is in effect for this field. Insert specifies that new characters are inserted before the character at the cursor position; overstrike specifies that the character at the current cursor position is overwritten. The user can toggle between these modes. This clause sets the initial mode. Insert is the default for multiple character fields; overstrike is the default for single character fields.

LEFT | RIGHT

Specifies that the cursor is initially at the leftmost character or the rightmost character of the field. Left is the default.

LENGTH

LENGTH min , max
Specifies the minimum and maximum length (in characters) of a field. If the user enters fewer characters than the minimum or more characters than the maximum, an error message is issued.

LOOKUP

LOOKUP {lookup expression}
      [NOT]ON screen  [/database.record | /tabfile.table]
      BACKWARDS  n | FORWARDS  n
      ERROR  nnn 'message'
      IF ( expression )
      IN destination_expression
      LOCK locktype
      OPTIONAL | REQUIRED
      REPORT 'message'
      RETURNING expression, ...  TO variable, ...
      USING caseid  [ * ] | [ key, ...]
      VIA             *   |   key, ...

Uses another screen to locate a record. Use LOOKUP to establish the presence or absence of a record or to retrieve data from the record that is looked up. Use LOOKUP to verify the field data by testing stored value(s) in a record. LOOKUP can perform a number of functions:

It can test whether a specified record is present. Specify the keys of the record with USING or VIA clauses. If keys are not specified, the first record of that type is used.
It can test whether a specified record is not present. Specify the keys of the record with the USING or VIA clauses.
It can test the presence or absence of one of a set of records or of the nth record. Specify a partial key and the data is searched (forwards or backwards) from the point where the specified keys start.

It can test the current field to be equal to a variable in another record.

It can test an expression composed of fields from this record against an expression composed of variables from another record.

It can retrieve data from another record into variables in this record or into temporary variables. lookup expression

IN

DOSAGE,

FIELD DOSAGE -
      LOOKUP DOSAGE*QTY ON DRUGREF -
      USING -1,DRUGID IN MAXDOSE

[NOT]ON

ON

NOTON

screen name.

ON

NOTON checks that no records matching the search criteria exist. NOTON returns an error message if a record matching the search criteria is found.

For example, when adding new people, the social security number could be tested to be NOTON an inverted list of current social security numbers.

BACKWARDS n|
FORWARDS n

USING

VIA

FORWARD.

ERROR nnn

Specifies alternative text for error messages.
59 is "Lookup Failure"; 60 is "Lookup Warning".

IF

LOOKUP

IN

Specifies an expression which is tested against the current field or the source expression. If a match is not found, an error message is issued. Use variables from the screen being looked up.

If a full key is specified with a VIA or USING, IN tests on that record. If a partial key is specified, the set of records is searched for a match. If a number is specified on FORWARDS or BACKWARDS, the nth matching record is used.

LOCK

Specifies the

lock

OPTIONAL |
REQUIRED

REQUIRED

OPTIONAL

REQUIRED

REPORT

TO

TO

TO

TO

USING

LOOKUP

VIA

USING

VIA

TABLE

IN

FORWARD

BACKWARDS

Lookup examples:

A) This checks that a record (LOCREC) exists with a case id of -1 that has a key of LOCATION and gives an error message if the record is not there. The lookup screen is also called LOCREC and is in the form definition solely to be used as a lookup. It has just the keys defined and is never displayed.

FIELD LOCATION -
      LOOKUP ON LOCREC USING -1, LOCATION-
      ERROR 59 'Invalid Location Code - Please Re-enter'
..
RECORD LOCREC / COMPANY.LOCREC
  field ID
END RECORD

B) This checks for the opposite condition from A, that the record does not already exist and gives an error message if this is not a new location.

FIELD LOCATION LOOKUP NOTON LOCREC USING -1, LOCATION -
      ERROR 59 'Location Code Already Exists - Please Re-enter'

C) This checks the record is present and that STATUS ( a field on the location record) equals 1.

FIELD LOCATION 1 LOOKUP ON LOCREC USING -1, LOCATION-
      IN STATUS -
      ERROR 59 'Location Not Found or Not Active'

D) This returns the location status to a temporary field XSTATUS (which has been DECLAREd on the FORM command) and then displays the result.

FIELD LOCATION LOOKUP ON LOCREC USING -1, LOCATION-
      RETURNING STATUS to XSTATUS -
      ERROR 59 'Invalid Location Code - Please Re-enter'
FIELD XSTATUS DISPLAY 'Location Status'

If the screen which referenced the record LOCREC had a different name, say XLOCREC, for some reason, the lookup clause must name both the record and screen name:

RECORD XLOCREC / COMPANY.LOCREC
FIELD LOCATION LOOKUP ON XLOCREC / COMPANY.LOCREC

NOECHO

NOECHO
NOECHO suppresses the display of input for a field as it is entered and subsequent displays of the data portion of the field.

PATTERN

PATTERN 'edit pattern'
PATTERN specifies an edit for validating input data. If the value matches the pattern, the value is accepted. If it does not match, an error message is issued (Error 113) and the value is not accepted. An edit pattern is specified as characters that must match exactly and the percent sign (%), which indicates that from zero to 'n' characters are not tested. Character codes, such as those on the PICTURE clause, are not used. Both PATTERN and PICTURE clauses can be specified for the same field.

Example:
PATTERN '%-%'
PATTERN '%-%-%'
PATTERN 'E%/%E'
The first example tests that the input has a "-" somewhere in it. The second tests that there are two "-", possibly separated by other characters. The third example tests that the input begins and ends with an "E" and has a "/" somewhere in the middle.

PICTURE

PICTURE 'picture string'
PICTURE specifies a picture string for validating user input. The data is accepted when the value entered by the user matches the picture. If it does not match, an error message (Error 16) is issued and the data is not accepted. Any picture specifications are added to the default help screen for the field.

The picture must be the same length as the input field. When changing the length of the field to match the picture, the TYPE clause must precede the PICTURE clause.

The picture is composed of characters that must be matched exactly and character codes for each position in the input string. The character codes are:


a any letter
d any digit
n any letter or digit
s a
numeric value (0-9, decimal point, +, -, E)
u any uppercase letter
l any
lowercase letter
x any character

Using uppercase or lowercase for the codes determines whether or not blanks are also allowed. Codes in lowercase specify that blanks are not allowed. Codes in uppercase allow either the specified character type or a blank. For example, "A" indicates any letter or a blank; "D" indicates any digit or a blank; and so on. "x" matches anything except blank; "X" matches anything.

Example: The following PICTURE clause validates input of a social security number. The expected picture is 3 digits, a dash, 2 digits, a dash, and 4 digits (eg., 123-54-6789).
PICTURE 'ddd-dd-dddd'

PMTEDIT

PMTEDIT
    CAPITALIZE
    EDIT 'edit_template'
    LEADING 'leading_string'
    LEFT | RIGHT [FILL 'fill_character']
    LOWERCASE
    MONEY
    SCALE n
    STRIP 'strip_string'
    TRAILING 'trailing_string'
    TRUNCATE n
    UPPERCASE

The PMTEDIT clause specifies permanent edits (PerManenT EDITs) that are applied to the value in the variable. The value entered is edited according to the specified options and the edited value is stored in the database. The editing also updates the data on the screen. These edits are applied to the field whenever it is modified.

If the user inputs a field once and then edits it for input again without clearing it completely and re-entering it, this may cause problems. PMTEDIT updates the field and, once the field is edited and re-input, all characters are read again. A PMTEDIT such as LOWERCASE is no problem because making a field lowercase twice does not impact it; however clauses such as EDIT, LEADING, SCALE and TRAILING, all update the field. If the field is edited again, these clauses are applied again and may give unexpected results.

Any edits applied to a numeric field must produce a resulting legal numeric value (digits, a plus or minus character and/or a decimal point).

CAPITALIZE

Specifies that the first character of the string and every character following a blank is capitalised. Other characters are unaffected.

EDIT

Specifies a template that is used to edit the data. The circumflex ( ^ ) represents one character of the data value. Any other characters are inserted exactly as they appear in the template. The number of circumflex determines how many characters are going to be able to be entered. LEADING

Specifies a character string that is prefixed to the data. LEFT

FILL

RIGHT

Specifies that the entered characters are right-justified. Any unoccupied field positions are filled with the FILL character.

FILL

Specifies the fill character. Blank is the default fill character. LOWERCASE

LOWERCASE

CAPITALIZE

MONEY

Specifies that the dollar sign ($) and commas associated with a numeric field are removed. If MONEY is not specified, dollar sign and commas are illegal in a numeric field. Increase the width of the field with the TYPE clause to allow for these characters.

SCALE

Specifies a constant "n" by which a numeric value is multiplied. If the field is defined as a scaled variable in the schema, a scale factor of 1 specifies that the dictionary scaling is applied. STRIP

Specifies characters to be stripped from the field. Each character is treated as a single character and is stripped from the string wherever it occurs.

TRAILING

Specifies a character string that is appended to the field. TRUNCATE

Specifies that the field is truncated to "n" characters. UPPERCASE

Specifies that the field is converted to uppercase. Example: A field for entering a social security number may be defined with hyphens or slashes. The following strip clause removes these:
field SS pmtedit strip '-/'

PMTTYPE

PMTTYPE
    DATE     'date_format'
    EREAL    n , m
    INTEGER  n
    REAL     n , m
    STRING   n
    TIME     'time_map'

PMTTYPE changes the type and width of a field. When a variable is defined in the database or in a table, it can have a standard external format. For example, an integer might be defined as 4 characters long. The PMTTYPE allows for additional field positions which are not stripped out by one of the edit clauses.

(The DSPTYPE changes the width of the display field but not the number of digits. This allows for additional characters such as dollar signs or other edit characters.) The TYPE clause changes both the DSPTYPE and the PMTTYPE.

Fields cannot be changed from numeric to string or vice versa with this clause. To specify a DATE or TIME type for a temporary variable, declare the variable as real on the DECLARE clause of the FORM command.

DATE

Specifies a date integer described by a date format. EREAL

EREAL

INTEGER

Specifies a integer number n columns wide REAL

Specifies a real number n columns wide with m decimal places STRING

Specifies a string variable n characters wide TIME

Specifies a time variable described by a time format

PROMPT

[NO]PROMPT  [ 'prompt-string' | VARDESC | VARLABEL | VARNAME
              HILITE | VIDEO video_options
              AT [r] [,c]  ]

PROMPT specifies how the prompt for this field is displayed. NOPROMPT suppresses the prompt for the field. If both NOPROMPT and NODATA are specified, nothing is displayed and the cursor position remains unchanged.

prompt string

Specifies the prompt. VARDESC

Specifies that the variable name and label are the prompt. VARLABEL

Specifies that the variable label is the prompt. This is the default. VARNAME

Specifies that the variable name is the prompt. HILITE

Specifies the video attributes when the cursor is at this field. VIDEO

Specifies the video options when the cursor is not at this field (See

video treatment

AT

RANGE

RANGE (value1 [,value2])  ['error message']
      (value3 [,value4])  ['error message'] ...  [OPTIONAL]

RANGE (or RANGES) specifies ranges for edit checking. Ranges must be within any valid ranges specified for the variable on the data dictionary. The values specified can be constants or the keywords LO or HI meaning the lower and upper valid value respectively. Variable names or expressions are not allowed.

If the value entered is within a range, the value is accepted and the cursor moves on to the next field. If the value entered is within a range with a message, the message is issued and the user has a chance to correct or accept the value. If the value entered is outside all ranges, an error message is issued and the value is rejected unless OPTIONAL is specified. This allows the user to accept a value outside any of the ranges specified here. The user cannot enter a value outside any ranges specified in the data dictionary. Specify OPTIONAL once, after the final range.

Multiple ranges can be specified. The ranges must be in ascending order and cannot overlap.

Example: HEIGHT is defined in the data dictionary with the range 48 to 84 inches. The RANGE is specified to warn the user when values below 60 or above 78 inches are entered.

FIELD HEIGHT -
      RANGES    (LO, 60) 'Are you sure they are this short ?'-
                (61, 78)  -
                (79, HI) 'Are you sure they are this tall ?'

REQUIRED

REQUIRED
Specifies that the field is required. The user cannot skip this field and cannot go on to the next field without entering data. The user cannot clear a required field. If the required field is within a group, the group can be skipped but the user cannot save a record having skipped any required fields. (Error message 20)

Keys are required by default and need not be specified as REQUIRED.

Example : To ensure that the variable NAME is always entered:
FIELD NAME REQUIRED

This tests that the user has entered a value. This value may be blanks since blanks is a valid character string and is a valid missing value. To exclude blank names as well:

FIELD NAME REQUIRED -
      BOOLEAN (EXISTS(NAME)) -
      Error 57 'You must enter a name for an employee' -
      Error 20 'You must enter a name for an employee'

TYPE

TYPE
    DATE     'date_format'
    EREAL    n   , m
    INTEGER  n [ , m ]
    REAL     n   , m
    STRING   n
    TIME     'time_map'
    ZINTEGER n [ , m ]

Specifies the type and width of the field. The default is the data dictionary definition. TYPE does not affect the way the variable is stored in the database; it is always stored according to the data dictionary. The following types can be defined:

DATE

Specifies a date variable described by a date format. If a DATE type is specified for a temporary variable, that variable must be declared as real on the DECLARE clause on the FORM command.

EREAL

INTEGER

Specifies an integer number n columns wide, zero filled to m columns wide. REAL

Specifies a real number n columns wide with m decimal places. STRING

Specifies a string variable n characters wide. TIME

TIME

DECLARE

FORM

ZINTEGER

INTEGER

ZINTEGER

VALUELABELS

VALUELABELS ( value [ , value ] ) [ 'string' ], . . .
Specifies value labels for variables. If a variable is a temporary variable or does not have value labels, the VALUELABELS clause provides a means of defining them. If a variable already has value labels defined in the database, the VALUELABELS clause provides alternatives.

Example: To specify value labels for a temporary variable named AGECAT (age category):
For values 1 through 3, display "Children".
For values 4 through 6, display "Young Adults".
For values 7 through 9, display "Adults".

FIELD  AGECAT -
       VALUELABELS (1 ,3) 'Children' -
                   (4 ,6) 'Young Adults' -
                   (7 ,9) 'Adults'

WIDTH

WIDTH d,w
Specifies the display width d, and the total width w. The display width is the width seen on the screen, the total width is the maximum number of characters that can be entered.

For string fields only, if the total width is larger than the display width, the user can scroll horizontally through the field with the right and left arrows. This allows entry, editing and display of long strings in a limited area of the screen.