home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextLibrary / Documentation / Sybase / DBLIB / Section3 / bcp_init.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  3.7 KB  |  125 lines
  1. .Na "bcp_init"
  2. .mc |
  3. .Aa
  4. .Fu
  5. Initialize bulk copy.
  6. .Ih "bcp, initialize bulk copy"
  7. .Ih "bulk copy, initialize"
  8. .Ih "copy, bulk"
  9. .Sy
  10. .Sf "RETCODE bcp_init(dbproc, tblname, hfile, errfile, direction)"
  11. .Sp "DBPROCESS" "*dbproc"
  12. .Sp "char" "*tblname"
  13. .Sp "char" "*hfile"
  14. .Sp "char" "*errfile"
  15. .Sp "int" "direction"
  16. .Co
  17. .Bl
  18. \f2bcp_init()\f1 performs the necessary initializations for a bulk
  19. copy of data between the front-end and a \*S. It sets
  20. the default host file data formats and examines the structure
  21. of the database table.
  22. .Bl
  23. If a host file is being used (see the description of the \f2hfile\f1 parameter, below),
  24. .Ih "bcp, default data formats"
  25. the default data formats are as follows:
  26. .in +5n
  27. .Bl *
  28. The order, type, length and number of the columns in the
  29. host file are assumed to be identical to the order, type
  30. and number of the columns in the database table.
  31. .Bl *
  32. If a given database column's data is fixed-length, then
  33. the host file's data column will also be fixed-length.
  34. If a given database column's data is variable-length
  35. or may contain NULL values, the host file's data column
  36. will be prefixed by a 4-byte length value for SYBTEXT
  37. and SYBIMAGE data types, and a 1-byte length value for
  38. all other types.
  39. .Bl *
  40. There are no terminators of any kind between host file
  41. columns.
  42. .in -5n
  43. .sp 0.5v
  44. Any of these defaults can be overridden by calling \f2bcp_columns()\f1
  45. and \f2bcp_colfmt().\f1
  46. .Bl
  47. To use the bulk copy routines to copy data to a
  48. database table requires the following:
  49. .in +5n
  50. .Bl *
  51. The DBPROCESS structure must be usable for bulk copy
  52. purposes. This is accomplished by calling \f2BCP_SETL():\f1
  53. .SD
  54. .in +3n
  55. login = dblogin();
  56. BCP_SETL(login, TRUE);
  57. .in -3n
  58. .ED
  59. .Bl *
  60. If the table has no indexes, 
  61. the database option \f2select into/bulkcopy\f1 must be set to ``true''.
  62. The following SQL command will do this:
  63. .SD
  64. .in +3n
  65. sp_dboption 'mydb', 'select into/bulkcopy', 'true'
  66. .in -3n
  67. .ED
  68. See the \f2Commands Reference\f1 for further details on \f2sp_dboption\f1.
  69. .in -5n
  70. .Bl
  71. If no host file is being used, it's necessary to call \f2bcp_bind()\f1
  72. to specify the format and location in memory of each column's data value.
  73. .Bl
  74. \f2bcp_init()\f1 must be called before any other bulk copy
  75. functions. Failure to do so will result in an error.
  76. .Bl
  77. For information on the \f2bcp\f1 utility program, see its manual page
  78. in the \f2Commands Reference\f1.
  79. .Bz
  80. .Pa
  81. .Pi dbproc
  82. A pointer to the DBPROCESS structure that provides the connection
  83. for a particular front-end/\*S process.  It contains all the
  84. information that \*L uses to manage communications and data between the
  85. front end and \*S.
  86. .Pi tblname
  87. The name of the database table to be copied in or out.
  88. This name may also include the database name or the
  89. owner name. For example, "pubs.gracie.titles", "pubs..titles",
  90. "gracie.titles", and "titles" are all legal table names.
  91. .Pi hfile
  92. The name of the host file to be copied in or out.
  93. If no host file is involved (the situation when data is being
  94. copied directly from variables), \f2hfile\f1 should be NULL.
  95. .Pi errfile
  96. The name of the error file to be used. This error file
  97. will be filled with progress messages, error messages,
  98. and copies of any rows which, for any reason, could not
  99. be copied from a host file to a \*S table.
  100. If NULL is passed as \f2errfile\f1, no error file will be used.
  101. .Pi direction
  102. The direction of the copy. It must be one of two 
  103. values\(emDB_IN or DB_OUT. DB_IN indicates a copy from the host
  104. into the database table, while DB_OUT indicates a copy from the
  105. database table into the host file.
  106. .sp 0.5v
  107. It is illegal to request a bulk copy from the 
  108. database table (DB_OUT) without supplying a host file name.
  109. .in -.375i
  110. .Re
  111. .br
  112. SUCCEED or FAIL.
  113. .Sa
  114. bcp_batch,
  115. bcp_bind,
  116. bcp_colfmt,
  117. bcp_collen,
  118. bcp_colptr,
  119. bcp_columns,
  120. bcp_control,
  121. bcp_done,
  122. bcp_exec,
  123. bcp_sendrow
  124. .mc
  125.