@DO (format 1) - Start EDT procedures from work files

Format 1 of the @DO statement starts a @DO procedure, i.e. the text lines and EDT statements in the specified work file are processed.
For information on the structure and processing of EDT procedures, see section “EDT procedures”).

Operation	Operands	F mode, L mode
@DO	procnr [,] [ (param [,...]) ] [spec] [=line1,line2 [, [-] line3] ] [PRINT]

procnr	The number of the work file (1..22) whose content is to be processed by EDT. If the work file is empty, error message EDT4950 is issued.
param	Parameters which are passed to the procedure that is to be run. The parameters must be defined in the procedure using @PARAMS (see the @PARAMS statement). They are separated from one another by commas. If parameters (including empty parameters) are specified in a procedure which contains no @PARAMS statement then the statement is rejected with the message EDT4944. If too many parameters are specified then the error message EDT4963 or EDT4965 is output. A distinction is made between positional and keyword parameters. In the case of positional parameters, only the value of the parameter is passed. In the case of keyword parameters, an expression of the form formal=value is passed where formal is the keyword (not prefixed by the & character) with which the parameter was defined in the @PARAMS statement (detailed information on parameter transfer can be found in the description of the @PARAMS statement below). The positional parameters must be located before the keyword parameters and must be specified in precisely the same order as they were defined in @PARAMS. Keyword parameters can be specified in any order. If a positional parameter is specified after a keyword parameter then the statement is rejected with EDT4948. If a keyword parameter is specified more than once then the message EDT3911 is issued. The possible number of parameters is limited by the maximum length of an EDT statement.
spec	Loop counter. In the procedure, this can be used as an operand in EDT statements if it is necessary to address a line number. When the procedure is executed, EDT uses the current value of the loop counter at all times (see section “EDT procedures”). The loop counter must be one of the permitted special characters as otherwise @DO is rejected with the error message EDT3952. To avoid errors and unpredictable events, the following characters should not be used as a loop counter. % $ ? * ( : # + -  . < = > ’ ; The command syntax means that the '=' character cannot be specified at all. If the procedure is started in F mode then ';' may not be used. Suitable characters for the loop counter are: ! { } [ ] | / If the loop counter is not specified then it is considered to be undefined. If the sequence of operands line1,line2,[–]line3 is not specified then the loop counter has the value 1.
=line1,line2,[–]line3
	A procedure is repeated several times (see example 3). Before the first pass, EDT assigns the initial value line1 to the loop counter. After every pass, EDT increments or decrements (minus sign in front of line3) the loop counter by line3. The default value for line3 is 1. The procedure is repeated as long as the loop counter has not risen above (or fallen below) the value of line2. Otherwise the execution of the procedure is aborted. The procedure is passed through at least once since the counter value is checked after the last line has been processed (REPEAT UNTIL). If the presence of a @RETURN statement in the procedure means that the last line is not processed then no check is performed and the procedure is not repeated. Line number symbols (e.g. %,$) may also be specified for line1, line2 or line3. EDT uses the value which this symbol had when @DO is executed. If the value of this symbol changes during execution of the procedure then the number of passes is not affected. In the procedure, the loop counter is treated like a line number variable. The loop counter is therefore only replaced by the current value if it is addressed as a line number, in particular therefore not in literals. If the loop counter is specified in a statement which permits a line number with an implicit increment then – in the same way as for line number variables - the implicit increment is always considered to be 0.0001 (see example 6. The fact that a special character is only considered to be a loop counter if it is used instead of a line number and is specified as a loop counter in the calling @DO statement means that the same loop counter can be used more than once for nested external loops. In this case, it always has the values that are specified in the calling @DO statement (see example 7). It is not possible to access loop counters which have been specified in a lower nested level at call time. The symbols used there are not replaced by line numbers in higher levels and this usually results in syntax errors. The default value for line1, line2 and line3 is 1.
PRINT	Each line of the procedure should be logged (with expanded parameters) before it is executed. In interactive mode, the output is written to SYSOUT and in batch mode it is written to SYSLST. Specifying PRINT also causes all error messages to be output and sets the EDT error switch. Normally, the two messages EDT0901 and EDT4932 are not output in procedures and the EDT error switch is not set (see section “Message texts”).

The value of a positional parameter is determined by all the characters, including blanks, specified between the commas or parentheses.
If there are no characters between the commas or parentheses then the value of the positional parameter is a empty string.
The value of a keyword parameter is determined by all the characters, including blanks, specified between the equals sign and the following comma or parenthesis.
If there are no characters between the equals sign and the following comma or parenthesis then the value of the keyword parameter is a empty string.
A parameter may be enclosed in single quotes. These are not transferred if they occur as the first or last character in the parameter value and only double quotes occur between them.
In all other cases, the specified single quotes form part of the parameter (see the examples for the @PARAMS statement). The comma and closing parenthesis characters may only form part of a parameter if they occur in a substring in the parameter value that is enclosed by single quotes.
Single quotes must always occur in pairs in a parameter value. An individual single quote cannot be passed in a parameter value. If @QUOTE has already been used to assign the function of the single quote to another character then this does not apply to the single quotes enclosing the parameter value.
If a positional parameter is not specified then it is assigned the value of an empty string. If a keyword parameter is not specified then it is assigned the default value defined in the @PARAMS statement.

During parameter substitution, the specified parameters are converted into the character set used by the procedure work file. If the string variable contains characters which cannot be displayed in the target character set then these are replaced by a substitute character if such a character has been specified (see @PAR SUBSTITUTION-CHARACTER). Otherwise, the @DO statement is rejected and the error message EDT5453 is output.

The parameters may contain Unicode substitute representations. These are not expanded during the parameter substitution process. This is not done until the associated procedure line is executed.

EDT procedures can be interrupted at any time using [K2].
In the operating system, it is then possible to use /RESUME-PROGRAM to continue the procedure or use /INFORM-PROGRAM to return to EDT and abort the procedure.

The procedure cannot be aborted with /INFORM-PROGRAM while a user statement (see @USE) is being executed.

An illegal statement during execution does not cause the procedure to be aborted.

Example 1

1.     @SET #S0 = 'TEST OF PROCEDURE FILE 1'
1.     @PROC 1 ------------------------------------------------------- (1)
1.     @ @SET #S1 = #S0:1-4: ----------------------------------------- (2)
2.     @ @CREATE #S2: ' '*4,#S0:5-8:
3.     @ @CREATE #S3: ' '*9,#S0:9-24:
4.     @ @CREATE #S4: ' '*24
5.     @ @PRINT #S1.-#S4
6.     @ @PRINT #S0
7.     @END ---------------------------------------------------------- (3)
1.     @DO 1 --------------------------------------------------------- (4)
  #S01 TEST
  #S02      OF
  #S03          PROCEDURE FILE 1
  #S04
  #S00 TEST OF PROCEDURE FILE 1
1.

(1)	Processing switches to work file 1.
(2)	EDT statements are written to work file 1. When the procedure is called with @DO, these cause the string variables #S1 to #S4 to be created and output together with #S0.
(3)	@END causes a return from work file 1.
(4)	The procedure located in work file 1 is called.

Example 2

1.     @PROC 2 ------------------------------------------------------- (1)
1.     @ @PARAMS &STRING --------------------------------------------- (2)
2.     @ @SET #S1 = '+++++++++++'
3.     @ @SET #S2 = &STRING ------------------------------------------ (3)
4.     @ @PRINT #S2
5.     @END
1.     @DO 2(#S1) PRINT ---------------------------------------------- (4)
1.     @SET #S1 = '+++++++++++'
1.     @SET #S2 = #S1
1.     @PRINT #S2
  #S02 +++++++++++
1.     @DO 2('#S1') PRINT -------------------------------------------- (5)
1.     @SET #S1 = '+++++++++++'
1.     @SET #S2 = #S1
1.     @PRINT #S2
  #S02 +++++++++++
1.     @DO 2('BLANK''#S1''BLANK') PRINT ------------------------------------------ (6)
1.     @SET #S1 = '+++++++++++'
1.     @SET #S2 = 'BLANK''#S1''BLANK'
1.     @PRINT #S2
  #S02 #S1
1.

(1)	Processing switches to work file 2.
(2)	The first line stored in this work file is a @PARAMS statement. This makes it possible to address the positional parameter &STRING in this work file.
(3)	#S2 is to be assigned a value that is not available at the time work file 2 is defined and will only be defined in a @DO 2(...)... statement.
(4)	The value #S1 present in parentheses causes &STRING to be replaced globally by the value #S1 before the statements located in work file 2 are executed. PRINT causes the statements to be output before they are executed.
(5)	The value #S1 is now passed for the positional parameter &STRING. Since the first and last characters of this parameter value are single quotes they are removed when the parameter value is replaced in work file 2 as the PRINT operand here clearly shows. This therefore has the same effect as (4).
(6)	The only difference to (5) is that the parameter value has been extended by a preceding or following blank. However, this is sufficient to ensure that the content of the parameter value is passed.

Example 3

 1.     *
 2.     @PROC 3 ------------------------------------------------------- (1)
 1.     @ @CREATE $+1: $,'*' ------------------------------------------ (2)
 2.     @END ---------------------------------------------------------- (3)
 2.     @DO 3,!=1,15 -------------------------------------------------- (4)
 2.     @PRINT
 1.0000 *
 2.0000 **
 3.0000 ***
 4.0000 ****
 5.0000 *****
 6.0000 ******
 7.0000 *******
 8.0000 ********
 9.0000 *********
10.0000 **********
11.0000 ***********
12.0000 ************
13.0000 *************
14.0000 **************
15.0000 ***************
16.0000 **************** ---------------------------------------------- (5)
 2.

(1)	Processing switches to work file 3.
(2)	A single EDT statement is written to work file 3.
(3)	Processing returns to work file 0.
(4)	Work file 3 is executed. In this case, the ! character is used as a loop counter. Work file 3 is executed 15 times. It would be possible to address line numbers there using !. However, this can be omitted as in this example. The specification !=1,15 has the same effect as issuing @DO 3 fifteen times without this sequence of operands.
(5)	In the output, it can be seen that 15 new lines have been created.

Example 4

   5.     @PRINT
   1.0000 1111111
   2.0000 2222222
   3.0000 3333333
   4.0000 4444444
   5.     @SET #S4 = '-----------------'
   5.     @PROC 4 ------------------------------------------------------- (1)
   1.     @ @PRINT !.-.$ ------------------------------------------------ (2)
   2.     @ @PRINT #S4 N
   3.     @END
   5.     @DO 4,!=$,%,-1 ------------------------------------------------ (3)
   4.0000 4444444
-----------------
   3.0000 3333333
   4.0000 4444444
-----------------
   2.0000 2222222
   3.0000 3333333
   4.0000 4444444
-----------------
   1.0000 1111111
   2.0000 2222222
   3.0000 3333333
   4.0000 4444444
-----------------
   5.

(1)	Processing switches to work file 4.
(2)	A line number is addressed via the loop counter !.
(3)	Work file 4 is executed a number of times. On the first pass, the value of the highest assigned line number is assumed for !. On each subsequent pass, this value is reduced by 1 (third line=-1) until the line number has the value of the lowest assigned line number (%).

Example 5

1.     @PROC 4 ------------------------------------------------------- (1)
1.     @READ 'PROC-FILE.4' ------------------------------------------- (2)
6.     @PRINT
1.0000 @PARAMS &A, &OPTION=ALL 
2.0000 ABCABCABCABC
3.0000 EFG
4.0000 @ON  1 CHANGE &OPTION 'ABC' TO '&A'
5.0000 @5: &A
6.     @END ---------------------------------------------------------- (3)
1.     @DO 4 ('A','B',OPTION=R) -------------------------------------- (4)
6.     @PRINT
1.0000 ABCABCABCA,'B ------------------------------------------------- (5)
2.0000 EFG
5.0000  A,''B
6.

(1)	Processing switches to work file 4.
(2)	The SAM file PROC-FILE.4 is read into work file 4.
(3)	Processing returns to work file 0.
(4)	The default value ALL of the keyword parameter &OPTION is replaced by R at call time. As a result, the search and replace operation in line 1 is performed backwards.
(5)	The execution of the work file caused lines to be written to the current work file. In line 1, EDT has removed one of the 2 successive single quotes. In line 3, EDT has taken over the parameter value unchanged.

Example 6

1.     AAA
2.     BBB
3.     CCC
4.     @PROC 1
1.     @@COPY 1-3 TO ! ----------------------------------------------- (1)
2.     @END 
4.     @DO 1,!=4,4 --------------------------------------------------- (2)
5.0002 @DO 1,!=5.0,5.0 ----------------------------------------------- (3)
6.0002 @PRINT -------------------------------------------------------- (4)
1.0000 AAA
2.0000 BBB
3.0000 CCC
4.0000 AAA
4.0001 BBB
4.0002 CCC
5.0000 AAA
5.0001 BBB
5.0002 CCC
6.0002

(1)	The procedure file contains a statement in which the increment is implicitly defined by specifying the line number of the target range.
(2)	Calls the procedure with loop counter 4.
(3)	Calls the procedure with loop counter 5.0.
(4)	The output shows that the implicit increment 0.0001 is always used for the loop counter as is also the case for line number variables.

Example 7

1.     @PROC 1
1.     @   @DO 2, !=!,1,-1 ------------------------------------------- (1)
1.     @END 
1.     @PROC 2
1.     @   @SET #L1 = ! ---------------------------------------------- (2)
2.     @   @SET #S1 = C #L1 ------------------------------------------ (3)
3.     @   @PRINT #S1 ------------------------------------------------ (4)
3.     @END 
1.     @DO 1,!=1.4 --------------------------------------------------- (5)
  #S01    1.0000 ----------------------------------------------------- (6)
  #S01    2.0000
  #S01    1.0000
  #S01    3.0000
  #S01    2.0000
  #S01    1.0000
  #S01    4.0000
  #S01    3.0000
  #S01    2.0000
  #S01    1.0000
1. 

(1)	A @DO procedure is stored in work file 1. In this case, the loop counter ! is significant for two reasons: on the one hand, it is redefined by the @DO procedure call in work file 2 and, on the other, the current value of the loop counter specified when work file 1 was called is taken over as the initial value. This is possible because substitution is only performed in locations where the ! symbol is also used as a line number.
(2)	In work file 2, the current value of the work file's loop counter is assigned to the line number variable #L1.
(3)	The line number variable #L1 is stored in printable form in #S1.
(4)	The string variable #S1 is output.
(5)	When work file 1 is called, the loop counter is allowed to run from 1 to 4.
(6)	The result indicates that the internal loop counter (in work file 2) runs backwards 4 times until it reaches 1.0000 on the basis of the starting values 1.0000 to 4.0000.