PROTOTYPED CALL

The prototyped call interface provides a way to declare the number and type of parameters that are required by a program or procedure. Prototypes are declared with the definition specification. This permits a wide variety of data types to be specified as parameters.

All data types, with the exception of data structures, can be declared as a parameter of a procedure prototype. Data structures can be passed as character strings and then referenced using a based variable in the subprocedure. See the following subheading, Data Structures and Prototyped Procedures, for information on passing data structures to subprocedures. Figure 9.17 shows the call interface to a prototyped procedure.

Figure 9.17: Passing data to subprocedures.

Figure 9.17, line 4, includes the CVTCASE source file. (Note: The source code for CVTCASE is listed in Figure 9.19.) These prototypes are necessary to allow the compiler to do parameter-type checking at compile time. On line 5, the procedure MAKEUPPER is called. This procedure converts the data in the parameter passed to it to uppercase. The NAME field is passed and converted to uppercase.

Line 2 indicates the NAME field's initial value for this field. After the CALLP operation is performed on line 5, the data in NAME is converted to uppercase. Figure 9.18 illustrates the conversion.

 Position        *....v....1....v....2....v....3....v Before          'Skyline PigeON ComPANY' After           'SKYLINE PIGEON COMPANY' 

Figure 9.18: Before-images and after-images of the name field.

In Figure 9.17, on line 6, the IF operation is used to compare two values for equality. The TOUPPER procedure is called, with the COMPNAME field being passed to it. The TOUPPER function reads the input parameter (i.e., COMPNAME) and returns the uppercase equivalent. The returned value is actually inserted into the expression at the location of the subprocedure call. In this example, the returned value is then compared to the value on the right side of the equals sign. The content of the COMPNAME field is unchanged by the TOUPPER procedure. Figure 9.19 shows the source code for CVTCASE.

Figure 9.19: Prototypes for three conversion procedures.

Figure 9.19 contains the source code of the prototypes for the TOUPPER, TOLOWER, and MAKEUPPER procedures. The properties of the parameters passed to these procedures are declared within the prototype. Any names assigned to the parameters, on the prototype statements, are discarded by the compiler. The remaining parameter information must match the properties specified for the procedure interface. The procedure interface for these procedures is listed in Figure 9.20.

Figure 9.20: Procedure interface for TOUPPER.

The procedure prototype is similar to a named parameter list. It defines the parameter interface of a called procedure. The procedure interface is functionally similar to the *ENTRY PLIST used by the traditional RPG call interface. One additional function of a prototyped procedure is that the called procedure can return a value. When the prototyped procedure is used in an expression (see line 5 in Figure 9.17), the called procedure is expected to return a value. In the example TOUPPER procedure, the returned value is the uppercase equivalent of the input parameter.

The returned value can be used in an expression. The EVAL, IF, DOW, DOU, and WHEN operations support conditional expressions. The EVAL operation supports assignment expressions. In addition, if a procedure returning a value is evoked through the CALLP operation, the return value is ignored.

The return value is declared on the procedure prototype name definition statement. This source statement contains the letters PR in positions 24 and 25. The name of the procedure is identified on this line along with the properties of the return value.

Figure 9.20 contains the start of the CVTTOOLS source file. For purposes of explanation, this source file is divided into two sections.

In Figure 9.19, lines 4 to 12 define the TOUPPER procedure. The procedure interface is declared on lines 5 and 6. The letters PI, in positions 24 and 25 of line 5, indicate that line 5 is the procedure interface definition statement. The name of the procedure and the properties of the return value (if any) are specified on this statement.

On line 6, the first (and only) parameter is defined. This parameter's properties must exactly match those of the procedure prototype. The names of the parameters are used by the procedure to access the parameter data. This is in contrast to the parameter names on prototype statements, which are discarded by the compiler.

Figure 9.21 lists the MAKEUPPER source code. This is a continuation of the CVTTOOLS source file that begins in Figure 9.20.

Figure 9.21: Procedure interface for MAKEUPPER.

The MAKEUPPER procedure accepts one character field as a parameter (line 15), processes the data (lines 26 and 27), and then returns the modified value to the caller (lines 28 and 29).

In order to correctly access this data, the length of the value passed to the procedure must be determined. This is accomplished with a system function named CEEDOD. In order to call this procedure with the CALLP operation (line 24), a prototype for CEEDOD must be included in the source file. The prototypes for this and several other system functions are included in a source file named SYSINLINE. This source file is included using the /COPY compiler directive on line 2 of Figure 9.20. It is also listed in its entirety in Appendix D.