COPY(QUEL) 1/19/79 COPY(QUEL) NAME copy - copy data into/from a relation from/into a UNIX file. SYNOPSIS copy relname (domname = format {, domname = format }) direction "filename" DESCRIPTION Copy moves data between INGRES relations and standard UNIX files. Relname is the name of an existing relation. In general domname identifies a domain in relname. Format indicates the format the UNIX file should have for the corresponding domain. Direction is either into or from. Filename is the full UNIX pathname of the file. On a copy from a file to a relation, the relation cannot have a secondary index, it must be owned by you, and it must be updatable (not a secondary index or system relation). Copy cannot be used on a relation which is a view. For a copy into a UNIX file, you must either be the owner of the relation or the relation must have retrieve permission for all users, or all permissions for all users. The formats allowed by copy are: i1,i2,i4 - The data is stored as an integer of length 1, 2, or 4 bytes in the UNIX file. f4,f8 - The data is stored as a floating point number (either single or double precision) in the UNIX file. c1,c2,...,c255 - The data is stored as a fixed length string of characters. c0 - Variable length character string. d0,d1,...,d255 - Dummy domain. Corresponding domains in the relation and the UNIX file do not have to be the same type or length. Copy will convert as necessary. When converting anything except character to character, copy checks for overflow. When converting from character to character, copy will blank pad or truncate on the right as necessary. The domains should be ordered according to the way they should appear in the UNIX file. Domains are matched according to name, thus the order of the domains in the relation and in the UNIX file does not have to be the same. - 1 - COPY(QUEL) 1/19/79 COPY(QUEL) Copy also provides for variable length strings and dummy domains. The action taken depends on whether it is a copy into or a copy from. Delimitors for variable length strings and for dummy domains can be selected from the list of: nl - new line character tab - tab character sp - space nul or null - null character comma - comma colon - colon dash - dash lparen - left parenthesis rparen - right parenthesis x - any single character 'x' The special meaning of any delimitor can be turned off by preceeding the delimitor with a `\'. The type specifier can optionally be in quotes ("c0delim"). This is usefully if you wish to use a single character delimitor which has special meaning to the QUEL parser. When the direction is from, copy appends data into the relation from the UNIX file. Domains in the INGRES relation which are not assigned values from the UNIX file are assigned the default value of zero for numeric domains, and blank for character domains. When copying in this direction the following special meanings apply: c0delim - The data in the UNIX file is a variable length character string terminated by the delimitor delim. If delim is missing then the first comma, tab, or newline encountered will terminate the string. The delimitor is not copied. For example: pnum=c0 - string ending in comma, tab, or nl. pnum=c0nl - string ending in nl. pnum=c0sp - string ending in space. pnum=c0z - string ending in the character `z'. pnum="c0%" - string ending in the character `%'. A delimitor can be escaped by preceeding it with a `\'. For example, using name = c0, the string ``Blow\, Joe,'' will be accepted into the domain as ``Blow, Joe''. d0delim - The data in the UNIX file is a variable length character string delimited by delim. The string is read and discarded. The delimitor rules are identical for c0 and d0. The domain name is ignored. - 2 - COPY(QUEL) 1/19/79 COPY(QUEL) d1,d2,...,d255 - The data in the UNIX file is a fixed length character string. The string is read and discarded. The domain name is ignored. When the direction is into, copy transfers data into the UNIX file from the relation. If the file already existed, it is truncated to zero length before copying begins. When copying in this direction, the following special meanings apply: c0 - The domain value is converted to a fixed length character string and writted into the UNIX file. For character domains, the length will be the same as the domain length. For numeric domains, the standard INGRES conversions will take place as specified by the `-i', `-f', and `-c' flags (see ingres(unix)). c0delim - The domain will be converted according to the rules for c0 above. The one character delimitor will be inserted immediately after the domain. d1,d2,...,d255 - The domain name is taken to be the name of the delimitor. It is written into the UNIX file 1 time for d1, 2 times for d2, etc. d0 - This format is ignored on a copy into. d0delim - The delim is written into the file. The domain name is ignored. If no domains appear in the copy command (i.e. copy relname () into/from "filename") then copy automatically does a ``bulk'' copy of all domains, using the order and format of the domains in the relation. This is provided as a convenient shorthand notation for copying and restoring entire relations. To copy into a relation, you must be the owner or all users must have all permissions set. Correspondingly, to copy from a relation you must own the relation or all users must have at least retrieve permission on the relation. Also, you may not copy a view. EXAMPLE /* Copy data into the emp relation */ copy emp (name=c10,sal=f4,bdate=i2,mgr=c10,xxx=d1) from "/mnt/me/myfile" - 3 - COPY(QUEL) 1/19/79 COPY(QUEL) /* Copy employee names and their salaries into a file */ copy emp (name=c0,comma=d1,sal=c0,nl=d1) into "/mnt/you/yourfile" /* Bulk copy employee relation into file */ copy emp () into "/mnt/ours/ourfile" /* Bulk copy employee relation from file */ copy emp () from "/mnt/thy/thyfile" SEE ALSO append(quel), create(quel), quel(quel), permit(quel), view(quel), ingres(unix) BUGS Copy stops operation at the first error. When specifying filename, the entire UNIX directory pathname must be provided, since INGRES operates out of a different directory than the user's working directory at the time INGRES is invoked. - 4 -