REINPUT

REINPUT  [FULL]  [(statement-parameters)]

USING HELP

WITH-TEXT-option
  [MARK-option]      
  [ALARM-option]      

This document covers the following topics:

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

Related Statements: DEFINE WINDOW | INPUT | SET WINDOW

Belongs to Function Group: Screen Generation for Interactive Processing


Function

The REINPUT statement is used to return to and re-execute an INPUT statement. It is generally used to display a message indicating that the data input as a result of the previous INPUT statement were invalid. See Example 1.

No WRITE or DISPLAY statements may be executed between an INPUT statement and its corresponding REINPUT statement. The REINPUT statement is not valid in batch mode.

The REINPUT statement, when executed, repositions the program status regarding subroutine, special condition and loop processing as it existed when the INPUT statement was executed (as long as the status of the INPUT statement is still active). If the loop was initiated after the execution of the INPUT statement and the REINPUT statement is within this loop, the loop will be discontinued and then restarted after the INPUT statement has been reprocessed as a result of REINPUT.

If a hierarchy of subroutines was invoked after the execution of the INPUT statement, and the REINPUT is performed within a subroutine, Natural will trace back all subroutines automatically and reposition the program status to that of the INPUT statement.

It is not possible, however, to have an INPUT statement positioned within a loop, a subroutine or a special condition block, and then execute the REINPUT statement when the status under which the INPUT statement was executed has already been terminated. An error message will be produced and program execution terminated when this error condition is detected.

See also Dialog Design, Statements REINPUT/REINPUT FULL (in the Programming Guide).

Note:

When an input/output field (option (AD=M)) is displayed by an INPUT statement, the data visible on screen is only moved back into the variable if the field is regarded as "modified". A field gets the status MODIFIED when any of the following conditions applies:

  • The field content was changed (that is, different data was entered into the field).

  • The key EEOF (erase to end of field) is pressed on an empty field.

  • Blanks are entered in an empty field or behind the last non-blank character in the field.

  • The profile parameter CVMIN has been set to ON, and the field data is manipulated by edit operations which lastly result in the restoration of its content (for example, by overwriting the first character with the same character).

The content of a field that lastly remains unmodified is not transferred from the screen field into the variable.

The execution of a REINPUT statement (without FULL option) does not affect the MODIFIED state of an input/output field. A field continues to be considered non-modified unless it is manipulated via the INPUT statement by using any of the operations listed above. Conversely speaking, a field is treated as modified if at least one of the aforementioned operations was performed, irrespective of how often the INPUT statement was re-posted by REINPUT statements (without FULL option).

In other words, a field value displayed using an INPUT statement, which was triggered by a REINPUT statement (without FULL option), is only transferred into the variable if the field was modified in terms of the aforementioned field manipulations.

The MODIFIED status can be checked in the program code if an attribute control variable (option CV) was assigned to the field which is checked with the MODIFIED option, for example, of the IF statement after the INPUT statement.

Syntax Description

Syntax Element Description
REINPUT FULL
FULL Option:

If you specify the FULL option in a REINPUT statement, the corresponding INPUT statement will be re-executed fully:

  • With an ordinary REINPUT statement (without FULL option), the contents of variables that were changed between the INPUT and REINPUT statement will not be displayed; that is, all variables on the screen will show the contents they had when the INPUT statement was originally executed.

  • With a REINPUT FULL statement, all changes that have been made after the initial execution of the INPUT statement will be applied to the INPUT statement when it is re-executed; that is, all variables on the screen contain the values they had when the REINPUT statement was executed.

Note:
The contents of input-only fields (AD=A) will be deleted again by REINPUT FULL.

Another characteristic of the REINPUT FULL statement is that the status of attribute control variables is reset to NOT MODIFIED. This is not done with the ordinary REINPUT statement. To check if an attribute control variable has been assigned the status MODIFIED, use the MODIFIED option.

See also Example 3 - REINPUT FULL WITH MARK POSITION.

statement-parameters
Parameters:

Parameters specified in a REINPUT statement will be applied to all fields specified in the statement.

Any parameter specified at element (field) level (see MARK Option) will override any corresponding parameter at statement level.

Parameters that can be specified with the REINPUT statement: Specification (S = at statement level, E = at element level)
AD - Attribute Definition * SE
CD - Color Definition S

* If AD=P is specified at statement level, all fields - except those used in the MARK option - are protected.

The individual session parameters are described in the Parameter Reference.

USING HELP
USING HELP Option:

This option causes the helproutine defined for the INPUT map to be invoked.

USING HELP used in combination with the MARK option causes the helproutine defined for the first field specified in the MARK option to be invoked. If no helproutine is defined for that field, the helproutine for the map will be invoked.

Example:

REINPUT USING HELP MARK 3

As a result, the helproutine defined for the third field in the INPUT map will be invoked.

WITH-TEXT-option
WITH TEXT Option:

The WITH TEXT option is used to provide text which is to be displayed in the message line.

See WITH TEXT Option.

MARK-option
MARK Option

With the MARK option, you can mark a specific field, that is, specify a field in which the cursor is to be placed when the REINPUT statement is executed. See MARK Option.

ALARM-option
ALARM Option:

This option causes the sound alarm feature of the terminal to be activated when the REINPUT statement is executed.

See ALARM Option.

WITH TEXT Option

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.

[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 no
operand2 C S       A U                       yes no
operand3 C S       A U N P I F B D T L       yes no

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

Syntax Element Description:

Syntax Element Description
operand1
Message Text from Natural Message File:

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.

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.

attributes
Output Attributes:

It is possible to assign various output attributes for operand1/operand2. These attributes and the syntax that may be used are described in the section Output Attributes.

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 occurrence (1 - 7) of operand3.

See also Example 4 - WITH TEXT Options.

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

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 may be:

../graphics/cbo3.gif

AD=ad-value
CD=cd-value
CV=variable

../graphics/cbc3.gif

 
 

../graphics/dot3.gif

For the possible session parameter values, refer to the corresponding sections in the Parameter Reference documentation:

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

MARK Option

With the MARK option, you can mark a specific field, that is, specify a field in which the cursor is to be placed when the REINPUT statement is executed. You can also mark a specific position within a field. Moreover, you can make fields input-protected, and change their display and color attributes.

MARK [POSITION operand4 [IN]] [FIELD]

operand5
*fieldname

[(attributes)]

 

Operand Definition Table:

Operand Possible Structure Possible Formats Referencing Permitted Dynamic Definition
operand4 C S           N P I                 yes no
operand5 C S A         N P I                 yes no

Syntax Element Description:

Syntax Element Description

operand5
*fieldname

Field to be Marked:

All AD=A or AD=M (that is, non-protected) fields specified in an INPUT statement are sequentially numbered (beginning with 1) by Natural. operand5 represents the number of the field in which the cursor is to be positioned.

The *fieldname notation is used to position to a field (as used in the INPUT statement) using the name of the field as a reference.

If the corresponding INPUT field is an array, a unique index or an index range may be used to reference one or more occurrences of the array.

INPUT #ARRAY (A1/1:5)
...
REINPUT (AD=P) 'TEXT' MARK *#ARRAY (2:3)

If operand5 is also an array, the values in operand5 are used as field numbers for the INPUT array.

RESET #X(N2/1:2)
INPUT #ARRAY ...
...
REINPUT (AD=P) 'TEXT' MARK #X (1:2)
MARK POSITION
MARK POSITION Option:

With this option, you can have the cursor placed at a specific position - as specified with operand4 - within a field.

See also Example 3 - REINPUT FULL WITH MARK POSITION.

operand4
Cursor Position:

operand4 specifies the cursor position.

operand4 must not contain decimal digits.

attributes
Attribute Assignments:

See Attribute Assignments.

Attribute Assignments

With explicit attributes, you can define the display presentation and color of the WITH TEXT message and also the layout of the MARK field (which is positioned by the REINPUT statement).

 

B

 

 

BL

 
  C     GR  
  D     NE  
AD=[P] I   CD= PI [CV=operand6]
  N     RE  
  U     TU  
  V     YE  

Operand Definition Table:

Operand Possible Structure Possible Formats Referencing Permitted Dynamic Definition
operand6   S                            C     no no

With the attribute AD=P, you can make an input field (AD=A or AD=M) input-protected.

Note:
You cannot use an attribute to make output-only fields (AD=O) available for input.

For information on the attributes AD, CD and CV, refer to the Parameter Reference.

The attributes for the WITH TEXT and MARK fields need not be specified in a fixed manner, but can also be assigned dynamically by means of a control variable, which is referenced in a (CV=operand6) clause. See Example 5 - REINPUT with Attribute Assignment Using a Control Variable.

If both an AD and a CV option are specified for the same field, the attributes from the AD option are completely ignored, except (AD=P) which remains in effect.

If a CD and a CV option are specified for the same field, the color from the CV option is used. If the CV variable contains no color specification, the color from the CD option is applied to that field.

If AD=P is specified at statement level, all fields except those specified in the MARK option are input-protected. See also Example 2 - REINPUT with Attribute Assignment.

ALARM Option

[AND] [SOUND] ALARM

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

Examples

Example 1 - REINPUT Statement

** Example 'REIEX1': REINPUT                                            
************************************************************************
DEFINE DATA LOCAL                                                       
1 #FUNCTION (A1)                                                        
1 #PARM     (A1)                                                        
END-DEFINE                                                              
*                                                                       
INPUT #FUNCTION #PARM                                                   
*                                                                       
DECIDE FOR FIRST CONDITION                                              
  WHEN #FUNCTION = 'A' AND #PARM = 'X'                                  
    REINPUT 'Function A with parameter X selected.'                     
            MARK *#PARM                                                 
  WHEN #FUNCTION = 'C' THRU 'D'                                         
    REINPUT 'Function C or D selected.'                                 
  WHEN #FUNCTION = 'X'                                                  
    STOP                                                                
  WHEN NONE                                                                 
    REINPUT 'Please enter a valid function.'                            
            MARK *#FUNCTION
END-DECIDE                 
*                          
END

Output of Program REIEX1:

#FUNCTION A #PARM Y

And after pressing ENTER:

PLEASE ENTER A VALID FUNCTION
#FUNCTION A #PARM Y

Example 2 - REINPUT with Attribute Assignment

** Example 'REIEX2': REINPUT  (with attributes)                         
************************************************************************
DEFINE DATA LOCAL                                                       
1 #A (A20)                                                              
1 #B (N7.2)                                                             
1 #C (A5)                                                               
1 #D (N3)                                                               
END-DEFINE                                                              
*                                                                       
INPUT (AD=A) #A  #B  #C  #D                                             
*                                                                       
IF #A = ' ' OR #B = 0                                                   
  REINPUT (AD=P) 'RETYPE VALUES'                                        
                 MARK *#A (AD=I CD=RE)    /* put cursor on first field  
                      *#B (AD=U CD=PI)    /* and change colors    
END-IF                                                                  
*                                                                       
END

Example 3 - REINPUT FULL with MARK POSITION

** Example 'REIEX3': REINPUT  (with FULL and POSITION option)           
************************************************************************
DEFINE DATA LOCAL                                                       
1 #A (A20)                                                              
1 #B (N7.2)                                                             
1 #C (A5)                                                               
1 #D (N3)                                                               
END-DEFINE                                                              
*                                                                       
INPUT (AD=M) #A  #B  #C  #D                                             
*                                                                       
IF #A = ' '                                                             
  COMPUTE #B = #B + #D                                                  
  RESET #D                                                              
END-IF                                                                  
*                                                                       
IF #A = SCAN 'TEST' OR = ' '                                            
REINPUT FULL 'RETYPE VALUES' MARK POSITION 5 IN *#A             
END-IF                                                                  
*   
END

Output of Program REIEX3:

RETYPE VALUES 
#A                      #B        0.00 #C       #D    0

Example 4 - WITH TEXT Options

** Example 'REIEX4': REINPUT (with TEXT option)                         
************************************************************************
DEFINE DATA LOCAL                                                       
01 #NAME   (A8)                                                         
01 #TEXT   (A20)                                                        
END-DEFINE                                                              
*                                                                       
*                                                                       
INPUT WITH TEXT 'Enter a program name.' 'Program name:' #NAME           
*                                                                       
IF #NAME = ' '                                                          
  REINPUT WITH TEXT 'Input missing. Enter a name.'                    
END-IF                                                                  
*                                                                       
IF #NAME NE MASK (A)                                                    
  MOVE 'Invalid input.' TO #TEXT                                        
  REINPUT WITH TEXT ':1: Name must start with a letter.',#TEXT      
ELSE                                                                    
  /* Using Natural error message 7600 for demonstration                 
  COMPRESS *INIT-USER 'on' *DAT4I INTO #TEXT                            
  INPUT WITH TEXT *-7600,#NAME,#TEXT 'Input accepted.'
END-IF                                                
END

Example 5 - REINPUT with Attribute Assignment Using a Control Variable

DEFINE DATA LOCAL
1 #HELLO (A5)  INIT <'HELO'>
1 #VAR   (A20) INIT <'Enter "HELLO"'>
1 #CV (C)
END-DEFINE
*
INPUT (IP=OFF) #HELLO (AD=M)
*
IF #HELLO NE 'HELLO' THEN
  MOVE (AD=U CD=RE) TO #CV
  REINPUT FULL WITH TEXT #VAR (CD=YE)
               MARK *#HELLO   (CV=#CV)
END-IF
END