Programming Guide : Using 3GL in Your Application : How You Can Call 3GL Procedures : How You Can Pass Parameters to 3GL Procedures
 
Share this page          
How You Can Pass Parameters to 3GL Procedures
To pass parameters to a 3GL procedure, you specify a list of expressions. Because you do not include parameter names, you must specify the parameters by position. The syntax for calling a 3GL procedure is:
[return_variable =] callproc procedurename
          [(expression | byref(variable)
          {, expression | byref(variable)})]
Each expression in the list must correspond to a parameter in the 3GL procedure parameter list. You must verify that each expression matches the data type and position of the corresponding parameter. The expression you pass to the 3GL procedure can be a constant or any legal OpenROAD expression, so long as the resulting data type is compatible with the data type of the corresponding 3GL procedure parameter.
Because 3GL procedures do not allow null values, you cannot pass a simple variable with a value of null. If your variable is nullable in 4GL, you can pass it using the ifnull function. This function helps ensure that a fixed value, instead of a null, is passed when a null in encountered.
For more information about the ifnull function, see the Language Reference Guide.
Examples—Passing Parameters to a 3GL Procedure:
The following example calls a C procedure, my3glprocedure. This procedure's three parameters are simple data types: two integers and a varchar. The second parameter references intvar, a 4GL integer variable, and the third references a 4GL varchar variable called video.title:
callproc my3glprocedure(256, 3 + intvar,
    'Free movie this week is ' + video.title);
The my3glprocedure procedure declared corresponding parameters as follows:
my3glprocedure (var1, var2, var3)
int    var1, var2;
char   *var3;
{
   ...
}
For information about matching data types between 3GL procedures and OpenROAD variables, see the Language Reference Guide online help.
Note:  Because the parameters must match exactly in position and type, you must specify all parameters to a 3GL procedure. The OpenROAD runtime system does not check errors in parameter passing to 3GL procedures; such errors can result in abnormally terminated programs. If you are using OpenROAD Workbench, it could abort without saving your changes.
As with 4GL procedures, OpenROAD lets you pass parameters to 3GL procedures by reference. The following example shows two parameters passed by reference and one passed by value:
callproc my3glprocedure(byref(floatvar), 36,
    byref(textvar));
To help ensure full portability across all systems, pass all floating point parameters to C procedures with the byref qualifier, even if you do not want to change the value of the data in the C procedure. For example, the following statement calls the scale_y_array procedure, passing it two floating point parameters (vmin and vmax) by reference:
callproc scale_y_array(byref(vmin), byref(vmax),
    ymax - (labelheight*2), 0, sales_array);
IMPORTANT!  There are limits to the number of parameters you can pass to a 3GL procedure. The specific limit depends on the platform, the language in which the procedure is written, and the data types of the parameters. If you want your application to be portable across all platforms, do not pass more than 39 parameters to a 3GL procedure.
IMPORTANT!  If you pass floating point parameters to C procedures without the byref qualifier, the limit may be smaller. Floats passed by value require an 8-byte parameter for a copy of the float, whereas floats passed by reference require only a 4-byte parameter for the address of the float (on 32-bit platforms).