Author: turnstep
Date: Wed Jul 22 18:48:05 2009
New Revision: 13105
Modified:
DBD-Pg/trunk/Pg.pm
Log:
Clean up COPY docs.
Modified: DBD-Pg/trunk/Pg.pm
==============================================================================
--- DBD-Pg/trunk/Pg.pm (original)
+++ DBD-Pg/trunk/Pg.pm Wed Jul 22 18:48:05 2009
@@ -4029,7 +4029,7 @@
=head2 COPY support
-DBD::Pg allows for the quick (bulk) reading and storing of data by using
+DBD::Pg allows for quick (bulk) reading and storing of data by using
the B<COPY> command. The basic process is to use C<$dbh-E<gt>do> to issue a
COPY command, and then to either add rows using L</pg_putcopydata>, or to
read them by using L</pg_getcopydata>.
@@ -4040,16 +4040,17 @@
$dbh->do("COPY foobar FROM STDIN");
-This would tell the server to enter a COPY IN state. It is now ready to
+This would tell the server to enter a COPY IN mode (yes, that's confusing, but
+the I<mode> is COPY IN because of the I<command> COPY FROM). It is now ready
to
receive information via the L</pg_putcopydata> method. The complete syntax of
the
COPY command is more complex and not documented here: the canonical
PostgreSQL documentation for COPY can be found at:
http://www.postgresql.org/docs/current/static/sql-copy.html
-Once the COPY command has been issued, no other SQL commands are allowed
-until L</pg_putcopyend> has been issued, or the final L</pg_getcopydata> has
-been called.
+Once a COPY command has been issued, no other SQL commands are allowed
+until L</pg_putcopyend> has been issued (for COPY FROM), or the final
+L</pg_getcopydata> has been called (for COPY TO).
Note: All other COPY methods (pg_putline, pg_getline, etc.) are now
heavily deprecated in favor of the pg_getcopydata, pg_putcopydata, and
@@ -4057,14 +4058,14 @@
=head3 B<pg_getcopydata>
-Used to retrieve data from a table after the server has been put into COPY OUT
-mode by calling "COPY tablename TO STDOUT". Data is always returned
+Used to retrieve data from a table after the server has been put into a
+COPY OUT mode by calling "COPY tablename TO STDOUT". Data is always returned
one data row at a time. The first argument to pg_getcopydata
is the variable into which the data will be stored (this variable should not
-be undefined, or it may throw a warning, although it may be a reference). This
-method returns a number greater than 1 indicating the new size of the
variable,
-or a -1 when the COPY has finished. Once a -1 has been returned, no other
action is
-necessary, as COPY mode will have already terminated. Example:
+be undefined, or it may throw a warning, although it may be a reference). The
+pg_gecopydata method returns a number greater than 1 indicating the new size
of
+the variable, or a -1 when the COPY has finished. Once a -1 has been returned,
no
+other action is necessary, as COPY mode will have already terminated. Example:
$dbh->do("COPY mytable TO STDOUT");
my @data;
@@ -4105,7 +4106,7 @@
When you are finished with pg_putcopydata, call pg_putcopyend to let the
server know
that you are done, and it will return to a normal, non-COPY state. Returns a 1
on
-success. This method will fail if called when not in a COPY IN or COPY OUT
state.
+success. This method will fail if called when not in COPY IN mode.
=head2 Large Objects
