The evaluation block (EVALBLOCK)

The evaluation block is a control block that IRXEXEC uses to return the result from the exec. The exec can return a result on either the RETURN or EXIT instruction. For example, the REXX instruction

RETURN var1

returns the value of the variable VAR1. IRXEXEC returns the value of VAR1 in the evaluation block.

If the exec you are running will return a result, specify the address of an evaluation block when you call IRXEXEC (parameter 6). You must obtain the storage for the control block yourself.

If the exec does not return a result or you want to ignore the result, you need not allocate an evaluation block. On the call to IRXEXEC, you must pass all of the parameters. Therefore, specify an address of 0 for the evaluation block.

If the result from the exec fits into the evaluation block, the data is placed into the block (EVDATA field) and the length of the block is updated (ENVLEN field). If the result does not fit into the area provided in the evaluation block, IRXEXEC:

Places as much of the result that will fit into the evaluation block in the EVDATA field
Sets the length of the result field (EVLEN) to the negative of the length that is required to store the complete result.

The result is not lost. The system has its own evaluation block that it uses to store the result. If the evaluation block you passed to IRXEXEC is too small to hold the complete result, you can then use the IRXRLT (get result) routine. Allocate another evaluation block that is large enough to hold the result and call IRXRLT. On the call to the IRXRLT routine, you pass the address of the new evaluation block. IRXRLT copies the result from the exec that was stored in the system's evaluation block into your evaluation block and returns. Get result routine - IRXRLT describes the routine in more detail.

If you call IRXEXEC and do not pass the address of an evaluation block, and the exec returns a result, you can use the IRXRLT routine after IRXEXEC completes to obtain the result.

To summarize, if you call IRXEXEC to run an exec that returns a result and you pass the address of an evaluation block that is large enough to hold the result, IRXEXEC returns the result in the evaluation block. In this case, IRXEXEC does not store the result in its own evaluation block.

If IRXEXEC runs an exec that returns a result, the result is stored in the system's evaluation block if:

The result did not fit into the evaluation block that you passed on the call to IRXEXEC
You did not specify the address of an evaluation block on the call

You can then obtain the result by allocating a large enough evaluation block and calling the IRXRLT routine to get the result. The result is available until one of the following occurs:

IRXRLT is called and successfully obtains the result
Another REXX exec runs in the same language processor environment, or
The language processor environment is terminated

The language processor environment is the environment in which the language processor processes the exec. See Language Processor Environments for more information about the initialization and termination of environments and customization services.

The evaluation block consists of a header and data, which contains the result. Table 1 shows the format of the evaluation block. Additional information about each field is described after the table.

TSO/E provides a mapping macro IRXEVALB for the evaluation block. The mapping macro is in SYS1.MACLIB.

Table 1. Format of the evaluation block
Offset (decimal)	Number of bytes	Field name	Description
0	4	EVPAD1	A fullword that must contain X'00'. This field is reserved and is not used.
4	4	EVSIZE	Specifies the total size of the evaluation block in doublewords.
8	4	EVLEN	On entry, this field is not used and must be set to X'00'. On return, it specifies the length of the result, in bytes, that is returned. The result is returned in the EVDATA field at offset +16.
12	4	EVPAD2	A fullword that must contain X'00'. This field is reserved and is not used.
16	n	EVDATA	The field in which IRXEXEC returns the result from the exec. The length of the field depends on the total size specified for the control block in the EVSIZE field. The total size of the EVDATA field is: `EVSIZE * 8 - 16` It is suggested that you use 250 bytes for the EVDATA field. For information about the values IRXEXEC returns, if the language processor detects a syntax error in the exec, see How IRXEXEC returns information about syntax errors.

If the result does not fit into the EVDATA field, IRXEXEC stores as much of the result as it can into the field and sets the length field (EVLEN) to the negative of the required length for the result. You can then use the IRXRLT routine to obtain the result. See Get result routine - IRXRLT for more information.

On return, if the result has a length of 0, the length field (EVLEN) is 0, which means the result is null. If no result is returned on the EXIT or RETURN instruction, the length field contains X'80000000'.

If you invoke the exec as a "command" (bit 0 is set on in parameter 3), the result the exec returns must be a numeric value. The result can be from -2,147,483,648 to +2,147,483,647. If the result is not numeric or is greater than or less than the valid values, this indicates a syntax error and the value 20026 is returned in the EVDATA field.