CREATE PROCEDURE (SQL)

The CREATE PROCEDURE (SQL) statement creates an SQL procedure at the current server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

The privileges held by the authorization ID of the statement must include at least one of the following:

The privilege to create in the schema. For more information, see Privileges necessary to create in a schema.
Administrative authority

The privileges held by the authorization ID of the statement must include at least one of the following:

For the SYSPROCS catalog view and SYSPARMS catalog table:
- The INSERT privilege on the table, and
- The system authority *EXECUTE on library QSYS2
Administrative authority

The privileges held by the authorization ID of the statement must include at least one of the following:

The following system authorities:
- *USE on the Create Program (CRTPGM) command, and
Administrative authority

If SQL names are specified and a user profile exists that has the same name as the library into which the procedure is created, and that name is different from the authorization ID of the statement, then the privileges held by the authorization ID of the statement must include at least one of the following:

The system authority *ADD to the user profile with that name
Administrative authority

If a distinct type is referenced, the privileges held by the authorization ID of the statement must include at least one of the following:

For each distinct type identified in the statement:
- The USAGE privilege on the distinct type, and
- The system authority *EXECUTE on the library containing the distinct type
Administrative authority

For information on the system authorities corresponding to SQL privileges, see Corresponding System Authorities When Checking Privileges to a Function or Procedure and Corresponding System Authorities When Checking Privileges to a Distinct Type.

Syntax

>>-CREATE PROCEDURE--procedure-name----------------------------->
 
>--+-----------------------------------------+------------------>
   '-(--+-------------------------------+--)-'
        | .-,-------------------------. |
        | V                           | |
        '-----parameter-declaration---+-'
 
>--LANGUAGE SQL--option-list--+----------------------+--SQL-routine-body-><
                              '-SET OPTION-statement-'

parameter-declaration:
 
   .-IN----.
|--+-------+--parameter-name--data-type-------------------------|
   +-OUT---+
   '-INOUT-'
 
data-type:
 
|--+-built-in-type------+---------------------------------------|
   '-distinct-type-name-'

option-list:
 
   .-NOT DETERMINISTIC-. (1)   .-MODIFIES SQL DATA-.
|--+-------------------+-------+-------------------+------------>
   '-DETERMINISTIC-----'       +-READS SQL DATA----+
                               '-CONTAINS SQL------'
 
   .-CALLED ON NULL INPUT-.  .-DYNAMIC RESULT SETS--0-------.
>--+----------------------+--+------------------------------+--->
                             '-DYNAMIC RESULT SETS--integer-'
 
>--+-------------------------+--+---------------------+--------->
   '-SPECIFIC--specific-name-'  +-DISALLOW DEBUG MODE-+
                                +-ALLOW DEBUG MODE----+
                                '-DISABLE DEBUG MODE--'
 
   .-FENCED-----.  .-OLD SAVEPOINT LEVEL-.
>--+------------+--+---------------------+---------------------->
   '-NOT FENCED-'  '-NEW SAVEPOINT LEVEL-'
 
   .-COMMIT ON RETURN NO--.
>--+----------------------+-------------------------------------|
   '-COMMIT ON RETURN YES-'

Notes:

The optional clauses can be specified in a different order.

SQL-routine-body:
 
|--+-SQL-control-statement-----------------------+--------------|
   +-ALLOCATE DESCRIPTOR-statement---------------+
   +-ALTER PROCEDURE (External)-statement--------+
   +-ALTER SEQUENCE-statement--------------------+
   +-ALTER TABLE-statement-----------------------+
   +-COMMENT-statement---------------------------+
   +-COMMIT-statement----------------------------+
   +-CONNECT-statement---------------------------+
   +-CREATE ALIAS-statement----------------------+
   +-CREATE DISTINCT TYPE-statement--------------+
   +-CREATE FUNCTION (External Scalar)-statement-+
   +-CREATE FUNCTION (External Table)-statement--+
   +-CREATE FUNCTION (Sourced)-statement---------+
   +-CREATE INDEX-statement----------------------+
   +-CREATE PROCEDURE (External)-statement-------+
   +-CREATE SCHEMA-statement---------------------+
   +-CREATE SEQUENCE-statement-------------------+
   +-CREATE TABLE-statement----------------------+
   +-CREATE VIEW-statement-----------------------+
   +-DEALLOCATE DESCRIPTOR-statement-------------+
   +-DECLARE GLOBAL TEMPORARY TABLE-statement----+
   +-DELETE-statement----------------------------+
   +-DESCRIBE-statement--------------------------+
   +-DESCRIBE INPUT-statement--------------------+
   +-DESCRIBE TABLE-statement--------------------+
   +-DISCONNECT-statement------------------------+
   +-DROP-statement------------------------------+
   +-EXECUTE IMMEDIATE-statement-----------------+
   +-GET DESCRIPTOR-statement--------------------+
   +-GRANT-statement-----------------------------+
   +-INSERT-statement----------------------------+
   +-LABEL-statement-----------------------------+
   +-LOCK TABLE-statement------------------------+
   +-REFRESH TABLE-statement---------------------+
   +-RELEASE-statement---------------------------+
   +-RELEASE SAVEPOINT-statement-----------------+
   +-RENAME-statement----------------------------+
   +-REVOKE-statement----------------------------+
   +-ROLLBACK-statement--------------------------+
   +-SAVEPOINT-statement-------------------------+
   +-SELECT INTO-statement-----------------------+
   +-SET CONNECTION-statement--------------------+
   +-SET CURRENT DEBUG MODE-statement------------+
   +-SET CURRENT DEGREE-statement----------------+
   +-SET DESCRIPTOR-statement--------------------+
   +-SET ENCRYPTION PASSWORD-statement-----------+
   +-SET PATH-statement--------------------------+
   +-SET RESULT SETS-statement-------------------+
   +-SET SCHEMA-statement------------------------+
   +-SET TRANSACTION-statement-------------------+
   +-UPDATE-statement----------------------------+
   '-VALUES INTO-statement-----------------------'

built-in-type:
 
|--+-+---SMALLINT---+--------------------------------------------------------------------------+--|
   | +-+-INTEGER-+--+                                                                          |
   | | '-INT-----'  |                                                                          |
   | '---BIGINT-----'                                                                          |
   |                  .-(5,0)------------------------.                                         |
   +-+-+-DECIMAL-+-+--+------------------------------+-----------------------------------------+
   | | '-DEC-----' |  |             .-,0--------.    |                                         |
   | '-NUMERIC-----'  '-(--integer--+-----------+--)-'                                         |
   |                                '-, integer-'                                              |
   |          .-(--53--)------.                                                                |
   +-+-FLOAT--+---------------+-+--------------------------------------------------------------+
   | |        '-(--integer--)-' |                                                              |
   | +-REAL---------------------+                                                              |
   | |         .-PRECISION-.    |                                                              |
   | '-DOUBLE--+-----------+----'                                                              |
   |                    .-(--1--)-------.                                                      |
   +-+-+-+-CHARACTER-+--+---------------+----------+--+----------------+---------------------+-+
   | | | '-CHAR------'  '-(--integer--)-'          |  +-FOR BIT DATA---+                     | |
   | | '-+-+-CHARACTER-+--VARYING-+--(--integer--)-'  +-FOR SBCS DATA--+                     | |
   | |   | '-CHAR------'          |                   +-FOR MIXED DATA-+                     | |
   | |   '-VARCHAR----------------'                   '-ccsid-clause---'                     | |
   | |                                          .-(--1M--)-------------.                     | |
   | '-----+-+-CHARACTER-+--LARGE OBJECT-+------+----------------------+--+----------------+-' |
   |       | '-CHAR------'               |      '-(--integer--+---+--)-'  +-FOR SBCS DATA--+   |
   |       '-CLOB------------------------'                    +-K-+       +-FOR MIXED DATA-+   |
   |                                                          +-M-+       '-ccsid-clause---'   |
   |                                                          '-G-'                            |
   |                .-(--1--)-------.                                                          |
   +-+---GRAPHIC----+---------------+-------+--+--------------+--------------------------------+
   | |              '-(--integer--)-'       |  '-ccsid-clause-'                                |
   | +-+-GRAPHIC VARYING-+--(--integer--)---+                                                  |
   | | '-VARGRAPHIC------'                  |                                                  |
   | |             .-(--1M--)-------------. |                                                  |
   | '---DBCLOB----+----------------------+-'                                                  |
   |               '-(--integer--+---+--)-'                                                    |
   |                             +-K-+                                                         |
   |                             +-M-+                                                         |
   |                             '-G-'                                                         |
   |             .-(--1--)-------.                                                             |
   +-+-+-BINARY--+---------------+---------+-----------------+---------------------------------+
   | | |         '-(--integer--)-'         |                 |                                 |
   | | '-+-BINARY VARYING-+--(--integer--)-'                 |                                 |
   | |   '-VARBINARY------'                                  |                                 |
   | |                              .-(--1M--)-------------. |                                 |
   | '---+-BLOB----------------+----+----------------------+-'                                 |
   |     '-BINARY LARGE OBJECT-'    '-(--integer--+---+--)-'                                   |
   |                                              +-K-+                                        |
   |                                              +-M-+                                        |
   |                                              '-G-'                                        |
   +-+-DATE-------------------+----------------------------------------------------------------+
   | |       .-(--0--)-.      |                                                                |
   | +-TIME--+---------+------+                                                                |
   | |            .-(--6--)-. |                                                                |
   | '-TIMESTAMP--+---------+-'                                                                |
   |             .-(--200--)-----.                                                             |
   +---DATALINK--+---------------+--+--------------+-------------------------------------------+
   |             '-(--integer--)-'  '-ccsid-clause-'                                           |
   '---ROWID-----------------------------------------------------------------------------------'
 
ccsid-clause:
 
                   .-NOT NORMALIZED-.
|--CCSID--integer--+----------------+---------------------------|
                   '-NORMALIZED-----'

Description

procedure-name

Names the procedure. The combination of name, schema name, the number of parameters must not identify a procedure that exists at the current server.

For SQL naming, the procedure will be created in the schema specified by the implicit or explicit qualifier.

For system naming, the procedure will be created in the schema specified by the qualifier. If no qualifier is specified:

If the value of the CURRENT SCHEMA special register is *LIBL, the procedure will be created in the current library (*CURLIB).
Otherwise, the procedure will be created in the current schema.

(parameter-declaration,...)

Specifies the number of parameters of the procedure and the data type of each parameter. A parameter for a procedure can be used only for input, only for output, or for both input and output. Although not required, you can give each parameter a name.

The maximum number of parameters allowed in an SQL procedure is 1024.

IN

Identifies the parameter as an input parameter to the procedure. Any changes made to the parameter within the procedure are not available to the calling SQL application when control is returned.

OUT

Identifies the parameter as an output parameter that is returned by the procedure. If the parameter is not set within the procedure, the null value is returned.

INOUT

Identifies the parameter as both an input and output parameter for the procedure.

parameter-name

Names the parameter. The name cannot be the same as any other parameter-name for the procedure.

data-type

Specifies the data type of the parameter. The data type can be a built-in data type or a distinct data type.

built-in-type: Specifies a built-in data type. For a more complete description of each built-in data type, see CREATE TABLE.
distinct-type-name: Specifies a distinct type. The length, precision, or scale attributes for the parameter are those of the source type of the distinct type (those specified on CREATE DISTINCT TYPE). For more information on creating a distinct type, see CREATE DISTINCT TYPE.
If the name of the distinct type is unqualified, the database manager resolves the schema name by searching the schemas in the SQL path.

If a CCSID is specified, the parameter will be converted to that CCSID prior to passing it to the procedure. If a CCSID is not specified, the CCSID is determined by the default CCSID at the current server at the time the procedure is called.

LANGUAGE SQL

Specifies that this is an SQL procedure.

DYNAMIC RESULT SETS integer

Specifies the maximum number of result sets that can be returned from the procedure. integer must be greater than or equal to zero and less than 32768. If zero is specified, no result sets are returned. If the SET RESULT SETS statement is issued, the number of results returned is the minimum of the number of result sets specified on this keyword and the SET RESULT SETS statement. If the SET RESULT SETS statement specifies a number larger than the maximum number of result sets, a warning is returned. Note that any result sets from cursors that have a RETURN TO CLIENT attribute are included in the number of result sets of the outermost procedure.

The result sets are scrollable if the cursor is used to return a result set and the cursor is scrollable. If a cursor is used to return a result set, the result set starts with the current position. Thus, if 5 FETCH NEXT operations have been performed prior to returning from the procedure, the result set will start with the 6th row of the result set.

Result sets are only returned if the procedure is directly called or if the procedure is a RETURN TO CLIENT procedure and is indirectly called from ODBC, JDBC, OLE DB, .NET, the SQL Call Level Interface, or the iSeries Access Family Optimized SQL API. For more information about result sets, see SET RESULT SETS.

SPECIFIC specific-name

Provides a unique name for the procedure. The name is implicitly or explicitly qualified with a schema name. The name, including the schema name, must not identify the specific name of another procedure or function that exists at the current server. If unqualified, the implicit qualifier is the same as the qualifier of the procedure name. If qualified, the qualifier must be the same as the qualifier of the procedure name.

If specific-name is not specified, it is the same as the procedure name. If a function or procedure with that specific name already exists, a unique name is generated similar to the rules used to generate unique table names.

DETERMINISTIC or NOT DETERMINISTIC

Specifies whether the procedure returns the same results each time the procedure is called with the same IN and INOUT arguments.

NOT DETERMINISTIC: The procedure may not return the same result each time the procedure is called with the same IN and INOUT arguments, even when the referenced data in the database has not changed.
DETERMINISTIC: The procedure always returns the same results each time the procedure is called with the same IN and INOUT arguments, provided the referenced data in the database has not changed.

CONTAINS SQL, READS SQL DATA, or MODIFIES SQL DATA

Specifies which SQL statements may be executed in the procedure or any routine called from this procedure. See Appendix B. Characteristics of SQL statements for a detailed list of the SQL statements that can be executed under each data access indication.

CONTAINS SQL: Specifies that SQL statements that neither read nor modify SQL data can be executed by the procedure.
READS SQL DATA: Specifies that SQL statements that do not modify SQL data can be included in the procedure.
MODIFIES SQL DATA: Specifies that the procedure can execute any SQL statement except statements that are not supported in procedures.

CALLED ON NULL INPUT

Specifies that the procedure is to be invoked, if any, or all, argument values are null, making the procedure responsible for testing for null argument values. The procedure can return a null or nonnull value.

DISALLOW DEBUG MODE, ALLOW DEBUG MODE, or DISABLE DEBUG MODE

Indicates whether the procedure is created so it can be debugged by the Unified Debugger. If DEBUG MODE is specified, a DBGVIEW option in the SET OPTION statement must not be specified.

DISALLOW DEBUG MODE: The procedure cannot be debugged by the Unified Debugger. When the DEBUG MODE attribute of the procedure is DISALLOW, the procedure can be subsequently altered to change the debug mode attribute.
ALLOW DEBUG MODE: The procedure can be debugged by the Unified Debugger. When the DEBUG MODE attribute of the procedure is ALLOW, the procedure can be subsequently altered to change the debug mode attribute.
DISABLE DEBUG MODE: The procedure cannot be debugged by the Unified Debugger. When the DEBUG MODE attribute of the procedure is DISABLE, the procedure cannot be subsequently altered to change the debug mode attribute.

If DEBUG MODE is not specified, but a DBGVIEW option in the SET OPTION statement is specified, the procedure cannot be debugged by the Unified Debugger, but may be debugged by the system debug facilities. If neither DEBUG MODE nor a DBGVIEW option is specified, the debug mode used is from the CURRENT DEBUG MODE special register.

FENCED or NOT FENCED

This parameter is allowed for compatibility with other products and is not used by DB2 UDB for iSeries.

OLD SAVEPOINT LEVEL or NEW SAVEPOINT LEVEL

Specifies whether a new savepoint level is to be created on entry to the procedure.

OLD SAVEPOINT LEVEL: A new savepoint level is not created. Any SAVEPOINT statements issued within the procedure with OLD SAVEPOINT LEVEL implicitly or explicitly specified on the SAVEPOINT statement are created at the same savepoint level as the caller of the procedure. This is the default.
NEW SAVEPOINT LEVEL: A new savepoint level is created on entry to the procedure. Any savepoints set within the procedure are created at a savepoint level that is nested deeper than the level at which this procedure was invoked. Therefore, the name of any new savepoint set within the procedure will not conflict with any existing savepoints set in higher savepoint levels (such as the savepoint level of the calling program) with the same name.

COMMIT ON RETURN

Specifies whether the database manager commits the transaction immediately on return from the procedure.

NO

The database manager does not issue a commit when the procedure returns. NO is the default.

YES

The database manager issues a commit if the procedure returns successfully. If the procedure returns with an error, a commit is not issued.

The commit operation includes the work that is performed by the calling application process and the procedure.

If the procedure returns result sets, the cursors that are associated with the result sets must have been defined as WITH HOLD to be usable after the commit.

SET OPTION-statement

Specifies the options that will be used to create the procedure. For example, to create a debuggable procedure, the following statement could be included:

SET OPTION DBGVIEW = *SOURCE

For more information, see SET OPTION.

The options CLOSQLCSR, CNULRQD, COMPILEOPT, NAMING, and SQLCA are not allowed in the CREATE PROCEDURE statement.

SQL-routine-body

Specifies a single SQL statement, including a compound statement. See SQL control statements for more information about defining SQL procedures.

CONNECT, SET CONNECTION, RELEASE, DISCONNECT, and SET TRANSACTION statements are not allowed in a procedure that is running on a remote application server. COMMIT and ROLLBACK statements are not allowed in an ATOMIC SQL procedure or in a procedure that is running on a connection to a remote application server.

Notes

General considerations for defining procedures: See CREATE PROCEDURE for general information on defining procedures.

Procedure ownership: If SQL names were specified:

If a user profile with the same name as the schema into which the procedure is created exists, the owner of the procedure is that user profile.
Otherwise, the owner of the procedure is the user profile or group user profile of the job executing the statement.

If system names were specified, the owner of the procedure is the user profile or group user profile of the job executing the statement.

Procedure authority: If SQL names are used, procedures are created with the system authority of *EXCLUDE on *PUBLIC. If system names are used, procedures are created with the authority to *PUBLIC as determined by the create authority (CRTAUT) parameter of the schema.

If the owner of the procedure is a member of a group profile (GRPPRF keyword) and group authority is specified (GRPAUT keyword), that group profile will also have authority to the procedure.

Error handling in procedures: Consideration should be given to possible exceptions that can occur for each SQL statement in the body of a procedure. Any exception SQLSTATE that is not handled within the procedure using a handler within a compound statement, results in the exception SQLSTATE being returned to the caller of the procedure.

Creating the procedure: When an SQL procedure is created, SQL creates a temporary source file that will contain C source code with embedded SQL statements. A program object is then created using the CRTPGM command. The SQL options used to create the program are the options that are in effect at the time the CREATE PROCEDURE statement is executed. The program is created with ACTGRP(*CALLER).

When an SQL procedure is created, the procedure's attributes are stored in the created program object. If the *PGM object is saved and then restored to this or another system, the catalogs are automatically updated with those attributes.

During restore of the procedure:

If the specific name was specified when the procedure was originally created and it is not unique, an error is issued.
If the specific name was not specified, a unique name is generated if necessary.
If the same procedure name and number of parameters already exists,
- If the name of the created program is the same as the one registered in the catalog, the procedure information in the catalog will be replaced.
- Otherwise, the procedure cannot be registered, and an error is issued.

The specific procedure name is used as the name of the member in the source file and the name of the program object, if it is a valid system name. If the procedure name is not a valid system name, a unique name is generated. If a source file member with the same name already exists, the member is overlaid. If a module or a program with the same name already exists, the objects are not overlaid, and a unique name is generated. The unique names are generated according to the rules for generating system table names.

Invoking the procedure: If a DECLARE PROCEDURE statement defines a procedure with the same name as a created procedure, and a static CALL statement where the procedure name is not identified by a variable is executed from the same source program, the attributes from the DECLARE PROCEDURE statement will be used rather than the attributes from the CREATE PROCEDURE statement.

The CREATE PROCEDURE statement applies to static and dynamic CALL statements as well as to a CALL statement where the procedure name is identified by a variable.

SQL procedures must be called using the SQL CALL statement. When called, the SQL procedure runs in the activation group of the calling program.

Syntax alternatives: The following keywords are synonyms supported for compatibility to prior releases. These keywords are non-standard and should not be used:

The keywords VARIANT and NOT VARIANT can be used as synonyms for NOT DETERMINISTIC and DETERMINISTIC.
The keywords NULL CALL and NOT NULL CALL can be used as synonyms for CALLED ON NULL INPUT and RETURNS NULL ON NULL INPUT.
DYNAMIC RESULT SET, RESULT SETS, and RESULT SET may be used as synonyms for DYNAMIC RESULT SETS.

Example

Create an SQL procedure that returns the median staff salary. Return a result set containing the name, position, and salary of all employees who earn more than the median salary.

   CREATE PROCEDURE MEDIAN_RESULT_SET (OUT medianSalary DECIMAL(7,2))
        LANGUAGE SQL 
        DYNAMIC RESULT SETS 1
   BEGIN 
        DECLARE v_numRecords INTEGER DEFAULT 1;
        DECLARE v_counter INTEGER DEFAULT 0;
        DECLARE c1 CURSOR FOR 
           SELECT salary 
              FROM staff 
              ORDER BY salary;
        DECLARE c2 CURSOR WITH RETURN FOR 
           SELECT name, job, salary 
              FROM staff 
              WHERE salary > medianSalary
              ORDER BY salary;
        DECLARE EXIT HANDLER FOR NOT FOUND
           SET medianSalary = 6666; 
        SET medianSalary = 0;
        SELECT COUNT(*) INTO v_numRecords FROM STAFF;
        OPEN c1;
        WHILE v_counter < (v_numRecords / 2 + 1) 
           DO FETCH c1 INTO medianSalary;
           SET v_counter = v_counter + 1;
        END WHILE;
        CLOSE c1;
        OPEN c2;
   END

[ Top of Page | Previous Page | Next Page | Contents | Index ]