ILE RPG Language Reference
A prototype is a definition of the call interface.
It includes the following information:
- Whether the call is bound (procedure) or dynamic (program)
- How to find the program or procedure (the external name)
- The number and nature of the parameters
- Which parameters must be passed, and which are optionally passed
- Whether operational descriptors should be passed
- The data type of the return value, if any (for a procedure)
A prototype may be explicitly or implicitly defined.
If the procedure is called from a different RPG module, the prototype
must be explicitly specified in both the calling module and the module
that defines the procedure. If the procedure is only called within
the same module, the prototype may be explicitly defined, or it may
be omitted. If the prototype is omitted, the compiler will implicitly
define it from the procedure interface.
For modules that call a procedure that is defined
in a different module, a prototype must be included in the definition
specifications of the program or procedure that makes the call. The
prototype is used by the compiler to call the program or procedure
correctly, and to ensure that the caller passes the correct parameters.
The following rules apply to prototype definitions.
- A prototype name must be specified in positions 7-21. If the keyword
EXTPGM or EXTPROC is specified on the prototype definition, then any
calls to the program or procedure use the external name specified
for that keyword. If neither keyword is specified, then the external
name is the prototype name, that is, the name specified in positions
7-21 (in uppercase).
- Specify PR in the Definition-Type entry (positions 24-25). Any
parameter definitions must immediately follow the PR specification.
The prototype definition ends with the first definition specification
with non-blanks in positions 24-25 or by a non-definition specification.
- Specify any of the following keywords as they pertain to the call
interface:
- EXTPROC(name)
- The call will be a bound procedure call that uses the external
name specified by the keyword.
- EXTPGM(name)
- The call will be an external program call that uses the external
name specified by the keyword.
- OPDESC
- Operational descriptors are to be passed with the parameters
that are described in the prototype.
- RTNPARM
- The return value is to be handled as a parameter. This may
improve performance when calling the procedure, especially for large
return values.
- A return value (if any) is specified on the PR definition. Specify
the length and data type of the return value. In addition, you may
specify the following keywords for the return value:
- DATFMT(fmt)
- The return value has the date format specified by the keyword.
- DIM(N)
- The return value is an array or data structure with
N elements.
- LIKEDS(data_structure_name)
- The returned value is a data structure. (You cannot refer to
the subfields of the return value when you call the procedure.)
- LIKEREC(name{,type})
- The returned value is a data structure defined like the specified
record format name.
Note:
You cannot refer to the subfields
of the return value when you call the procedure.
- LIKE(name)
- The return value is defined like the item specified by the keyword.
- PROCPTR
- The return value is a procedure pointer.
- TIMFMT(fmt)
- The return value has the time format specified by the keyword.
- VARYING{(2|4)}
- A character, graphic, or UCS-2 return value has a variable-length
format.
For information on these keywords, see Definition-Specification Keywords. Figure 67 shows a prototype for a subprocedure CVTCHR that
takes a numeric input parameter and returns a character string. Note
that there is no name associated with the return value. For this reason,
you cannot display its contents when debugging the program.
Figure 67. Prototype for CVTCHR
* The returned value is the character representation of
* the input parameter NUM, left-justified and padded on
* the right with blanks.
D CVTCHR PR 31A
D NUM 31P 0 VALUE
* The following expression shows a call to CVTCHR. If
* variable rrn has the value 431, then after this EVAL,
* variable msg would have the value
* 'Record 431 was not found.'
C EVAL msg = 'Record '
C + %TRIMR(CVTCHR(RRN))
C + ' was not found '
If you are writing a prototype for an exported subprocedure
or for a main procedure, put the prototype in a /COPY file and copy
the prototype into the source file for both the callers and the module
that defines the procedure. This coding technique provides maximum
parameter-checking benefits for both the callers and the procedure
itself, since they all use the same prototype.
[ Top of Page | Previous Page | Next Page | Contents |
Index ]