libpq++.sgml

关系型数据库 Postgresql 6.5.2

	const char *PgDatabase::FieldName(int field_num)
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>FieldNum</function>
       PQfnumber Returns the field (attribute) index associated with 
       the given field name. 
       <synopsis>
	int PgDatabase::FieldNum(const char* field_name)
       </synopsis>
       -1 is returned if the given name does not match any field.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>FieldType</function>
       Returns the field type associated with the given field index. The 
       integer returned is an internal coding of the type. Field indices
       start at 0. 
       <synopsis>
	Oid PgDatabase::FieldType(int field_num)
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>FieldType</function>
       Returns the field type associated with the given field name. The 
       integer returned is an internal coding of the type. Field indices
       start at 0. 
       <synopsis>
	Oid PgDatabase::FieldType(const char* field_name)
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>FieldSize</function>
       Returns the size in bytes of the field associated with the given 
       field index. Field indices start at 0. 
       <synopsis>
	short PgDatabase::FieldSize(int field_num)
       </synopsis>
       Returns the space allocated for this field in a database tuple given
       the field number. In other words the size of the server's binary 
       representation of the data type. -1 is returned if the field is 
       variable size.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>FieldSize</function>
       Returns the size in bytes of the field associated with the given 
       field index. Field indices start at 0. 
       <synopsis>
	short PgDatabase::FieldSize(const char *field_name)
       </synopsis>
       Returns the space allocated for this field in a database tuple given
       the field name. In other words the size of the server's binary 
       representation of the data type. -1 is returned if the field is 
       variable size.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>GetValue</function>
       Returns a single field (attribute) value of one tuple of a PGresult. 
       Tuple and field indices start at 0. 
       <synopsis>
	const char *PgDatabase::GetValue(int tup_num, int field_num)
       </synopsis>
       For most queries, the value returned by GetValue is a null-terminated 
       ASCII string representation of the attribute value. But if BinaryTuples() 
       is TRUE, the value returned by GetValue is the binary representation 
       of the type in the internal format of the backend server (but not including 
       the size word, if the field is variable-length). It is then the programmer's 
       responsibility to cast and convert the data to the correct C type. The 
       pointer returned by GetValue points to storage that is part of the 
       PGresult structure. One should not modify it, and one must explicitly 
       copy the value into other storage if it is to be used past the lifetime 
       of the PGresult structure itself.  BinaryTuples() is not yet implemented.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>GetValue</function>
       Returns a single field (attribute) value of one tuple of a PGresult. 
       Tuple and field indices start at 0. 
       <synopsis>
	const char *PgDatabase::GetValue(int tup_num, const char *field_name)
       </synopsis>
       For most queries, the value returned by GetValue is a null-terminated 
       ASCII string representation of the attribute value. But if BinaryTuples() 
       is TRUE, the value returned by GetValue is the binary representation 
       of the type in the internal format of the backend server (but not including 
       the size word, if the field is variable-length). It is then the programmer's 
       responsibility to cast and convert the data to the correct C type. The 
       pointer returned by GetValue points to storage that is part of the 
       PGresult structure. One should not modify it, and one must explicitly 
       copy the value into other storage if it is to be used past the lifetime 
       of the PGresult structure itself.  BinaryTuples() is not yet implemented.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>GetLength</function>
       Returns the length of a field (attribute) in bytes. Tuple and field 
       indices start at 0. 
       <synopsis>
	int PgDatabase::GetLength(int tup_num, int field_num)
       </synopsis>
       This is the actual data length for the particular data value, that 
       is the size of the object pointed to by GetValue. Note that for
       ASCII-represented values, this size has little to do with the binary 
       size reported by PQfsize.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>GetLength</function>
       Returns the length of a field (attribute) in bytes. Tuple and field 
       indices start at 0. 
       <synopsis>
	int PgDatabase::GetLength(int tup_num, const char* field_name)
       </synopsis>
       This is the actual data length for the particular data value, that 
       is the size of the object pointed to by GetValue. Note that for
       ASCII-represented values, this size has little to do with the binary 
       size reported by PQfsize.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>DisplayTuples</function>
       Prints out all the tuples and, optionally, the attribute names to the 
       specified output stream. 
       <synopsis>
	void PgDatabase::DisplayTuples(FILE *out = 0, int fillAlign = 1, 
	const char* fieldSep = "|",int printHeader = 1, int quiet = 0)
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>PrintTuples</function>
       Prints out all the tuples and, optionally, the attribute names to the 
       specified output stream. 
       <synopsis>
	void PgDatabase::PrintTuples(FILE *out = 0, int printAttName = 1, 
	int terseOutput = 0, int width = 0) 
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>GetLine</function>
       <synopsis>
	int PgDatabase::GetLine(char* string, int length)
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>PutLine</function>
       <synopsis>
	void PgDatabase::PutLine(const char* string)
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>OidStatus</function>
       <synopsis>
	const char *PgDatabase::OidStatus()
       </synopsis>
      </para>
     </listitem>
     <listitem>
      <para>
       <function>EndCopy</function>
       <synopsis>
	int PgDatabase::EndCopy()
       </synopsis>
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </sect1>

  <sect1>
   <title>Asynchronous Notification</title>
    
   <para>
    <productname>Postgres</productname> supports asynchronous notification 
    via the <command>LISTEN</command> and <command>NOTIFY</command>
    commands.  A backend registers its interest in a particular semaphore
    with the <command>LISTEN</command> command.
    All backends that are listening on a
    particular named semaphore will be notified asynchronously when 
    a <command>NOTIFY</command> of
    that name is executed by another backend.   No additional
    information is passed from the notifier to the listener.  Thus,
    typically, any actual data that needs to be communicated is transferred
    through the relation.
    
    <note>
     <para>
      In the past, the documentation has associated the names used for asyncronous
      notification with relations or classes. However, there is in fact no
      direct linkage of the two concepts in the implementation, and the
      named semaphore in fact does not need to have a corresponding relation
      previously defined.
     </para>
    </note>
   </para>
   <para>
    <filename>libpq++</filename> applications are notified whenever a 
    connected backend has
    received an asynchronous notification.  However, the communication from
    the backend to the frontend is not asynchronous.  
    The <filename>libpq++</filename> application
    must poll the backend to see if there is any pending notification
    information.  After the execution of a query, a frontend may call 
    <function>PgDatabase::Notifies</function>
    to see if any notification data is currently available from the backend. 
    <function>PgDatabase::Notifies</function>
    returns the notification from a list of unhandled notifications from the
    backend. The function eturns NULL if there is no pending notifications from the
    backend.   
    <function>PgDatabase::Notifies</function>
    behaves like the popping of a stack.  Once a notification is returned
    from <function>PgDatabase::Notifies</function>,
    it is considered handled and will be removed from the list of
    notifications.
    
    <itemizedlist>
     <listitem>
      <para>
       <function>PgDatabase::Notifies</function>
       retrieves pending notifications from the server.
       
       <synopsis>
	PGnotify* PgDatabase::Notifies()
       </synopsis>
      </para>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    The second sample program gives an example of the use of asynchronous
    notification.
   </para>
  </sect1>

  <sect1>
   <title>Functions Associated with the COPY Command</title>
   
   <para>
    The <command>copy</command> command in <productname>Postgres</productname> 
    has options to read from or write to the network
    connection used by <filename>libpq++</filename>.  
    Therefore, functions are necessary to
    access this network connection directly so applications may take full
    advantage of this capability.
    
    <itemizedlist>
     <listitem>
      <para>
       <function>PgDatabase::GetLine</function>
       reads a newline-terminated line of characters (transmitted by the
       backend server) into a buffer 
       <replaceable class="parameter">string</replaceable>
       of size <replaceable class="parameter">length</replaceable>.
       <synopsis>
	int PgDatabase::GetLine(char* string, int length)
       </synopsis>
      </para>
      <para>
       Like the Unix system routine
       <function>fgets (3)</function>,
       this routine copies up to 
       <literal><replaceable class="parameter">length</replaceable>-1</literal>
       characters into 
       <replaceable class="parameter">string</replaceable>.
       It is like 
       <function>gets (3)</function>,
       however, in that it converts the terminating newline into a null
       character.
      </para>
      <para>
       <function>PgDatabase::GetLine</function>
       returns EOF at end of file, 0 if the entire line has been read, and 1 if the
       buffer is full but the terminating newline has not yet been read.
      </para>
      <para>
       Notice that the application must check to see if a new line consists
       of a single period ("."), which indicates that the backend
       server has finished sending the results of the 
       <command>copy</command>.
       Therefore, if the application ever expects to receive lines
       that are more than
       <literal><replaceable class="parameter">length</replaceable>-1</literal>
       characters long, the application must be sure to check the return
       value of <function>PgDatabase::GetLine</function> very carefully.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>PgDatabase::PutLine</function>
       Sends a null-terminated <replaceable class="parameter">string</replaceable>
       to the backend server.
       <synopsis>
	void PgDatabase::PutLine(char* string)
       </synopsis>
      </para>
      <para>
       The application must explicitly send a single period character (".")
       to indicate to the backend that it has finished sending its data.
      </para>
     </listitem>
     <listitem>
      <para>
       <function>PgDatabase::EndCopy</function>
       syncs with the backend.
       <synopsis>
	int PgDatabase::EndCopy()
       </synopsis>
       This function waits until the backend has
       finished processing the <command>copy</command>.
       It should either be issued when the
       last string has been sent to the backend using
       <function>PgDatabase::PutLine</function>
       or when the last string has been received from the backend using
       <function>PgDatabase::GetLine</function>.
       It must be issued or the backend may get <quote>out of sync</quote> with
       the frontend.  Upon return from this function, the backend is ready to
       receive the next query.
      </para>	    
      <para>
       The return value is 0 on successful completion, nonzero otherwise.
      </para>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    As an example:
    
    <programlisting>
	PgDatabase data;
	data.Exec("create table foo (a int4, b char16, d float8)");
	data.Exec("copy foo from stdin");
	data.putline("3\etHello World\et4.5\en");
	data.putline("4\etGoodbye World\et7.11\en");
	&amp;...
	data.putline(".\en");
	data.endcopy();
    </programlisting>
   </para>
  </sect1>

  <sect1>
   <title>Caveats</title>
    
   <para>
    The query buffer is 8192 bytes long, and queries over that length will
    be silently truncated.
   </para>
  </sect1>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->