In addition to commands, procedure lines can also contain data and statements. In S procedures, data can also be transferred with the SEND-DATA command and statements can be transferred with the SEND-STMT command.
This section deals with the following topics:
reading in data
generating an end-of-file condition
mixing data, statement and command lines
Reading in data
There are various ways of transferring data lines to a program. For example, a file containing the data lines can be opened in the program, or data can be read from SYSDTA.
In order for an input file to be opened and data lines to be read in the program, this file must be assigned to the program. This operates in procedures just as it does on the system level. For a detailed description, see the manual entitled “Introductory Guide to DMS” [1].
The standard path for inputting data is SYSDTA. Like the system files SYSCMD, SYSLST and SYSOUT, SYSDTA belongs to the SYSFILE environment. SYSDTA is a logical file (system file) and designates the path by which data is forwarded from the system to a program.
In S procedures (in contrast to non-S procedures), SYSDTA is assigned by default to SYSCMD. For example, using the ASSIGN-SYSDTA command, SYSDTA can be assigned to a file from which the program then reads the data records sequentially (for information on ASSIGN-SYSDTA, see “Commands” [3]).
If SYSDTA is assigned to a file in a procedure, it is exactly the same as assigning a file on the system level. However, the data lines can also be written directly into the procedure.
If SYSDTA is redirected using the command ASSIGN-SYSDTA TO-FILE=*SYSCMD, the program reads the data lines from the procedure.
In S procedures, the SEND-DATA command can be used to transmit data lines to the program which is loaded. In this case, each command call contains a data record or an expression that yields the data record when evaluated.
Data can also be written to separate data lines without the SEND-DATA command call.
A procedure line then contains exactly one input data record. However, you must also make sure that the end-of-file condition is generated (for information on the end-of-file condition, see "Data and statements "). Any ISAM key contained in the records is ignored.
Nevertheless, entering data by means of the SEND-DATA command has several advantages:
the procedure line “containing” the data record can be introduced by a tag
the procedure line with the data record can contain a comment
the data record can extend over several continuation lines
the data and end-of-file condition are generated by means of a standard interface (see the section “Creating the end-of-file condition”).
Example
/ABC = 'Word ' /DEF = 'processing' /START-EXE PROGRAM1 “Load program PROGRAM1” /SEND-DATA ABC “Input: Word” /SEND-DATA 'INPUT' “Input: INPUT” /SEND-DATA 'This is a very long input record that - /must always contain more than 72 characters' /SEND-DATA ABC // DEF “Input: Word /SEND-DATA ... processing”
In this example, different data records are read in consecutively. The fourth call of SEND-DATA contains as an argument an expression that yields the input “Word processing” when evaluated.
SEND-DATA can also be called within a loop in which input data records are generated successively.
Example
/SET-VARIABLE A = 'Text' /SET-VARIABLE B = 'verarbeitung' /SET-VARIABLE C = A // B /BEGIN-BLOCK PROGRAM-INPUT=*MIXED-WITH-CMD /START-EXE PROGRAM1 "Load program PROGRAM1" /FOR EINGABE = (A,B,C) "FOR loop in which the contents" / "of the variables A, B and C" / "are assigned sequentially“ / "to the control variable INPUT" /SEND-DATA EINGABE /END-FOR /END-BLOCK
Input records can also be written directly into a procedure line, without using the command call /SEND-DATA.
Example
/SET-PROCEDURE-OPTIONS DATA-ESCAPE-CHAR = *STD /VAR1 = 'Word ' /VAR2 = 'processing' /START-EXE PROGRAM1 “Load program PROGRAM1” &VAR1 'INPUT' &(VAR1 // VAR2) ...
In this example, the following data lines are transferred sequentially:
Text 'INPUT' Word processing
Mixing data, command and statement lines
For forwarding commands and data lines, SDF-P provides the command SEND-DATA. This allows commands and data lines to be mixed as desired.
SDF-P also offers a separate command for forwarding statements to a program: SEND-STMT. When this command is used, the statement is transferred as an operand value in the command call directly or is transferred as an expression that yields the statement when evaluated.
Mixing of data lines and command lines can also be declared in the BEGIN-BLOCK command, using the operand PROGRAM-INPUT=*MIXED-WITH-CMD. This setting applies to the current command block and to all blocks nested within this block; it cannot be deactivated in a subordinate block.
PROGRAM-INPUT=*MIXED-WITH-CMD has the effect that the system handles data and command lines “analogously”. This means that the command line does not trigger an endof-file condition. Instead, the system interrupts the program:
The system cancels the program’s “ready-to-receive state”, which corresponds to interrupting a program using HOLD-PROGRAM.
The system executes the commands until another data or statement line is read in.
The system reactivates the program’s “ready-to-receive state”, which corresponds to resuming a program using RESUME-PROGRAM.
Data or statement lines are then forwarded to the program until another command or a statement is read in or until the end-of-file condition is generated explicitly (for example, using /SEND-DATA *EOF).
Example
/BEGIN-BLOCK PROGRAM-INPUT=*MIXED-WITH-CMD / "DData and command lines can be mixed" /START-EXE PROGRAM1 "Start PROGRAM1" /FOR V = *LIST(L) "FOR loop, control variable: V" / "is passed to PROGRAM1" &V /END-FOR /END-BLOCK
In this example, the program PROGRAM1 is started up. As soon as data is requested from SYSDTA, the program is interrupted; the subsequent commands (BEGIN-BLOCK and
FOR) are executed.
In the FOR loop, the contents of the first element of the list L are first assigned to the variable V.
The next line (&V) is a data line. The program is resumed and the data line (i.e. the contents of variable V) is transferred to the program.
As soon as data is again requested from SYSDTA, the program is executed. If the list variable L contains additional elements, the loop is resumed and the contents of the next element are assigned to the variable V.
Data input is terminated when the list variable L has been “processed” and the FOR loop has been terminated.
END-BLOCK cancels the PROGRAM-INPUT=*MIXED-WITH-CMD setting with the result that the next command generates the end-of-file condition.
If data, statement and command lines can be mixed, this also applies when calling nested procedures using CALL-PROCEDURE or INCLUDE-PROCEDURE. The program is interrupted and the called procedure is first processed in command mode. Before data is again forwarded to the requesting program, the RESUME-PROGRAM command must be called (the “ready-to-receive state” must be re-enabled). Note, however, that an implicit RESUME-PROGRAM command must not be used here.
Therefore, data procedures must begin with the RESUME-PROGRAM command (in addition, S procedures must begin with a slash!).
The HOLD-PROGRAM can be used to interrupt data input once again in order to allow an explicit or implicit EXIT-PROCEDURE to be executed.
Example
BEGIN-BLOCK PROGRAM-INPUT=*MIXED-WITH-CMD
/START-EXE PROGRAM2
/CALL-PROCEDURE DATA.PROC "Data procedure call"
-----> /RESUME-PROGRAM "Program is ready to receive"
input-1
input-2
..
/HOLD-PROGRAM "Program is interrupted"
/EXIT-PROCEDURE
<---/...
"Superordinate procedure is resumed"
If the data procedure is not terminated with HOLD-PROGRAM, the end-of-file condition is generated after the last procedure line.
The setting PROGRAM-INPUT=*MIXED-WITH-CMD in the calling procedure does not apply in the data procedure. However, the /HOLD-PROGRAM command call does not yet generate an end-of-file condition. The procedure’s commands are executed, i.e. the procedure is terminated (implicitly if EXIT-PROCEDURE is omitted). In the calling procedure, however, the end-of-file condition is canceled, i.e. the program continues executing after the substituted RESUME-PROGRAM.
If an error occurs when a command is being executed, control is passed in command mode to the next error handling block (IF-BLOCK-ERROR).
Restrictions
The commands of the AID debugging utility must not be mixed with data. Mixing data lines with these commands may lead to unexpected program behavior since the program is resumed after each command (see the “AID” manual [6]).
The error status of statements is not always passed across to the command level. Consequently, it is possible that errors at statement level will not be processed until the end of the program when they are handled at command level by an IF-BLOCK-ERROR block.Setting BEGIN-BLOCK PROGRAM-INPUT=*STD/*MIXED-WITH-CMD has the following effects:
With PROGRAM-INPUT=*STD, the input of a command (not HOLD-PROGRAM) causes an end-of-file condition for statement inputs, and particular program responses (e.g. for TERM with errors). Errors, if any, are passed to the command level when the program terminates. I.e. they can subsequently be processed further using IF-BLOCK-ERROR.
Example
/BEGIN-BLOCK PROGRAM-INPUT=*STD /START-EXE MY-UTILITY "IF EOF DURING RDSTMT: TERMINATE" //... "FEHLER" /IF-BLOCK-ERROR; WRITE-TEXT 'ERROR DUE TO EOF'; END-IF /... "ERROR PROCESSING" /END-BLOCK
PROGRAM-INPUT=*MIXED-WITH-CMD(PROPAGATE-STMT-RC=*STD) interrupts command inputs while program statements (and possible errors) are input. However, no error will be passed to the command level. In this case, IF-BLOCK-ERROR will not process the error at statement level. However, the error can be interrogated using the predefined function STMT-SPINOFF( ); i.e. instead of IF-BLOCK-ERROR, IF-STMT-SPINOFF( ) must be specified.
Example
/BEGIN-BLOCK PROGRAM-INPUT=*MIXED-WITH-CMD /START-EXE MY-UTILITY "IF EOF DURING RDSTMT: TERMINATE" //... "ERROR" /IF-BLOCK-ERROR; WRITE-TEXT 'NO TEXT WRITTEN'; END-IF /... "NO ERROR PROCESSING AT COMMAND LEVEL" /END-BLOCK / "EOF IS NOW REPORTED, BECAUSE NO FURTHER DATA INPUT TAKES PLACE." / "PPROGRAM TERMINATES." / "N ERROR IS PASSED TO THE COMMAND LEVEL AFTER BLOCK END"
The operand setting PROGRAM-INPUT=*MIXED-WITH-CMD(PROPAGATE-STMT-RC=*TO-CMD-RC) interrupts the command input while program statements (and possibly errors) are entered. Return codes from program statements are transferred to the command level. In this manner, any errors occurring in the statement level can be handled with the IF-BLOCK-ERROR command and the predefined functions SUBCODE1( ), SUBCODE2( ) and MAINCODE( ).
Example
/BEGIN-BLOCK PROGRAM-INPUT=*MIXED-WITH-CMD - /(PROPAGATE-STMT-RC=*TO-CMD-RC) /START-LMS //... "ERROR AT STATEMENT LEVEL" //... /IF-BLOCK-ERROR /... "ERROR PROCESSING AT COMMAND LEVEL" /END-IF //END /END-BLOCK
Creating the end-of-file condition
Whether the system will create the end-of-file condition or execute a command depends on the setting of the PROGRAM-INPUT operand in the BEGIN-BLOCK command. For the default setting, BEGIN-BLOCK PROGRAM-INPUT=*STD, the end-of-file condition will be created if a command is called in the data stream. That is to say, data and command lines must not be mixed here - unless SEND-DATA is specified.
Example
/PROG: BEGIN-BLOCK /ABC = 'Word ' /DEF = 'processing' /START-EXE PROGRAM1 “Load PROGRAM1” &ABC INPUT &(ABC // DEF) ... /WRITE-TEXT ... /END-BLOCK PROG
In this example, the command WRITE-TEXT terminates the data input. From the initial slash, the system recognizes the line as a command line, and generates the end-of-file condition. After the program has terminated, the command is executed.
If the SEND-DATA command is used with the default setting of BEGIN-BLOCK to pass data to the program then - in order to generate the end-of-file condition - the operand
RECORD = *EOF must be specified in the last SEND-DATA command.
Example
/PROG: BEGIN-BLOCK /VAR1 = 'Word ' /VAR2 = 'processing' /START-EXE PROGRAM1 “Load PROGRAM1” /SEND-DATA VAR1 “Input: Word “ /SEND-DATA 'INPUT' “Input: INPUT” /SEND-DATA VAR1 // VAR2 “Input: Word processing” /SEND-DATA RECORD=*EOF “End of input: EOF”
The program can read the data records in sequentially.
Example
/PROG: BEGIN-BLOCK
/SET-VARIABLE A = 'Word '
/SET-VARIABLE B = 'processing'
/SET-VARIABLE C = A // B
/BEGIN-BLOCK PROGRAM-INPUT=
*MIXED-WITH-CMD
/START-EXE PROGRAM1 “Load PROGRAM1”
/FOR INPUT = (A,B,C) “FOR loop in which the contents of ”
/ “variables A, B, C are assigned in ”
/ “turn to the control variable”
/SEND-DATA INPUT “INPUT”
/END-FOR
/SEND-DATA *EOF “End of input: EOF”
/END-BLOCK
As described above, specifying BEGIN-BLOCK PROGRAM-INPUT=*MIXED-WITH-CMD allows data and command lines to be mixed without additionally specifying a SEND-DATA command. However, it is still necessary to specify SEND-DATA=*EOF to generate the endof-file condition.
Example
One command block is nested within another. In the superordinate block, PROGRAM-INPUT=*MIXED-WITH-CMD is set; this also affects the subordinate block.
/BEGIN-BLOCK PROGRAM-INPUT=*MIXED-WITH-CMD /... /COMP: BEGIN-BLOCK /START-EXE $RZ.FOR1 PROGRAM STATIST ... END /SEND-DATA *EOF /START-EXE $BINDER ... /END-BLOCK COMP ... /END-BLOCK
In the subordinate block, the FORTRAN compiler FOR1 reads in a FORTRAN program line by line until the system detects a command call.
The program is interrupted and the command is executed. The end-of-file condition is generated, thus activating end-of-file handling in the compiler. The FORTRAN program is compiled.
The static linkage editor BINDER is then called. The compiler FOR1 is unloaded and BINDER is loaded and started. Statements to the BINDER then follow.
If the /SEND-DATA *EOF command call were to be omitted in this example, the following would occur:
Data input would be interrupted by the first command, without an end-of-file condition starting the compiler, because in this case PROGRAM-INPUT=*MIXED-WITH-CMD was specified.
This command (START-EXE $BINDER) would be executed, i.e. the compiler FOR1 would be unloaded (without first writing the results of the compilation) and the BINDER program would be loaded.
Since no end-of-file condition was generated, the program was not compiled.Consequently, BINDER cannot access a newly compiled program.