Call Bound Procedure (CALLPRC)
Where allowed to run:
|
Parameters Examples Error messages |
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. If the called procedure returns a value, such as an error code, the returned value can be stored into a CL variable by specifying the CL variable name for the CL variable for returned value (RTNVAL) parameter.
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 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 255 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 called procedure.
Parameters may be passed by reference or passed by value.
Restrictions:
- The CALLPRC command is valid only within an ILE CL module.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| PRC | Procedure | Character value | Required, Positional 1 |
| PARM | Parameters | Values (up to 300 repetitions): Element list | Optional, Positional 2 |
| Element 1: Parameter | Not restricted | ||
| Element 2: Passed | *BYREF, *BYVAL | ||
| RTNVAL | CL variable for returned value | CL variable name, *NONE | Optional, Positional 3 |
| Top |
Procedure (PRC)
Specifies the name of the procedure to be called.
- name
- Specify the name of the procedure to be 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.
| Top |
Parameters (PARM)
Specifies parameter values that are to be passed to the called procedure. Passing parameters is optional; if no parameters are specified, no parameters will be passed to the called procedure. Up to 300 parameters can be specified.
Element 1: Parameter
- *OMIT
- The parameter is omitted. A null pointer is to be passed to the called procedure. When *OMIT is specified for element 1, you cannot specify *BYVAL for element 2.
- parameter-value
- Specify a value that is to be passed to the called procedure as a parameter. The parameter value can be specified as a character string constant, a numeric constant, a logical constant, a double-precision floating point constant, or a CL variable.
The type and length of each parameter must be the same in both the calling and called procedures. The order in which parameters 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 are defined in the called procedure, the extra parameters are ignored. If the calling procedure specifies fewer parameters than are defined in 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 called procedure can receive less than the number of bytes passed (in this case, no message is sent). For example, if a called procedure specifies that 4 characters are to be received and ABCDEF is passed, only ABCD is accepted and used by the called 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 sn.nEsn; where s is a plus sign (+) or a minus sign(-); for example, -2.47E+3 or 3.653E24. A single-precision floating-point number cannot be passed to a called procedure.
- A CL 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 keyword. 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.
Element 2: Passed
- *BYREF
- The parameter is to be passed by reference. Passing a parameter by reference means that the actual parameter is a pointer which points to storage in the calling procedure which contains the CL variable or constant value. If the called procedure is a CL procedure, all parameters must be passed by reference. If a CL variable is passed by reference, the called procedure can change its value and the change is reflected in the calling procedure. If a constant is passed by reference, a copy of the constant is made in the calling procedure and a pointer to that copy is passed to the called procedure.
- *BYVAL
- The parameter is to be passed by value. Passing a parameter by value means that the called procedure receives a copy of the parameter. If the parameter is a CL variable, changes made to the parameter by the called procedure do not change the CL variable in the calling procedure. The called procedure must be defined to receive a parameter that is passed by value.
| Top |
CL variable for returned value (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 ILE C or ILE C++), you must either specify an integer CL variable (specified as TYPE(*INT) or TYPE(*UINT) on the DCL statement) or use the %BINARY or %BIN built-in function on a character CL variable (specified as TYPE(*CHAR) on the DCL statement) used for the return value parameter.
- *NONE
- The called procedure does not return a value.
- CL-variable-name
- Specify the name of the CL variable that is to contain the return value from the called procedure. This may be a decimal, integer, or character CL variable. Variables used as return variables will automatically be aligned on a 16-byte boundary.
| Top |
Examples
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: Passing 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 is called. 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 Using %BIN
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.
Example 7: Calling a Procedure that Returns a Binary Number Using an Integer CL Variable
DCL VAR(&VAR2) TYPE(*INT) LEN(4) : CALLPRC PRC(RTNINT) RTNVAL(&VAR2)
The procedure named RTNINT returns a 4-byte binary value, which is stored in the 4-byte signed integer CL variable &VAR2.
Example 8: Calling a Procedure Passing a Parameter By Value
DCL VAR(&POS) TYPE(*INT) LEN(2)
:
CALLPRC PRC(SCAN_STRING) PARM((&STR1 *BYREF) (' ' *BYVAL))
RTNVAL(&POS)
The procedure named SCAN_STRING is called with two parameters. The CL variable &STR1 is passed by reference and the constant character string ' ' (one blank) is passed by value to SCAN_STRING. Procedure SCAN_STRING must be defined to receive the first parameter as a pointer to a character string and the second parameter as a one-byte character string. The SCAN_STRING procedure returns a 2-byte binary value, which is stored in the 2-byte signed integer CL variable &POS.
| Top |
| Top |