ALTER PROCEDURE (SQL)

The ALTER PROCEDURE (SQL) statement alters a 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:

• For the procedure identified in the statement:
  • The ALTER privilege for the procedure, and
  • The system authority *EXECUTE on the library containing the procedure.
• Administrative authority

If a distinct type is referenced in a parameter-declaration, 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

>>-ALTER-------------------------------------------------------->
 
>--+-PROCEDURE--procedure-name--+--------------------------+-+-->
   |                            '-(--+----------------+--)-' |
   |                                 '-parameter-type-'      |
   '-SPECIFIC PROCEDURE--specific-name-----------------------'
 
     .-ALTER-.
>--+-+-------+--option-list---------+--------------------------><
   '-REPLACE--routine-specification-'
 
routine-specification:
 
|--+-------------------------------------+--+-------------+----->
   '-(--+---------------------------+--)-'  '-option-list-'
        | .-,---------------------. |
        | V                       | |
        '---parameter-declaration-+-'
 
>--+----------------------+--SQL-routine-body-------------------|
   '-SET OPTION-statement-'
 
parameter-declaration:
 
   .-IN----.
|--+-------+--parameter-name--data-type-------------------------|
   +-OUT---+
   '-INOUT-'
 
parameter-type:
 
|----data-type--+------------+----------------------------------|
                '-AS LOCATOR-'
 
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-'
 
                            .-FENCED-----.
>--+---------------------+--+------------+---------------------->
   +-ALLOW DEBUG MODE----+  '-NOT FENCED-'
   +-DISABLE DEBUG MODE--+
   '-DISALLOW DEBUG MODE-'
 
   .-OLD SAVEPOINT LEVEL-.  .-COMMIT ON RETURN NO--.
>--+---------------------+--+----------------------+------------|
   '-NEW SAVEPOINT LEVEL-'  '-COMMIT ON RETURN YES-'
 

1. The clauses in the option-list can be specified in any 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 or SPECIFIC PROCEDURE

Identifies the procedure to alter. procedure-name must identify a procedure that exists at the current server.

The specified procedure is altered. The owner of the procedure and all privileges on the procedure are preserved.

PROCEDURE procedure-name

Identifies the procedure by its name. The procedure-name must identify exactly one procedure. The procedure may have any number of parameters defined for it. If there is more than one procedure of the specified name in the specified or implicit schema, an error is returned.

PROCEDURE procedure-name (parameter-type,...)

Identifies the procedure by its procedure signature, which uniquely identifies the procedure. The procedure-name (parameter-type,...) must identify a procedure with the specified procedure signature. The specified parameters must match the data types in the corresponding position that were specified when the procedure was created. The number of data types and the logical concatenation of the data types is used to identify the specific procedure instance which is being altered. Synonyms for data types are considered a match.

If procedure-name() is specified, the procedure identified must have zero parameters.

procedure-name

Identifies the name of the procedure.

(parameter-type,...)

Identifies the parameters of the procedure.

If an unqualified distinct type name is specified, the database manager searches the SQL path to resolve the schema name for the distinct type.

For data types that have a length, precision, or scale attribute, use one of the following:

• Empty parenthesis indicates that the database manager ignores the attribute when determining whether the data types match. For example, DEC() will be considered a match for a parameter of a procedure defined with a data type of DEC(7,2). However, FLOAT cannot be specified with empty parenthesis because its precision value indicates a specific data type (REAL or DOUBLE).
• If a specific value for a length, precision, or scale attribute is specified, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE PROCEDURE statement. If the data type is FLOAT, the precision does not have to exactly match the value that was specified because matching is based on the data type (REAL or DOUBLE).
• If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default attributes of the data type are implied. The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE PROCEDURE statement.

Specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that the database manager ignores the attribute when determining whether the data types match. If either clause is specified, it must match the value that was implicitly or explicitly specified in the CREATE PROCEDURE statement.

AS LOCATOR

Specifies that the procedure is defined to receive a locator for this parameter. If AS LOCATOR is specified, the data type must be a LOB or a distinct type based on a LOB.

SPECIFIC PROCEDURE specific-name

Identifies the procedure by its specific name. The specific-name must identify a specific procedure that exists at the current server.

ALTER option-list

Indicates that one or more of the options of the procedure are to be altered. If ALTER PROCEDURE ALTER option-list is specified and an option is not specified, the value from the existing procedure definition is used.

NOT DETERMINISTIC or 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.

MODIFIES SQL DATA, READS SQL DATA, CONTAINS SQL, or NO SQL

Specifies the classification of SQL statements that this procedure, or any routine called by this procedure, can execute. The database manager verifies that the SQL statements issued by the procedure and all routines called by the procedure are consistent with this specification. For the classification of each statement, see SQL statement data access indication in routines.

MODIFIES SQL DATA

Specifies that the procedure can execute any SQL statement except statements that are not supported in procedures.

READS SQL DATA

Specifies that the procedure can execute statements with a data access classification of READS SQL DATA or CONTAINS SQL.

CONTAINS SQL

Specifies that the procedure can only execute statements with a data access classification of CONTAINS SQL.

CALLED ON NULL INPUT

Specifies that the procedure will be called if any, or all, parameter values are null.

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 result sets returned is the minimum of the number of results 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 a 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 both the following are true:

• 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, and
• the external program does not have an attribute of ACTGRP(*NEW).

For more information about result sets see SET RESULT SETS.

FENCED or NOT FENCED

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

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

Indicates whether the procedure 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 can 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.

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.

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 within the procedure will not conflict with any existing 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.

YES

The database manager issues a commit when 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 must have been defined as WITH HOLD to be usable after the commit.

REPLACE routine-specification

Indicates that the existing procedure definition, including options and parameters, is to be replaced by those specified in this statement. The values of all options are replaced when a procedure is replaced. If an option is not specified, the same default is used as when a new SQL procedure is created, for more information see CREATE PROCEDURE (SQL).

(parameter-declaration,...)

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

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

IN

Identifies the parameter as an input parameter to the procedure.

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. If the parameter is not set within the procedure, its input value is returned.

parameter-name

Names the parameter for use as an SQL variable. The name cannot be the same as any other parameter-name for the procedure.

data-type

Specifies the data type of the parameter. 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.

option-list

List of options for the procedure being altered. These options are the same ones that are listed above under ALTER option-list. If a specific option is not specified, the same default that is used when a new procedure is created is used. For more information see CREATE PROCEDURE (SQL).

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 or replacing procedures: See CREATE PROCEDURE for general information on defining a procedure. ALTER PROCEDURE (SQL) allows individual attributes or the routine specification to be altered while preserving the privileges on the procedure.

Alter Procedure Replace considerations: When an SQL procedure is replaced, 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 ALTER PROCEDURE (SQL) statement is executed. The program is created with ACTGRP(*CALLER).

When an SQL procedure is altered, a new *PGM object is created and 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.

The specific 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.

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.

Examples

Modify the definition for an SQL procedure so that SQL changes are committed on return from the SQL procedure.

  ALTER PROCEDURE UPDATE_SALARY_2 
    ALTER COMMIT ON RETURN YES