psqlODBC 16 for RISC OS
=======================

This is a port of the PostgreSQL ODBC driver psqlODBC 16.00.0000, with the
libpq client library from PostgreSQL 16.15, to the RISC OS !ODBC manager.
It is built as a Rink segment that the manager's iODBC loader loads from
ODBC$DriverDir, in the same way as the earlier psqlodbc ports.

Sources
-------
  psqlODBC  https://ftp.postgresql.org/pub/odbc/versions.old/src/psqlodbc-16.00.0000.tar.gz
  libpq     https://ftp.postgresql.org/pub/source/v16.15/postgresql-16.15.tar.bz2

Only the files needed by the driver are included.  RISC OS changes are
marked with RISCOS conditionals.  New files are:

  h.config, h.pg_config*, h.pg_config_paths
                       RISC OS configuration (32 bit, single threaded)
  c.netdb              IPv4 getaddrinfo/getnameinfo using gethostbyname
  c.getcwd             getcwd using OS_FSControl 37
  c.pg_strong_random   random bytes from the CryptRandom module

Building
--------
Needs Acorn C/C++ (Norcroft) with C99 support, TCPIPLibs, CLibSupport,
the iODBC headers and rink.  Build from Sourcery, or run amu with
Makefile32 from the Source directory.  The driver's headers are in
Source.h.  PostgreSQL headers that are included by path, such as
"common/base64.h", are in the separate ^.pgincludes directory
(common, lib, libpq, mb, port, utils), because Sourcery projects only
have a single h directory.  It is on the include path as
HostFS::Tardis.$.Files.Develop.Projects.Libraries.ODBC.Drivers.PostgreSQL.psqlodbc16000000.pgincludes
in Sourcery.Includes and the Makefiles; change it there if your tree is
elsewhere.  PostgreSQL's c.h and port.h are renamed cheader.h
and pgport.h so their names don't clash with the c and port
directories.  Source.h.riscostypes lets the driver build against both
current TCPIPLibs and releases from before 2002 (which clash with
<stdint.h> and lack socklen_t and getaddrinfo).

Link with newrink 0.17 from Projects.Utilities.newrink, built with -via
and -l support, not the older two file rink in Projects.Utilities.rink:
!ODBC only loads newrink's single file segments.  Sourcery's rink tool
passes the object list with -via and names the output with -l, so the
result is the single file psqlodbclnk, which goes in

  driver.psqlodbc16000000.psqlodbclnk

Installing
----------
1. Copy the driver.psqlodbc16000000 directory into !ODBC.Drivers using !ODBCMan
2. Add the [PostgreSQL16] section from odbcinst.ini to the manager's
   odbcinst.ini, or create a data source with !ODBCMan.
3. Use Driver = <ODBC$DriverDir>.psqlodbc16000000.psqlodbc in odbc.ini,
   and set UnloadSafe = 1 so that !ODBC unloads the driver when the
   last client disconnects, or add in !ODBCMan.

The older psqlodbc drivers can stay installed alongside this one.

Configuration files
-------------------
The driver reads its settings through iODBC from Choices:ODBC.odbc/ini
(or the file named by ODBCINI), like the 7.5 driver.  In a data source
section, Servername is the host, Port the TCP port and Database only the
database name.

  Logs (Debug, CommLog)  <ODBC$LogDir>, or Logdir in the data source;
                         <Wimp$ScrapDir> if that can't be opened.
                         Names are mylog_<task>_<pid>/log and
                         psqlodbc_<task>_<pid>/log.
  Password file          Choices:ODBC.pgpass, in the libpq .pgpass
                         format (host:port:database:user:password).
                         PGPASSFILE or the passfile keyword override it.
  Service file           Choices:ODBC.pg_service/conf, then
                         <ODBC$Dir>.pg_service/conf.

Socket errors are reported with the TCPIPLibs message, for example
"Connection refused", as the C library has no text for them.

Requirements and limitations
----------------------------
- Needs PostgreSQL 7.4 or later on the server (protocol 3).
- TCP/IP only.  Unix domain sockets are not supported, so Servername must
  be set.
- IPv4 only.
- No SSL/TLS or GSSAPI: set SSLmode = disable (or allow/prefer).  The
  server must not require hostssl connections.
- SCRAM-SHA-256 authentication, which PostgreSQL 16 uses by default, needs
  the CryptRandom module to be loaded.  Without it the connection fails
  with "could not generate nonce".  MD5, password and trust authentication
  do not need CryptRandom.
- ANSI driver only (no Unicode/W entry points).
- Single threaded.  The driver must only be used by one task at a time.
- Large objects (lo_*) and PQprint are not included.
- The ODBC 2 entry points (SQLAllocEnv, SQLError, SQLTransact and so on)
  are not exported, as in psqlODBC 16 itself.  iODBC maps them to the
  ODBC 3 functions.

Licence
-------
psqlODBC is distributed under the GNU Lesser General Public License
(license.txt).  libpq is under the PostgreSQL licence (COPYRIGHT).
