View source for 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.

See also: [[Screen Attribute]]

===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.

===Syntax===
[[Image:InputFields.png|900px]]

Note that in the "field-spec" and "helpstring" parts, multiple values are separated by semi-colons and are placed within the quotation marks together (i.e. "item;item;item"). In the  MAT array-name part, multiple values are separated by commas and there are no quotation marks.

===Parameters===
See also [[Screen I/O]] for complete descriptions 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 an asterisks 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 variables used.

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 [[Definitions]] for the insertable syntax and additional information. 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.

Following the colon, Variable name or Mat array-name specify which variables the entered information is under. 

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.

===Supplemental Syntax ("field-spec" parameter)===
[[Image:InputFields2.png|800px]]

==="field-spec" Parameters===
{{Input Fields Parameters}}

===Supplemental Syntax ("helpstring")===
[[file:InputFields3.png|800px]]

==="Helpstring" Parameters===
The above syntax may be inserted where the "helpstring" parameter appears in the main diagram for full screen processing statements. It determines window placement.

The "1", "2" and "3" parameters denote the user level for which the field should be automatically displayed. (This option works in conjunction with the BRconfig.sys file's USERLEVEL specification.)

(a) A specification of "1" would indicate that the information provided in this field help text is very important and it should be automatically displayed to most users -even those who are experienced.
(b) A specification of "2" would indicate that the information should be automatically displayed to anybody who is at an intermediate level (or less) of experience with the software.
(c) A specification of "3" indicates that the information should be automatically displayed only to novice users of the software. Automatic display of all field help text, regardless of the user level specified here, can be turned off when the BRconfig.sys file's USERLEVEL specification is set to 0. 

Field help text remains available to all users, even if it isn't automatically displayed to them, when they press the <HELP> key. (Pressing <HELP> a second time initiates regular help processing.)

The next block of parameters identifies the placement of the window that is to
display the field help text. The letter parameters correlate to the following
meaning:
"A" is above the field
"B" is below the field
"L" is to the left of the field
"R" is to the right of the field

A greater-than (>) or less-than (<) sign may be specified along with either A or B.

Greater-than (points to the right) specifies that the window is to be placed flush right with the field. Less-than (points to the left) specifies flush left placement. When neither sign is specified, the window is centered above or below the field. Business Rules always attempts to use the specified placement instructions. However, if the amount of room on the screen does not permit this, default placement will occur.

The "int" parameter may also be used to identify window position. It allows field help windows to directly interact with I/O windows. "Int" represents an integer from 1 to 127 (inclusive) that identifies the number of an open window file. It causes the field help text to be sent to a window which is already displayed on the screen. If the number specified is not a valid window file, default field help window placement will occur.

Use of the "int" parameter can result in two major screen optimizations:
(a) it significantly reduces the number of times that the screen is repainted
(rather than displaying a different window for each field, Business Rules just
displays the open window),
(b) it causes Business Rules to rewrite the contents of the window only when
necessary (thus when the cursor moves between two fields with the same
help text, no rewrite occurs).
"Int" is particularly desirable for Unix / Linux terminals, especially when large amounts of text are being repeatedly displayed.

The "sep" parameter represents a non-numeric and non- alphabetic character that will be used as a separator. The character which is used may not appear within the help text. ADS recommends the use of a semi-colon (;) for this separator if it is not required in the text. The same character which is used as the "sep" before the text must also be specified as the "sep" after the text.

The "text" parameter represents the field help information that is to be displayed to the user. Business Rules automatically determines the width and height of the window according to the width of the lines and the number of rows of text that are specified for this parameter. The new-line character (CHR$(10)) or a backslash and lowercase n () may be used to indicate the start of a new line of text. The maximum line length for field help text is 78 characters. An error will occur when lines longer than this are specified. Although Business Rules displays up to 1000 characters of text in a field help window, 100 characters should be considered a more practical limit.

The "X" parameter denotes a field for which there is to be no help text. It may be repeated as many times as are necessary. If you wish to provide help text for
only the fourth field, you would begin the helpstring specification with "XXX" to denote that there is no field help for the first three fields.

The "field-num" parameter may be used to specify the same text that has already
been identified for an earlier field. Only backward references are allowed. "Fieldnum" represents the number of the field for which text has already been
specified; it must be preceded by an ampersand (&) and followed by a semicolon
(;).

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

===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.) For specific information about inputting or outputting multiple fields in a single statement, see [[Screen I/O]].
: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.)<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.

<noinclude>
[[Category:Statements]]
[[Category:Window File Processing Statements]]
</noinclude>

===NxtRow, Next and NxtCol===

The '''NxtRow''', '''Next''', and '''NxtCol'''  [[internal functions]] we're introduced in [[BR!]] [[4.20]].

[[Next (Internal Function)|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.