SB - Selection Box

Selection boxes in an INPUT statement are available on mainframe computers only. For other platforms, selection boxes may be defined in the map editor only.

Selection boxes can be attached to input fields. They are a comfortable alternative to help routines attached to fields, since you can code a selection box direct in your program. You do not need an extra program as with help routines.

You may define a selection box clause for every INPUT variable of type alpha, regardless if this field is an input or output field, or both.

The syntax is:

SB=operand1 [,operand1]...

where operand1 represents a value operand which is used to fill up the selection box with items.

Operand	Possible Structure						Possible Formats													Referencing Permitted	Dynamic Definition
`operand1`	C	S	A				A													yes	no

With SB, you specify the values to be displayed within the selection box.

To assign a selection box to a field, specify the attribute SB for an alpha INPUT field in your Natural program using the following example syntax:

INPUT #FLD (SB='value1', #ITEM1, #ITEM2(1:3), #ITEM3(*))

The following topics are covered below:

Syntactical Considerations
Runtime Considerations
Features
Restrictions

Syntactical Considerations

It is possible to assign both a selection box and a help routine to a field.

Selection boxes can be defined for every variable field in an INPUT statement. Exceptions are the following:

System Variables	For example: `PROGRAM`, `COM`
Named Constants (mainframe only)	defined with a `CONST` clause of `DEFINE DATA` statement.

In addition to the SB attribute, other attributes can be defined as well, for example: AD or CD.

The selection box field does not have to be modifiable, as is the case with AD=A or AD=M. In other words, it is possible to provide a selection box (and select values) even for a write-protected output field, such as AD=O. If you use AD=O, the user is forced to choose from a set of predefined values, which themselves appear in a selection box.

Runtime Considerations

Selection Box Position

When a program containing a selection box is executed, the selection box is positioned on the screen according to the same positioning algorithm used for help windows; that is, the size and position of the selection box are determined automatically, "near" the field.

Selection Box Attributes

The color and intensified attributes assigned to the field are also applied to the values displayed in the corresponding selection box.

Edit Masks in Selection Boxes

If an edit mask has been defined for the field, the edit mask is applied to all selection box values.

To define an edit mask for a field:

Using the INPUT statement, you can define an edit mask for a field. This is demonstrated in following code example.

DEFINE DATA
LOCAL
1 A(A4)
END-DEFINE
MOVE 'ABCD' TO A
*
SET KEY PF1 = HELP
FORMAT KD=ON
*
INPUT A (AD=M EM=X.X.X.X SB='1234','WXYZ')
WRITE A
END

Selection Box Line Sizes

The line size of the selection box matches the field length to which the box corresponds.

If a value intended for the selection box exceeds the line size of the selection box, the value is truncated.

Sequence of Selection Box Values

Selection box values are displayed in the order they appear in the SB attribute.

Features

How a Selection Box is Displayed

For a field with attached selection box, an indicator "V" is displayed next to the field.

Invoking Selection Boxes

To open a selection box, there are two ways to open a selection box:

Enter a question mark (?) in the V-field and press ENTER.

Or position the cursor on the V-field and press the help key (for example, PF1), if you have defined it to do so. See the next section for more details.

To define a help key to invoke the selection box, you can define a help-key (for example, PF1) to make invoking the selection box much simpler.

This is done by adding the following line of code to your program:

SET KEY PF1=HELP

Scrolling in a Selection Box

There are two ways to scroll in a selection box:

By putting the cursor on the MORE line and pressing ENTER.
Or by using the terminal commands %W- and %W+ assigned to PF-keys (for example, PF7/PF8).

Selecting a Value in a Selection Box

A value is selected from the selection box and copied into the field by putting the cursor on the value and pressing ENTER.

Duplicate Lines in a Selection Box

Lines with the same content which directly follow each other are suppressed.

For example, the following code

INPUT #FLD (SB='123', '456', 'XYZ', 'XYZ', 'XYZ', 'ABC', 'DEF')

produces the following output to the selection box:

123
456
XYZ
ABC
DEF

In the preceding example, XYZ is only displayed once. The other occurrences are considered redundant since they directly follow one another.

However, this line of code

INPUT #FLD (SB='123', 'XYZ', '456', 'XYZ', 'ABC', 'XYZ', 'DEF')

produces the following output to the selection box:

123
XYZ
456
XYZ
ABC
XYZ
DEF

In this case, all three occurrences of XYZ are displayed, since they do not directly follow one another.

Blank Lines in Selection Boxes

A blank line is only displayed the first time it appears; all subsequent blank lines are suppressed.

Restrictions

The number of operands in the SB clause is limited to 20.

The maximum number of values in a selection box is 248. When that limit has been reached, further values are not displayed. No error message is issued when the limit has been exceeded.