Rinput select

From Br Wiki
Jump to: navigation, search

The RInput Select (RIN S) statement combines the capabilities of PRINT FIELDS and INPUT SELECT so that it both prints a series of menu selections and sets up an input screen for the selection. The only data which is accepted by RInput Select is the pressing of either Enter or one of the function keys; neither action changes any of the data in the fields, but they do cause the CMDKEY and the CURFLD system functions to be set. RInput Select additionally allows the use of field help windows for any or all of the defined fields.

1.) The cursor's field movement will respond to the arrow keys without regard to the order of the options. The down arrow will move to the field below the cursor's current position.The up arrow moves the cursor to the field above its current position, the left arrow searches to the left of the current field and continues up the screen and then from the end of the screen until it finds another field or itself. The right arrow works the same way, except right and down the screen. If there is no field in the same column as the cursor, the up or down arrow will stay at the current field.
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, please 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 unselected
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 space bar will now move the cursor from option to option.
6.) INPUT SELECT and RINPUT SELECT will now hide the cursor if ATTR (floating attribute) is specified.

Comments and Examples

In the following example, RINPUT SELECT is used to set up a menu with four fields for selection. Each field has an associated field help window which is automatically displayed upon field entry when the BRConfig.sys USERLEVEL specification is set to anything but 0. (See USERLEVEL in BRConfig.sys for more information.)

00100 PRINT NEWPAGE
00105 DIM FSPEC$*45,MENU$(4),C$*200
00110 LET FSPEC$="10,10,C 12;10,27,C 15;16,10,C 13;16,27,C 4"
00120 DATA "Post entries","Re-Edit entries","Clear entries","Quit"
00130 READ MAT MENU$
00140 LET C$="1B;Posts all transactions;1B;Print another edit listing;"&"1B;Clear all the entries and start over;1B;Return to the menu;"
00160 RINPUT SELECT FSPEC$,ATTR "R",HELP C$: MAT MENU$

NOTICE that the ATTR parameter in line 160 is set to R. This causes the current field to be reversed, thus helping the operator to identify the current field as it moves about the screen.

Business Rules will stop and wait for operator input when it executes line 160 (the "SELECT" keyword will be displayed in the status line). The rules for cursor movement and menu selection are the same for RINPUT SELECT as they are for INPUT SELECT (see INPUT SELECT for more information).

RINPUT SELECT will not modify any of the variables to be displayed, it may include literals in the variable list. Thus lines 120 and 130 in the previous example could be deleted if line 160 were changed as follows:

00160 RINPUT SELECT FSPEC$,ATTR "R",HELP C$: "Post entries","Re-edit entries","Clear entries","Quit"

RINPUT SELECT "10,10,20/CC 30": "DATA" - centers on the 20 char display area - The shaded text area will be the greater of 20 non-proportional positions or the actual length of the proportional text.

RINPUT SELECT "10,10,1/C 30": "DATA" -use this for variable cursor bar RINPUT SELECT "10,30,1/CC 30": "DATA" -use this for centering variable cursor bar The displayed length of 1 retricts the shaded text area to the actual length of the proportional text. The data length of 30 sets the field capacity. If the field capacity is not specified, it defaults to the maximum length of the associated variable.

Syntax

RINPUT  [#<window number>,] SELECT {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>][,...]

Rinputselect.png

Supplemental Syntax ("field-spec" parameter)

Fieldspec.png

See Field Specs for more information, including syntax parameters.

Supplemental Syntax ("helpstring" parameter)

Helpstring.png

See Field Help for more information, including syntax parameters.

Parameters

With the exceptions of the "SELECT" keyword and the "data-item" parameter, the syntax diagrams of RINPUT SELECT and RINPUT FIELDS are identical.

"#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.

The "SELECT" keyword is used to indicate that only a selection (pressing Enter or one of the function keys) is allowed as input for this statement.

Mat string array, string expression, or "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.

The "data-item" parameter represents the list of items to be output. Either a variable name or a literal string is accepted for this parameter.

INPUT SELECT and RINPUT SELECT will now hide the cursor if ATTR (floating attribute) is specified.

See Screen I/O for a continued description of the parameters for RINPUT SELECT.

Technical Considerations

1.) Relevant error conditions are: CONV, ERROR, EXIT, HELP, IOERR, and SOFLOW.
2.) CMDKEY is set in the same manner with RINPUT SELECT as it is with RINPUT FIELDS.
3.) When field help text is available but not automatically displayed upon field entry, the operator may press the <HELP> key to see the field window. Pressing <HELP> a second time creates an error that may be trapped with the HELP error condition, thus allowing for two levels of field help. When the HELP error condition is not used to trap a second pressing of <HELP>, the field help window is simply undisplayed (no execution error will occur).
4.) PRINT NEWPAGE should be executed before any full screen processing operation. This will fully remove any data that may remain from previous screen operations.
5.) Keyboard buffering operates identically for RINPUT SELECT as it does for INPUT. Buffering may be turned on or off with the BRConfig.sys file TYPEAHEAD specification.
6.) See also SETENV() function relating to window size.