The PREPARE statement prepares an SQL statement for later execution.
|
Embedded Mode P |
Dynamic Mode |
Interactive Mode |
|
statement_identifier |
A single identifier used to identify the statement to be prepared. |
|
host_variable_identifier_1 |
A single host variable identifier of type character string. It receives the unique value which is either generated by Adabas SQL Gateway Embedded SQL or is defined in the application program. This value identifies the statement to be prepared. |
|
OUTPUT hvu |
The definition of the SQL descriptor area used to describe the expected output of the identified statement. |
|
INPUT hvu |
The definition of the SQL descriptor area used to describe the expected input of the identified statement. |
|
character_string_constant |
Explicitly contains the source statement to be prepared. |
|
host_variable_identifier_2 |
A single host variable identifier which contains the character-string representation of the statement to be prepared. |
|
host_variable_specification |
A single host variable identifier. It must have been defined in the application program according to the host language rules. The value of the host variable must be the address of an SQL descriptor area (SQLDA). |
The PREPARE statement performs the following actions:
COMPILATION: An SQL statement in a character-string representation is compiled into an executable SQL statement which is called the prepared statement. If an error is encountered by Adabas SQL Gateway Embedded SQL which prevents the SQL statement to be compiled successfully, an error is passed back to the application program in the SQLCODE field of the SQLCA. In this case no prepared statement is created.
IDENTIFICATION: The prepared statement is kept for later execution. It is identified by the statement identifier provided by the application program or is generated by Adabas SQL Gateway Embedded SQL and passed back into host variable 1. If it is intended that the statement identifier is to be generated by Adabas SQL Gateway Embedded SQL it is necessary to initialize the variable with blanks or an empty string prior to execution. Otherwise, Adabas SQL Gateway Embedded SQL will use the actual (non-blank) value of the variable. This identification will be used to refer to the prepared statement in a DESCRIBE, DECLARE CURSOR or EXECUTE statement.
DEALLOCATE PREPARE may be used to explicitly delete a prepared statement.
DESCRIPTION: The nature of the prepared statement can be determined and conveyed to the user by supplying appropriate SQL descriptor area variables. The functionality of a DESCRIBE statement can be incorporated into the PREPARE statement. For a full description of this functionality refer to the relevant passages of the section DESCRIBE Statement in this section.
The character-string must contain one of the following statements:
COMMIT, CREATE, DELETE, DROP, INSERT, ROLLBACK, SELECT, or UPDATE.
The statement string cannot contain host variables, instead it may contain host variable markers . A host variable marker is represented by a question mark (?). Host variable markers mark those places where values are to be inserted at the time the prepared statement is executed. For a description of how host variable markers are replaced by real values, see EXECUTE. In general, a host variable marker can be used in an SQL statement wherever a host variable can normally appear with the following restriction:
Note: At compilation time, it must be possible to determine the data type resulting from the expression(s) contained in this statement.
None.
This statement may be mixed with any other DML, DDL and/or DCL statements in the same transaction.
Example
The following example prepares the SQL statement with Id 'identifier1' to remove all rows from the table 'cruise'.
PREPARE identifier1 FROM
'delete from cruise';
The following example prepares an SQL statement to delete a single row from the table cruise, where the row to be deleted is identified by it's cruise identifier given in a host variable. Note the use of the host variable marker `?'.
PREPARE statement_identifier FROM
'delete from cruise where cruise_identifier = ?';
The following example prepares a dynamic SELECT statement where the format of the derived columns is not known until runtime, and hence, the SQLDA needs to be used.
PREPARE statement_identifier INTO OUTPUT :sqlda
FROM :dyn_select_identifier ;