$Id: NEW-COMMANDS,v 1.2 2004/04/23 17:48:41 karl Exp $

These are quick notes on the new commands until the main documentation has
been updated, massaged, reworked, etc.

pg_blocking connection

    This function is related to asynchronous query processing.

    This sets whether a connection is set for blocking or nonblocking, and
    allows that state to be changed.

     syntax:
     pg_blocking connection - returns the current state, 1 = blocking, 0 = non
     pg_blocking connection 1 - sets the connection to blocking
     pg_blocking connection 0 - sets the connection to nonblocking

    Note - I'm not sure about all of the ramifications of setting a connection
    nonblocking.  Even with a connection in the (default) blocking state, 
    pg_isbusy seems to work OK and can be used in conjunction with pg_getresult
    to keep from blocking while processing query results.

pg_cancelrequest connection

    This function is related to asynchronous query processing.

    This request that postgresql abandon processing of the current command
    issued via pg_sendquery.

    There is no guarantee that the request will be cancelled.  If it is and
    you were in the middle of a transaction, the entire transaction 
    is cancelled.

    You still need to call pg_getresult repeatedly until it doesn't return
    anything, and handle (and discard) all of the returned result handles.


pg_quote 

    This escapes a string by making it Postgres-safe.  It quotes single
    quotes and backslashes.  If you're doing something like
    pg_exec "insert into foo(name='$name');" and name contains a single
    quote, it'll fail.  Passign value strings through pg_quote
    make sure they can be used as values and stuff in Postgres.

    pg_exec "insert into foo(name=[pg_quote $name]);" will make
    sure that any special characters that occur in name, such as
    single quote or backslash, will be properly quoted.

pg_exec 

pg_execute 

pg_getresult connection

    This is an asynchronous request processing function.

    This will return the same sort of result handle that pg_exec returns.

    If there is no query currently being processed or all of the results have
    been obtained, pg_getresult returns nothing.


pg_isbusy connection

    This function is related to asynchronous query processing.

    pg_getresult can block if results aren't yet available.  To avoid this,
    you can use pg_isbusy to check to see if the connection is busy processing
    a query.

    If this returns 1, pg_getresult will block if called.  If it's 0, you can
    safely call pg_getresult and it won't block.


pg_listen 

pg_on_connection_loss 

pg_result 

pg_sendquery connection query

    This works like pg_exec, except that the query is issued asynchronously
    and pg_sendquery returns immediately without providing a result handle.

    To get result handles resulting from the execution of pg_sendqery (and 
    there may be more than one if there are multiple SQL commands in the 
    query), you need to repeatedly call

	pg_getresult connection

