SB - Selection Box

#### Search Results

Search

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

### On this page

- Syntactical Considerations
- Runtime Considerations
- Features
- Restrictions