From e6c1fbab5c99fd72b3a893b0896de702496d907a Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Wed, 2 Sep 1998 03:01:02 +0000 Subject: [PATCH] Add more new pages. --- doc/src/sgml/ref/commands.sgml | 5 + doc/src/sgml/ref/listen.sgml | 148 ++++++++++++++++++++++++ doc/src/sgml/ref/load.sgml | 157 ++++++++++++++++++++++++++ doc/src/sgml/ref/lock.sgml | 167 +++++++++++++++++++++++++++ doc/src/sgml/ref/move.sgml | 199 +++++++++++++++++++++++++++++++++ doc/src/sgml/ref/notify.sgml | 161 ++++++++++++++++++++++++++ 6 files changed, 837 insertions(+) create mode 100644 doc/src/sgml/ref/listen.sgml create mode 100644 doc/src/sgml/ref/load.sgml create mode 100644 doc/src/sgml/ref/lock.sgml create mode 100644 doc/src/sgml/ref/move.sgml create mode 100644 doc/src/sgml/ref/notify.sgml diff --git a/doc/src/sgml/ref/commands.sgml b/doc/src/sgml/ref/commands.sgml index d151fe02a7..ebf8091b87 100644 --- a/doc/src/sgml/ref/commands.sgml +++ b/doc/src/sgml/ref/commands.sgml @@ -27,6 +27,11 @@ &declare; &delete; &dropFunction; +&listen; +&load; +&lock; +&move; +¬ify; &reset; &revoke; &rollback; diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml new file mode 100644 index 0000000000..2ed7ab8b22 --- /dev/null +++ b/doc/src/sgml/ref/listen.sgml @@ -0,0 +1,148 @@ + + + +LISTEN + +SQL - Language Statements + + + +LISTEN + + +Listen for notification on a relation + + + + +1998-09-01 + + +LISTEN classname + + + + +1998-09-01 + + +Inputs + + + + + + +classname + + + +Table object used for notification. + + + + + + + +1998-04-15 + + +Outputs + + + + + + +LISTEN + + + +Message returned upon successful completion of registration. + + + + + + + + +1998-04-15 + + +Description + + +LISTEN is used to register the current backend as a listener on the relation +classname. +When the command +NOTIFY classname +is called either from within a rule or at the query level, the +frontend applications corresponding to the listening backends +are notified. When the backend process exits, this registration +is cleared. + + +This event notification is performed through the libpq protocol +and frontend application interface. The application program +must call the routine +PQnotifies +in order to find out the name of the class to which a given +notification corresponds. If this code is not included in +the application, the event notification will be queued and +never be processed. + + + +1998-04-15 + + +Notes + + +Note that classname +needs not to be a valid class name but can be any string valid as a name up to 32 +characters long. + + +A restriction in some previous releases of + Postgres that a +classname +which does not correspond to an actual table must be enclosed in double-quotes +is no longer present. + + + + + +Usage + + + +postgres=> listen virtual; +LISTEN +postgres=> notify virtual; +NOTIFY +ASYNC NOTIFY of 'virtual' from backend pid '11239' received + + + + + + +Compatibility + + + + + + +1998-09-01 + + +SQL92 + + + There is no LISTEN statement in SQL92. + diff --git a/doc/src/sgml/ref/load.sgml b/doc/src/sgml/ref/load.sgml new file mode 100644 index 0000000000..a72675105a --- /dev/null +++ b/doc/src/sgml/ref/load.sgml @@ -0,0 +1,157 @@ + + + +LOAD + +SQL - Language Statements + + + +LOAD + + +Dynamically loads an object file + + + + +1998-09-01 + + + + +LOAD 'filename' + + + + +1998-09-01 + + +Inputs + + + + + + +filename + + + +Object file for dynamic loading. + + + + + + + +1998-04-15 + + +Outputs + + + + + + +LOAD + + + + + + + + + + + +1998-04-15 + + +Description + + +Loads an object (or ".o") file into the +Postgres backend address space. Once a +file is loaded, all functions in that file can be accessed. This +function is used in support of ADT's. + + +If a file is not loaded using +LOAD, +the file will be loaded automatically the first time the +function is called by Postgres. +LOAD +can also be used to reload an object file if it has been edited and +recompiled. Only objects created from C language files are supported +at this time. + + + +1998-04-15 + + +Notes + + +Functions in loaded object files should not call functions in other +object files loaded through the +LOAD +command, meaning, for example, that all functions in file A should +call each other, functions in the standard or math libraries, or in +Postgres itself. They should not call functions defined in a different +loaded file B. This is because if B is reloaded, the Postgres loader is +not able to relocate the calls from the functions in A into +the new address space of B. If B is not reloaded, however, there will +not be a problem. + + +Object files must be compiled to contain position independent code. +For example, +on DECstations you must use +/bin/cc +with the "-G 0" option when compiling object files to be +loaded. + + +Note that if you are porting Postgres + to a new platform, LOAD +will have to work in order to support ADTs. + + + + + +Usage + + + + --Load the file /usr/postgres/demo/circle.o + -- + LOAD "/usr/postgres/demo/circle.o" + + + + + + +Compatibility + + + + + + +1998-04-15 + + +SQL92 + + +There is no LOAD statement in SQL92. + + diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml new file mode 100644 index 0000000000..480ad84401 --- /dev/null +++ b/doc/src/sgml/ref/lock.sgml @@ -0,0 +1,167 @@ + + + +LOCK + +SQL - Language Statements + + + +LOCK + + +Explicit lock of a table inside a transaction + + + + +1998-09-01 + + +LOCK [TABLE] table + + + + +1998-09-01 + + +Inputs + + + + + + +table + + + + The name of an existing table to lock. + + + + + + +1998-04-15 + + +Outputs + + + + + + +DELETE 0 + + + +Message returned on a successful lock. +LOCK is implemented as a +DELETE FROM table +which is guaranteed to not delete any rows. + + + +ERROR table: Table does not exist. + + + +Message returned if table don't exist. + + + + + + + + +1998-04-15 + + +Description + + + The LOCK statement locks in exclusive mode a table inside + a transaction. The classic use for this is + the case where you want to select some data, then + update it inside a transaction. + If you don't explicit lock a table using LOCK statement, it will be + implicit locked only at first UPDATE, INSERT or DELETE operation. + If you don't exclusive lock the table before the select, some + other user may also read the selected data, and try and do + their own update, causing a deadlock while you both wait + for the other to release the select-induced shared lock so + you can get an exclusive lock to do the update. + + + Another example of deadlock is where one user locks one + table, and another user locks a second table. While both + keep their existing locks, the first user tries to lock + the second user's table, and the second user tries to lock + the first user's table. Both users deadlock waiting for + the tables to become available. The only solution to this + is for both users to lock tables in the same order, so + user's lock acquisitions and requests to not form a deadlock. + + + +1998-04-15 + + +Notes + + +LOCK is a PostgreSQL language extension. + +LOCK works only inside transactions. + + +Bug + +If the locked table is dropped then it will be automatically + unlocked even if a transaction is still in progress. + + + + + + +Usage + + + + + --Explicit locking to prevent deadlock: + -- + BEGIN WORK; + LOCK films; + SELECT * FROM films; + UPDATE films SET len = INTERVAL '100 minute' + WHERE len = INTERVAL '117 minute'; + COMMIT WORK; + + + + + + +Compatibility + + + + + + +1998-04-15 + + +SQL92 + + + There is no LOCK TABLE in SQL92, + it uses SET TRANSACTION to specify + concurrency level on transactions. + diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml new file mode 100644 index 0000000000..af81ac28dc --- /dev/null +++ b/doc/src/sgml/ref/move.sgml @@ -0,0 +1,199 @@ + + + +MOVE + +SQL - Language Statements + + + +MOVE + + +Moves cursor position + + + + +1998-09-01 + + +MOVE [ selector ] { [ # | ALL ] } IN cursor + + + + +1998-09-01 + + +Inputs + + + + + + +selector + + + + + + + +FORWARD + + + +Skip next row(s), it is assumed by default + if selector is omitted. + + + +BACKWARD + + + +Skip previous row(s). + + + + + +# + + + + An unsigned integer that specify how many rows to skip. + + + +ALL + + + +Skip all remaining rows. + + + +cursor + + + + An open cursor's name. + + + + + + + +1998-09-01 + + +Outputs + + + + + + +MOVE + + + + Message returned if successfully. + + + +NOTICE: PerformPortalFetch: portal cursor not found. + + + + If cursor is not declared. + + + + + + + + +1998-04-15 + + +Description + + + MOVE allows a user to move cursor position for specified + number of rows. MOVE works like fetch command: it + fetches rows, but put them nowhere. + + + +1998-04-15 + + +Notes + + +MOVE is a Postgres language extension. + + + Refer to FETCH statements for further description + of valid arguments. + Refer to DECLARE statements to declare a cursor. + Refer to BEGIN WORK, COMMIT WORK, ROLLBACK WORK statements + for further information about transactions. + + + + + +Usage + + + + --set up and use a cursor: + -- + BEGIN WORK; + DECLARE liahona CURSOR + FOR SELECT * FROM films; + + --Skip first 5 rows: + -- + MOVE FORWARD 5 IN liahona; + + --Fetch 6th row in the cursor liahona: + -- + FETCH 1 IN liahona; + + code |title |did| date_prod|kind |len + -----+------+---+----------+----------+------ + P_303|48 Hrs|103|1982-10-22|Action | 01:37 + + -- close the cursor liahona and commit work: + -- + CLOSE liahona; + COMMIT WORK; + + + + + + +Compatibility + + + + + + +1998-09-01 + + +SQL92 + + + There is no SQL92 MOVE statement. + diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml new file mode 100644 index 0000000000..a9a3e8f52f --- /dev/null +++ b/doc/src/sgml/ref/notify.sgml @@ -0,0 +1,161 @@ + + + +NOTIFY + +SQL - Language Statements + + + +NOTIFY + + +Signals all frontends and backends listening on a class + + + + +1998-09-01 + + + + +NOTIFY classname + + + + +1998-09-01 + + +Inputs + + + + + + +classname + + + +Table or arbitrary relation class used for notification. + + + + + + + +1998-09-01 + + +Outputs + + + + + + +NOTIFY + + + +Notification message from backend. + + + + + + + + +1998-09-01 + + +Description + + + NOTIFY is used to awaken all backends and consequently all + frontends that have executed LISTEN on +classname. + This can be used either within an instance-level rule +as part of the action body or from a normal query. + + + When used from within a normal query, +this can be thought of as interprocess communication (IPC). When +used from within a rule, this can be thought of as an alerter mechanism. + + Notice that the mere fact that a notify has been + executed does not imply anything in particular about the state + of the class (e.g., that it has been updated), + nor does the notification protocol transmit any useful information + other than the class name. +Therefore, all notify does is indicate that some backend wishes its peers to + examine classname + in some application-specific way. + + In fact, classname + need not be the name of an SQL class at all. + It is best thought of as a condition name + that the application programmer selects. + + This event notification is performed through the libpq protocol + and frontend application interface. The application program + must call the routine PQnotifies in order to find out the +name of the class to which a given + notification corresponds. +If this code is not included in the application, +the event notification will be + queued and never be processed. + + + +1998-09-01 + + +Notes + + + + + + + + +Usage + + + + +-- Configure and execute a listen/notify sequence +-- from psql +postgres=> create table t (i int4); +postgres=> listen t; +LISTEN +postgres=> notify t; +NOTIFY +ASYNC NOTIFY of 't' from backend pid '10949' received + + + + + + +Compatibility + + + + + + +1998-09-01 + + +SQL92 + + +There is no NOTIFY statement in SQL92. + +