home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dbconvert.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  11.2 KB  |  265 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                dbconvert
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbconvert
  6.  
  7.   FUNCTION:
  8.        Convert data from one datatype to another.
  9.  
  10.   SYNTAX:
  11.        DBINT dbconvert(dbproc, srctype, src, srclen, desttype, dest, destlen)
  12.  
  13.        DBPROCESS *dbproc;
  14.        int       srctype;
  15.        BYTE      *src;
  16.        DBINT     srclen;
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbconvert               Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.        int       desttype;
  27.        BYTE      *dest;
  28.        DBINT     destlen;
  29.  
  30.   COMMENTS:
  31.  
  32.        o This routine allows  the  program  to  convert  data  from  one
  33.          representation  to  another.  To determine whether a particular
  34.          conversion is permitted, the program can  call  dbwillconvert()
  35.          before attempting a conversion.
  36.        o dbconvert() can convert data stored in any  of  the  SQL Server
  37.          datatypes (although, of course, not all conversions are legal):
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                dbconvert
  47.   ______________________________________________________________________
  48.               SQL Server type          Program variable type
  49.  
  50.               SYBCHAR                  DBCHAR
  51.               SYBTEXT                  DBCHAR
  52.               SYBBINARY                DBBINARY
  53.               SYBIMAGE                 DBBINARY
  54.               SYBINT1                  DBTINYINT
  55.               SYBINT2                  DBSMALLINT
  56.               SYBINT4                  DBINT
  57.               SYBFLT8                  DBFLT8
  58.               SYBBIT                   DBBIT
  59.               SYBMONEY                 DBMONEY
  60.               SYBDATETIME              DBDATETIME
  61.  
  62.        o The table below lists the datatype conversions that dbconvert()
  63.          supports.   The  source  datatypes are listed down the leftmost
  64.          column and the destination datatypes are listed along  the  top
  65.          row  of  the  table.   (For  brevity, the prefix "SYB" has been
  66.  
  67.  
  68.   dbconvert               Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          eliminated from each datatype.) T  (TRUE)  indicates  that  the
  71.          conversion  is  supported; F (FALSE) indicates that the conver-
  72.          sion is not supported.
  73.  
  74.             FROM:            TO:                 BIN-                                                                            DATE-
  75.             CHAR             CHATR      TEXTT      ARYT       IMATGE     INTT1      INTT2      INTT4      FLTT8      BITT    MONEYT        TIMTE
  76.             TBEIXNTARY             TT         TT         TT         TT         TT         TT         TT         TT        TT         TT          TF
  77.             IIMNATG1E              TT         TT         TT         TT         TT         TT         TT         TT        TT         TT          FF
  78.             IINNTT24               TT         TT         TT         TT         TT         TT         TT         TT        TT         TT          FF
  79.             FBLITT8               TT         TT         TT         TT         TT         TT         TT         TT        TT         TF          FF
  80.             MDOANTEEYTIME           TT         TT         TT         TT         TF         TF         TF         TF        TF         TF          FT
  81.  
  82.        o A conversion to or from the datatypes SYBBINARY and SYBIMAGE is
  83.          a  straight  bit-copy, except when the conversion involves SYB-
  84.          CHAR or SYBTEXT.  When converting SYBCHAR or  SYBTEXT  data  to
  85.          SYBBINARY  or  SYBIMAGE,  dbconvert() interprets the SYBCHAR or
  86.          SYBTEXT string  as  hexadecimal,  whether  or  not  the  string
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                dbconvert
  91.   ______________________________________________________________________
  92.          contains a leading "0x".  When converting SYBBINARY or SYBIMAGE
  93.          data  to  SYBCHAR or SYBTEXT, dbconvert() creates a hexadecimal
  94.          string without a leading "0x".
  95.  
  96.        o Converting a SYBMONEY, SYBCHAR, or SYBTEXT value to SYBFLT8 may
  97.          result  in  some loss of precision.  Converting a SYBFLT8 value
  98.          to SYBCHAR or SYBTEXT may also result in some  loss  of  preci-
  99.          sion.
  100.        o Converting a SYBFLT8 value to SYBMONEY can result in  overflow,
  101.          because     the     maximum     value     for    SYBMONEY    is
  102.          $922,337,203,685,477.58.
  103.  
  104.        o If overflow occurs when converting integer  or  float  data  to
  105.          SYBCHAR  or SYBTEXT, the first character of the resulting value
  106.          will contain an asterisk ("*") to indicate the error.
  107.        o A conversion to SYBBIT has the following effect: If  the  value
  108.          being converted is not 0, the SYBBIT value will be set to 1; if
  109.  
  110.  
  111.  
  112.   dbconvert               Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.          the value is 0, the SYBBIT value will be set to 0.
  115.  
  116.        o In certain cases, it can be useful to  convert  a  datatype  to
  117.          itself.   For instance, a conversion of SYBCHAR to SYBCHAR with
  118.          a destlen of -1 serves as a useful way to append a null  termi-
  119.          nator to a string, as the example below illustrates.
  120.        o Here's  a  short  example  that  illustrates  how  to   convert
  121.          SQL Server data obtained with dbdata():
  122.  
  123.          DBCHAR        title[81];
  124.          DBCHAR        price[9];
  125.  
  126.          /* read the query into the command buffer */
  127.          dbcmd(dbproc, "select title, price, royalty from pubs..titles");
  128.  
  129.          /* send the query to SQL Server */
  130.          dbsqlexec(dbproc);
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89                dbconvert
  135.   ______________________________________________________________________
  136.  
  137.          /* get ready to process the results of the query */
  138.          dbresults(dbproc);
  139.  
  140.          /* process each row */
  141.          while (dbnextrow(dbproc) != NO_MORE_ROWS)
  142.          {
  143.              /* the first dbconvert() adds a null terminator to the string */
  144.              dbconvert(dbproc, SYBCHAR, (dbdata(dbproc,1)), (dbdatlen(dbproc,1)),
  145.                  SYBCHAR, title, (DBINT)-1);
  146.              /* the second dbconvert() converts money to string */
  147.              dbconvert(dbproc, SYBMONEY, (dbdata(dbproc,2)), (DBINT)-1, SYBCHAR, price, (DBINT)-1);
  148.  
  149.              if (dbdatlen(dbproc,3) != 0)
  150.                  printf ("%s\n $%s  %ld\n", title, price, *((DBINT *)dbdata(dbproc,3)));
  151.          }
  152.  
  153.  
  154.  
  155.  
  156.   dbconvert               Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.          In the dbconvert() calls it  was  not  necessary  to  cast  the
  159.          returns   from   dbdata(),  because  dbdata()  returns  a  BYTE
  160.          pointer-precisely the datatype dbconvert() expects in the third
  161.          parameter.
  162.  
  163.        o If you're binding data to variables with dbbind()  rather  than
  164.          accessing the data directly with dbdata(), dbbind() can perform
  165.          the conversions itself, making dbconvert() unnecessary.
  166.        o Example 5 in the DB-Library  Reference  Supplement  illustrates
  167.          several more types of conversions using dbconvert().
  168.  
  169.        o For more information on SQL Server datatypes, see the  Commands
  170.          Reference and the types manual page in this document.
  171.  
  172.   PARAMETERS:
  173.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  174.            connection for a particular front-end/SQL Server process.  It
  175.            contains all the information that DB-Library uses  to  manage
  176.  
  177.  
  178.   9                       Version 4.0 -- 5/1/89                dbconvert
  179.   ______________________________________________________________________
  180.            communications and data between the front end and SQL Server.
  181.            In dbconvert(), the DBPROCESS is used only to supply any cus-
  182.            tom null values that  the  program  may  have  specified  via
  183.            dbsetnull().  If dbproc is NULL, dbconvert() uses the default
  184.            values for null value data conversions.
  185.        srctype -  The datatype of the data which  is  to  be  converted.
  186.            This  parameter  can  be  any of the SQL Server datatypes, as
  187.            listed in the first table above.
  188.        src -  A pointer to the data which is to be converted.   If  this
  189.            pointer  is  NULL, dbconvert() will place an appropriate null
  190.            value in the destination variable.  You can use  dbdata()  to
  191.            get the SQL Server data.
  192.        srclen -  The length, in bytes, of the data to be converted.   If
  193.            the  srclen  is  0, the source data is assumed to be null and
  194.            dbconvert() will place an appropriate null value in the  des-
  195.            tination variable.  Otherwise, this length is ignored for all
  196.            datatypes except character, text,  binary,  and  image.   For
  197.  
  198.  
  199.  
  200.   dbconvert               Version 4.0 -- 5/1/89                       10
  201.   ______________________________________________________________________
  202.            SYBCHAR data, a length of -1 indicates  that  the  string  is
  203.            null-terminated.  You can use dbdatlen() to get the length of
  204.            SQL Server data.
  205.        desttype -  The datatype that the source data is to be  converted
  206.            into.  This parameter can be any of the SQL Server datatypes,
  207.            as listed in the first table above.
  208.        dest -  A pointer to the destination variable that  will  receive
  209.            the  converted  data.   If  this pointer is NULL, dbconvert()
  210.            will call the user-supplied error handler (if any) and return
  211.            FAIL.
  212.        destlen -  The length, in bytes,  of  the  destination  variable.
  213.            destlen is ignored for fixed-length datatypes.  For a SYBCHAR
  214.            destination, the value of destlen must be the total length of
  215.            the  destination  buffer space.  A length of -1 for a SYBCHAR
  216.            or SYBBINARY destination means that there is sufficient space
  217.            available.   In  addition, for a SYBCHAR destination a length
  218.            of  -1  will  cause  the  character  string  to  be  given  a
  219.  
  220.  
  221.  
  222.   11                      Version 4.0 -- 5/1/89                dbconvert
  223.   ______________________________________________________________________
  224.            terminating null.
  225.  
  226.   RETURNS:
  227.        The length of the converted  data,  in  bytes,  if  the  datatype
  228.        conversion   succeeds.   If  the  conversion  fails,  dbconvert()
  229.        returns -1.  If dbconvert() fails, it will  first  call  a  user-
  230.        supplied  error  handler  (if  any) and set the global DB-Library
  231.        error value.
  232.  
  233.        This routine may fail for several reasons: the requested  conver-
  234.        sion  was  not  available; the conversion resulted in truncation,
  235.        overflow, or loss of precision in the destination variable; or  a
  236.        syntax  error  occurred  in converting a character string to some
  237.        numeric type.
  238.  
  239.   SEE ALSO:
  240.        dbaltbind, dbbind, dberrhandle, dbsetnull, dbwillconvert, errors,
  241.  
  242.  
  243.  
  244.   dbconvert               Version 4.0 -- 5/1/89                       12
  245.   ______________________________________________________________________
  246.        types
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.