IEDTCMD - Execute EDT statements

This call passes a statement or sequence of statements to EDT for execution.
If the application field (length 4) is empty then processing returns immediately to the calling program.

The following statements are permitted at the IEDTCMD interface.

The user-defined statements are also permitted (see chapter “User defined statements -@USE”).

The @EDIT statement (except with format 4 - @EDIT LONG...) is always interpreted as @EDIT ONLY at the IEDTCMD interface and causes a switchover to line mode dialog.

The EDT statement symbol does not have to be specified (except in the case of @:).

The program run (initialization, transition to user dialog, termination with unload and release of memory) is controlled by means of the sequence of statements passed to EDT.

Once EDT has been loaded, its data area is initialized (on the 1st call only).

After executing the sequence of statements, EDT returns to the calling program.

@HALT in the passed sequence of statements results in the termination of EDT (release of memory and unloading).

If the statement sequence does not end with @HALT then control returns to the calling program without the data area being released. Processing can be continued by issuing a new call with a statement sequence or @HALT can be specified to terminate EDT.

In a routine which processes a user-defined statement or in a user routine (see section “User defined statements - @USE” and “User routines - @RUN”), it is only possible to call the IEDTCMD interface if the call is intended to address an instance of EDT other than the calling instance.

If statements addressed to the calling EDT instance use the global control block EDTGLCB passed to the statement routine then they are permitted only via the IEDTEXE interface. A call of the IEDTCMD interface from a statement routine with the EDTGLCB of the calling instance is rejected with the return code EUPPAERR/EUPPA08. For further information, see chapter “User defined statements - @USE” and following sections.

If an error occurs (syntax or runtime error) then execution is immediately interrupted with a corresponding return code and an error message. In such cases, the EGLCMDS (in EDTGLCB) field is used as an error pointer. This points to the start of the invalid statement within the statement sequence. For reasons of compatibility, the first character after the record length field is numbered '1' (using this numbering convention, the first character in the passed statement sequence has the number '3'). Counting is always performed in characters not in bytes. The return code EUPSYERR or EUPRTERR is passed.

User dialog

It is possible to switch to the user dialog by means of the @DIALOG statement (screen dialog) or by means of @EDIT ONLY (line mode dialog) in the passed statement sequence.

Whenever processing switches to the screen dialog as the result of @DIALOG in the passed statement sequence, the transferred messages (MESSAGE1, MESSAGE2) are displayed in the message lines.

@EDIT ONLY switches to line mode dialog (read with RDATA).

The user dialog is terminated with @END, @HALT or @RETURN or, in F mode,by pressing the [K1] key.

EDT passes a return code to the global control block EDTGLCB (EGLRETC). After termination of the user dialog, execution of the statement sequence is continued. The @END statement sets the same return code as @HALT.

If <message> is specified in a @HALT or @RETURN statement then the message text is also entered in the EGLRMSGF message field of the EDTGLCB control block.

If the dialog was terminated with @HALT ABNORMAL then the main return code EUPABERR is set.

If the flag EUPNTXT is set in EDTUPCB then the specification of message or ABNORMAL is rejected with an error message (in the dialog).

The flag EGLSTXIT in EDTGLCB is evaluated on every call via the IEDTCMD interface. On return to the calling program, the EDT interrupt routines are exited (if they have been requested).

If the flag EUPNUSER is set in EDTUPCB then attempts to execute a @USE statement are rejected in the dialog.

Control structures

The following data areas must be defined before calling the function:

• the control block EDTGLCB

• the control block EDTUPCB

• the statement sequence (COMMAND)

• 2 optional message lines (MESSAGE1 and MESSAGE2), otherwise a null pointer

The control blocks can be found in the section “Generation and structure of the control blocks”. The COMMAND, MESSAGE1 and MESSAGE2 buffers are described in the section on buffers.

If the screen is not split, MESSAGE1 is displayed in the message line in the dialog. If the screen is split, MESSAGE1 is displayed in the first and MESSAGE2 in the second message line.

If the length field of MESSAGE1 or MESSAGE2 has a value smaller than or equal to 4 then the corresponding message is not output. If this occurs in the first call to the user dialog, the EDT start message is output.
The same applies if a null pointer is called specified.

If @DIALOG or @EDIT ONLY occurs other than as the last statement in the statement sequence then it should be noted that the return code and message in EDTGLCB may be due to subsequent statements.

Call

The following specifications are required (see overview):

• Entry of values in the required fields in the EDTGLCB and EDTUPCB control blocks.

• Entry of the statement sequence in the COMMAND buffer.

• Entry of the message texts in the MESSAGE1 and MESSAGE2 or entry of null pointers in the corresponding fields in the parameter list.

• Call of the entry point address IEDTCMD with the parameter list

Overview

(For the control blocks, see section “EDTGLCB - Global EDT control block”).

Entry point address     :     IEDTCMD

Parameter list         :     A (EDTGLCB, EDTUPCB, COMMAND,

 MESSAGE1, MESSAGE2)

Call parameter		Return parameter
EDTGLCB:	EGLUNIT EGLVERS EGLINDB EGLCCSN	EDTGLCB:	EGLRETC EGLRMSG EGLCMDS EGLFILE
EDTUPCB:	EUPUNIT EUPVERS EUPINHBT
COMMAND MESSAGE1 / NULL MESSAGE2 / NULL

Note
On each return, the return code and the name of the current work file (EGLFILE) are entered in the EDTGLCB control block.

Return codes

EGLMRET	EGLRS1
EUPRETOK	EUPOK00 EUPOK04 EUPOK08 EUPOK12 EUPOK16 EUPOK20
EUPSYERR EUPRTERR EUPEDERR EUPOSERR EUPUSERR EUPPAERR	00 00 00 00 00 EUPPA04 EUPPA08 EUPPA12 EUPPA16 EUPPA20 EUPPA24
EUPSPERR EUPABERR	00 EUPOK08

EGLMRET and EGLRS1 are fields in the control block EDTGLCB. For the meaning of the return codes, see section “EDTGLCB - Global EDT control block”.

Example

*****************************************************************
* CMDBSP:  EXAMPLE OF EXECUTION OF AN EDT STATEMENT SEQUENCE    *
*          IN UNICODE MODE                                      *
*          (PAR SPLIT=OFF,LOWER=ON,SCALE=ON,INDEX=ON;DIALOG)    *
*****************************************************************
*
CMDBSP   START
CMDBSP   AMODE ANY
CMDBSP   RMODE ANY
         BALR  R10,0
         USING *,R10
         MVC   EGLCCSN,CCSN041
         LA    R13,SAVEAREA
         LA    R1,CMDPL
         L     R15,=V(IEDTCMD)
         BALR  R14,R15

         TERM  ,
*
* DATA AREA
R1       EQU   1
R10      EQU   10
R13      EQU   13
R14      EQU   14
R15      EQU   15
*
SAVEAREA DS    18F
* - CONTROL BLOCKS (EDTGLCB, EDTUPCB)
         IEDTGLCB C,VERSION=2
         IEDTUPCB C,VERSION=3
* - STATEMENT SEQUENCE (COMMAND)
CMDDIA   DC    Y(CMDDIAL)
         DC    CL2' '
         DC    C'PAR SPLIT=OFF,LOWER=ON,SCALE=ON,INDEX=ON;DIALOG'
CMDDIAL  EQU   *-CMDDIA
* - MESSAGE LINE (MESSAGE1)
MSG1DIA  DC    Y(MSG1DIAL)
         DC    CL2' '
         DC    C'DIALOG END WITH HALT OR <K1>'
MSG1DIAL EQU   *-MSG1DIA
* - MESSAGE LINE (MESSAGE2)
MSG2DIA  DC    Y(MSG2DIAL)
         DC    CL2' '
MSG2DIAL EQU   *-MSG2DIA
* - PARAMETER LIST FOR CMD
CMDPL    DC    A(EDTGLCB)
         DC    A(EDTUPCB)
         DC    A(CMDDIA)
         DC    A(MSG1DIA)
         DC    A(MSG2DIA)
*
CCSN041  DC    CL8’EDF041 ’
*
         END   CMDBSP

Call in the C program

Required include files:

#include <stdio.h>

#include <iedtgle.h>

The control blocks EDTGLCB and EDTUPCB are declared and
initialized as follows:

iedglcb glcb = IEDGLCB_INIT;

iedupcb upcb = IEDUPCB_INIT;

For the format and values to be entered in the structures command, message1 andmessage2, refer to the example in section “Example 1 - C main program”.

The IEDTCMD function is called with the addresses of these structures:

IEDTCMD(&glcb,&upcb,&command,&message1,&message2);