The CALL statement calls a procedure or a foreign procedure.
This statement can be embedded in an application program or issued through the use of dynamic SQL statements. It is an executable statement that can be dynamically prepared. When invoked using the command line processor, there are some additional rules for specifying arguments of the procedure. For more information, refer to "Using command line SQL statements and XQuery statements".
If a matching procedure exists that the authorization ID of the statement is not authorized to execute, an error is returned (SQLSTATE 42501).
>>-CALL--procedure-name--+----------------------------+-------->< | .-,----------------. | | V | | '-(------| argument |---+--)-' argument |--+--------------------+--+-expression-+-----------------------| '-parameter-name--=>-' +-DEFAULT----+ '-NULL-------'
A named argument must be specified only once (implicitly or explicitly) (SQLSTATE 4274K).
Named arguments are not supported on the call to an uncataloged procedure (SQLSTATE 4274K).
Named arguments correspond to the same named parameter, regardless of the order in which they are specified.
If the DEFAULT keyword is specified, the default as defined in the CREATE PROCEDURE statement is used if it exists; otherwise the null value is used as the default.
If the NULL keyword is specified, the null value is passed as the parameter value.
Parameter assignments: When the CALL statement is executed, the value of each of its arguments is assigned (using storage assignment) to the corresponding parameter of the procedure. A parameter value that is defined to have a default value can be omitted from the argument list when invoking the procedure.
When the CALL statement is executed, control is passed to the procedure according to the calling conventions of the host language. When execution of the procedure is complete, the value of each parameter of the procedure is assigned (using storage assignment) to the corresponding argument of the CALL statement defined as OUT or INOUT. If an error is returned by the procedure, OUT arguments are undefined and INOUT arguments are unchanged. For details on the assignment rules, see "Assignments and comparisons".
When the CALL statement is in an SQL procedure and is calling another SQL procedure, assignment of XML parameters is done by reference. When an XML argument is passed by reference, the input node trees, if any, are used directly from the XML argument, preserving all properties, including document order, the original node identities, and all parent properties.
Procedure signatures: A procedure is identified by its schema, a procedure name, and the number of parameters. This is called a procedure signature, which must be unique within the database. There can be more than one procedure with the same name in a schema, provided that the number of parameters is different for each procedure.
SQL path: A procedure can be invoked by referring to a qualified name (schema and procedure name), followed by an optional list of arguments enclosed by parentheses. A procedure can also be invoked without the schema name, resulting in a choice of possible procedures in different schemas with the same number of parameters. In this case, the SQL path is used to assist in procedure resolution. The SQL path is a list of schemas that is searched to identify a procedure with the same name and number of parameters. For static CALL statements, SQL path is specified using the FUNCPATH bind option. For dynamic CALL statements, SQL path is the value of the CURRENT PATH special register.
If a matching module is not found or there are no candidate procedures in the matching module, then a procedure not found error is returned (SQLSTATE 42884). If there are multiple candidate procedures, choose the candidate procedure with the least number of parameters. Resolution is complete if the authorization ID of the CALL statement has EXECUTE privilege on the module of the remaining candidate procedure, otherwise an authorization error is returned (SQLSTATE 42501).
Retrieving the DB2_RETURN_STATUS from an SQL procedure: If an SQL procedure successfully issues a RETURN statement with a status value, this value is returned in the first SQLERRD field of the SQLCA. If the CALL statement is issued in an SQL procedure, use the GET DIAGNOSTICS statement to retrieve the DB2_RETURN_STATUS value. The value is -1 if the SQLSTATE indicates an error. The values is 0 if no error is returned and the RETURN statement was not specified in the procedure.
Returning result sets from procedures: If the calling program is written using CLI, JDBC, or SQLJ, or the caller is an SQL procedure, result sets can be returned directly to the caller. The procedure indicates that a result set is to be returned by declaring a cursor on that result set, opening a cursor on the result set, and leaving the cursor open when exiting the procedure.
Improving performance: The values of all arguments are passed from the application to the procedure. To improve the performance of this operation, host variables that correspond to OUT parameters and have lengths of more than a few bytes should be set to the null value before the CALL statement is executed.
Nesting CALL statements: Procedures can be called from routines as well as application programs. When a procedure is called from a routine, the call is considered to be nested.
Client program:
EXEC SQL CALL PROCA;
PROCA:
EXEC SQL CALL PROCB;
PROCB:
EXEC SQL DECLARE B1 CURSOR WITH RETURN TO CLIENT ...;
EXEC SQL DECLARE B2 CURSOR WITH RETURN TO CALLER ...;
EXEC SQL DECLARE B3 CURSOR FOR SELECT UDFA FROM T1;
UDFA:
EXEC SQL CALL PROCC;
PROCC:
EXEC SQL DECLARE C1 CURSOR WITH RETURN TO CLIENT ...;
EXEC SQL DECLARE C2 CURSOR WITH RETURN TO CALLER ...;
Compilation of CALL statements from DB2® for i and DB2 for z/OS®: The compilation of CALL statements from DB2 for i and DB2 for z/OS implicitly behave as if CALL_RESOLUTION DEFERRED was specified. When CALL statements are compiled with CALL_RESOLUTION DEFERRED, all arguments must be provided via host variables, and expressions are not allowed.
Syntax alternatives: There is an older form of the CALL statement that can be embedded in an application by precompiling the application with the CALL_RESOLUTION DEFERRED option. This option is not available for SQL procedures and federated procedures.
CREATE PROCEDURE PARTS_ON_HAND (IN PARTNUM INTEGER,
OUT COST DECIMAL(7,2),
OUT QUANTITY INTEGER)
EXTERNAL NAME 'parts!onhand'
LANGUAGE JAVA
PARAMETER STYLE DB2GENERAL;
...
CallableStatement stpCall;
String sql = "CALL PARTS_ON_HAND (?, ?, ?)";
stpCall = con.prepareCall(sql); /*con is the connection */
stpCall.setInt(1, hvPartnum);
stpCall.setBigDecimal(2, hvCost);
stpCall.setInt(3, hvQuantity);
stpCall.registerOutParameter(2, Types.DECIMAL, 2);
stpCall.registerOutParameter(3, Types.INTEGER);
stpCall.execute();
hvCost = stpCall.getBigDecimal(2);
hvQuantity = stpCall.getInt(3);
...
This application code fragment will invoke the Java method onhand in class parts, because the procedure name specified on the CALL statement is found in the database and has the external name parts!onhand.
CREATE PROCEDURE AUGUSTUS.FOO (INT) SPECIFIC FOO_1 ...
CREATE PROCEDURE AUGUSTUS.FOO (DOUBLE, DECIMAL(15, 3)) SPECIFIC FOO_2 ...
CREATE PROCEDURE JULIUS.FOO (INT) SPECIFIC FOO_3 ...
CREATE PROCEDURE JULIUS.FOO (INT, INT, INT) SPECIFIC FOO_4 ...
CREATE PROCEDURE CAESAR.FOO (INT, INT) SPECIFIC FOO_5 ...
CREATE PROCEDURE NERO.FOO (INT,INT) SPECIFIC FOO_6 ...
CALL FOO(I1, I2)
"JULIUS", "AUGUSTUS", "CAESAR"
Following through the algorithm...
The procedure with specific name FOO_6 is eliminated as a candidate, because the schema "NERO" is not included in the SQL path. FOO_1, FOO_3, and FOO_4 are eliminated as candidates, because they have the wrong number of parameters. The remaining candidates are considered in order, as determined by the SQL path. Note that the types of the arguments and parameters are ignored. The parameters of FOO_5 exactly match the arguments in the CALL, but FOO_2 is chosen because "AUGUSTUS" appears before "CAESAR" in the SQL path.
CREATE PROCEDURE update_order(
IN IN_POID BIGINT,
IN IN_CUSTID BIGINT DEFAULT GLOBAL_CUST_ID,
IN NEW_STATUS VARCHAR(10) DEFAULT NULL,
IN NEW_ORDERDATE DATE DEFAULT NULL,
IN NEW_COMMENTS VARCHAR(1000)DEFAULT NULL)...
CALL update_order (5000, NEW_STATUS => 'Shipped')
CALL update_order (5002,
IN_CUSTID => 1001,
NEW_STATUS => 'Received',
NEW_COMMENTS => 'Customer satisfied with the order.')
CREATE PROCEDURE p1(i1 INT)...
CREATE PROCEDURE p1(i1 INT DEFAULT 0, i2 INT DEFAULT 0)...
CALL p1(i2=>1)
Starting with DB2 Version 9.7 Fix Pack 1, the argument names
are taken into consideration during the candidate selection process.
Therefore, only the second version of p1 will
be considered a candidate. Furthermore, it can be successfully called
because i1 in this version of p1 is
defined with a default, so only specifying i2 on
the call to p1 is valid. CREATE PROCEDURE p1(i1 INT, i2 INT DEFAULT 0)...
CREATE PROCEDURE p1(i1 INT DEFAULT 0, i2 INT DEFAULT 0, i3 INT DEFAULT 0)...
CALL p1(i2=>1)
Starting with DB2 Version 9.7 Fix Pack 1, one of the criteria
for a procedure parameter which does not have a corresponding argument
in the CALL statement (specified by either position or name) is that
the parameter is defined with a default value. Therefore, the first
version of p1 is not considered a candidate.