begriffs open source - ai-pg/blob - full-docs/txt/ecpg-commands.txt

   1
   2 34.3. Running SQL Commands #
   3
   4    34.3.1. Executing SQL Statements
   5    34.3.2. Using Cursors
   6    34.3.3. Managing Transactions
   7    34.3.4. Prepared Statements
   8
   9    Any SQL command can be run from within an embedded SQL application.
  10    Below are some examples of how to do that.
  11
  12 34.3.1. Executing SQL Statements #
  13
  14    Creating a table:
  15 EXEC SQL CREATE TABLE foo (number integer, ascii char(16));
  16 EXEC SQL CREATE UNIQUE INDEX num1 ON foo(number);
  17 EXEC SQL COMMIT;
  18
  19    Inserting rows:
  20 EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
  21 EXEC SQL COMMIT;
  22
  23    Deleting rows:
  24 EXEC SQL DELETE FROM foo WHERE number = 9999;
  25 EXEC SQL COMMIT;
  26
  27    Updates:
  28 EXEC SQL UPDATE foo
  29     SET ascii = 'foobar'
  30     WHERE number = 9999;
  31 EXEC SQL COMMIT;
  32
  33    SELECT statements that return a single result row can also be executed
  34    using EXEC SQL directly. To handle result sets with multiple rows, an
  35    application has to use a cursor; see Section 34.3.2 below. (As a
  36    special case, an application can fetch multiple rows at once into an
  37    array host variable; see Section 34.4.4.3.1.)
  38
  39    Single-row select:
  40 EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
  41
  42    Also, a configuration parameter can be retrieved with the SHOW command:
  43 EXEC SQL SHOW search_path INTO :var;
  44
  45    The tokens of the form :something are host variables, that is, they
  46    refer to variables in the C program. They are explained in
  47    Section 34.4.
  48
  49 34.3.2. Using Cursors #
  50
  51    To retrieve a result set holding multiple rows, an application has to
  52    declare a cursor and fetch each row from the cursor. The steps to use a
  53    cursor are the following: declare a cursor, open it, fetch a row from
  54    the cursor, repeat, and finally close it.
  55
  56    Select using cursors:
  57 EXEC SQL DECLARE foo_bar CURSOR FOR
  58     SELECT number, ascii FROM foo
  59     ORDER BY ascii;
  60 EXEC SQL OPEN foo_bar;
  61 EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
  62 ...
  63 EXEC SQL CLOSE foo_bar;
  64 EXEC SQL COMMIT;
  65
  66    For more details about declaring a cursor, see DECLARE; for more
  67    details about fetching rows from a cursor, see FETCH.
  68
  69 Note
  70
  71    The ECPG DECLARE command does not actually cause a statement to be sent
  72    to the PostgreSQL backend. The cursor is opened in the backend (using
  73    the backend's DECLARE command) at the point when the OPEN command is
  74    executed.
  75
  76 34.3.3. Managing Transactions #
  77
  78    In the default mode, statements are committed only when EXEC SQL COMMIT
  79    is issued. The embedded SQL interface also supports autocommit of
  80    transactions (similar to psql's default behavior) via the -t
  81    command-line option to ecpg (see ecpg) or via the EXEC SQL SET
  82    AUTOCOMMIT TO ON statement. In autocommit mode, each command is
  83    automatically committed unless it is inside an explicit transaction
  84    block. This mode can be explicitly turned off using EXEC SQL SET
  85    AUTOCOMMIT TO OFF.
  86
  87    The following transaction management commands are available:
  88
  89    EXEC SQL COMMIT #
  90           Commit an in-progress transaction.
  91
  92    EXEC SQL ROLLBACK #
  93           Roll back an in-progress transaction.
  94
  95    EXEC SQL PREPARE TRANSACTION transaction_id #
  96           Prepare the current transaction for two-phase commit.
  97
  98    EXEC SQL COMMIT PREPARED transaction_id #
  99           Commit a transaction that is in prepared state.
 100
 101    EXEC SQL ROLLBACK PREPARED transaction_id #
 102           Roll back a transaction that is in prepared state.
 103
 104    EXEC SQL SET AUTOCOMMIT TO ON #
 105           Enable autocommit mode.
 106
 107    EXEC SQL SET AUTOCOMMIT TO OFF #
 108           Disable autocommit mode. This is the default.
 109
 110 34.3.4. Prepared Statements #
 111
 112    When the values to be passed to an SQL statement are not known at
 113    compile time, or the same statement is going to be used many times,
 114    then prepared statements can be useful.
 115
 116    The statement is prepared using the command PREPARE. For the values
 117    that are not known yet, use the placeholder “?”:
 118 EXEC SQL PREPARE stmt1 FROM "SELECT oid, datname FROM pg_database WHERE oid = ?"
 119 ;
 120
 121    If a statement returns a single row, the application can call EXECUTE
 122    after PREPARE to execute the statement, supplying the actual values for
 123    the placeholders with a USING clause:
 124 EXEC SQL EXECUTE stmt1 INTO :dboid, :dbname USING 1;
 125
 126    If a statement returns multiple rows, the application can use a cursor
 127    declared based on the prepared statement. To bind input parameters, the
 128    cursor must be opened with a USING clause:
 129 EXEC SQL PREPARE stmt1 FROM "SELECT oid,datname FROM pg_database WHERE oid > ?";
 130 EXEC SQL DECLARE foo_bar CURSOR FOR stmt1;
 131
 132 /* when end of result set reached, break out of while loop */
 133 EXEC SQL WHENEVER NOT FOUND DO BREAK;
 134
 135 EXEC SQL OPEN foo_bar USING 100;
 136 ...
 137 while (1)
 138 {
 139     EXEC SQL FETCH NEXT FROM foo_bar INTO :dboid, :dbname;
 140     ...
 141 }
 142 EXEC SQL CLOSE foo_bar;
 143
 144    When you don't need the prepared statement anymore, you should
 145    deallocate it:
 146 EXEC SQL DEALLOCATE PREPARE name;
 147
 148    For more details about PREPARE, see PREPARE. Also see Section 34.5 for
 149    more details about using placeholders and input parameters.