Input Fields

The Input Fields (IN F) statement uses the capabilities of full screen processing to set up fields for input and to accept input from anywhere on the screen. The input fields may utilize a wide variety of display and control attributes. In addition, the Input Fields statement uses the capabilities of field help windows to set up help messages for any or all of the fields it defines.

Update to Input Fields: ^KeyStroke and ^DataChg.

See also: Format Specifications.

See (4.3) Text format.

Comments and Examples

Input Fields accepts data from anywhere on the screen except the status line. One field or several fields may be entered with the INPUT FIELDS statement.

PRINT FIELDS, INPUT FIELDS, RINPUT FIELDS, INPUT SELECT and RINPUT SELECT all utilize full screen processing and field help windows. See the Screen I/O for examples common to all of these statements.

Input Across Multiple Windows

As of 4.3, BR allows for input across multiple windows, as in the following example:

00010  (R)INPUT FIELDS  #121: “10, 10, C 20, UH; 10, 12, PIC(##/##/##), UH;#124,10, 10, C 30, UH”: aaa$, bbb$, ccc$

This will input the first two fields on window #121 and the third field on window #124. The ‘#window-number,’ prefix may appear in any row or col FIELDS specification and overrides the window number that follows the PRINT/INPUT/RINPUT keyword.

Syntax

INPUT [#<window number>,] FIELDS {MAT< string array>|<string expression>|"<field spec>[;...]"} [,ATTR "<attributes>"|<string expression>] [,HELP <string expression>|MAT< array name>|"<helpstring>[;...]"] : {<variable name>|MAT< array name>}[,...] [<error condition> <line ref>][,...]

Parameters

See also Screen I/O for a continued description of the parameters for INPUT FIELDS.

"#Win-num," is an optional parameter to specify the number of the window the INPUT FIELDS will work with. If none is selected, the fields remain the default screen. The number must be between a (#) and a comma.

This syntax also works for the INPUT SELECT statement.

Mat string array, string expression, and "field spec" are used to identify the fields used. See also Field specs.

The "ATTR" keyword identifies that a separate set of attributes should be used for the current input field. It must be followed by either the "attributes" parameter or the "string expression" parameter. "Attributes" represents an insertable syntax that identifies the monochrome, color and control attributes that are to be used for the field. See Attribute (Screen) for details. If used, the value of "string expression" must include the same elements as are required in the "attributes" parameter.

Following the HELP parameter, if the "string-expr" or "MAT string-array" parameters are used to specify field help text, each must include the same elements that are identified in the "helpstring" specification. Business Rules assumes that multiple field help specifications will be identified in the same field order which is indicated in the field definition string.

"Variable name" or "MAT array-name" identifies the information that is to be input or output by the statement. A colon (:) must separate this from any previous parameters in the statement. At least one "var-name" or "MAT array-name" must be specified and multiple variables must be separated by commas

The "error-cond" portion of the parameter identifies the error to be trapped, and the "line-ref" portion identifies the line to which execution should be transferred when such an error is trapped.

As of 4.3, the TEXT parameter is available too.

^KeyStroke and ^DataChg

As of 4.30, two new INPUT FIELDS field attributes are now supported which provide detailed control of user input:

• ^KEYSTROKE - return control to the program when a keystroke is entered
• ^DATACHG - return control to the program when data is changed

(a subset of ^KEYSTROKE)

When control is returned to a program as a result of these attributes, one of three new Fkey values is applied:

• 140 - a character was appended to the data
• 141 - the data changed other than appending a character
• 142 - ( applies only to ^KEYSTROKE ) the data is unchanged but a key was pressed or a mouse action occurred that did not trigger a field exit

When a key is pressed with ^KEYSTROKE or ^DATACHG that sets a 140, 141 or 142 FKEY, it will also set the KStat$ value. This allows the program to see what key was pressed. This KSTAT$ value will be cleared on the next RINPUT Fields operation.

If a navigation key operates within the field and ^KEYSTROKE is specified, it triggers fkey 142. If the navigation key causes focus to leave the field, fkeys 140-142 are not generated and KSTAT is not set.

Note

While shift, control and alt do not change either the functionality or fkey value of navigation keys, KSTAT$ produces unique values for each of these settings. This complicates things a bit but provides more options for programmed responses to custom key combinations.

Supplemental Syntax ("field-spec" parameter)

See Field Specs for more information, including syntax parameters. In the place of PIC, #PIC or Text could be used. #PIC allows numeric data from a string to be used, while Text forms a text box for input.

Supplemental Syntax ("helpstring")

See Field Help for additional information, including syntax parameters.

Defaults

1.) Display to and input from the screen.

2.) Do not alter attribute when field is current.

3.) Do not display field help text.

4.) Interrupt the program if an error occurs and "ON error" is not active.

5.) Fraction length = 0.

6.) Maximum DIM length.

7.) Use current attributes.

8.) Center window above field.

9.) R if possible; attempt B, L, then A if necessary.

Technical Considerations

1.) Relevant error conditions are: CONV, ERROR, EXIT, HELP, IOERR, and SOFLOW.

2.) When OPTION INVP is in effect, normal input of commas and periods is interchanged in PIC, N, NZ, L, G and GZ format specifications to support European- style numbers.

3.) There may be more or fewer fields identified in the helpstring than there are defined in the full screen processing statement.

4.) See Functions for information about CNT, which applies to errors in field definition arrays used in full screen processing. CNT returns the number of the last successfully processed variable or the last successfully compiled element of the array.

5.) See CURFLD, which returns the relative number of the field containing the cursor from the last INPUT FIELDS statement.

6.) When PIC is used with INPUT FIELDS for numeric input and all digit specifiers are "#", the cursor will automatically skip over non-numeric characters which are displayed in the field. In the following example, line 20 creates an output field of eight positions, but the operator will only be able to key in the six numeric positions:

00020 INPUT FIELDS "5,10,PIC(##/##/##),r": D

7.) Uppercase or lowercase conversion upon input is available when the C, V or G format specifications are followed by either a U (convert to uppercase) or an L (convert to lowercase). See the CL, CU, GL, GU, VL and VU format specifications in File I/O for more information.

8.) When RETRY is executed after an error has occurred in an INPUT FIELDS statement, the cursor is automatically positioned at the start of the field which caused the error.

9.) Keyboard buffering operates identically for INPUT FIELDS as it does for INPUT. Buffering may be turned on or off with the BRConfig.sys file TYPEAHEAD specification.

10) Using an alpha character for field length in INPUT FIELDS or PRINT FIELDS will now produce an error. Previously the characters as well as the attributes following it were being ignored. (This may affect your programs). Extraneous characters in attribute specifications will still be ignored.

11.) The FMT specification is now supported for validating and formatting of entered data. See "FMT" Spec in the Format Specifications section for complete information.

12.) A special hot-key value (trailing attribute spec in FIELDS operation) of 10000 denotes the Enter key, and generates a zero fkey value.

13.) Hot field fkey values may now be in the ranges

• 1-128 (Note - 90-99 may be assigned special functions in BR.)
  
• 1000-9999

14.)Use INPUT FIELDS ... NOWAIT to raise a TAB.

15.) The ATTR parameter in FIELDS and SELECT statements now accepts MAT variables. This feature allows for a different "current" attribute for each input field. Thus if using INPUT SELECT to select many items from a list, the non-current and current attributes may be different for both selected and un-selected items. NOTE the following sample syntax:

00100 INPUT FIELDS MAT F$, ATTR MAT FF$:MAT DATA$

MAT FF$ is compiled for attributes ONLY, and stops at the end of the array or the first error. If there are not enough attributes for each entry field, the first one will be used. For an example of this feature in action, enter and execute the following sample program:

00100 ! matattr ! example of ATTR MAT attrs specification
00110 PRINT NEWPAGE
00120 PRINT FIELDS "1,2,c 30,/RGBH:R": "[F6]-End selections"
00130 DIM ATTRS$(15),SPEC$(15),DATA$(15)*8
00140 FOR I=1 TO UDIM(ATTRS$) ! set up mats
00150 LET ATTRS$(I)="U/RGB:R"
00160 LET SPEC$(I)=STR$(I+3)&",10,c 8,N/RGB"
00170 READ DATA$(I) : LET SEL$=SEL$&" "
00180 NEXT I
00190 DATA "One","Two","Three","Four","Five","Six","Seven","Eight","Nine","Ten","Eleven","Twelve","Thirteen","Fourteen","Fifteen"
00200 RINPUT SELECT MAT SPEC$,ATTR MAT ATTRS$: MAT DATA$
00210 IF CMDKEY>0 THEN GOTO 250
00220 LET ATTRS$(CURFLD)="HU/RGBH:R" : LET CURFLD(CURFLD) : LET  
SPEC$(CURFLD)=SREP$(SPEC$(CURFLD),",N/RGB",",UHR/HRGB") !:! change attributes  of selections
00230 LET SEL$(CURFLD:CURFLD)="x" ! could reverse logic of prev. line to   unselect
00240 GOTO 200
00250 !
00260 FOR I=1 TO LEN(SEL$)
00270 IF SEL$(I:I)<>" " THEN PRINT DATA$(I);" ";
00280 NEXT I

Window On A Field

The ability to enter and process more text than a window field can display at one time is included. This lays the groundwork for supporting proportional fonts. You can, for example, enter and maintain fifty characters of data in a ten character window field on any platform.

The syntax for enabling this capability is:

INPUT FIELDS "xx,yy,8/C 12,UH": name$

Which enables up to 12 characters to be entered into an 8 character window field.

This syntax was changed in version 4.17. Formerly, a window on a field syntax was "xx,yy,C 8/12,UH":name$

Mat Grouping

MAT grouping is allowed in all full screen-processing statements. This allows you to indicate that input or output should alternate between all MAT variables which are specified within parentheses in the I/O list.

In the following code fragment, the A$ variable identifies the positions on the screen from which input values should be drawn. Business Rules will assign the first input value to the first element of B$. However, because the B$ and C matrices are specified within parentheses, it will then assign the second input value to the first element of C. The third value will go to B$, the fourth to C, and so on until both matrices are fully assigned. The last input value will go to X$.

00020 INPUT FIELDS A$: (MAT B$,MAT C),X$

Without MAT grouping, the above line must be coded as follows in order to achieve the same results (this example assumes that B$ and C have each been dimensioned for five elements):

00020 INPUT FIELDS A$: B$(1),C(1),B$(2),C(2),B$(3),C(3),B$(4),C(4),B$(5),C(5),X$

MAT grouping is a lot easier to code, executes faster, and most importantly, it handles much larger arrays than are possible without using MAT grouping, as the resulting compiled line takes up less space in memory. The number of matrices that can be grouped together is 62, which in practical terms is unlimited. All matrices in a group must have the same number of elements per matrix, or an error 0106 will result. Only MAT variables may be used in such groupings.

Also see Error 0106 in ERROR CODES for additional information.

Timeout (Wait) Processing

The WAIT= parameter and TIMEOUT error trap may now be used with INPUT/RINPUT statements to force releasing of records. This feature is useful for multi-user situations.

WAIT= specifies the number of seconds the system should wait for operator input before responding with a TIMEOUT error condition. Note that WAIT=0 instructs the system to wait for zero seconds, not to ignore the WAIT instruction. Also, -1 is a special WAIT value that instructs the system to wait forever, if necessary. Every time the operator presses any key, the clock is reset for WAIT seconds.

00100 INPUT WAIT=10:X$ TIMEOUT 100
00110 RINPUT WAIT=10:X$ TIMEOUT 100
00120 LINPUT WAIT=10:X$ TIMEOUT 100
00130 INPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
00140 INPUT #11,FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
00150 RINPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
00160 INPUT SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100
00170 RINPUT #11,SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100

The TIMEOUT error condition traps time-out errors (error code 4145) and specifies the line number of an appropriate error- handling routine.

0100 RELEASE #ITEM:
00110 PRINT "OVER TIME LIMIT"
00120 PRINT "Your hold on inventory items has expired, re-enter order."

Before releasing the record, you may want to go to a routine that warns with a message and a few beeps that the hold on records is about to be released, then gives the operator an opportunity to continue data entry. See the KStat$ internal function for information on how to use the WAIT parameter with that function.

Feature Deletion

Formerly the FIELDS trailing attribute supported specification of an X'xx' scancode. This caused considerable confusion because the value produced was translated to its functional equivalent for fkey purposes (e.g. X'02' became fkey 90 - pgup).

This hex scancode capability has been removed as of this release.

It is necessary to specify only numeric values for trailing attribute hot key values. These values correspond to FKEY results that are produced by clicking on the hot field.

NxtRow, Next and NxtCol

The NxtRow, Next, and NxtCol internal functions we're introduced, and compatible with INPUT FIELDS, in BR! 4.20.

Next, NxtRow and NxtCol

The keyword Next can be used in the same manner as CUR in that the next cursor position within a 2D control can be identified.

00100 INPUT FIELDS "row,col,GRID 10/60, SUB, NEXT, NOWAIT": next_pos

The NxtRow is an internal function that identifies the character position or cell row associated with the next cursor position (e.g. where the mouse was last clicked). If the next cursor position is in a 2D control, then NxtRow specifies the row of the cell within the 2D control. If not it specifies the first character position of the next control to receive focus.

NxtCol specifies the column of the respective position.

With respect to these functions, the next cursor position can be the result of keyboard or mouse activity. If the next position results from keyboard activity then NxtRow has the same value as CurRow when Enter is pressed or control was returned in response to a leading attribute such as X (return control upon exit). When the mouse is used to return control to a program, the next cursor position is the pointer location that is double clicked or hot location that is single clicked.

One key concept here is that just as one must keep track of what type of control was last accessed, by means other than CurRow and CurCol, similarly **one must determine the type of control to be next accessed by means other than NxtRow and NxtCol**. This can be done with the system function NxtFld plus hotkey event (fkey) numbers.