RETURN (Return to Caller)
| Free-Form Syntax | RETURN{(HMR)} expression |
| Code | Factor 1 | Extended Factor 2 | ||||
|---|---|---|---|---|---|---|
| RETURN (H M/R) | expression | |||||
The RETURN operation causes a return to the caller. If a value is returned to the caller, the return value is specified in the expression operand.
- The halt indicators are checked. If a halt indicator is on, the procedure ends abnormally. (All open files are closed, an error return code is set to indicate to the calling routine that the procedure has ended abnormally, and control returns to the calling routine.)
- If no halt indicators are on, the LR indicator is checked. If LR is on, the program ends normally. (Locked data area structures, arrays, and tables are written, and external indicators are reset.)
- If no halt indicator is on and LR is not on, the procedure returns to the calling routine. Data is preserved for the next time the procedure is run. Files and data areas are not written out. See the chapter on calling programs and procedures in the Rational Development Studio for i: ILE RPG Programmer's Guide for information on how running in a *NEW activation group affects the operation of RETURN.
When a subprocedure returns, the return value, if specified on the prototype of the called program or procedure, is passed to the caller. Automatic files are closed. Nothing else occurs automatically. All static or global files and data areas must be closed manually. You can set on indicators such as LR, but this will not cause program termination to occur.
For information on how operation extenders H, M, and R are used, see Precision Rules for Numeric Operations.
In a subprocedure that returns a value, a RETURN operation must be coded within the subprocedure. The actual returned value has the same role as the left-hand side of the EVAL expression, while the extended factor 2 of the RETURN operation has the same role as the right-hand side. An array may be returned only if the prototype has defined the return value as an array.
Attention!
If the subprocedure returns a value, you should ensure that a RETURN operation is performed before reaching the end of the procedure. If the subprocedure ends without encountering a RETURN operation, an exception is signalled to the caller.
Performance tip
Specifying the RTNPARM keyword on your prototype may significantly improve the performance for returning large values. See RTNPARM for more information.
For more information, see Call Operations.
* This is the prototype for subprocedure RETNONE. Since the
* prototype specification does not have a data type, this
* subprocedure does not return a value.
D RetNone PR
* This is the prototype for subprocedure RETFLD. Since the
* prototype specification has the type 5P 2, this subprocedure
* returns a packed value with 5 digits and 2 decimals.
* The subprocedure has a 5-digit integer parameter, PARM,
* passed by reference.
D RetFld PR 5P 2
D Parm 5I 0
* This is the prototype for subprocedure RETARR. The data
* type entries for the prototype specification show that
* this subprocedure returns a date array with 3 elements.
* The dates are in *YMD/ format.
D RetArr PR D DIM(3) DATFMT(*YMD/)
* This procedure (P) specification indicates the beginning of
* subprocedure RETNONE. The data specification (D) specification
* immediately following is the procedure-interface
* specification for this subprocedure. Note that the
* procedure interface is the same as the prototype except for
* the definition type (PI vs PR).
P RetNone B
D RetNone PI
* RetNone does not return a value, so the RETURN
* operation does not have factor 2 specified.
C RETURN
P RetNone E
* The following 3 specifications contain the beginning of
* the subprocedure RETFLD as well as its procedure interface.
P RetFld B
D RetFld PI 5P 2
D Parm 5I 0
D Fld S 12S 1 INZ(13.8)
* RetFld returns a numeric value. The following RETURN
* operations show returning a literal, an expression and a
* variable. Note that the variable is not exactly the same
* format or length as the actual return value.
C RETURN 7
C RETURN Parm * 15
C RETURN Fld
P RetFld E * The following 3 specifications contain the beginning of the
* subprocedure RETARR as well as its procedure interface.
P RetArr B
D RetArr PI D DIM(3)
D SmallArr S D DIM(2) DATFMT(*ISO)
D BigArr S D DIM(4) DATFMT(*USA)
* RetArr returns a date array. Note that the date
* format of the value specified on the RETURN operation
* does not have to be the same as the defined return
* value.
* The following RETURN operation specifies a literal.
* The caller receives an array with the value of the
* literal in every element of the array.
C RETURN D'1995-06-27'
* The following return operation returns an array
* with a smaller dimension than the actual return value.
* In this case, the third element would be set to the
* default value for the array.
C RETURN SmallArr
* The following return operation returns an array
* with a larger dimension than the actual return
* value. In this case, the fourth element of BigArr
* would be ignored.
C RETURN BigArr
P RetArr E