Calling a user-defined statement

Entering the defined user statement symbol (spec) for a user-defined statement starts the corresponding statement as a subroutine.

Any required text can be passed to the statement routine.

If an entry point (@USE COMMAND= ...,ENTRY=entry,...) was defined at the time of declaration with @USE, then the entire text following the user statement symbol is passed to the statement routine when the user-defined statement is entered. This text can be interpreted by the statement routine as required.

If no entry point (@USE COMMAND= ...,ENTRY=*,...) was defined at the time of declaration with @USE, then, when the user-defined statement is entered, the name of theentry point (entry) must be specified. After this, a string is specified and this is passed to the statement routine.

spec entry [chars]

In this case, entry can be considered as the statement name and chars as an operand. If the compatible format of the @USE statement has been used, then at most the first 8 characters (in uppercase and converted to the EDF03IRV character set) of the user-defined statement are considered to constitute the name of the entry point.

If the new format has been used, then at most the first 32 characters (in uppercase and converted to the EDF03IRV character set) are considered to constitute the name of the entry point.

Entry points which are specified in this way in the user-defined statement itself must therefore not contain any lowercase characters.

It is advisable to separate the statement name in this type of user-defined statement from the remainder of the statement with a space in order to avoid interpretation errors due to this truncation after 8 or 32 characters.

If it is not possible to convert the text that is to be passed to the statement routine into the character set which was defined via the initialization routine (see “Calling the initialization routine for a user-defined statement”) then the statement is rejected with an error message.

If the user statement symbol is identical to the current EDT statement symbol then the EDT statement has priority. This means that only if no EDT statement (in any permitted abbreviated form) can be identified is it assumed that the statement in question is a user statement. It is the user's responsibility to avoid conflicts.

When the statement routine is branched to, the registers are loaded as follows:

Register	Data area
(R1) (R13) (R14) (R15)	A (PARAMETERLIST) A (SAVEAREA) A (RETURN) V (ENTRY)

For an explanation of the register contents, see section “Calling EDT”.

Parameter list       :     A (EDTGLCB, COMMAND)

EDT passes the following parameters to the statement routine:

• EDTGLCB
  Global EDT control block which is supplied by EDT and is already initialized.
  The control block may no longer be modified once the user routine is exited.

  The version of the EDTGLCB control block that is used is determined via the initialization routine (see section “Calling the initialization routine for a user-defined statement”). EDT passes the key used to send the statement in the EGLCDS field (only in the case of statement filters, see section “Special application as statement filter”).

  The control block is described in section “EDTGLCB - Global EDT control block”.

• COMMAND
  Buffer provided by EDT which contains the string which was specified on the entry of the external statement.

  The user statement symbol is not passed. The maximum length is 32763 bytes + 4 byte length field (see section “Buffers”).

  The COMMAND buffer is coded in the character set which was declared via the initialization routine (see the section on calling the initialization routine for a user-defined statement).

  EDT enters the name of the character set in the EGLCCSN field.
  The character set may be converted to uppercase before being passed to the statement routine depending on the @PAR LOW setting.

Note

The remainder of the description relates to a call issued with version 2 of the EDTGLCB control block. For a description of a call using version 1 of the control block, see [3].

A statement routine should always query the version of the received EDTGLCB control block.

Overview

EDT calls the statement routine with the following parameter list:

Parameter list        :     A (EDTGLCB, COMMAND)

Call parameter		Return parameter
Values supplied by EDT before the external statement routine is called		Evaluated by EDT after control is returned from the external statement routine
EDTGLCB:	EGLUNIT EGLVERS EGLCCSN EGLCDS EGLUSR1 EGLUSR2	EDTGLCB:	EGLRETC EGLRMSG EGLCMDS EGLFILE EGLUSR2
COMMAND

Return codes for user-defined statements

The return codes are set by the statement routine and evaluated by EDT. If the statement routine has not entered any message text in the EGLRMSG field then EDT issues the following messages depending on the return code:

EGLMRET	EGLSR1	Meaning
EUPRETOK EUPSYERR EUPRTERR	00 00 00	No message. Message EDT3991 Message EDT5991

If the statement routine has stored a user-defined message in the EGLRMSG field then EDT outputs this message instead of the messages described above (also in the case of EUPRETOK).
Depending on the return code, the statement routine's message text is used in one of the EDT messages EDT0999, EDT3999 or EDT5999.

If a different return code is received, EDT issues the message EDT5410. In this case, the user-defined message specified in the EGLRMSG field is not output.

Usually, the statement routine is intended to communicate with the calling EDT instance, i.e. it uses the EDTGLCB passed at the interface for EDT subroutine interface calls.

The statement routines can be used to execute the following functions:

• the record access functions IEDTGET, IEDTPUT, etc. (see section “Logical recordaccess functions”).

• the IEDTEXE function which executes an EDT statement (see section “IEDTEXE -Execute EDT statements without screen dialog”).

  The following statements may not be specified for IEDTEXE:

  • a further user-defined statement

  • the user routine call (@RUN)

  • the statements @DIALOG, @EDIT, @END, @HALT, @MODE and @RETURN

  • the procedure calls @DO and @INPUT.

In exceptional cases, it may be necessary for the statement routine to communicate with another EDT instance. To do this, it is necessary to use an EDTGLCB which has been initialized independently of the supplied EDTGLCB or which has not been initialized at all. Since the two EDT instances run completely independently of one another, calls to the other instance are not subject to any restrictions. If this method is used, it is not possible to access the calling instance's data.