libpq++.sgml

关系型数据库 Postgresql 6.5.2

 <chapter id="libpqplusplus">
  <title>libpq C++ Binding</title>
  
  <para>
   <filename>libpq++</filename> is the C++ API to 
   <productname>Postgres</productname>.
   <filename>libpq++</filename>  is a set of classes which allow
   client programs to connect to the 
   <productname>Postgres</productname> backend server. These connections
   come in two forms: a Database Class and a Large Object class.
  </para>

  <para>
   The Database Class is intended for manipulating a database. You can
   send all sorts of SQL queries to the <productname>Postgres</productname> 
   backend server and retrieve the responses of the server.
  </para>

  <para>
   The Large Object Class is intended for manipulating a large object
   in a database. Although a Large Object instance can send normal
   queries to the <productname>Postgres</productname> backend server 
   it is only intended for simple
   queries that do not return any data. A large object should be seen
   as a file stream. In the future it should behave much like the C++ file
   streams
   <literal>cin</literal>,
   <literal>cout</literal>
   and
   <literal>cerr</literal>.
  </para>

  <para>
   This chapter is based on the documentation
   for the <filename>libpq</filename> C library.  Three
   short programs are listed at the end of this section as examples of
   <filename>libpq++</filename> programming 
   (though not necessarily of good programming).
   There are several examples of <filename>libpq++</filename> 
   applications in
   <filename>src/libpq++/examples</filename>, including the source
   code for the three examples in this chapter.
  </para>

  <sect1>
   <title>Control and Initialization</title>
    
   <sect2>
    <title>Environment Variables</title>
    <para>
     The following environment variables can be used to set up default
     values for an environment and to avoid hard-coding database names into
     an application program:
     <note>
      <para>
       Refer to the <xref endterm="libpq" linkend="libpq-envars"> for a complete
       list of available connection options.
      </para>
     </note>
    </para>

    <para>
     The following environment variables can be used to select default
     connection parameter values, which will be used by PQconnectdb or
     PQsetdbLogin if no value is directly specified by the calling code.
     These are useful to avoid hard-coding database names into simple
     application programs.
     <note>
      <para>
       <filename>libpq++</filename> uses only environment variables or PQconnectdb
       conninfo style strings.
      </para>
     </note>
	  
     <itemizedlist>
      <listitem>
       <para>
	<envar>PGHOST</envar> sets the default server name.
	If a non-zero-length string is specified, TCP/IP communication is used.
	Without a host name, libpq will connect using a local Unix domain socket.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGPORT</envar>  sets the default port or local Unix domain socket
	file extension for communicating with the <productname>Postgres</productname>
	backend.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGDATABASE</envar>  sets the default 
	<productname>Postgres</productname> database name.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGUSER</envar>
	sets the username used to connect to the database and for authentication.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGPASSWORD</envar>
	sets the password used if the backend demands password authentication.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGREALM</envar> sets the Kerberos realm to  use  with  
	<productname>Postgres</productname>,
	if  it is different from the local realm.  If
	<envar>PGREALM</envar> is set, <productname>Postgres</productname> 
	applications  will  attempt
	authentication  with  servers for this realm and use
	separate ticket files to avoid conflicts with  local
	ticket  files.   This  environment  variable is only
	used if Kerberos authentication is selected by the backend.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGOPTIONS</envar> sets additional runtime  options  for  
	the <productname>Postgres</productname> backend.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGTTY</envar> sets the file or tty on which  debugging  
	messages from the backend server are displayed.
       </para>
      </listitem>
     </itemizedlist>
    </para>
	
    <para>
     The following environment variables can be used to specify user-level default
     behavior for every Postgres session:
	  
     <itemizedlist>
      <listitem>
       <para>
	<envar>PGDATESTYLE</envar>
	sets the default style of date/time representation.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGTZ</envar>
	sets the default time zone.
       </para>
      </listitem>
     </itemizedlist>
    </para>
    
    <para>
     The following environment variables can be used to specify default internal
     behavior for every Postgres session:
     
     <itemizedlist>
      <listitem>
       <para>
	<envar>PGGEQO</envar>
	sets the default mode for the genetic optimizer.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGRPLANS</envar>
	sets the default mode to allow or disable right-sided plans in the optimizer.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGCOSTHEAP</envar>
	sets the default cost for heap searches for the optimizer.
       </para>
      </listitem>
      <listitem>
       <para>
	<envar>PGCOSTINDEX</envar>
	sets the default cost for indexed searches for the optimizer.
       </para>
      </listitem>
     </itemizedlist>
    </para>
	
    <para>
     Refer to the <command>SET</command> <acronym>SQL</acronym> command
     for information on correct values for these environment variables.
    </para>
   </sect2>
  </sect1>

  <sect1>
   <title>libpq++ Classes</title>

   <sect2>
    <title>Connection Class: <classname>PgConnection</classname></title>

    <para>
     The connection class makes the actual connection to the database and is inherited
     by all of the access classes.
    </para>
   </sect2>

   <sect2>
    <title>Database Class: <classname>PgDatabase</classname></title>

    <para>
     The database class provides C++ objects that have a connection
     to a backend server. To create such an object one first needs
     the apropriate environment for the backend to access.
     The following constructors deal with making a connection to a backend
     server from a C++ program.
    </para>
   </sect2>
  </sect1>

  <sect1>
   <title>Database Connection Functions</title>
   <para>
    <itemizedlist>
     <listitem>
      <para>
       <function>PgConnection</function>
       makes a new connection to a backend database server.
       <synopsis>
	PgConnection::PgConnection(const char *conninfo)
       </synopsis>
       Although typically called from one of the access classes, a connection to
       a backend server is possible by creating a PgConnection object.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>ConnectionBad</function>
       returns whether or not the connection to the backend server succeeded or
       failed.  
       <synopsis>
	int PgConnection::ConnectionBad()
       </synopsis>
       Returns TRUE if the connection failed.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>Status</function>
       returns the status of the connection to the backend server.
       <synopsis>
	ConnStatusType PgConnection::Status()
       </synopsis>
       Returns either CONNECTION_OK or CONNECTION_BAD depending on the state
       of the connection.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>PgDatabase</function>
       makes a new connection to a backend database server.
       <synopsis>
	PgDatabase(const char *conninfo)
       </synopsis>
       After a PgDatabase has been created it should be checked to make sure
       the connection to the database succeded before sending
       queries to the object. This can easily be done by
       retrieving the current status of the PgDatabase object with the
       <function>Status</function> or <function>ConnectionBad</function> methods.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>DBName</function>
       Returns the name of the current database.
       <synopsis>
	const char *PgConnection::DBName()
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>Notifies</function>
       Returns the next notification from a list of unhandled notification messages 
       received from the backend.
       <synopsis>
	PGnotify* PgConnection::Notifies()
       </synopsis>
       See PQnotifies() for details.
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </sect1>

  <sect1>
   <title>Query Execution Functions</title>
   <para>  
    <itemizedlist>
     <listitem>
      <para>
       <function>Exec</function>
       Sends a query to the backend server.  It's probably more desirable to
       use one of the next two functions.
       <synopsis>
	ExecStatusType PgConnection::Exec(const char* query)
       </synopsis>
       Returns the result of the query. The following status results can be expected:
       
       <simplelist>
	<member>
	 PGRES_EMPTY_QUERY
	</member>
	<member>
	 PGRES_COMMAND_OK, if the query was a command
	</member>
	<member>
	 PGRES_TUPLES_OK, if the query successfully returned tuples
	</member>
	<member>
	 PGRES_COPY_OUT
	</member>
	<member>
	 PGRES_COPY_IN
	</member>
	<member>
	 PGRES_BAD_RESPONSE, if an unexpected response was received
	</member>
	<member>
	 PGRES_NONFATAL_ERROR
	</member>
	<member>
	 PGRES_FATAL_ERROR
	</member>
       </simplelist>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>ExecCommandOk</function>
       Sends a command query to the backend server.
       <synopsis>
	int PgConnection::ExecCommandOk(const char *query)
       </synopsis>
       Returns TRUE if the command query succeeds.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>ExecTuplesOk</function>
       Sends a command query to the backend server.
       <synopsis>
	int PgConnection::ExecTuplesOk(const char *query)
       </synopsis>
       Returns TRUE if the command query succeeds and there are tuples to be retrieved.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>ErrorMessage</function>
       Returns the last error message text.
       <synopsis>
	const char *PgConnection::ErrorMessage()
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>Tuples</function>
       Returns the number of tuples (instances) in the query result. 
       <synopsis>
	int PgDatabase::Tuples()
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>Fields</function>
       Returns the number of fields (attributes) in each tuple of the query result. 
       <synopsis>
	int PgDatabase::Fields()
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>FieldName</function>
       Returns the field (attribute) name associated with the given field index. 
       Field indices start at 0. 
       <synopsis>