CALLPRC (Call Bound Procedure)
CALLPRC Command syntax diagram
Purpose
The Call Bound Procedure (CALLPRC) command calls a bound procedure named on the command, and passes control to it. Optionally, the procedure issuing the CALLPRC command can pass parameters to the called procedure. The CALLPRC command can be used in compiled ILE control language (CL) programs and modules. Upon return, the return code from the called procedure will be placed in the RTNCDE parameter if specified.
Each parameter value passed to the called procedure can be a character string constant, a numeric constant, a logical constant, a floating-point constant, or a CL program variable. If a floating-point constant is specified, the value is converted to double-precision format and passed to the called program. If parameters are passed, the value of the constant or variable is available to the program that is called. Parameters cannot be passed in any of the following forms: lists of values, qualified names, expressions, or keyword parameters. Up to 300 parameters can be passed to the called procedure.
| Note: | Although the CALLPRC command will allow up to 300 parameters to be passed, the number that the called procedure can accept will depend on the language of the called procedure. For example, a CL procedure cannot accept more than 40 parameters. |
If parameters are passed to a procedure using the CALLPRC command, the values of the parameters are passed in the order in which they appear on the CALLPRC command; this order must match the order in which they appear in the parameter list in the calling procedure.
Parameters in a called procedure can be used in place of its variables. However, no storage in the called procedure is associated with the variables it receives. Instead, if a variable is passed, the storage for the variable is in the procedure in which it was originally declared. If a constant is passed, a copy of the constant is made in the calling procedure and that copy is passed to the called procedure.
The result is that if a variable is passed, the called procedure can change its value and the change is reflected in the calling procedure. If a constant is passed, and its value is changed by the called procedure, the changed value is not known to the calling procedure. Therefore, if the calling procedure calls the same procedure again, the values of constants are set to their original values, but the variables do not change.
Required Parameters
- PRC
- Specifies the name of the procedure being called. The procedure must be in the same program as the calling procedure or in a service program specified at the time the calling program was created. The procedure name may be up to 256 bytes long. The procedure name will be case sensitive. A CL variable cannot be specified for the procedure name.
Optional Parameters
- PARM
- Specifies one or more parameter values that are passed to the called
procedure. Each of the values can be specified in only one of the following
forms: a character string constant, a numeric constant, logical constant,
double-precision floating point constant, or program variable.
*OMIT: Specifies a null value is passed to another procedure.
parameter-value: Specify one or more parameter values that are passed to the called program. Each of the values can be specified in only one of the following forms: a character string constant, a numeric constant, logical constant, double-precision floating point constant, or program variable.
The type and length of each parameter must be the same in both the calling and called procedures. The order in which they are sent and received must also be the same. The number of parameters specified by the calling procedure does not have to match the number of parameters specified by the called procedure. If the calling procedure specifies more parameters than the called prodedure, the extra parameters are ignored. If the calling procedure specifies fewer parameters than the called procedure and the called procedure references the missing parameters, runtime results will be unpredictable.
Parameters can be passed and received as follows:
- Character string constants are neither padded with blanks or null
terminated. The operational descriptor for the parameter will have the length
of the string. The character string "*OMIT" may not be specified as a constant
value; when "*OMIT" is specified a null pointer will be passed to the called
procedure.
The called procedure can receive less than the number of bytes passed (in this case, no message is sent). For example, if a procedure specifies that 4 characters are to be received and ABCDEF is passed, only ABCD is accepted and used by the procedure. Quoted character strings can also be passed.
- Decimal constants are passed in packed form and with a length of (15 5),
where the value is 15 digits long, of which 5 digits are decimal positions. If
a parameter of 12345 is passed, the called procedure must declare the decimal
field as (15 5); the parameter is received as 1234500000 (which is
12,345.00000).
- Logical constants are passed as 1 byte with a logical value of 'F1'X or
'F0'X.
- Floating-point literals and floating-point special values (*NAN, *INF, and
*NEGINF) are passed as double-precision floating-point numbers in IEEE format,
which occupy 8 bytes and are specified in the form
n.n E n; for example, 2.47E3). A
single-precision floating-point number cannot be passed to a called procedure.
- A procedure variable can be passed, in which case the called procedure must
declare the field to match the variable defined in the calling procedure. For
example, if a CL procedure defines a decimal variable named &CHKNUM as (5
0), the called procedure must declare the field as packed with 5 digits total,
with no decimal positions.
If either a decimal constant or a program variable can be passed to the called procedure, the parameter should be defined as (15 5), and any calling procedure must adhere to that definition. If the type, number, order, and length of the parameters do not match between the calling and called procedures (other than the length exception noted previously for character constants), unpredictable results will occur.
- Operational descriptors will always be built for character arguments passed on the PARM parameter. The called procedure can use the information in the descriptor to determine the length of the argument. For character string constants, the length will be the actual length of the constant. For character variables, the length will be the declared length of the variable.
- Character string constants are neither padded with blanks or null
terminated. The operational descriptor for the parameter will have the length
of the string. The character string "*OMIT" may not be specified as a constant
value; when "*OMIT" is specified a null pointer will be passed to the called
procedure.
- RTNVAL
- Specifies the variable to contain the return value from the called
procedure. If the value returned by the called procedure is a binary number
(types int or short in C/400), specify the %BINARY
built-in function on the return value parameter.
*NONE: The called procedure does not return a value.
return-variable-name: The name of the variable that is to contain the return value from the called procedure. This may be either a decimal or a character variable. Variables used as return variables will be aligned on a 16-byte boundary.
Examples for CALLPRC
Example 1: Calling a Procedure
CALLPRC PRC(PAYROLL)
The procedure named PAYROLL is called with no parameters being passed to it. The PAYROLL procedure does not return a value
Example 2: Defining a Character Constant
CALLPRC PRC(PAYROLL) PARM('1')
The procedure named PAYROLL is called with a character constant passed as a quoted string. The PAYROLL procedure does not return a value
Example 3: Passing Parameters
CALLPRC PRC(PAYROLL) PARM(CHICAGO 1234 &VAR1) RTNVAL(*NONE)
The procedure named PAYROLL. The calling procedure passes three parameters: a character string (CHICAGO), a decimal value (1234.00000), and the contents of the CL variable &VAR1. The attributes of the variable determine the attributes of the third parameter. The PAYROLL procedure does not return a value.
Example 4: Calling Procedure with Floating-Point Values
CALLPRC PRC(PRC1) PARM(1.5E3 *INF) RTNVAL(&RVAL)
The procedure named PRC1 is called with two double-precision floating-point values being passed to it. The returned value is stored in variable &RVAL.
Example 5: Ignoring the Return Value of a Procedure
CALLPRC PRC(PRC1) PARM(1.5E3 *INF) RTNVAL(*NONE)
The procedure named PRC1 is called with two double-precision floating-point values being passed to it. The returned value is ignored and therefore unavailable to the calling procedure.
Example 6: Calling a Procedure that Returns a Binary Number
CALLPRC PRC(RTNINT) RTNVAL(% BIN($RTNV 1 4))
The procedure named RTNINT returns a 4-byte binary value. It is stored in the first four bytes of variable $RTNV. Variable &RTNV is of type *CHAR and has a length of at least 4.
Error messages for CALLPRC
*ESCAPE Messages
- CPF0806
- Error found when procedure started.