INPUT Syntax 1 - Dynamic Screen Layout Specification

#### Search Results

Search

# INPUT Syntax 1 - Dynamic Screen Layout Specification

This form of the `INPUT` statement is used to create a layout of an `INPUT` screen, or to create an `INPUT` data layout which is to be read in batch mode from a sequential input file.

`INPUT` | [`WINDOW='`window-name`'`] [`NO ERASE`]
| [`(`statement-parameters`)`]
| [WITH-TEXT-option]
| [MARK-option]
| [ALARM-option]
|  | n `X` n `T` x/y / |  |  |  |  | `'`text`'` `'`c`'(`n`)` |  | [`(`attributes`)`] |  |  |  |
|  | `'-'` `'`=`'` |  |  | `*IN` `*OUT` `*OUTIN` |  | operand1 [`(`parameter`)`] |

This document covers the following topics:

- INPUT Syntax 1 - Description

- Examples - INPUT Syntax 1

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

## INPUT Syntax 1 - Description

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
operand1 |  | S | A | G | N | A | U | N | P | I | F | B | D | T | L |  | G |  | yes | yes

Syntax Element Description:

Syntax Element | Description
--- | ---
`INPUT WINDOW='window-name'` | INPUT WINDOW='window-name' Option: With this option, you indicate that the `INPUT` statement is to be executed for the specified window. The specified window must be defined in a `DEFINE WINDOW` statement; see Example 2 - INPUT Statement with DEFINE WINDOW Statement. The specified window is only active for the duration of that `INPUT` statement, and is automatically deactivated when the `INPUT` statement has been executed. See also the statements `DEFINE WINDOW` and `SET WINDOW`.
`NO ERASE` | NO ERASE Option: This option causes a screen map of an `INPUT` statement to be overlaid onto an existing screen without erasing the screen contents. Screen as used here refers to a logical screen rather than a physical screen. All unprotected fields that existed on the screen are converted to protected (display only) fields. The old data remain on the screen until the new layout is displayed. If a field from the new screen content partially overlays an existing field, the one character before the new field and the next character in the existing field will be replaced by a blank.
`statement-parameters` | Statement Parameter(s): One or more parameters, enclosed within parentheses, may be specified immediately after the `INPUT` statement or an element being displayed. For a list of parameters that can be specified with the `INPUT` statement, refer to the section Statement Parameters. Each parameter specified in this manner will override any previous parameter specified in a `GLOBALS` command, `SET GLOBALS` or `FORMAT` statement. If more than one parameter is specified, one or more blanks must be present between each entry. An entry may not be split between two statement lines. The parameter settings applied here will only be regarded for variable fields, but they have no effect on text-constants. If you would like to set field attributes for a text-constant, they have to be set explicitly for this element. Example:
    DEFINE DATA LOCAL
    1 VARI (A4)     INIT <'1234'>                  /*     Output
    END-DEFINE                                     /*    Produced
    *                                              /*    ---------
    INPUT           'Text'           VARI          /*    Text 1234
    INPUT (AD=U)    'Text'           VARI          /*    Text 1234
    INPUT           'Text' (AD=U)    VARI (AD=U)   /*    Text 1234
    INPUT           'Text' (AD=U)    VARI          /*    Text 1234
    END
Examples of using parameters at the statement and element level are provided below.
`WITH TEXT-option` | WITH TEXT Option: This option is used to provide text which is to be displayed in the message line; see WITH TEXT Option below.
`MARK-option` | MARK Option: See the section MARK Option below.
`ALARM-option` | Alarm Option: See the section Alarm Option below.
Other syntax elements (`nX`, `nT`, `x/y`, `operand1`, etc.) | Field Positioning, Text Specification, Attribute Assignment: See the section Field Positioning, Text Specification, Attribute Assignment below.

### Statement Parameters

Parameters that can be specified with the INPUT statement | Specification (S = at statement level, E = at element level)
--- | ---
`AD` | Attribute Definition | SE
`AL` | Alphanumeric Length for Output | SE
`CD` | Color Definition | SE
`CV` | Control Variable | SE
`DF` | Date Format | SE
`DL` | Display Length for Output | SE
`DY` | Dynamic Attributes | SE
`EM` | Edit Mask | SE
`EMU` | Unicode Edit Mask | E
`FL` | Floating Point Mantissa Length | SE
`HE` | Helproutine | SE
`IP` | Input Prompting Text | SE
`LS` | Line Size | S
`MC` | Multiple-Value Field Count | S
`MS` | Manual Skip | S
`NL` | Numeric Length for Output | SE
`PC` | Periodic Group Count | S
`PM` | Print Mode * | SE
`PS` | Page Size ** | S
`SB` | Selection Box | E
`SG` | Sign Position | SE
`ZP` | Zero Printing | SE

* The `PM` session parameter may not be specified for text constants.

** The `PS` session parameter setting is not considered if the number of occurrences of an array exceeds the PS value.

The individual session parameters are described in the Parameter Reference.

### WITH TEXT Option

[`WITH`] `TEXT` |  | `*` operand1 operand2 |  | [(attributes)][,operand3] 7

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
operand1 | C | S |  |  |  |  | N | P | I |  | B* |  |  |  |  |  |  | yes | yes
operand2 | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  | yes | yes
operand3 | C | S |  |  |  | A | N | P | I | F | B | D | T | L |  |  |  | yes | yes

* Format B of `operand1` may be used only with a length of less than or equal to 4.

`WITH TEXT` is used to provide text which is to be displayed in the message line. This is usually a message indicating what action should be taken to process the screen or to correct an error.

Syntax Element Description:

Syntax Element | Description
--- | ---
`operand1` | Message Text Number: `operand1` represents the number of a message text that is to be retrieved from a Natural message file. You can retrieve either user-defined messages or Natural system messages: If you specify a positive value of up to four digits (for example: `954`), you will retrieve user-defined messages. If you specify a negative value of up to four digits (for example: `-954`), you will retrieve Natural system messages. See also Example 4 - WITH TEXT Options in the description of the `REINPUT` statement. Natural message files are created and maintained with the `SYSERR` utility as described in the relevant documentation.
`operand2` | Message Text: `operand2` represents the message to be placed in the message line. See also Example 4 - WITH TEXT Options in the description of the `REINPUT` statement.
`attributes` | Output Attributes: It is possible to assign various output attributes for operand1/2. These attributes and the syntax that may be used are described in the section Output Attributes below.
`operand3` | Dynamic Replacement of Message Text: `operand3` represents a numeric or text constant or the name of a variable. The values provided are used to replace parts of a message text that are either specified with `operand1` or `operand2`. The notation `:n:` is used within the message text as a reference to `operand3` contents, where `n` represents the `operand3` occurrence (1 - 7). See also Example 4 - WITH TEXT Options in the description of the `REINPUT` statement. Note Multiple specifications of `operand3` must be separated from each other by a comma. If the comma is used as a decimal character (as defined with the session parameter `DC`) and numeric constants are specified as `operand3`, put blanks before and after the comma so that it cannot be misinterpreted as a decimal character. Alternatively, multiple specifications of `operand3` can be separated by the input delimiter character (as defined with the session parameter `ID`); however, this is not possible in the case of `ID=/` (slash), because the slash has a different meaning in the `INPUT` statement syntax. Leading zeros or trailing blanks will be removed from the field value before it is displayed in a message.

#### Output Attributes

attributes indicates the output attributes to be used for text display. Attributes can be:

| `AD`=ad-value `CD`=cd-value `PM`=pm-value |
| ad-value cd-value |

Where:

`ad-value`, `cd-value` and `pm-value` denote the possible values of the corresponding session parameters `AD`, `CD` and `PM` described in the relevant sections of the Parameter Reference documentation.

The compiler actually accepts more than one attribute value for an output field. For example, you can specify: `AD=BDI`. In such a case, however, only the last value applies. In the given example, only the value `I` becomes effective and the output field is displayed intensified.

For an alphanumeric/Unicode constant (Natural data format A or U), you can specify `ad-value` and/or `cd-value` without preceding `CD=` or `AD=`, respectively. The single value entered is then checked against all possible `CD` values first. For example: a value of `IRE` will be interpreted as intensified/red but not as intensified/right-justified/mandatory. You cannot combine a single `cd-value` or `ad-value` with a value preceded by `CD=` or `AD=`.

### MARK Option

With the `MARK` option, you can cause the cursor to be placed at any non-protected field on screen. In addition, you can specify the position of the cursor within that field. By default, that is, when the `MARK` option is omitted, the cursor is placed at the beginning of the first non-protected field.

`MARK` [`POSITION` operand4 [`IN`]] [`FIELD`] |  | operand1 *fieldname |

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand4` | C | S |  |  |  |  | N | P | I |  |  |  |  |  |  |  |  | yes | yes
`operand1` | C | S | A |  |  |  | N | P | I |  |  |  |  |  |  |  |  | yes | yes

Syntax Element Description:

Syntax Element | Description
--- | ---
`operand1` | Field Reference Number: `operand1` specifies the number of the field where the cursor is to be positioned in. Each field attribute `AD=A` or `AD=M` (that is, non-protected field) specified in an `INPUT` statement is assigned a field reference number, beginning with 1.
`*fieldname` | Field Name for Referencing: Instead of the field reference number, the field name may be used to position to a field, using the `*fieldname` notation.
`operand4` | Cursor Position within Referenced Field: With `MARK POSITION`, you can have the cursor placed at a specific position - as specified with `operand4` - within a field specified with `operand1` or `*fieldname`. `operand4` must not contain decimal digits.

#### Examples:

    MARK #NUMBER               /* Field number
    MARK 3                     /* Third map field
    MARK *#FIELD1              /* Map field
    MARK POSITION 3 IN #NUMBER /* Third character in field number

See also Example 3 - INPUT Statement with MARK POSITION Option at the end of this section.

### ALARM Option

This option causes the sound alarm feature of the terminal to be activated when the `INPUT` statement is executed. The appropriate hardware must be available to be able to use this feature.

[`AND`] [`SOUND`] `ALARM`

#### Default Prompting Text

Unless the session parameter `IP` (input prompting) is set to `IP=OFF`, the field name of the field used in an `INPUT` statement will be displayed preceding the field value (forms mode) or as a prompting keyword to select the field (keyword/delimiter mode). This default field name may be overridden by specifying either a `'text'` element (which replaces the default name) or `'-'` (which suppresses the display of the default field name) immediately preceding the field name.

### Field Positioning, Text Specification, Attribute Assignment

Several notations are available for field positioning, attribute assignment, and text creation.

Syntax Element Description:

Syntax Element | Description
--- | ---
`nX` | Insert Option: This option causes n spaces to be inserted between fields.
`n`T | Tabulator Option: This option causes positioning (tabulation) to print position n.
`x/y` | Positioning Option: Places the next element on line x, beginning in column y. y must not be zero. Backward positioning in the same line is not permitted.
`'text'` | Write Protection: Causes text to be displayed write protected; see also Text Notation, Defining a Text to Be Used with a Statement.
`'c' (n)` | Character Repetition: Identical to `'text'`, except that the character c is displayed n times. n must be `1 - 132`; see also Text Notation, Defining a Character to Be Displayed n Times before a Field Value.
`attributes` | Display Attributes: Attributes to be used for display. See Attributes below.
`'-'` | Minus Sign: When placed before a field, `'-'` suppresses the generation of a field name as prompting text. Note Any text string before a field will replace the field name as prompting text.
`'='` | Equal Sign: When placed before a field, `'='` results in the display of the field heading followed by the field contents.
`'/'` | Slash Sign: When placed between fields or text elements, `'/'` causes positioning to the beginning of the next print line. The contents of fields may be specified for input, output only, and output for modification using the attribute settings `AD=A`, `AD=O`, and `AD=M` respectively. The default is `AD=A`. All fields specified with `AD=A` (input only) or `AD=M` (output for modification) will create unprotected fields on the screen. A value for such a field may be entered by the user. For TTY devices, output for modification fields will occupy twice the size of the field (one for output, one for input) so that a new value may be entered. An input field (with `AD=A` or `AD=M`) specified as non-displayable will always start on a new line on a TTY device. Example:
    INPUT #A (AD=A) #B (AD=O) #C (AD=M)
`#A` is an input field which is unprotected, i.e., a value is to be entered for the field. `#B` is a field which is to be displayed write-protected, that is, no value may be entered for the field. `#C` is a field whose current value is to be displayed, and the value may be modified by entering a new value for the field.
`*IN, *OUT and *OUTIN` | Field Attribute Definition: Equivalent to the attributes `AD=A`, `AD=O`, `AD=M` respectively. Note If a non-modifiable system variable is used in an `INPUT` statement, the value will be displayed as an output-only field `AD=O` or `*OUT` attribute.
`operand1` | Field(s) to be Used: `operand1` represents the field to be used. Database fields or user-defined variables may be specified. Natural directly maps the content of each field from the data area to the `INPUT` statement, no move operation is necessary. When the content of a database field is modified as a result of `INPUT` processing, only the value as contained in the data area is modified. Appropriate database `UPDATE` / `STORE` statements must be used to change the content of the database. When the name of a group of database fields is referenced in an `INPUT` statement, all fields belonging to that group will be individually used as input fields. When reference is made to a range of occurrences within an array, all occurrences are individually processed as input fields, but no prompting text will be created for each individual occurrence, only for the first one. On z/OS, arrays with ranges that allow to vary the number of occurrences at execution time may not be specified.
`parameter(s)` | Parameter(s): One or more parameters, enclosed within parentheses, may be specified immediately after `operand1` (see table and example below). Each parameter specified will override any previous parameter specified in a `GLOBALS` command, `SET GLOBALS` (in Reporting Mode) or `FORMAT` statement. If more than one parameter is specified, they must be separated by one or more blanks from one another. Each parameter specification must not be split between two statement lines. The parameter settings applied here will only be regarded for variable fields, but they have no effect on text constants. If you would like to set field attributes for a text-constant, they have to be set explicitly for this element. For information on the individual parameters, see the table in the section Statement Parameters. Note The session parameter `EM` will be referenced dynamically in the DDM if an edit mask is defined for a database field. Edit masks may be specified for output and input fields. When an edit mask is defined for an input field, the data for the field must be entered according to the edit mask specification.

#### Attributes

The following attributes may be used:

|  |  | `B` |  |  |  |  |  |  | `BL` |  |  |  |  |  |  |  |
| `C` |  |  | `GR` |  | `C`
| `D` |  |  | `NE` |  | `D`
[`AD=`] | `I` |  | [`CD=`] | `PI` | [`PM=`] | `I`
| `N` |  |  | `RE` |  | `N`
| `U` |  |  | `TU` |  |
| `V` |  |  | `YE` |  |
|  |  | 1 |  |  |  |  |  |  | 2 |  |  |  |  |  | 3 |  |

1. Display attributes; see the session parameter `AD` (in the Parameter Reference).

2. Color attributes; see the session parameter `CD` (in the Parameter Reference).

3. Print mode attributes; see the session parameter `PM` (in the Parameter Reference).

## Examples - INPUT Syntax 1

- Example 1 - INPUT Statement

- Example 2 - INPUT Statement with DEFINE WINDOW Statement

- Example 3 - INPUT Statement with MARK POSITION Option

### Example 1 - INPUT Statement

    ** Example 'IPTEX1': INPUT
    ************************************************************************
    DEFINE DATA LOCAL
    1 #FNC  (A1)
    END-DEFINE
    *
    INPUT 10X 'SELECTION MENU FOR EMPLOYEES SYSTEM' /
          10X '-' (35) //
          10X 'ADD      (A)' /
          10X 'UPDATE   (U)' /
          10X 'DELETE   (D)' /
          10X 'STOP     (.)' //
          10X 'PLEASE ENTER FUNCTION: ' #FNC
    *
    DECIDE ON EVERY VALUE OF #FNC
      VALUE 'A'   /* invoke the object containing the add function here
        WRITE 'Add function selected.'
      VALUE 'U'   /* invoke the object containing the update function here
        WRITE 'Update function selected.'
      VALUE 'D'   /* invoke the object containing the delete function here
        WRITE 'Delete function selected.'
      VALUE '.'
        STOP
      NONE
        REINPUT 'Please enter a valid function.' MARK *#FNC
    END-DECIDE
    *
    END

#### Output of Program IPTEX1:

    SELECTION MENU FOR EMPLOYEES SYSTEM
    -----------------------------------

    ADD      (A)
    UPDATE   (U)
    DELETE   (D)
    STOP     (.)

    PLEASE ENTER FUNCTION:

### Example 2 - INPUT Statement with DEFINE WINDOW Statement

    ** Example 'INPEX1': INPUT (with DEFINE WINDOW statement)
    ************************************************************************
    DEFINE DATA LOCAL
    1 #STRING (A15)
    END-DEFINE
    *
    DEFINE WINDOW WIND1
      SIZE 10 * 40
      BASE 5 / 10
      FRAMED ON POSITION TEXT
    *
    INPUT WINDOW='WIND1'
          'PLEASE ENTER HERE:' / #STRING
    *
    END

#### Output of Program INPEX1:

    +----------------------------------Top+
    ! PLEASE ENTER HERE:                  !
    ! #STRING                             !
    !                                     !
    !                                     !
    !                                     !
    !                                     !
    !                                     !
    !                                     !
    +-------------------------------Bottom+

### Example 3 - INPUT Statement with MARK POSITION Option

    ** Example 'INPEX2': INPUT (with POSITION)
    ************************************************************************
    DEFINE DATA LOCAL
    1 #START (A30)
    END-DEFINE
    *
    ASSIGN #START = 'EXAM_'
    *
    INPUT (AD=M) MARK POSITION 5 IN *#START
         / 'PLEASE COMPLETE START VALUE FOR SEARCH'
         / 5X #START
    END

#### Output of Program INPEX2:

    PLEASE COMPLETE START VALUE FOR SEARCH
           #START EXAM[]

### On this page

- INPUT Syntax 1 - Description
- Examples - INPUT Syntax 1