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]

nX
nT
x/y
/

 

'text'
'c'(n)

[(attributes)]  

 

'-'
'='

*IN
*OUT
*OUTIN

operand1 [(parameter)]

This document covers the following topics:

For explanations 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.

nT
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 mainframe computers, 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 - Syntax 1

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[]