head	1.13;
access;
symbols;
locks; strict;
comment	@# @;


1.13
date	92.07.14.05.54.17;	author ptong;	state Exp;
branches;
next	1.12;

1.12
date	92.07.13.03.45.59;	author ptong;	state Exp;
branches;
next	1.11;

1.11
date	91.08.16.01.55.21;	author kemnitz;	state Exp;
branches;
next	1.10;

1.10
date	91.08.13.21.39.10;	author kemnitz;	state Exp;
branches;
next	1.9;

1.9
date	91.03.26.18.47.57;	author kemnitz;	state Exp;
branches;
next	1.8;

1.8
date	91.03.09.05.35.39;	author kemnitz;	state Exp;
branches;
next	1.7;

1.7
date	91.03.08.02.54.12;	author kemnitz;	state Exp;
branches;
next	1.6;

1.6
date	91.03.08.01.05.13;	author kemnitz;	state Exp;
branches;
next	1.5;

1.5
date	91.02.25.09.54.29;	author mike;	state Exp;
branches;
next	1.4;

1.4
date	90.07.20.09.48.54;	author claire;	state Exp;
branches;
next	1.3;

1.3
date	90.07.19.16.59.39;	author keongwoo;	state Exp;
branches;
next	1.2;

1.2
date	90.07.19.16.45.30;	author keongwoo;	state Exp;
branches;
next	1.1;

1.1
date	90.07.18.16.21.53;	author mao;	state Exp;
branches;
next	;


desc
@man page for the copy postquel command
@


1.13
log
@reformated
@
text
@.\" XXX standard disclaimer belongs here....
.\" $Header: /home/postgres/mer/refs/postquel/RCS/copy,v 1.12 1992/07/13 03:45:59 ptong Exp ptong $
.SP COPY COMMANDS 6/14/90
.XA 2 Copy
.uh NAME
.lp
copy \*- copy data to or from a class from or to a \*(UU file.
.uh SYNOPSIS
.lp
.(l
\fBcopy\fR [\fBbinary\fR] classname direction ( "filename" | \fBstdin\fR | \fBstdout\fR )
.)l
.uh DESCRIPTION
.lp
.b Copy
moves data between \*(PP classes and standard \*(UU files.
The keyword
.b binary
change the behavior of field formatting,
as described below.
.i Classname
is the name of an existing class.
.i Direction
is either 
.b to
or 
.b from .
.i Filename
is the \*(UU pathname of the file.  In place of a filename, stdin and stdout
can be used so that input to
.b copy
can be written by a LIBPQ application and 
output from the
.b copy
command can be read by a LIBPQ application.
The 
.b binary
keyword will force all data to be stored/read as binary objects rather than
as ASCII text.  It is somewhat faster than the normal
.b copy
command, but is not generally portable, and the files generated are somewhat
larger, although this factor is highly dependent on the data itself.
.uh FORMAT OF OUTPUT FILES
.lp
When
.b copy
is used without the
.b binary
keyword, the file generated will have each instance on a line, with each
attribute separated by tabs (\t).  Embedded tabs will be preceeded by a
backslash character (\\).  The attribute values themselves are strings generated
by the output function associated with each attribute type.  The output
function for a type should not try to generate the backslash character - this
will be handled by 
.b copy
itself.
.lp
Note that on input to 
.b copy
backslashes are considered to be special control characters, and should be
doubled if you want to embed a backslash, ie, the string "12\\19\\88" will be
converted by
.b copy
to "12\19\88".  The actual format for each instance is
.lp
<attr1><tab><attr2><tab>...<tab><attrn><newline>
.lp
If 
.b copy
is sending its output to standard output instead of a file, it will send a
period (.) followed immediately by a newline, on a line by themselves, when
it is done.  Similarly, if
.b copy
is reading from standard input, it will expect a period (.) followed by a
newline, as the first two characters on a line, to denote end-of-file.
However,
.b copy
will terminate (followed by the backend itself) if a true EOF is encountered.
.lp
.b NULL
attributes are handled simply as null strings, that is, consecutive tabs in
the input file denote a 
.b NULL
attribute.
.lp
In the case of
.b copy
.b binary,
the first four bytes in the file will be the number of instances in the file.
If this number is
.i zero,
the
.b copy
.b binary
command will read until end of file is encountered.  Otherwise, it will
.i stop
reading when this number of instances has been read.  Remaining data in the
file will be ignored.
.lp
The format for each instance in the file is as follows.  Note that this format
must be followed
.i EXACTLY.
Unsigned four byte integer quantities are called uint32 in the below
description.
.lp
uint32 totallength (not including itself),
.lp
uint32 number of null attributes
.lp
[uint32 attribute number of first null attribute
.lp
...
.lp
uint32 attribute number of nth null attribute],
.lp
<data>
.lp
.i "Alignment of binary data"
.lp
On Sun 3's, 2 byte attributes are aligned on two-byte boundaries, and all
larger attributes are aligned on four-byte boundaries.  Character attributes
are aligned on single-byte boundaries.  On other machines, all attributes
larger than 1 byte are aligned on four-byte boundaries.  Note that variable
length attributes are preceeded by the attribute's length; arrays are simply
contiguous streams of the array element type.
.lp
.uh "SEE ALSO"
.lp
append(commands), create(commands), vacuum(commands), libpq.
.uh BUGS
.lp
.A Files 
used as arguments to the
.b copy
command must reside on or be accessable to the
the database server machine by being either on local disks or a networked
file system.
.lp
.b Copy
stops operation at the first error.
This should not lead to problems
in the event of a
.b copy
.b from,
but the target relation will, of course, be partially modified
in a
.b copy 
.b to.
The ``vacuum'' query should be used to clean up after a
failed copy.
.lp
Because \*(PP operates out of a different directory 
than the user's working directory at the time \*(PP is invoked,
the result of copying to a file 
.q "foo"
(without additional path information)
may yield unexpected results for the naive user.
The full pathname should be used when specifying files to be copied.
.lp
.b Copy
has virtually no error checking, and a malformed input file will likely cause
the backend to crash.  Humans should avoid using copy for input whenever
possible.
@


1.12
log
@Fixed up formating
@
text
@d2 1
a2 1
.\" $Header: /home/postgres/mer/refs/postquel/RCS/copy,v 1.11 1991/08/16 01:55:21 kemnitz Exp ptong $
d11 1
a11 1
\fBcopy\fR [\fBbinary\fR] classname direction { "filename" | stdin | stdout }
d129 1
a129 4
append(postquel),
create(postquel),
vacuum(postquel),
libpq(commands).
@


1.11
log
@made various fixes - added Mike's stuff.
@
text
@d2 1
a2 1
.\" $Header: RCS/copy,v 1.10 91/08/13 21:39:10 kemnitz Exp Locker: kemnitz $
d10 3
a12 5
.b copy
[
.b binary
] classname
direction "filename" | stdin | stdout
d51 1
a51 1
backslash character (\).  The attribute values themselves are strings generated
@


1.10
log
@cleaned up some of the remarks.
@
text
@d2 1
a2 1
.\" $Header: RCS/copy,v 1.9 91/03/26 18:47:57 kemnitz Exp Locker: kemnitz $
d89 2
a90 1
.b copy binary,
d95 2
a96 1
.b copy binary
d133 1
d148 2
a149 1
copy \fBfrom\fR,
d152 3
a154 1
.b copy \fBto\fR.  The ``vacuum'' query can be used to clean up after a
@


1.9
log
@Added discussion about number of instances being at the head of the
file.
@
text
@d2 1
a2 1
.\" $Header: RCS/copy,v 1.8 91/03/09 05:35:39 kemnitz Exp Locker: kemnitz $
a13 2
.b (
.b )
d73 2
a74 2
period (.) followed immediately by a newline (\n), on a line by themselves,
when it is done.  Similarly, if
d77 1
a77 1
newline (\n), as the first two characters on a line, to denote end-of-file.
d99 1
a99 1
.pp
d107 1
d109 1
d111 1
d113 1
d115 1
d118 2
a119 1
.i Alignment of binary data
d135 5
a139 1
used as arguments to the copy command must reside on the database server.
d148 2
a149 1
.b copy \fBto\fR.
d159 1
a159 1
b Copy
d161 2
a162 1
the backend to crash.
@


1.8
log
@Fixed a couple of little things.
@
text
@d2 1
a2 1
.\" $Header: RCS/copy,v 1.7 91/03/08 02:54:12 kemnitz Exp Locker: kemnitz $
d92 15
a106 2
the instance format is as follows.  Unsigned four byte integer quantities are
called uint32 in the below description.
a121 3
.lp
While it is possible to send and receive binary data through standard input
and output, it is not recommended.
@


1.7
log
@Added discussion about copy file formats.
@
text
@d2 1
a2 1
.\" $Header: RCS/copy,v 1.6 91/03/08 01:05:13 kemnitz Exp Locker: kemnitz $
d36 1
a36 1
can be written by an application and 
d39 1
a39 1
command can be read by an application.
d82 1
a82 1
will do the right thing if a true EOF is encountered.
d115 3
a117 3
append(commands),
create(commands),
introduction(commands).
@


1.6
log
@Agrees with new syntax
@
text
@d2 1
a2 1
.\" $Header: RCS/copy,v 1.5 91/02/25 09:54:29 mike Exp Locker: kemnitz $
d26 1
a26 1
is the name of an existing relation.
d38 1
a38 1
.b copy 
d47 66
d123 1
a123 1
Copy
d130 1
a130 1
copy \fBto\fR.
d139 4
@


1.5
log
@objectified
@
text
@d2 1
a2 1
.\" $Header: RCS/copy,v 1.4 90/07/20 09:48:54 claire Exp Locker: mike $
d13 1
a13 3
[
.b nonulls
] ] classname
a14 1
copy-specification
d16 1
a16 4
direction filename [
.b using
map_classname
]
d21 1
a21 1
The keywords
a22 2
and
.b nonulls
a26 26
.i Copy-specification
looks like:
.(l
[{domain-format} { ,domain-format}]
.)l
where \fIdomain-format\fR is either
.(l
domname [ = domtype] [delim]
or string-constant.
.)l
In the first case,
.i domname
identifies a domain
(usually an attribute in
.i classname ,
but possibly a dummy),
.i domtype
indicates the format the \*(UU file
should have for the corresponding domain,
and
.i delim
is a character which delimits the domain.
Note that,
as specified below,
.i delim
can only be specified for dummy fields or fields of type \fBtext\fR.
d33 2
a34 41
is the \*(UU pathname of the file.
Map_classname
is the name of a class to which
.A OID
mapping information
will be appended.
.sp
On a
copy 
.b from
a \*(UU file to a class,
the class cannot have a secondary index and
it must be owned by the owner running the command,
or the owner cannot have used the rule system to restrict
your access to the class.
If the class is a system catalog,
you must have the catalog update privilege.
.sp
For a
copy 
.b to
a \*(UU file from a class,
you must either be the owner of the class,
or the owner must not have restricted your access to the class.
If the file already existed, it is truncated to zero 
length before copying begins.
.\"
.\" XXX  No views yet
.\"
.\" .it Copy 
.\" cannot be performed on a view.
.\"
.uh "DOMAIN FORMATS"
.lp
The domains should be ordered according to
the way they should appear in the \*(UU file.
Domains are matched according to name,
so the order of the fields in the \*(UU file need not be the
same as the order of the fields in the source/target class.
.sp
There are four types of objects in \*(UU files which 
d36 4
a39 22
can work with:
internal form fields (stored as binary objects),
external form fields (stored as text strings),
dummy domains,
and 
strings.
.sp
If 
.i domtype
is not specified for a field,
then is is assumed to be of type \fItext\fR.
Text objects are stored as delimited,
variable-length character strings.
The default field delimiter is \fItab\fR for all fields but the last,
for which the default delimiter is \fInewline\fR.
A field which is not of type text but
is to be stored in a \*(UU file as such is converted
to its external form before being written to the file.
(The same is true of character arrays,
but delimiters are used solely as separators
and the fields are truncated or space-padded as necessary
to make them the appropriate length.)
d42 2
a43 57
keyword will force all text and character array domains
to be stored/read as binary objects rather than
external-form objects.
.sp
If 
.i domtype
is not a character type,
then the attribute is stored in a binary format.
Binary objects may take one of two forms.
If
.b nonulls
is specified,
then the internal representation of the attribute value is simply
written to disk.
This is the same binary format as used in \*(II.
Otherwise,
a somewhat more complicated, 
\*(PP-specific scheme is used.
In general,
.b binary
is the most compact data representation.
.sp
Dummy domains are any domain for which
\fIdomname\fR
is not an attribute in 
\fIclassname.\fR
They can only be used with copy
.b from 
in which case they indicate that a field in a format consistent
with
.it
domtype
should be skipped.
Typically,
dummy domains will be of the form
.(l
dummy1 = char[45]
dummy2 = text
.)l
.in 0
.in .5i
.fi
String domains are only usable with copy \fBto\fR and may not have delimiters.
They are simply written to disk per-instance in the place specified.
.sp
In a copy \fBfrom\fR,
domains in the \*(PP class which are not
assigned values from the \*(UU file will be
set to 
null.
.sp
If no domains appear in the copy command, e.g.,
.(l
copy classnname ( ) to/from filename
.)l
.fi
then
d45 2
a46 92
automatically does a 
.q "bulk"
copy of all domains,
using the order of the domains in the relation.
By default,
attributes are copied as text with the default text delimiters.
If the optional
.b binary
keyword is specified,
then the attributes are bulk-copied as binary objects.
This is provided as a convenient shorthand
notation for copying and restoring entire relations.
.uh "EXAMPLES"
.lp
/* Define the emp class */
   create emp (name=char16,sal=float4,bdate=int2,mgr=text) 
.sp
/* Copy mixed-format data into the emp class */
   copy emp (name=char16,sal=float4,bdate=int2,mgr=text) 
     from \*(lq/usr2/me/myfile\*(rq
.sp
/* Copy employee names and salaries into a text file */
   copy emp (name=char16, sal=text) to \*(lqyourfile\*(rq
.sp
/* Copy employee names and managers into a binary file */
   copy binary emp (name=char16, mgr=text) to \*(lq../theirfile\*(rq
.sp
/* Bulk copy the emp class into a text file */
   copy emp ( ) to \*(lq~/ours/ourfile\*(rq
.sp
/* Bulk copy the emp class from a binary file */
   copy binary emp ( ) from \*(lq~thy/thyfile\*(rq
.uh "OID MAPPING"
.lp
Specifying a
map_relname
will cause 
.b copy
to append
.A OID
mapping data to that class.
If it does not exist,
it will be created as if the following command had been executed:
.(l
create map-classname ( old=OID, new=OID )
.)l
.in 0
.fi
.in .5i
As an example of the use of this facility,
consider a class which has circular data dependencies in its
attributes:
.(l
people1 (name=char16, parent=OID, child=OID)
.)l
.in .5i
.fi
If this class were simply copied into a new class,
say people2,
the
.A OID
attributes of people2 would still contain values which
represented instances in people1.
.in 0
.in .5i
The commands
.(l
copy people1 (name=char16, parent=OID, child=OID)
	to hodedo using whoof
copy people2 (name=char16, parent=OID, child=OID)
	from hodedo using whoof
.)l
would correctly fill class 
.q "whoof"
with the appropriate
.A OID
values.
Specifically, the first copy will fill in the old
.A OID s
in whoof,
while the second will insert the new
.A OID s.
Running the queries
.(l
replace people2 (parent=whoof.new) where
	whoof.old=people2.parent
replace people2 (child=whoof.new) where
	whoof.old=people2.child
.)l
.in 0
.in .5i
would then change the fields appropriately.
d54 2
a55 2
.A OID
mapping does not work in Version 2.1.
d72 1
a72 3
That is, 
the file may not end up in the intended directory if
the full pathname is not specified during the copy process.
@


1.4
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" $Header: RCS/copy,v 1.3 90/07/19 16:59:39 keongwoo Exp Locker: claire $
d7 1
a7 1
copy \*- copy data to or from a relation from or to a \*(UU file.
d15 1
a15 1
] ] relname
d21 1
a21 1
map_relname
d26 1
a26 1
moves data between \*(PP relations and standard \*(UU files.
d33 1
a33 1
.i Relname
d49 1
a49 1
.i relname ,
d68 2
a69 2
Map_relationname
is the name of a relation to which
d77 2
a78 2
a \*(UU file to a relation,
the relation cannot have a secondary index and
d81 2
a82 2
your access to the relation.
If the relation is a system catalog,
d88 3
a90 3
a \*(UU file from a relation,
you must either be the owner of the relation,
or the owner must not have restricted your access to the relation.
d105 1
a105 1
same as the order of the fields in the source/target relation.
d158 1
a158 1
\fIrelname.\fR
d176 1
a176 1
They are simply written to disk per-tuple in the place specified.
d179 1
a179 1
domains in the \*(PP relation which are not
d186 1
a186 1
copy relationname ( ) to/from filename
d205 1
a205 1
/* Define the emp relation */
d208 1
a208 1
/* Copy mixed-format data into the emp relation */
d218 1
a218 1
/* Bulk copy the emp relation into a text file */
d221 1
a221 1
/* Bulk copy the emp relation from a binary file */
d231 1
a231 1
mapping data to that relation.
d235 1
a235 1
create map-relationname ( old=OID, new=OID )
d241 1
a241 1
consider a relation which has circular data dependencies in its
d248 1
a248 1
If this relation were simply copied into a new relation,
d253 1
a253 1
represented tuples in people1.
d263 1
a263 1
would correctly fill relation 
d291 1
a291 1
mapping does not work in Version 2.
@


1.3
log
@a lot of changes on font type
@
text
@d2 1
a2 1
.\" $Header: RCS/copy,v 1.2 90/07/19 16:45:30 keongwoo Exp Locker: keongwoo $
@


1.2
log
@made copy from italic to bold
@
text
@d2 1
a2 1
.\" $Header: RCS/copy,v 1.1 90/07/18 16:21:53 mao Exp Locker: keongwoo $
d159 2
a160 2
They can only be used with
\fIcopy from,\fR
d190 1
a190 1
copy
d228 1
a228 1
copy
d287 1
a287 1
introduction(postquel).
@


1.1
log
@Initial revision
@
text
@d2 1
a2 1
.\" $Header: copy,v 1.8 89/03/28 15:18:47 wensel Exp $
d108 1
a108 1
.i copy
@