Rinput fields

From Br Wiki
Jump to: navigation, search

The RInput Fields (RI F) statement combines the functions of the PRINT FIELDS and INPUT FIELDS statements. RInput Fields displays data on the screen or in a window under format and attribute control, displays fields help windows for any or all of the printed fields, accepts changes in the data, and changes values of variables.

1.) MAT grouping is now allowed in all full screen-processing statements. This feature allows you to indicate that input or output should alternate between all MAT variables that 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. As usual, 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, it 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 are no limit. 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.

See error 0106 for additional information.



2.) 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.

 INPUT WAIT=10:X$ TIMEOUT 100
 RINPUT WAIT=10:X$ TIMEOUT 100
 LINPUT WAIT=10:X$ TIMEOUT 100
 INPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
 INPUT #11,FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
 RINPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
 INPUT SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100
 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.

 00100 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 "KSTAT$" function for information on how to use the WAIT parameter with that function.

3.) 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:
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
4.) Using an alpha character for field length in INPUT FIELDS or PRINT FIELDS will now produce an error. Previously the character as well as the attributes following it were being ignored. (This may affect your programs). Extraneous characters in attribute specifications will still be ignored.
5.) The FMT specification is now supported for better formatting of entered data. On output to the screen with RINPUT FIELDS, FMT is equivalent to the C format spec (no formatting or Verifying of data is done). See "FMT" in the Format Specifications section for complete information.

Comments and Examples

PRINT FIELDS, INPUT FIELDS, and RINPUT FIELDS are all used for full-screen processing. See Screen I/O for information and examples common to all three of these statements.

One field or several fields can be entered with the RINPUT FIELDS statement. The statements in lines 150 and 160 below:

00150 PRINT FIELDS MAT FD$: X, Y, Z$
00160 INPUT FIELDS MAT FD$: X, Y, Z$

Could be replaced with the single statement in line 170:

00170 RINPUT FIELDS MAT FD$: X, Y, Z$

See new Text format.

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

RINPUT  [#<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>][,...]

Rinputfields.png

Supplemental Syntax ("field-spec" parameter)

Fieldspec.png

See Field Specs for details on this supplemental syntax, including parameter descriptions. In the place of PIC, #PIC, #FMT or Text could be used. #PIC and #FMT allow numeric data from a string to be used, while Text forms a text box for input.

Supplemental Syntax ("helpstring" parameter)

Helpstring.png

See Field Help for more information.

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; attempts B, L, then A if necessary.

Parameters

"#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 RINPUT SELECT statement.

Mat string array, string expression, and "field spec" are used to specify the field used. See Field Specs for parameters on the supplemental syntax. If the "string-expr" or "MAT string-array" parameters are used to specify the Field definition, each must include the same elements that are identified in the "field-spec" parameter.

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 variables to which the input is to be assigned. With RINPUT FIELDS and RINPUT SELECT, the current values of are output, the output values are updated by the operator, and the updated values are re-input to the specified variables. A colon (:) must separate the these from any previous parameters in the statement. At least one "variable 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.

See Screen I/O for continued descriptions of the parameters for RINPUT FIELDS.

As of 4.3, the TEXT parameter is available too.

Technical Considerations

1.) Relevant error conditions are: CONV, ERROR, Exit, HELP, IOERR, and SOFLOW.
2.) When OPTION INVP is in effect, normal printing and input of commas and periods is altered in PIC, N, NZ, L, G and GZ format specifications to produce European-style numbers. See the OPTION statement for details.
3.) See the Functions chapter for information about the CNT function, which returns the number of the last successfully compiled element of the field definition array or the last successfully processed field when an error has occurred.
4.) See the Functions and Help Facility chapters for information about the CURFLD function, which returns the relative number (subscript of the field definition array) of the field containing the cursor from the last INPUT FIELDS or RINPUT FIELDS statement.
5.) If RINPUT FIELDS is to be retried after an error, the cursor will automatically be positioned on the field that caused the error.
6.) Business Rules! automatically selects either the monochrome or color attributes of a RINPUT FIELDS statement according to the type of monitor being used.
7.) If one of the function keys is pressed during any input operation from the keyboard, no interrupt occurs. Instead, the CMDKEY function is set and pressing <CR> is simulated. This situation is true even when the ATTN and FNKEY parameters are specified in an ON error-cond statement.
8.) Keyboard buffering operates identically for RINPUT FIELDS as it does for INPUT. Buffering may be turned on or off with the BRConfig.sys file TYPEAHEAD specification.

See Also