Alternatives

# HG changeset patch # User Mark Brand # Date 1297931190 -3600 # Node ID 727f84d128a17e76ea57ae3d2fb962dcbcc4b4cd # Parent a617b89f069685bfff7545ba77189f963cf02b75 upgrade package freetds to cvs diff -r a617b89f0696 -r 727f84d128a1 src/freetds-1-fastforward.patch --- a/src/freetds-1-fastforward.patch Mon Feb 14 17:10:13 2011 +0100 +++ b/src/freetds-1-fastforward.patch Thu Feb 17 09:26:30 2011 +0100 @@ -166168,7 +166168,7 @@ Alternatives -@@ -243,3291 +220,3204 @@ You may be wondering how these libraries fit with Perl, PHP, TCL, Python, or oth +@@ -243,4721 +220,4947 @@ You may be wondering how these libraries fit with Perl, PHP, TCL, Python, or oth Sybase OpenClient @@ -166509,22 +166509,66 @@ - - +- <command>Make</> +- +-Now you're ready to build. Follow these easy steps. +- +- +- Download the tarball and unpack it. +- Alternatively, get the latest build from CVS +- +- +-CVS users will need the GNU autotools: Autoconf, Automake, and libtool. +- +- +-. +- +- Change to the freetds directory. +- +- run ./configure with any options you need. +- +- make; make install; make clean +- +- +- +-You normally need to be root to make install, unless you used the +- +-With any luck, you've built and installed the &freetds; libraries. +- +- +- +- +- +- OS-specific Issues +- +- If you've recently built and installed &freetds; and noticed steps peculiar to your OS, we'll happily include your comments here. +Building from CVS is described in the file INSTALL.CVS. -+ + +- One thing that can be said, if it's not too obvious: check with your vendor or favorite download site. &freetds; is routinely rolled up into OS install packages. We know of packages for Debian, Red Hat, FreeBSD, and NetBSD. The installation through the package management systems in these environments may well reduce your work to simply make install. +- +- +- The &freetds; ODBC driver compiles under + + For Everyone Else + (&freetds; for Dummies?) -+ -+ + +- + +- VC++. Project files are included in the win32 directory. See also Makefile.win32. +The GNU development system can generate code for a wide variety of hardware architectures and operating systems, virtually all of which can run FreeTDS in consequence. The work of building and installing the FreeTDS libraries begins with the command configure, which generates the Makefile that governs how the code is compiled, linked, and installed. Once you've configured the project, make will manage the rest of the build. + ODBC Preparation -+ + +- Dev-C++ +- MingW +If you intend to build the FreeTDS ODBC driver — and want to use a Driver Manager (DM), as most people do — install the Driver Manager before configuring FreeTDS. configure will detect the the DM and use its header (.h) files for ODBC constants and such. If your DM is installed in an unusual directory, you may have to provide the directory name as a parameter to configure. + -+ + +- gcc under cygwin. +FreeTDS doesn't require a DM. You can build the ODBC driver without one, as long as you have the requisite header files: sql.h, sqlext.h and sqltypes.h. These can be taken from either the iODBC or UnixODBC distributions. Put them wherever you like (e.g., /usr/local/include). Because FreeTDS won't detect your (missing) DM, it won't automatically build the ODBC driver, so you'll have to tell configure what to do and where to look. Cf. + -+ + +- The Borland Builder 6.0 compiler is also reported to work, but requires some tweaking of the #include statements. We would apply any patches that make this work cleanly. +The simplest form of running configure is: + + $ ./configure @@ -166688,36 +166732,10 @@ + + + - <command>Make</> -- --Now you're ready to build. Follow these easy steps. -- -- -- Download the tarball and unpack it. -- Alternatively, get the latest build from CVS -- -- --CVS users will need the GNU autotools: Autoconf, Automake, and libtool. -- -- --. -- -- Change to the freetds directory. -- -- run ./configure with any options you need. -- -- make; make install; make clean -- -- -- --You normally need to be root to make install, unless you used the -- --With any luck, you've built and installed the &freetds; libraries. -- -- -- -+ ++ <command>Make</> + +- +- +Now you're ready to build. Follow these easy steps. + + Download the tarball and unpack it. @@ -166742,45 +166760,52 @@ +With any luck, you've built and installed the &freetds; libraries. + + - -- -- OS-specific Issues -- -- If you've recently built and installed &freetds; and noticed steps peculiar to your OS, we'll happily include your comments here. -- -- One thing that can be said, if it's not too obvious: check with your vendor or favorite download site. &freetds; is routinely rolled up into OS install packages. We know of packages for Debian, Red Hat, FreeBSD, and NetBSD. The installation through the package management systems in these environments may well reduce your work to simply make install. -- -- -- The &freetds; ODBC driver compiles under ++ + + OS-specific Issues + -+ -+If you've recently built and installed &freetds; and noticed steps peculiar to your OS, we'll happily include your comments here. - -- - -- VC++. Project files are included in the win32 directory. See also Makefile.win32. -+One thing that can be said, if it's not too obvious: check with your vendor or favorite download site. &freetds; is routinely rolled up into OS install packages. We know of packages for Debian, Red Hat, FreeBSD, and NetBSD. The installation through the package management systems in these environments may well reduce your work to simply make install. -+ - -- Dev-C++ -- MingW -+ Win32 and Win64 - -- gcc under cygwin. -+Building for Windows using Microsoft's compiler is supported via the NMakefile included in the distribution. Set up the command-line build environment per Microsoft's instructions, and run e.g. - -- The Borland Builder 6.0 compiler is also reported to work, but requires some tweaking of the #include statements. We would apply any patches that make this work cleanly. -+ -+ $ nmake -fNmakefile -nologo apps PLATFORM=win32 CONFIGURATION=debug - -- -- -+Perhaps you're shaking your head at such an old school approach. Over the years, Microsoft's proprietary project-configuration files have proved difficult to support. Every version is different, and there are a great many versions in use in the wild at any one time. As the project changes, it becomes impossible to maintain these kinds of files. - From the Department of Double Emulation: &freetds; builds as a .dll under WINE and as a .a under Interix. See the mailing list archives (second half of 2003) for details. - +- VMS® +- &freetds; will probably build and run on most versions of OpenVMS Alpha 7.0 and later with DEC/Compaq C 6.0 or later. Other prerequisites: ++If you've recently built and installed &freetds; and noticed steps peculiar to your OS, we'll happily include your comments here. ++ + +- +- gunzip +- vmstar +- MMS or MMK +- +- +- +- Build Instructions +- +- Decompress and unpack the source archive using gunzip and vmstar. If +-you are untarring on an ODS-5 disk, you should use the /ODS2 or -o +-option to create universally VMS-friendly filenames; otherwise the build will fail to locate some files. ++One thing that can be said, if it's not too obvious: check with your vendor or favorite download site. &freetds; is routinely rolled up into OS install packages. We know of packages for Debian, Red Hat, FreeBSD, and NetBSD. The installation through the package management systems in these environments may well reduce your work to simply make install. ++ + +- Set default to the top-level source directory and run the configuration +-script: ++ Win32 and Win64 ++ ++Building for Windows using Microsoft's compiler is supported via the NMakefile included in the distribution. Set up the command-line build environment per Microsoft's instructions, and run e.g. + + +- $ @[.vms]configure +- ++ $ nmake -fNmakefile -nologo apps PLATFORM=win32 CONFIGURATION=debug + +- This creates a descrip.mms in the top-level source +-directory which you may execute by simply running MMS (if you have the Module Management System that +-is part of DECset) or MMK (a freeware MMS alternative available from www.madgoat.com). ++Perhaps you're shaking your head at such an old school approach. Over the years, Microsoft's proprietary project-configuration files have proved difficult to support. Every version is different, and there are a great many versions in use in the wild at any one time. As the project changes, it becomes impossible to maintain these kinds of files. + +- Further information can be found in the in the source distribution. +- + Other ways to build under Windows® + + @@ -166798,68 +166823,11 @@ +From the Department of Double Emulation: &freetds; builds as a .dll under WINE and as a .a under Interix. See the mailing list archives (second half of 2003) for details. + + - VMS® -- &freetds; will probably build and run on most versions of OpenVMS Alpha 7.0 and later with DEC/Compaq C 6.0 or later. Other prerequisites: - -- -- gunzip -- vmstar -- MMS or MMK -- -- -- -- Build Instructions -- -- Decompress and unpack the source archive using gunzip and vmstar. If --you are untarring on an ODS-5 disk, you should use the /ODS2 or -o --option to create universally VMS-friendly filenames; otherwise the build will fail to locate some files. -+&freetds; will probably build and run on most versions of OpenVMS Alpha 7.0 and later with DEC/Compaq C 6.0 or later. Other prerequisites: -+ -+ -+ gunzip -+ vmstar -+ MMS or MMK -+ -+ -+ Build Instructions -+ - -- Set default to the top-level source directory and run the configuration --script: -+Decompress and unpack the source archive using gunzip and vmstar. If -+ you are untarring on an ODS-5 disk, you should use the /ODS2 or -o -+ option to create universally VMS-friendly filenames; otherwise the build will fail to locate some files. -+ - -+Set default to the top-level source directory and run the configuration -+ script: -+ - -- $ @[.vms]configure -- -- -- This creates a descrip.mms in the top-level source --directory which you may execute by simply running MMS (if you have the Module Management System that --is part of DECset) or MMK (a freeware MMS alternative available from www.madgoat.com). -+ $ @[.vms]configure -+ - -- Further information can be found in the in the source distribution. -- -+ This creates a descrip.mms in the top-level source -+ directory which you may execute by simply running MMS (if you have the Module Management System that -+ is part of DECset) or MMK (a freeware MMS alternative available from www.madgoat.com). -+ ++ VMS® - - -+Further information can be found in the in the source distribution. -+ -+ -+ - OS X® +- OS X® - As of this writing ($Date: 2011/01/25 06:18:53 $), the regular distribution compiles on OS X. Releases prior to 0.63 either did not compile or required patching. - - @@ -166875,7 +166843,83 @@ - $ ./configure --disable-libiconv --disable-odbc - - -+ +- Overwrite FreeTDS's libtool with a symbolic link to your (better) one +- +- If you run configure again, you'll need to perform this step +-again, because libtool will have been regenerated in its fossilized state. +- $ ln -sf /usr/local/bin/libtool +- +- +- +- To check that you've done everything correctly up to this +-point, +- +- $ ./libtool --version +- +- libtool should report version 1.5.2 (or whatever version you downloaded, and not 1.4). +- And finally, of course +- +- $ make && make install +- +- ++&freetds; will probably build and run on most versions of OpenVMS Alpha 7.0 and later with DEC/Compaq C 6.0 or later. Other prerequisites: ++ ++ ++ gunzip ++ vmstar ++ MMS or MMK ++ ++ ++ Build Instructions ++ + +- +- +- ++Decompress and unpack the source archive using gunzip and vmstar. If ++ you are untarring on an ODS-5 disk, you should use the /ODS2 or -o ++ option to create universally VMS-friendly filenames; otherwise the build will fail to locate some files. ++ + +- AIX® +- +-AIX® can induce linker indigestion. libtool doesn't always understand that a .a file +-can be a shared library. One solution is to build only static libraries with the +- +-Another problem seems to be that the linker isn't asked to pull in all the requisite libraries. Cf. this helpful +-mailing list message. +- +- ++Set default to the top-level source directory and run the configuration ++ script: ++ ++ ++ $ @[.vms]configure ++ + +- GNU/Linux distributions that use RPMs +- +-You may find it convenient to make an RPM from the source distribution, in which case you'll be glad to +-know it is easily done: ++ This creates a descrip.mms in the top-level source ++ directory which you may execute by simply running MMS (if you have the Module Management System that ++ is part of DECset) or MMK (a freeware MMS alternative available from www.madgoat.com). ++ + +- +- $ rpmbuild -ta freetds-0.63RC9.tar.gz +- ++Further information can be found in the in the source distribution. ++ ++ ++ ++ OS X® + +- +- +As of this writing ($Date: 2011/02/13 01:54:38 $), the regular distribution compiles on OS X. Releases prior to 0.63 either did not compile or required patching. + + + $ ./configure --disable-libiconv --disable-odbc + - Overwrite FreeTDS's libtool with a symbolic link to your (better) one -- -- If you run configure again, you'll need to perform this step --again, because libtool will have been regenerated in its fossilized state. -- $ ln -sf /usr/local/bin/libtool -- -- -- -- To check that you've done everything correctly up to this --point, -- -- $ ./libtool --version -- -- libtool should report version 1.5.2 (or whatever version you downloaded, and not 1.4). ++ Overwrite FreeTDS's libtool with a symbolic link to your (better) one + + If you run configure again, you'll need to perform this step + again, because libtool will have been regenerated in its fossilized state. @@ -166916,16 +166947,7 @@ + + $ ./libtool --version + libtool should report version 1.5.2 (or whatever version you downloaded, and not 1.4). - And finally, of course -- -- $ make && make install -- -- -- -- -- -- -- ++ And finally, of course + + $ make && make install + @@ -166935,32 +166957,12 @@ +]]> + + - AIX® -- --AIX® can induce linker indigestion. libtool doesn't always understand that a .a file --can be a shared library. One solution is to build only static libraries with the -- --Another problem seems to be that the linker isn't asked to pull in all the requisite libraries. Cf. this helpful --mailing list message. -- -- -- -- GNU/Linux distributions that use RPMs -- --You may find it convenient to make an RPM from the source distribution, in which case you'll be glad to --know it is easily done: - -- -- $ rpmbuild -ta freetds-0.63RC9.tar.gz -- ++ AIX® ++ +AIX® can induce linker indigestion. libtool doesn't always understand that a .a file + can be a shared library. One solution is to build only static libraries with the - -- -- ++ +Another problem seems to be that the linker isn't asked to pull in all the requisite libraries. Cf. this helpful + mailing list message. + @@ -167207,9 +167209,6 @@ - Attempt to convert servername to an IP address with inet_addr(3). - Request name-lookup from the operating system via gethostbyname(3) or similar. - -- -- If the TDS version and port are not read from &freetdsconf;, they are derived from the compiled-in defaults and overridden by applicable environment variables. -- + This description applies to &dblib; and &ctlib;. ODBC lookup is different. + + Find servername in &freetdsconf;. If a section with that name exists, use the hostname, port, and TDS version specified therein. @@ -167217,6 +167216,9 @@ + Request name-lookup from the operating system via gethostbyname(3) or similar. + +- If the TDS version and port are not read from &freetdsconf;, they are derived from the compiled-in defaults and overridden by applicable environment variables. +- +- - As you can see, if most of your servers use the same TDS version and answer to the default port, then you don't need to list them all in &freetdsconf;. You can simply compile in the right defaults — or set the TDSPORT and TDSVER environment variables — and rely on DNS for name resolution. - - @@ -167258,7 +167260,7 @@ - - +Just as DNS defines hostnames for network addresses, &freetdsconf; uses a servername to define the properties of your server. - ++ +In general, the servername is arbitrary and local; it's used only by your client programs to tell &freetds; which server to connect to. You can choose any name you like. + +Sybase SQL Anywhere (a/k/a Sybase ASA), however, is fussy. Unless you use the ASA Database property, you must use the database's name as your servername. Otherwise, the server will refuse your connection. @@ -167274,7 +167276,7 @@ + + + -+ + + &freetds; also supports an older configuration file format, known as the interfaces file. Use &freetdsconf; unless interfaces is needed for your situation. It is easier to read, and it is where all the new options are being added. &freetds; looks for &freetdsconf; first, falling back on interfaces only if &freetdsconf; is not found. + +Should you need it, more information about interfaces can be found in the Appendix. @@ -167843,14 +167845,14 @@ + + + -+ + +- +- The <filename>locales.conf</filename> file +For more about the wonderful world of &freetds; logs, see Logging. + + + Deprecated options</> - -- <sect1 id="locales"> -- <title>The <filename>locales.conf</filename> file ++ +The following options have long been deprecated. + + @@ -168614,7 +168616,7 @@ - - +To complete successfully, the ODBC tests require some additional setup. In your PWD file, add a SRV entry specifying the DSN entry for your odbc.ini. The ODBC tests all build their own odbc.ini and try to redirect the Driver Manager to it, however this functionality is very DM dependent and may well fail unless you have either iODBC or unixODBC. - ++ + + The PWD provided by &freetds; includes usernames and passwords that probably don't exist on your server. + @@ -168628,6 +168630,8 @@ +To connect to a database server, a library such as &freetds; needs some information about the connection. By server, which IP address and port is do you mean? Which user is requesting the connection, and what authentication does he offer? Every database library needs a way to capture and convey that information. ++ODBC was conceived as a general interface definition, not tied to any particular database or access library. For that reason, ODBC also needs to know which driver to use with a given server. + - -For details on tsql, see the its man page. - @@ -168636,7 +168640,7 @@ - <application>Unit Tests</application> - -The source code directory of each &freetds; library includes a unittests directory. -+ODBC was conceived as a general interface definition, not tied to any particular database or access library. For that reason, ODBC also needs to know which driver to use with a given server. ++The original ODBC solution to this conundrum employed the odbc.ini file. odbc.ini stored information about a server, known generically as a Data Source Name (DSN). ODBC applications connected to the server by calling the function SQLConnect(DSN, UID, PWD), where DSN is the Data Source Name entry in odbc.ini, UID is the username, and PWD the password. Any and all information about the DSN was kept in odbc.ini. And all was right with the world. - -$ ls -d -1 src/*/unittests @@ -168647,7 +168651,8 @@ -src/tds/unittests - - -+The original ODBC solution to this conundrum employed the odbc.ini file. odbc.ini stored information about a server, known generically as a Data Source Name (DSN). ODBC applications connected to the server by calling the function SQLConnect(DSN, UID, PWD), where DSN is the Data Source Name entry in odbc.ini, UID is the username, and PWD the password. Any and all information about the DSN was kept in odbc.ini. And all was right with the world. ++The ODBC 3.0 specification introduced a new function: SQLDriverConnect. ++ The connection attributes are provided as a single argument, a string of concatenated name-value pairs. SQLDriverConnect subsumed the functionality of SQLConnect, in that the name-value pair string allowed the caller to pass — in addition the the original DSN, UID, and PWD — any other parameters the driver could accept. Moreover, the application can specify which driver to use. In effect, it became possible to specify the entire set of DSN properties as parameters to SQLDriverConnect, obviating the need for odbc.ini. This led to the use of the so-called DSN-less configuration, a setup with no odbc.ini. -The unit tests rely on the PWD file in root of the FreeTDS source tree. -PWD holds a username, password, servername, and database to be used for the unit tests. We try to make sure to leave nothing behind: any data and objects created are either temporary or removed at the end of the test. The tests should all work, subject to disclaimers in the directory's README. @@ -168665,9 +168670,6 @@ - - - -+The ODBC 3.0 specification introduced a new function: SQLDriverConnect. -+ The connection attributes are provided as a single argument, a string of concatenated name-value pairs. SQLDriverConnect subsumed the functionality of SQLConnect, in that the name-value pair string allowed the caller to pass — in addition the the original DSN, UID, and PWD — any other parameters the driver could accept. Moreover, the application can specify which driver to use. In effect, it became possible to specify the entire set of DSN properties as parameters to SQLDriverConnect, obviating the need for odbc.ini. This led to the use of the so-called DSN-less configuration, a setup with no odbc.ini. -+ +But FreeTDS did not start out as an ODBC driver (remember &dblib; and &ctlib;), and has always had its own way to store server properties: &freetdsconf;. When Brian added the &freetds; ODBC driver, he began by supporting the old SQLConnect, using odbc.ini to describe the DSN. That choice complied with the expectations of the Driver Managers, and minimized the amount of duplicated information in the configuration files. But it can be a little confusing, too, because odbc.ini in effect points to &freetdsconf;. We call this configuration ODBC-combined, because it supports all three FreeTDS libraries. + +As progress on the the &freetds; ODBC library progressed, the driver was made able to read the connection attributes directly from odbc.ini, rather than leaning on &freetdsconf;. For installations that don't need &dblib; and &ctlib;, this ODBC-only setup is simpler. @@ -169591,11 +169593,15 @@ -If &freetds; runs into a character it can not convert, its behavior varies according to the severity of the problem. On retrieving data from the server, &freetds; substitutes an ASCII '?' in the character's place, and emits a warning message stating that some characters could not be converted. On sending data to the server, &freetds; aborts the query and emits an error message. It is well to ensure that the data contained in the database is representable in the client's character set. + + ++ ++If &freetds; runs into a character it can not convert, its behavior varies according to the severity of the problem. On retrieving data from the server, &freetds; substitutes an ASCII '?' in the character's place, and emits a warning message stating that some characters could not be converted. On sending data to the server, &freetds; aborts the query and emits an error message. It is well to ensure that the data contained in the database is representable in the client's character set. ++ - -If you have a mix of character data that can not be contained in a single-byte character set, you may wish to use UTF-8. UTF-8 is a variable length unicode encoding that is compatible with ASCII in the range 0 to 127. With UTF-8, you are guaranteed to never have an unconvertible character. -+If &freetds; runs into a character it can not convert, its behavior varies according to the severity of the problem. On retrieving data from the server, &freetds; substitutes an ASCII '?' in the character's place, and emits a warning message stating that some characters could not be converted. On sending data to the server, &freetds; aborts the query and emits an error message. It is well to ensure that the data contained in the database is representable in the client's character set. ++If you have a mix of character data that can not be contained in a single-byte character set, you may wish to use UTF-8. UTF-8 is a variable length unicode encoding that is compatible with ASCII in the range 0 to 127. With UTF-8, you are guaranteed to never have an unconvertible character. + ++ &freetds; is not fully compatible with multi-byte character sets such as UCS-2. You must use an ASCII-extension charset (e.g., UTF-8, ISO-8859-*)not EBCDIC or other weird charsets. Great care should be taken testing applications using these encodings. Specifically, many applications do not expect the number of characters returned to exceed the column size (in bytes). -&freetds; is not fully compatible with multi-byte character sets such as UCS-2. You must use an ASCII-extension charset (e.g., UTF-8, ISO-8859-*)not EBCDIC or other weird charsets. Great care should be taken testing applications using these encodings. Specifically, many applications do not expect the number of characters returned to exceed the column size (in bytes). - @@ -169603,10 +169609,6 @@ - - -Configuring for <acronym>UTF-8</> &freetdsconf; setting -+If you have a mix of character data that can not be contained in a single-byte character set, you may wish to use UTF-8. UTF-8 is a variable length unicode encoding that is compatible with ASCII in the range 0 to 127. With UTF-8, you are guaranteed to never have an unconvertible character. -+ -+ &freetds; is not fully compatible with multi-byte character sets such as UCS-2. You must use an ASCII-extension charset (e.g., UTF-8, ISO-8859-*)not EBCDIC or other weird charsets. Great care should be taken testing applications using these encodings. Specifically, many applications do not expect the number of characters returned to exceed the column size (in bytes). -+ +In the following example, a server named mssql will return data encoded in the UTF-8 character set. + + Configuring for <acronym>UTF-8</> &freetdsconf; setting @@ -170119,7 +170121,12 @@ +Install openssl and stunnel on the Linux box: + stunnel.org + -+ + +- Set up FreeTDS to use the tunnel. If this is your unencrypted entry in +- &freetdsconf;: +- +- +-Unencrypted entry in &freetdsconf; + +Download the stunnel binary and openssl dll's for Windows. + @@ -170145,12 +170152,7 @@ + +where win2kserver is the hostname or IP address of the W2k box. + - -- Set up FreeTDS to use the tunnel. If this is your unencrypted entry in -- &freetdsconf;: -- -- --Unencrypted entry in &freetdsconf; ++ + +Set up FreeTDS to use the tunnel. If this is your unencrypted entry in + &freetdsconf;: @@ -170221,17 +170223,17 @@ - A non-interactive equivalent of the isql utility programs distributed by Sybase and Microsoft. Like them, bsqlodbc uses the command go on a line by itself as a separator between batches. The last batch need not be followed by go. It uses the ODBC API. + A non-interactive equivalent of the isql utility programs distributed by Sybase and Microsoft. Like them, bsqldb uses the command go on a line by itself as a separator between batches. The last batch need not be followed by go. + - -- bsqlodbc is a demonstration project, but can also aid in isolating problems. ODBC applications typically have many layers, and it can be difficult to know if a problem arises in a layer, or in the interface between layers. By executing a query in bsqlodbc, you can see if the functionality of the ODBC driver works when used as the folks who wrote the driver thought it would be used. -- -- ++ +bsqldb makes use of the db-lib API. Intended for production use. + + + + bsqlodbc + -+ + +- bsqlodbc is a demonstration project, but can also aid in isolating problems. ODBC applications typically have many layers, and it can be difficult to know if a problem arises in a layer, or in the interface between layers. By executing a query in bsqlodbc, you can see if the functionality of the ODBC driver works when used as the folks who wrote the driver thought it would be used. +- +- +A non-interactive equivalent of the isql utility programs distributed by Sybase and Microsoft. Like them, bsqlodbc uses the command go on a line by itself as a separator between batches. The last batch need not be followed by go. It uses the ODBC API. + @@ -170305,10 +170307,10 @@ + + defncopy + - ++ +Replaces a similar program of the same name distributed by Sybase. + - ++ +defncopy reads the text of a stored procedure or view, and writes a script suitable for recreating the procedure or view. For tables, it reads the output of sp_help and constructs a CREATE TABLE statement, complete with CREATE INDEX, too. + + @@ -170316,7 +170318,7 @@ + + fisql + - ++ +A complete replacement of the isql utility programs distributed by Sybase and Microsoft. Like them, fisql uses the command go on a line by itself as a separator between batches. + + @@ -170324,9 +170326,40 @@ + + freebcp + - ++ +Replicates the functionality of the bcp utility programs distributed by Sybase and Microsoft. ++freebcp makes use of the db-lib bcp API. ++ ++The manual pages or online help for Sybase or SQL Server can be referenced for more detailed information on bcp functionality. ++ ++ ++ ++ ++ osql ++ ++ ++A Bourne shell script that checks and reports on your configuration. ++ ++ ++ ++ ++ tsql ++ + ++A diagnostic tool that uses uses the lowest level FreeTDS library, libtds, as a way to isolate potential bugs in the protocol implementation. + ++tsql is not a replacement for a complete isql. ++ ++ ++ ++ ++ + ++ ++ ++ How to get what works with it working + - - - How to get what works with it working @@ -170337,25 +170370,18 @@ - <application>SQSH</application> - -SQSH is a command line based query tool written by Scott Gray to replace the isql utility that ships with Sybase ASE. It makes a great diagnostic tool for &freetds; as well. If you are having trouble, install SQSH (it's easy) and try getting that to work before more complicated arrangements. -+freebcp makes use of the db-lib bcp API. ++The following programs are known to work to some extent with &freetds;. Here you will find any special instructions for getting them compiled or running. ++ ++ <application>SQSH</application> - That advice is so good, it bears repeating. If you are having trouble, grab SQSH and get that to work. Not only will it help isolate the problem, it will give you a very capable tool. -+The manual pages or online help for Sybase or SQL Server can be referenced for more detailed information on bcp functionality. -+ -+ ++SQSH is a command line based query tool written by Scott Gray to replace the isql utility that ships with Sybase ASE. It makes a great diagnostic tool for &freetds; as well. If you are having trouble, install SQSH (it's easy) and try getting that to work before more complicated arrangements. + -+ -+ osql -+ - -- -+A Bourne shell script that checks and reports on your configuration. -+ -+ -+ -+ -+ tsql -+ ++ SQSH is an excellent tool. Because it uses &ctlib;, it works with &freetds;, but potentially — and with significant effort — it could be ported to ODBC and thus made useful for other server environments. Just a thought…. ++ + +- ++SQSH 2.1 includes direct support for &freetds;, so these instructions may not be necessary, but are still included just in case. - -SQSH 2.1 includes direct support for &freetds;, so these instructions may not be necessary, but are still included just in case. @@ -170364,7 +170390,10 @@ -After running configure in SQSH's directory (make sure you set the Sybase environment variable first), look for the Sybase_LIBS definition in the Makefile. Change the line to match this example. - -The <application>SQSH</application> Makefile -- ++After running configure in SQSH's directory (make sure you set the Sybase environment variable first), look for the Sybase_LIBS definition in the Makefile. Change the line to match this example. ++ ++ The <application>SQSH</application> Makefile + -# -# The following set of CT-LIB libraries were determined automatically -# by 'configure'. For most systems configure looks up the required @@ -170390,37 +170419,6 @@ - -After that just type make and you are off and running. - -+A diagnostic tool that uses uses the lowest level FreeTDS library, libtds, as a way to isolate potential bugs in the protocol implementation. -+ -+tsql is not a replacement for a complete isql. -+ -+ -+ - -+ -+ -+ -+ -+ How to get what works with it working -+ -+The following programs are known to work to some extent with &freetds;. Here you will find any special instructions for getting them compiled or running. -+ -+ <application>SQSH</application> - -- -- Perl -- There are a few ways to use Perl to connect to a SQL Server using &freetds;. -+SQSH is a command line based query tool written by Scott Gray to replace the isql utility that ships with Sybase ASE. It makes a great diagnostic tool for &freetds; as well. If you are having trouble, install SQSH (it's easy) and try getting that to work before more complicated arrangements. - -+ SQSH is an excellent tool. Because it uses &ctlib;, it works with &freetds;, but potentially — and with significant effort — it could be ported to ODBC and thus made useful for other server environments. Just a thought…. -+ -+ -+SQSH 2.1 includes direct support for &freetds;, so these instructions may not be necessary, but are still included just in case. -+ -+After running configure in SQSH's directory (make sure you set the Sybase environment variable first), look for the Sybase_LIBS definition in the Makefile. Change the line to match this example. -+ -+ The <application>SQSH</application> Makefile -+ + # + # The following set of CT-LIB libraries were determined automatically + # by 'configure'. For most systems configure looks up the required @@ -170444,11 +170442,15 @@ + At this point you can also enable readline support if you didn't specify it in the configure arguments. + +After that just type make and you are off and running. -+ + + + + Perl -+ + +- +- Perl +- There are a few ways to use Perl to connect to a SQL Server using &freetds;. +- +There are a few ways to use Perl to connect to a SQL Server using &freetds;. + DBD::Sybase @@ -171225,23 +171227,48 @@ - - -If you receive a message like -- ++ $ cd src/apps ++ $ TDSVER=7.0 ./tsql -H myhost -p 1433 -U user ++ ++ If you receive a message of 'Login Failed.' then your connectivity is OK, but you have a authentication issue. ++ ++If you receive a message like + - - Msg. No.: 18450 Severity: 14 State: 1 Login failed- User: loginid Reason: Not defined as a valid user of a trusted SQL Server connection - - -SQL Server is accepting only domain logins. This applies only to Microsoft SQL Server and you'll need to have your DBA verify that server logins are allowed, or use a domain login. -+ $ cd src/apps -+ $ TDSVER=7.0 ./tsql -H myhost -p 1433 -U user ++ ++ Msg. No.: 18450 Severity: 14 State: 1 Login failed- User: loginid Reason: Not defined as a valid user of a trusted SQL Server connection ++ ++ SQL Server is accepting only domain logins. This applies only to Microsoft SQL Server and you'll need to have your DBA verify that server logins are allowed, or use a domain login. ++ ++Finally, if you received a prompt, then try tsql using the servername. ++ ++ Connecting to the server using &freetdsconf; ++ ++ $ ./tsql -S myserver -U user + -+ If you receive a message of 'Login Failed.' then your connectivity is OK, but you have a authentication issue. ++ If this fails, FreeTDS is either not finding your &freetdsconf; file, finding the wrong one, or there is an error in the file. ++ ++ ++ ++ Logging ++ ++&freetds; has quite extensive logging capabilities. These are often invaluable in setting up new configurations, when it's hard to be sure precisely what configuration information is being used, and what communication is (not) working. Often such questions can be quickly resolved by turning on logging and examining the logs. ++ Environment Variables that Control Logging ++ ++ ++ TDSDUMP ++ - - -Finally, if you received a prompt, then try tsql using the servername. - - Connecting to the server using &freetdsconf; -+If you receive a message like ++Log files can be turned on using the TDSDUMP environment variable. For instance, setting the location of a dumpfile -$ ./tsql -S myserver -U user - @@ -171257,64 +171284,18 @@ - - Environment Variables that Control Logging - -- -- TDSDUMP -- -- Log files can be turned on using the TDSDUMP environment variable. For instance, setting the location of a dumpfile -+ -+ Msg. No.: 18450 Severity: 14 State: 1 Login failed- User: loginid Reason: Not defined as a valid user of a trusted SQL Server connection -+ -+ SQL Server is accepting only domain logins. This applies only to Microsoft SQL Server and you'll need to have your DBA verify that server logins are allowed, or use a domain login. -+ -+Finally, if you received a prompt, then try tsql using the servername. -+ -+ Connecting to the server using &freetdsconf; - --$ export TDSDUMP=/tmp/freetds.log -- --Will generate a log file named freetds.log in the /tmp directory. -- The filenames stdout and stderr are also supported. They can be handy if you want to intersperse the log output with your application's output, or if your application opens more than one connection. (The logfile is otherwise normally truncatated each time the library connects to the server.) -- -- -- -+ $ ./tsql -S myserver -U user -+ -+ If this fails, FreeTDS is either not finding your &freetdsconf; file, finding the wrong one, or there is an error in the file. -+ -+ -+ -+ Logging -+ -+&freetds; has quite extensive logging capabilities. These are often invaluable in setting up new configurations, when it's hard to be sure precisely what configuration information is being used, and what communication is (not) working. Often such questions can be quickly resolved by turning on logging and examining the logs. -+ Environment Variables that Control Logging -+ -+ -+ TDSDUMP -+ -+ -+Log files can be turned on using the TDSDUMP environment variable. For instance, setting the location of a dumpfile -+ + $ export TDSDUMP=/tmp/freetds.log + Will generate a log file named freetds.log in the /tmp directory. + The filenames stdout and stderr are also supported. They can be handy if you want to intersperse the log output with your application's output, or if your application opens more than one connection. (The logfile is otherwise normally truncatated each time the library connects to the server.) + + -- TDSDUMPCONFIG +- TDSDUMP - -- Set TDSDUMPCONFIG to a file to --write information to on how the configuration information is being --obtained, e.g. from environment variables, a &freetdsconf; file, or interfaces file. Sometimes it's unclear what source of information &freetds; is using to connect to a given servername. This variable can make that bright and clear. -- -- -- -- +- Log files can be turned on using the TDSDUMP environment variable. For instance, setting the location of a dumpfile + TDSDUMPCONFIG + - -- --What if you were running Apache/PHP? Apache has many children. --Setting the TDSDUMP (and/or TDSDUMPCONFIG) variable to a null string will cause &freetds; to open a log under every PID. ++ +Set TDSDUMPCONFIG to a file to + write information to on how the configuration information is being + obtained, e.g. from environment variables, a &freetdsconf; file, or interfaces file. Sometimes it's unclear what source of information &freetds; is using to connect to a given servername. This variable can make that bright and clear. @@ -171326,6 +171307,31 @@ + What if you were running Apache/PHP? Apache has many children. + Setting the TDSDUMP (and/or TDSDUMPCONFIG) variable to a null string will cause &freetds; to open a log under every PID. +-$ export TDSDUMP=/tmp/freetds.log +- +-Will generate a log file named freetds.log in the /tmp directory. +- The filenames stdout and stderr are also supported. They can be handy if you want to intersperse the log output with your application's output, or if your application opens more than one connection. (The logfile is otherwise normally truncatated each time the library connects to the server.) +- +- +- +- +- TDSDUMPCONFIG +- +- Set TDSDUMPCONFIG to a file to +-write information to on how the configuration information is being +-obtained, e.g. from environment variables, a &freetdsconf; file, or interfaces file. Sometimes it's unclear what source of information &freetds; is using to connect to a given servername. This variable can make that bright and clear. +- +- +- +- ++ $ export TDSDUMP="" ++ The log files will be named /tmp/freetds.log.9999, where 9999 is the pid number of the process generating the log. ++ + +- +-What if you were running Apache/PHP? Apache has many children. +-Setting the TDSDUMP (and/or TDSDUMPCONFIG) variable to a null string will cause &freetds; to open a log under every PID. +- -$ export TDSDUMP="" - -The log files will be named /tmp/freetds.log.9999, where 9999 is the pid number of the process generating the log. @@ -171345,10 +171351,6 @@ - - - -+ $ export TDSDUMP="" -+ The log files will be named /tmp/freetds.log.9999, where 9999 is the pid number of the process generating the log. -+ -+ +A couple of important notes about using the logs with &freetds;. First, + the logs tend to grow large, so trim or archive them often. Secondly, + &freetds; will record certain network packets to the log, this @@ -171564,7 +171566,7 @@ + + + - ++ +Logging. If everything seems a bit sluggish, check to make sure logging is turned off. TDSDUMP should not be defined, and there should be no dump file mentioned in &freetdsconf;. You can double-check by setting TDSDUMPCONFIG temporarily, which will log only the startup process. + + @@ -171577,7 +171579,7 @@ + Reverse lookup code has been removed as of version 0.62 due to wrong implementation. + + -+ + +Packet size. Check packet size setting on &freetdsconf; (see initial block size). Default value (no configuration) is usually fine. The slowness is due to multiple packet to use. + Under GNU/Linux system we use an optimization to reduce network traffic so you shouldn't see much difference using this system. + @@ -171620,12 +171622,12 @@ + Won't you please, please help me? + + -+ + +In the battle against frustration and wasted motion, this manual is our first defense. Our documentation is intended to make it possible for a knowledgeable user to, well, use &freetds; without further assistance. We strive to include all known features and behaviors here, so you can work quickly and anonymously, and go home before 5:00. Would that it were always thus. + + + Reconfirm the installation - ++ +For initial setup and login problems, review . Distinguish between network and server issues, between finding the server and logging into it. The TDSDUMPCONFIG log will show how the servername is being looked up, what address & port is being used, what TDS version is being used. The TDSDUMP log will show quite clearly whether or not the server accepted the connection, and whether or not the login succeeded. + +Remember compiled-in defaults can be displayed with tsql: @@ -171811,12 +171813,12 @@ + Show your work + +Great questions make the problem crystal clear to a tired developer after supper. - -- ++ +Show what you did, and show what happened. Throughout this User Guide, you've seen examples of screenshots; in each case the first line was the command entered, followed by the machine's response. By showing verbatim what you did and saw, you give someone who knows what to do a chance to look over your shoulder. Across the Internet! How cool is that? + +Whether you're having a problem with your own application or with something at a higher level, you're well advised to try to reproduce it using one of the &freetds; utilities, preferably one that used the same client library you're using. If, say, bsqldb works and your program doesn't, that's a clue. By the same token, if bsqldb exhibits problems, too, chances are you found a bug. Or — how to say it? — a missing feature. It's always good to know about those. -+ + +- + @@ -171914,11 +171916,7 @@ -The FAQ and in particular the news don't get updated often enough. If that's your thing, drop a line to your friendly project maintainer, James K. Lowden. - - -+ Be the Webmaster -+ -+The FAQ and in particular the news don't get updated often enough. If that's your thing, drop a line to your friendly project maintainer, James K. Lowden. -+ - +- - - Advocacy - @@ -171937,15 +171935,7 @@ - - If more people knew, fewer would be stuck. - -+ -+ -+ Light another's taper -+ -+Every question you answer on the mailing list will save someone time and, if done well, will actually improve your own knowledge. The project's developers will often answer technical questions that require substantial understanding of the code or suggest a possible bug. Setup issues, though, connecting and logging in to the server, getting Apache going, are questions many experienced users can and do answer, thereby fostering the community on which the project depends. -+ -+Your experience may well be more closely aligned with the question posed than that of anyone else reading the list that day. You may use that framework or language or OS, or have that particular server. No one, no matter how expert in the code, has used every configuration, version, OS, compiler, etc. Whether you simply confirm there's a problem in some particular arrangement, or say, dunno, works for me, you're adding information. -+ - +- - - - @@ -171957,33 +171947,7 @@ - -Can be found on www.freetds.org - -+ -+ -+ Ambitious ideas -+ -+If you want to get your hands really dirty, here are some big ideas to contemplate. -+ -+ -+ <literal>libtds2</literal> -+ -+After many years developing &freetds;, we've learned quite a bit about the protocol and how to write database libraries. Unfortunately, though, one of the things holding us back — and, obviously hampering the project — is the underlying utility library. -+ -+This wouldn't be a from-scratch effort; most of the code is already written. What's needed is a more uniform API that better reflects the TDS protocol, and that does not attempt character set conversions immediately on receipt of the data. -+ -+ -+ -+ <literal>libstddb</literal> -+ -+This would be a new client library modelled after stdio, a project to demonstrate what database programming should be like. -+ -+ -+ -+ Server code -+ -+&freetds; includes a little stub of a server, but it could be much more useful. One idea would be to make it a front-end to SQLite, thereby creating for the first time a TDS client & server pair composed entirely of free software. -+ -+ - +- - API Reference Manual - -The reference manual is installed as part of FreeTDS. It can be regenerated at any time using Doxygen with cd doc; make doc. @@ -172025,28 +171989,8 @@ - - - -+ -+ -+ Advocacy -+ -+Out of ten people you know, it's a fair bet 10 never heard of &freetds; and nine don't understand the problem it solves. Lots of places have begun to use Microsoft SQL Servers in all sorts of ways, and if you adhere to the Microsoft line, there's only one way to connect to them: from a Microsoft OS. -+ -+What can &freetds; do that can't be done any other way? Glad you asked. &freetds; can -+ -+ Connect to every version of either vendor's server, using the same binaries. -+ Provide a &ctlib; interface to Microsoft SQL Server. This feature alone allows DBD::Sybase and sqsh, among others, to connect to Microsoft's product. -+ Provide a bcp-capable interface and command-line utility on unix-like operating systems for Microsoft SQL Server. -+ Run on many more operating systems than either vendor's libraries do. -+ Get fixed, instead of telling you to get stuffed. -+ Amuse and inform. Also frustrate and infuriate, but we don't put that under Advocacy. -+ -+ -+If more people knew, fewer would be stuck. - -+ -+ -+ -+ Programming +- ++ Be the Webmaster - - db-lib API Implementation Summary @@ -172060,12 +172004,243 @@ - - Links such as these are quite perishable. Should you find them broken, please check the FreeTDS User Guide posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. - &dblibapisgml; ++The FAQ and in particular the news don't get updated often enough. If that's your thing, drop a line to your friendly project maintainer, James K. Lowden. ++ + + +- +- ct-lib API Implementation Summary +- Sybase ct-lib documentation can be found +- online +- and in PDF form. Links such as these are quite perishable. Should you find them broken, please check the FreeTDS User Guide posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. +- &ctlibapisgml; +- +- +- +- ODBC API Implementation Summary +- Microsoft's ODBC documentation is +- online. +- +- The functions are linked to the reference page on Microsoft's website. Links such as these are quite perishable. Should you find them broken, please check the FreeTDS User Guide posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. +- &odbcapisgml; ++ ++ Light another's taper ++ ++Every question you answer on the mailing list will save someone time and, if done well, will actually improve your own knowledge. The project's developers will often answer technical questions that require substantial understanding of the code or suggest a possible bug. Setup issues, though, connecting and logging in to the server, getting Apache going, are questions many experienced users can and do answer, thereby fostering the community on which the project depends. ++ ++Your experience may well be more closely aligned with the question posed than that of anyone else reading the list that day. You may use that framework or language or OS, or have that particular server. No one, no matter how expert in the code, has used every configuration, version, OS, compiler, etc. Whether you simply confirm there's a problem in some particular arrangement, or say, dunno, works for me, you're adding information. ++ + +- +- +- DB-Library for the Tenderfoot +- Mark Twain +- Few things are harder to put up with than the annoyance of a good example. +- +- Below is a complete sample working db-lib program, presented as a series of examples. +- Features of sample code +- Processes command-line options to select the server, database, username, and password +- Remaining arguments on the command line comprise the SQL query to execute +- Installs error and message handlers +- Illustrates correct row-processing +- Illustrates correct error detection and handling +- +- Other sample code may be found in the distribution, in the cleverly named samples directory. A complete program, heavily commented for your perusal, is apps/bsqldb.c. +- +- What's the big deal with errors? +- Correct handling of errors is extremely important in database applications because they involve two systems most others don't: the network and the database server. Both can give rise to errors that, if not detected and reported when they occur, let the application proceed blithely on until something truly mysterious happens. In the worst case, in the absence of a properly reported error, the application may seem to have updated the data, when in fact it did not. +- Every db-lib application uses the network, making it subject to network failures. Database programs also almost always have very high data integrity requirements. It is necessary to know the row was absolutely, positively committed, once and only once, without error or exception. Without taking great care to trap and handle all error conditions, no statement about the program's reliability can be made with confidence. +- +- +- How to Get and Build the sample code +- Run doc/grep_sample_code to extract the C code from the User Guide SGML source. +- Compile +- Link +- + +- Files Required to Build the Sample Code +- sybfront.h +- sybdb.h +- libsybdb.a or libsybdb.so +- +- Your library's extension may vary according to your operating system. +- +- The source code may be built with commands similar to these. The precise options and paths depend on your particular system. The commands below work with the GNU compiler and linker on an ELF system with dynamic linking, common on Linux and BSD systems. +-Building the Sample Code +- +- $ ../doc/grep_sample_code ../doc/userguide.sgml > sample.c +- $ cc -I /usr/local/include -Wl,-L/usr/local/lib -Wl,-R/usr/local/lib sample.c -lsybdb -o sample +- +- +- where /usr/local/include and /usr/local/lib are respectively the locations of your header files and libraries. +- +- +- We now proceed to the code proper. +- ++ ++ Ambitious ideas + +- Header files +- We need two header files to use db-lib. We need a few others to deal with I/O in C, as you know. Also declare the error and message handler functions, more about which later. ++If you want to get your hands really dirty, here are some big ideas to contemplate. ++ ++ ++ <literal>libtds2</literal> + +- +- Sample Code: <symbol>db-lib</> header files +- +- +-#include +-#include +-#include +-#include +-#include +-#include +-]]> ++After many years developing &freetds;, we've learned quite a bit about the protocol and how to write database libraries. Unfortunately, though, one of the things holding us back — and, obviously hampering the project — is the underlying utility library. + +-#include <sybfront.h> /* sybfront.h always comes first */ +-#include <sybdb.h> /* sybdb.h is the only other file you need */ ++This wouldn't be a from-scratch effort; most of the code is already written. What's needed is a more uniform API that better reflects the TDS protocol, and that does not attempt character set conversions immediately on receipt of the data. ++ + +-int err_handler(DBPROCESS*, int, int, int, char*, char*); +-int msg_handler(DBPROCESS*, DBINT, int, int, char*, char*, char*, int); +- +- ++ ++ <literal>libstddb</literal> ++ ++This would be a new client library modelled after stdio, a project to demonstrate what database programming should be like. + +- +- Prolog +- Nothing special here. Collect the command line parameters. We do this with the standard getopts(3) function. Cf. man 3 getopts for details. +- +- +- Sample Code: <symbol>db-lib</> prolog +- +-extern char *optarg; +-extern int optind; +- +-const static char syntax[] = +- "syntax: example -S server -D db -U user -P passwd\n"; +- +-struct { +- char *appname, *servername, *dbname, *username, *password; +-} options = {0,0,0,0,0}; + +-int +-main(int argc, char *argv[]) +-{ +- int i, ch; +- LOGINREC *login; +- DBPROCESS *dbproc; +- RETCODE erc; +- +- options.appname = basename(argv[0]); +- +- while ((ch = getopt(argc, argv, "U:P:S:D:")) != -1) { +- switch (ch) { +- case 'S': +- options.servername = strdup(optarg); +- break; +- case 'D': +- options.dbname = strdup(optarg); +- break; +- case 'U': +- options.username = strdup(optarg); +- break; +- case 'P': +- options.password = strdup(optarg); +- break; +- case '?': +- default: +- fprintf(stderr, syntax); +- exit(1); +- } +- } ++ ++ Server code + +- argc -= optind; +- argv += optind; +- +- if (! (options.servername +- && options.username && options.password)) { +- fprintf(stderr, syntax); +- exit(1); +- } +- +- Prolog Notes +- +- LOGINREC is a structure that describes the client. It's passed to the server at connect time. +- +- DBPROCESS is a structure that describes the connection. It is returned by dbopen(). +- +- RETCODE is the most common return code type for db-lib functions. +- +- ++&freetds; includes a little stub of a server, but it could be much more useful. One idea would be to make it a front-end to SQLite, thereby creating for the first time a TDS client & server pair composed entirely of free software. + + +- Initialize +- Initialize the library. Create and populate a LOGINREC record. +- +- +- Sample Code: <symbol>db-lib</> Initialize +- ++ + +- +- if (dbinit() == FAIL) { +- fprintf(stderr, "%s:%d: dbinit() failed\n", +- options.appname, __LINE__); +- exit(1); +- } +- +- +- dberrhandle(err_handler); +- dbmsghandle(msg_handler); ++ ++ Advocacy + +- +- if ((login = dblogin()) == NULL) { +- fprintf(stderr, "%s:%d: unable to allocate login structure\n", +- options.appname, __LINE__); +- exit(1); +- } ++Out of ten people you know, it's a fair bet 10 never heard of &freetds; and nine don't understand the problem it solves. Lots of places have begun to use Microsoft SQL Servers in all sorts of ways, and if you adhere to the Microsoft line, there's only one way to connect to them: from a Microsoft OS. + +- +- DBSETLUSER(login, options.username); +- DBSETLPWD(login, options.password); ++What can &freetds; do that can't be done any other way? Glad you asked. &freetds; can ++ ++ Connect to every version of either vendor's server, using the same binaries. ++ Provide a &ctlib; interface to Microsoft SQL Server. This feature alone allows DBD::Sybase and sqsh, among others, to connect to Microsoft's product. ++ Provide a bcp-capable interface and command-line utility on unix-like operating systems for Microsoft SQL Server. ++ Run on many more operating systems than either vendor's libraries do. ++ Get fixed, instead of telling you to get stuffed. ++ Amuse and inform. Also frustrate and infuriate, but we don't put that under Advocacy. ++ ++ ++If more people knew, fewer would be stuck. ++ ++ ++ ++ ++ Programming ++ + + + TDS protocol reference + +Can be found on www.freetds.org - ++ + API Reference Manual + +The reference manual is installed as part of FreeTDS. It can be regenerated at any time using Doxygen with cd doc; make doc. @@ -172103,23 +172278,13 @@ + + OK + - -- -- ct-lib API Implementation Summary -- Sybase ct-lib documentation can be found -- online -- and in PDF form. Links such as these are quite perishable. Should you find them broken, please check the FreeTDS User Guide posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. -- &ctlibapisgml; ++ +Function is implemented. Completely, we claim. + + + - - -- -- ODBC API Implementation Summary -- Microsoft's ODBC documentation is -- online. ++ + + + db-lib API Implementation Summary + @@ -172130,38 +172295,11 @@ + and can be + downloaded + as a PDF file. - -- The functions are linked to the reference page on Microsoft's website. Links such as these are quite perishable. Should you find them broken, please check the FreeTDS User Guide posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. -- &odbcapisgml; ++ + Links such as these are quite perishable. Should you find them broken, please check the FreeTDS User Guide posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. + &dblibapisgml; - - -- -- DB-Library for the Tenderfoot -- Mark Twain -- Few things are harder to put up with than the annoyance of a good example. -- -- Below is a complete sample working db-lib program, presented as a series of examples. -- Features of sample code -- Processes command-line options to select the server, database, username, and password -- Remaining arguments on the command line comprise the SQL query to execute -- Installs error and message handlers -- Illustrates correct row-processing -- Illustrates correct error detection and handling -- -- Other sample code may be found in the distribution, in the cleverly named samples directory. A complete program, heavily commented for your perusal, is apps/bsqldb.c. -- -- What's the big deal with errors? -- Correct handling of errors is extremely important in database applications because they involve two systems most others don't: the network and the database server. Both can give rise to errors that, if not detected and reported when they occur, let the application proceed blithely on until something truly mysterious happens. In the worst case, in the absence of a properly reported error, the application may seem to have updated the data, when in fact it did not. -- Every db-lib application uses the network, making it subject to network failures. Database programs also almost always have very high data integrity requirements. It is necessary to know the row was absolutely, positively committed, once and only once, without error or exception. Without taking great care to trap and handle all error conditions, no statement about the program's reliability can be made with confidence. -- -- -- How to Get and Build the sample code -- Run doc/grep_sample_code to extract the C code from the User Guide SGML source. -- Compile -- Link -- ++ + + + ct-lib API Implementation Summary + @@ -172170,7 +172308,20 @@ + and in PDF form. Links such as these are quite perishable. Should you find them broken, please check the FreeTDS User Guide posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. + &ctlibapisgml; + -+ + +- +- Initialization Notes +- +- Always make dbinit() the first db-lib call. +- +- Install the error- and mesage-handlers right away. They're explained in more detail later. +- +- dblogin() almost never fails. +-But check! No point in trying to use a null pointer. +- +- The LOGIN record isn't directly accessible. It's populated via macros like these. There are other fields, but these two are essential. Look for SETLsomething in the documentation. +- +- + + ODBC API Implementation Summary + @@ -172202,7 +172353,7 @@ +What's the big deal with errors? + +Correct handling of errors is extremely important in database applications because they involve two systems most others don't: the network and the database server. Both can give rise to errors that, if not detected and reported when they occur, let the application proceed blithely on until something truly mysterious happens. In the worst case, in the absence of a properly reported error, the application may seem to have updated the data, when in fact it did not. - ++ +Every db-lib application uses the network, making it subject to network failures. Database programs also almost always have very high data integrity requirements. It is necessary to know the row was absolutely, positively committed, once and only once, without error or exception. Without taking great care to trap and handle all error conditions, no statement about the program's reliability can be made with confidence. + + @@ -172212,33 +172363,14 @@ + Link + + - Files Required to Build the Sample Code -- sybfront.h ++ Files Required to Build the Sample Code + sybfront.h - sybdb.h -- libsybdb.a or libsybdb.so -- -- Your library's extension may vary according to your operating system. -- -- The source code may be built with commands similar to these. The precise options and paths depend on your particular system. The commands below work with the GNU compiler and linker on an ELF system with dynamic linking, common on Linux and BSD systems. --Building the Sample Code -- -- $ ../doc/grep_sample_code ../doc/userguide.sgml > sample.c -- $ cc -I /usr/local/include -Wl,-L/usr/local/lib -Wl,-R/usr/local/lib sample.c -lsybdb -o sample -- -- -- where /usr/local/include and /usr/local/lib are respectively the locations of your header files and libraries. -- -- -- We now proceed to the code proper. -- ++ sybdb.h + libsybdb.a or libsybdb.so + + Your library's extension may vary according to your operating system. + - -- Header files -- We need two header files to use db-lib. We need a few others to deal with I/O in C, as you know. Also declare the error and message handler functions, more about which later. ++ +The source code may be built with commands similar to these. The precise options and paths depend on your particular system. The commands below work with the GNU compiler and linker on an ELF system with dynamic linking, common on Linux and BSD systems. + Building the Sample Code + @@ -172247,10 +172379,7 @@ + + where /usr/local/include and /usr/local/lib are respectively the locations of your header files and libraries. + - -- -- Sample Code: <symbol>db-lib</> header files -- ++ +We now proceed to the code proper. + + Header files @@ -172260,49 +172389,39 @@ + + Sample Code: <symbol>db-lib</> header files + - - #include -@@ -3536,36 +3426,36 @@ the extent to which it is implemented. The Status field may be: - #include - #include - #include --]]> -- ++ ++#include ++#include ++#include ++#include ++#include ++#include + ]]> + - #include <sybfront.h> /* sybfront.h always comes first */ - #include <sybdb.h> /* sybdb.h is the only other file you need */ - - int err_handler(DBPROCESS*, int, int, int, char*, char*); - int msg_handler(DBPROCESS*, DBINT, int, int, char*, char*, char*, int); -- -- ++#include <sybfront.h> /* sybfront.h always comes first */ ++#include <sybdb.h> /* sybdb.h is the only other file you need */ ++ ++int err_handler(DBPROCESS*, int, int, int, char*, char*); ++int msg_handler(DBPROCESS*, DBINT, int, int, char*, char*, char*, int); + + + Prolog + Nothing special here. Collect the command line parameters. We do this with the standard getopts(3) function. Cf. man 3 getopts for details. - -- Prolog -- Nothing special here. Collect the command line parameters. We do this with the standard getopts(3) function. Cf. man 3 getopts for details. ++ + +- Connect to the server +- dbopen() forms a connection with the server. We pass our LOGINREC pointer (which describes the client end), and the name of the server. Then, optionally, we change to our favored database. If that step is skipped, the user lands in his default database. - -- -- Sample Code: <symbol>db-lib</> prolog -- --extern char *optarg; --extern int optind; -- --const static char syntax[] = -- "syntax: example -S server -D db -U user -P passwd\n"; -- --struct { -- char *appname, *servername, *dbname, *username, *password; --} options = {0,0,0,0,0}; - --int --main(int argc, char *argv[]) --{ +- +- Sample Code: <symbol>db-lib</> Connect to the server +- +- if ((dbproc = dbopen(login, options.servername)) == NULL) { +- fprintf(stderr, "%s:%d: unable to connect to %s as %s\n", +- options.appname, __LINE__, +- options.servername, options.username); +- exit(1); + + Sample Code: <symbol>db-lib</> prolog + @@ -172319,31 +172438,14 @@ + int + main(int argc, char *argv[]) + { - int i, ch; - LOGINREC *login; - DBPROCESS *dbproc; -@@ -3574,1390 +3464,1703 @@ main(int argc, char *argv[]) - options.appname = basename(argv[0]); - - while ((ch = getopt(argc, argv, "U:P:S:D:")) != -1) { -- switch (ch) { -- case 'S': -- options.servername = strdup(optarg); -- break; -- case 'D': -- options.dbname = strdup(optarg); -- break; -- case 'U': -- options.username = strdup(optarg); -- break; -- case 'P': -- options.password = strdup(optarg); -- break; -- case '?': -- default: -- fprintf(stderr, syntax); -- exit(1); -- } ++ int i, ch; ++ LOGINREC *login; ++ DBPROCESS *dbproc; ++ RETCODE erc; ++ ++ options.appname = basename(argv[0]); ++ ++ while ((ch = getopt(argc, argv, "U:P:S:D:")) != -1) { + switch (ch) { + case 'S': + options.servername = strdup(optarg); @@ -172361,49 +172463,31 @@ + default: + fprintf(stderr, syntax); + exit(1); - } -- -+ } -+ - argc -= optind; - argv += optind; - - if (! (options.servername -- && options.username && options.password)) { -- fprintf(stderr, syntax); -- exit(1); ++ } ++ } ++ ++ argc -= optind; ++ argv += optind; ++ ++ if (! (options.servername + && options.username && options.password)) { + fprintf(stderr, syntax); + exit(1); } -- -- Prolog Notes -- -- LOGINREC is a structure that describes the client. It's passed to the server at connect time. -- -- DBPROCESS is a structure that describes the connection. It is returned by dbopen(). -- -- RETCODE is the most common return code type for db-lib functions. -- -- -- + + Prolog Notes + -+ + +- if (options.dbname && (erc = dbuse(dbproc, options.dbname)) == FAIL) { +- fprintf(stderr, "%s:%d: unable to use to database %s\n", +- options.appname, __LINE__, options.dbname); +- exit(1); +LOGINREC is a structure that describes the client. It's passed to the server at connect time. + - -- Initialize -- Initialize the library. Create and populate a LOGINREC record. -- -- -- Sample Code: <symbol>db-lib</> Initialize -- ++ +DBPROCESS is a structure that describes the connection. It is returned by dbopen(). + - -- ++ +RETCODE is the most common return code type for db-lib functions. + + @@ -172417,61 +172501,36 @@ + + + - if (dbinit() == FAIL) { -- fprintf(stderr, "%s:%d: dbinit() failed\n", -- options.appname, __LINE__); -- exit(1); ++ if (dbinit() == FAIL) { + fprintf(stderr, "%s:%d: dbinit() failed\n", + options.appname, __LINE__); + exit(1); - } - -- ++ } ++ + - dberrhandle(err_handler); - dbmsghandle(msg_handler); -- -- ++ dberrhandle(err_handler); ++ dbmsghandle(msg_handler); + + - if ((login = dblogin()) == NULL) { -- fprintf(stderr, "%s:%d: unable to allocate login structure\n", -- options.appname, __LINE__); -- exit(1); ++ if ((login = dblogin()) == NULL) { + fprintf(stderr, "%s:%d: unable to allocate login structure\n", + options.appname, __LINE__); + exit(1); } -- -- -- Initialization Notes -- -- Always make dbinit() the first db-lib call. -- -- Install the error- and mesage-handlers right away. They're explained in more detail later. -- -- dblogin() almost never fails. --But check! No point in trying to use a null pointer. -- -- The LOGIN record isn't directly accessible. It's populated via macros like these. There are other fields, but these two are essential. Look for SETLsomething in the documentation. -- -- ++ DBSETLUSER(login, options.username); ++ DBSETLPWD(login, options.password); + + + Initialization Notes + -+ + +Always make dbinit() the first db-lib call. + -+ + +- +- +Install the error- and mesage-handlers right away. They're explained in more detail later. + + @@ -172487,44 +172546,25 @@ + dbopen() forms a connection with the server. We pass our LOGINREC pointer (which describes the client end), and the name of the server. Then, optionally, we change to our favored database. If that step is skipped, the user lands in his default database. + -- Connect to the server -- dbopen() forms a connection with the server. We pass our LOGINREC pointer (which describes the client end), and the name of the server. Then, optionally, we change to our favored database. If that step is skipped, the user lands in his default database. -- -- -- Sample Code: <symbol>db-lib</> Connect to the server -- +- Send a query + + Sample Code: <symbol>db-lib</> Connect to the server + - if ((dbproc = dbopen(login, options.servername)) == NULL) { -- fprintf(stderr, "%s:%d: unable to connect to %s as %s\n", -- options.appname, __LINE__, -- options.servername, options.username); -- exit(1); ++ if ((dbproc = dbopen(login, options.servername)) == NULL) { + fprintf(stderr, "%s:%d: unable to connect to %s as %s\n", + options.appname, __LINE__, + options.servername, options.username); + exit(1); - } -- -+ - if (options.dbname && (erc = dbuse(dbproc, options.dbname)) == FAIL) { -- fprintf(stderr, "%s:%d: unable to use to database %s\n", -- options.appname, __LINE__, options.dbname); -- exit(1); ++ } ++ ++ if (options.dbname && (erc = dbuse(dbproc, options.dbname)) == FAIL) { + fprintf(stderr, "%s:%d: unable to use to database %s\n", + options.appname, __LINE__, options.dbname); + exit(1); - } -- -- -- -- ++ } + + - -- -- Send a query ++ + + Send a query db-lib maintains a command buffer to hold the SQL to be sent to the server. Two functions — dbcmd() and dbfcmd() — build up the query from strings of text. The command buffer is reset after the query is sent to the server. @@ -173110,6 +173150,9 @@ + +Fetch All Rows! + db-lib doesn't insist every column — or even any column — be bound or otherwise retrieved into the application's variables. There is, however, one absolutely crucial, inflexible, unalterable requirement: the application must process all rows produced by the query. Before the DBPROCESS can be used for another query, the application must either fetch all rows, or cancel the results and receive an acknowledgement from the server. Cancelling is beyond the scope of this document, so for now fetch all rows. ++ ++ ++Now, at last, some sample code that fetches data. In the interest of simplicity, we don't bind anything except regular rows. - if (SYBCHAR != pcol->type) { - pcol->size = dbwillconvert(pcol->type, SYBCHAR); @@ -173130,9 +173173,6 @@ - exit(1); - } + -+Now, at last, some sample code that fetches data. In the interest of simplicity, we don't bind anything except regular rows. -+ -+ + + Sample Code: <symbol>db-lib</> Fetch Results + @@ -174803,12 +174843,7 @@ + + PREAMBLE + - -- If you have no Invariant Sections, write "with no Invariant -- Sections" instead of saying which ones are invariant. If you have -- no Front-Cover Texts, write "no Front-Cover Texts" instead of -- "Front-Cover Texts being LIST"; likewise for Back-Cover -- Texts. ++ +The purpose of this License is to make a manual, textbook, + or other written document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, @@ -174819,18 +174854,22 @@ + others. + +- If you have no Invariant Sections, write "with no Invariant +- Sections" instead of saying which ones are invariant. If you have +- no Front-Cover Texts, write "no Front-Cover Texts" instead of +- "Front-Cover Texts being LIST"; likewise for Back-Cover +- Texts. ++This License is a kind of "copyleft", which means that ++ derivative works of the document must themselves be free in the ++ same sense. It complements the GNU General Public License, which ++ is a copyleft license designed for free software. ++ + - If your document contains nontrivial examples of program - code, we recommend releasing these examples in parallel under your - choice of free software license, such as the GNU General Public - License, to permit their use in free software. - -+This License is a kind of "copyleft", which means that -+ derivative works of the document must themselves be free in the -+ same sense. It complements the GNU General Public License, which -+ is a copyleft license designed for free software. -+ - -- +We have designed this License in order to use it for manuals + for free software, because free software needs free documentation: + a free program should come with manuals providing the same @@ -174844,7 +174883,8 @@ + + APPLICABILITY AND DEFINITIONS + -+ + +- +This License applies to any manual or other work that + contains a notice placed by the copyright holder saying it can be + distributed under the terms of this License. The "Document",