home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / bcp_colfmt.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  9.0 KB  |  199 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89               bcp_colfmt
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  bcp_colfmt
  6.  
  7.   FUNCTION:
  8.        Specify the format of a host file for bulk copy purposes.
  9.  
  10.   SYNTAX:
  11.        RETCODE bcp_colfmt (dbproc, host_colnum, host_type,
  12.                            host_prefixlen, host_collen, host_term,
  13.                            host_termlen, table_colnum)
  14.  
  15.        DBPROCESS *dbproc;
  16.        int       host_colnum;
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   bcp_colfmt              Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.        int       host_type;
  27.        int       host_prefixlen;
  28.        DBINT     host_collen;
  29.        BYTE      *host_term;
  30.        int       host_termlen;
  31.        int       table_colnum;
  32.  
  33.   COMMENTS:
  34.  
  35.        o bcp_colfmt() allows you to specify the  host  file  format  for
  36.          bulk  copies.   For  bulk  copy purposes, a format contains the
  37.          following parts:
  38.             o A mapping from host file columns to database columns.
  39.  
  40.             o The datatype of each host file column.
  41.             o The length of the optional length prefix of each column.
  42.  
  43.             o The maximum length of the host file column's data.
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89               bcp_colfmt
  47.   ______________________________________________________________________
  48.  
  49.             o The optional terminating byte sequence for each column.
  50.             o The length of this optional terminating byte sequence.
  51.  
  52.        o Each call to bcp_colfmt() specifies the  format  for  one  host
  53.          file  column.  For  example,  if  you  have  a  table with five
  54.          columns, and want to change the default settings for  three  of
  55.          those  columns,  you  should first call bcp_columns(dbproc, 5),
  56.          and then call bcp_colfmt() five  times,  with  three  of  those
  57.          calls  setting  your  custom  format.   The remaining two calls
  58.          should have their host_type set to 0, and their host_prefixlen,
  59.          host_collen,  and host_termlen parameters set to -1. The result
  60.          of this would be to copy all five columns-three with your  cus-
  61.          tomized format and two with the default format.
  62.        o bcp_columns() must be called before any calls to bcp_colfmt().
  63.  
  64.        o You must call bcp_colfmt() for every column in the  host  file,
  65.          regardless  of  whether  some  of those columns use the default
  66.  
  67.  
  68.   bcp_colfmt              Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          format or are skipped.
  71.  
  72.        o To skip a column, set the table_column parameter to 0.
  73.        o For information on the bcp utility program, see its manual page
  74.          in the Commands Reference.
  75.  
  76.   PARAMETERS:
  77.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  78.            connection for a particular front-end/SQL Server process.  It
  79.            contains all the information that DB-Library uses  to  manage
  80.            communications and data between the front end and SQL Server.
  81.        host_colnum -  The column in the host file whose format is  being
  82.            specified.  The first column is number 1.
  83.        host_type -  The datatype  of  this  column  in  the  host  file,
  84.            expressed  as  a SQL Server datatype. If it is different from
  85.            the datatype of the  corresponding  column  in  the  database
  86.            table   (table_colnum),  the  conversion  will  be  performed
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89               bcp_colfmt
  91.   ______________________________________________________________________
  92.            automatically. See the dbconvert() manual page for a table of
  93.            allowable data conversions.  That manual page also contains a
  94.            list of SQL Server datatypes.
  95.  
  96.            If  you  want  to  specify  the  same  datatype  as  in   the
  97.            corresponding  column  of  the database table (table_colnum),
  98.            this parameter should be set to 0.
  99.        host_prefixlen -  The length of the length prefix for this column
  100.            in the host file. Legal prefix lengths are 1, 2, and 4 bytes.
  101.            To avoid using a length prefix, this parameter should be  set
  102.            to  0. To let bcp decide whether to use a length prefix, this
  103.            parameter should be set to -1.  In such a case, bcp will  use
  104.            a  length  prefix  (of  whatever  length is necessary) if the
  105.            database column length is variable.
  106.            If more than one means  of  specifying  a  host  file  column
  107.            length  is used (such as a length prefix and a maximum column
  108.            length, or a length prefix and a  terminator  sequence),  bcp
  109.  
  110.  
  111.  
  112.   bcp_colfmt              Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.            will look at all of them and use the one that results in  the
  115.            shortest amount of data being copied.
  116.  
  117.            One valuable use for  length  prefixes  is  to  simplify  the
  118.            specifying  of null data values in a host file. For instance,
  119.            assume you have a 1-byte length prefix for a  4-byte  integer
  120.            column.   Ordinarily,  the length prefix will contain a value
  121.            of 4, to indicate that a 4-byte value follows.   However,  if
  122.            the value of the column is null, the length prefix can be set
  123.            to 0, to indicate that 0 bytes follow for the column.
  124.        host_collen -  The maximum length of this column's  data  in  the
  125.            host  file,  not  including  the  length of any length prefix
  126.            and/or terminator. Setting host_collen to  0  signifies  that
  127.            the  data  is null.  Setting host_collen to -1 indicates that
  128.            the system should ignore this parameter (i.e.,  there  is  no
  129.            default maximum length).
  130.            For fixed-length datatypes, such as integers, the  length  of
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89               bcp_colfmt
  135.   ______________________________________________________________________
  136.            the data is constant, except for the  special  case  of  null
  137.            values.   Therefore,  for fixed-length datatypes, host_collen
  138.            must always be -1, except when the data  is  null,  in  which
  139.            case host_collen must be 0.
  140.  
  141.            For character, text, binary, and image data, host_collen  can
  142.            be  -1, 0, or some positive value.  If host_collen is -1, the
  143.            system will use  either  a  length  prefix  or  a  terminator
  144.            sequence  to  determine the length of the data.  (If both are
  145.            supplied, the system will use the one  that  results  in  the
  146.            shortest  amount  of data being copied.) If host_collen is -1
  147.            and neither a prefix length  nor  a  terminator  sequence  is
  148.            specified,  the  system  will  return  an  error message.  If
  149.            host_collen is 0, the system assumes the data  is  null.   If
  150.            host_collen   is   some   positive  value,  the  system  uses
  151.            host_collen as the maximum  data  length.   However,  if,  in
  152.            addition  to  a  positive host_collen, a prefix length and/or
  153.            terminator sequence is provided, the  system  determines  the
  154.  
  155.  
  156.   bcp_colfmt              Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.            data length by using the method that results in the  shortest
  159.            amount of data being copied.
  160.        host_term -  The terminator sequence to be used for this  column.
  161.            This  parameter is mainly useful for character, text, binary,
  162.            and image data types, because all other types  are  of  fixed
  163.            length.  To  avoid  using a terminator, set this parameter to
  164.            NULL.  To set the  terminator  to  the  NULL  character,  set
  165.            host_term to "\0".  To make the tab character the terminator,
  166.            set host_term to "\t".  To make  the  newline  character  the
  167.            terminator, set host_term to "\n".
  168.  
  169.            If more than one means  of  specifying  a  host  file  column
  170.            length  is used (such as a terminator and a length prefix, or
  171.            a terminator and a maximum column length), bcp will  look  at
  172.            all  of  them  and  use  the one that results in the shortest
  173.            amount of data being copied.
  174.        host_termlen -  The length, in bytes, of the terminator  sequence
  175.            to  be used for this column. To avoid using a terminator, set
  176.  
  177.  
  178.   9                       Version 4.0 -- 5/1/89               bcp_colfmt
  179.   ______________________________________________________________________
  180.            this value to -1.
  181.        table_colnum -  The corresponding column in the  database  table.
  182.            If this value is 0, this column will not be copied. The first
  183.            column is column 1.
  184.  
  185.   RETURNS:
  186.        SUCCEED or FAIL.
  187.  
  188.   SEE ALSO:
  189.        bcp_batch,   bcp_bind,   bcp_collen,   bcp_colptr,   bcp_columns,
  190.        bcp_control, bcp_done, bcp_exec, bcp_init, bcp_sendrow
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.