Functions and subroutines
The function calling mechanism is identical with that for subroutines. The only difference between functions and subroutines is that functions must return data, whereas subroutines need not.
- Internal
- If the routine name exists as a label in the program, the current
processing status is saved, so that it is later possible to return
to the point of invocation to resume execution. Control is then passed
to the first label in the program that matches the name. As with a
routine called by the CALL instruction, various other status information
(TRACE and NUMERIC settings and so forth) is saved too. See the CALL
instruction ( Purpose) for details
about this. You can use SIGNAL and CALL together to call an internal
routine whose name is determined at the time of execution; this is
known as a multi-way call (see SIGNAL).
If you are calling an internal routine as a function, you must specify an expression in any RETURN instruction to return from it. This is not necessary if it is called as a subroutine.
- Example:
-
/* Recursive internal function execution... */ arg x say x'! =' factorial(x) exit factorial: procedure /* Calculate factorial by */ arg n /* recursive invocation. */ if n=0 then return 1 return factorial(n-1) * n
Note: When there is a search for a routine, the language processor currently scans the statements in the REXX program to locate the internal label. During the search, the language processor may encounter a syntax error. As a result, a syntax error may be raised on a statement different from the original line being processed. - Built-in
- These functions are always available and are defined in the next section of this manual.
- External
- You can write or use functions that are external to your program
and to the language processor. External routines must be written in
REXX. You can call a REXX program as a function and, in this case,
pass more than one argument string. The ARG or PARSE ARG instructions
or the ARG built-in function can retrieve these argument strings.
When called as a function, a program must return data to the caller.
Note:
- External REXX functions can easily perform an EXEC CICS LINK to a program written in any CICS-supported language. Also, REXX/CICS command routines may be written in assembler.
- Calling an external REXX program as a function is similar to calling an internal routine. The external routine is, however, an implicit PROCEDURE in that all the caller's variables are always hidden and the status of internal values (NUMERIC settings and so forth) start with their defaults (rather than inheriting those of the caller).
- Other REXX programs can be called as functions. You can use either EXIT or RETURN to leave the called REXX program, and in either case you must specify an expression.
- With care, you can use the INTERPRET instruction to process a function with a variable function name. However, you should avoid this if possible because it reduces the clarity of the program.
Search order
The search order for functions is: internal routines take precedence, then built-in functions, and finally external functions.
Internal routines are not used if the function name is given as a literal string (that is, specified in quotation marks); in this case the function must be built-in or external. This lets you usurp the name of, say, a built-in function to extend its capabilities, yet still be able to call the built-in function when needed.
- Example:
-
/* This internal DATE function modifies the */ /* default for the DATE function to standard date. */ date: procedure arg in if in='' then in='Standard' return 'DATE'(in)
External functions and subroutines have a system-defined search order. The search order for external functions and subroutines follows.
- Search order for a DEFCMD defined command exec or other called
exec: Note: If this is an attempt to execute an authorized command, a check is made to see if this is an authorized user or the command is in an exec loaded from a VSE Librarian sublibrary specified on a SETSYS AUTHCLIB or SETSYS AUTHELIB command. If none of these are true, the command fails with a return code of -4.
- Within the current exec for an internal function or subroutine.
Note: This search can be bypassed by explicitly identifying the function (or subroutine) as external by enclosing its name in quotes. - Execs in storage (from an earlier EXECLOAD).
- The current RFS directory.
- The current PATH. RFS directories and VSE Librarian sublibraries are searched in the order listed in the most recent PATH command, if it was executed.
- VSE Librarian sublibraries in the order listed in the most recent
SETSYS AUTHCLIB command.
If the user is an authorized user or if the current exec was loaded from a sublibrary specified on the last SETSYS AUTHELIB command and the search is for an authorized command's program, then check the sublibraries specified on the most recent SETSYS AUTHCLIB command.
- VSE Librarian sublibraries in the order listed in the most recent SETSYS AUTHELIB command.
- VSE Librarian members with a member type of PROC in the LIBDEF PROC search chain for the CICS partition.
Errors during execution
If an external or built-in function detects an error of any kind, the language processor is informed, and a syntax error results. Execution of the clause that included the function call is, therefore, ended. Similarly, if an external function fails to return data correctly, the language processor detects this and reports it as an error.
If a syntax error occurs during the execution of an internal function, it can be trapped (using SIGNAL ON SYNTAX) and recovery may then be possible. If the error is not trapped, the program is ended.