Input Select

From Br Wiki
Jump to: navigation, search

The Input Select (IN S) statement uses the capabilities of full screen processing to set up a screen for menu selection. The only data which is accepted by INPUT SELECT is the pressing of either Enter, one of the function keys or a control key described below; neither action changes any of the data in the fields, but it does cause the CMDKEY and the CURFLD system functions to be set. Additionally, INPUT SELECT allows the use of field help windows for any or all of the defined fields.

Comments and Examples

In the following example, INPUT SELECT and PRINT FIELDS are used together 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;"
00150 PRINT FIELDS FSPEC$: MAT MENU$
00160 INPUT 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 (the field the cursor is on) to be reversed (appear highlighted), thus helping the operator to identify the current field as it moves about the screen.

Business Rules will enter SELECT mode (the SELECT keyword will be visible in the left corner of the status line) and wait for operator input when it executes line 160. At this time, the operator may use the following methods to move the cursor from one field to another:

  1. Press a data character - Pressing a letter (a-z) causes Business Rules to search the first uppercase character in all fields (starting with the first field after the current field) for an uppercase match of the character. Pressing a digit (0-9) causes Business Rules search the first digit in all fields for a match. Pressing a non-letter or non- digit character causes Business Rules search for the first match of the character. In all cases, if no match is found, the cursor will remain on the current field. If a match is found, the cursor will stop on that selection. If a match is found and "E" has been specified as a control attribute, an automatic enters for that selection occurs.
  2. Left and right arrows - Pressing the left arrow moves the cursor to the previous field; pressing the right arrow moves it to the next field.
  3. Up and down arrows - Pressing the up arrow moves the cursor to the next field up; pressing the down arrow moves it to the next field down.
  4. Tab, shift-tab, backspace - Pressing the tab key moves the cursor to the next field; pressing the shift-tab or backspace key moves it to the previous field.

On input (using the previous example), pressing a c or C will position the cursor at "Clear entries". Pressing a Q will position the cursor to "Quit". Upon completed execution of line 160, the CMDKEY and CURFLD functions will be set.

Syntax

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

InputSelect.png

Other than the use of the "SELECT" keyword in place of "FIELDS", the syntax diagrams and parameters for the INPUT SELECT and INPUT FIELDS statements are identical.

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.

Supplemental Syntax ("field-spec" parameter)

Fieldspec.png

See Field Specs for more information, including syntax parameters.

Supplemental Syntax ("helpstring")

Helpstring.png

See Field Help for additional information, including syntax parameters.

Technical Considerations

  1. Relevant error conditions are: CONV, ERROR, Exit, HELP, IOERR, and SOFLOW.
  2. FKey is set in the same manner with INPUT SELECT as it is with INPUT 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 helps 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. Keyboard buffering operates identically for INPUT SELECT as it does for INPUT. Buffering may be turned on or off with the BRConfig.sys file TYPEAHEAD specification

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.

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

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 previous 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

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

The space bar will now move the cursor from option to option. INPUT SELECT and RINPUT SELECT will now hide the cursor if ATTR (floating attribute) is specified.

Changes

When a new field is selected by either an arrow key, a search key value (pressing a letter that is capitalized in the SELECT array), or by mouse clicking on a new field, then the cursor will go to the field. An E requires a double click, an Enter, or search key selection to return control to the program, whereas an X will return to the program whenever a field is exited.

INPUT SELECT was changed in the following respects:

1.) Text can be hot (honor an Fkey specification)
2.) Any of the above selection methods produce the same results.
3.) CURFLD will reflect the field being exited. *important*
4.) NXTFLD will still reflect the field being entered.
5.) The cursor will NOT switch to the new field before giving control to the program.

If you desire that the field switch fully occur (CURFLD = NXTFLD) before giving the program control, then specify OPTION 43.

Notice:

00000 CURFLD and NXTFLD appear below the group.
00000 For menuing purposes, check CURFLD instead of NXTFLD
00000 Leaving "Grape" in the first group shows X attribute functionality
00000 Selection with X throughout is single click, while selection with E throughout is double click
00100    print NEWPAGE
00200    dim FSPEC$*33, FSPEC2$*33, SELECT$(3)
00300    let FSPEC$="1,1,C 10,E;2,1,C 10,E;3,1,C 10,X"
00400    let SELECT$(1)="Apple": let SELECT$(2)="Plum": let SELECT$(3)="Grape"
00500    print fields FSPEC$: MAT SELECT$
00600    input select FSPEC$: MAT SELECT$
00700    print fields "4,1,N 2;4,5,N 2": CURFLD, NXTFLD
00800    let FSPEC2$="6,1,C 10,E;7,1,C 10,E;8,1,C 10,E"
00900    print fields FSPEC2$: MAT SELECT$
01000    input select FSPEC2$: MAT SELECT$
01100    print fields "9,1,N 2;9,5,N 2": CURFLD, NXTFLD