Prototypes

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.

      * 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.