README

   1 YAZ++ - A C++ library for YAZ and a ZOOM C++ API.
   2
   3 $Id: README,v 1.5 2004-03-31 21:30:45 mike Exp $
   4
   5 Introduction
   6 ------------
   7
   8 YAZ++ is a set of libraries and header files that make it easier to
   9 use the the YAZ toolkit from C++, together with some utilities written
  10 using these libraries. It includes an implementation of the C++ binding
  11 for ZOOM and a powerful general-purpose Z39.50/SRW/SRU proxy.
  12
  13 YAZ++ and ZOOM C++ use the same BSD-like license as YAZ - see LICENSE
  14 file for details.
  15
  16 The proxy application and development library is covered by the
  17 GPL - see LICENSE.proxy for details.
  18
  19 Documentation
  20 -------------
  21
  22 The "doc" directory contains documentation in HTML and PDF.
  23 You can also read it online at http://www.indexdata.dk/yaz++/
  24
  25 Overview
  26 --------
  27
  28 YAZ++ builds a programmers' library libyaz++.lib and a few
  29 applications:
  30
  31   yaz-my-client      basic client
  32   yaz-my-server      basic server
  33   yaz-proxy          Z39.50/SRW/SRU proxy.
  34
  35 Directory structure of the YAZ++ package:
  36
  37   -- src (C++ library)
  38   -- zoom (C++ source for ZOOM)
  39   -- proxy (C++ source for proxy)
  40   -- include/yaz++ (C++ headers)
  41   -- include/yaz++/proxy (C++ headers for proxy)
  42   -- lib (compiled libraries)
  43   -- win (Windows build files)
  44   -- doc (DocBook-format documentation)
  45   -- etc (Proxy config + XSLT files)
  46
  47 Installation, Unix
  48 ------------------
  49
  50 Make sure you have a C and C++ compiler available. gcc and g++ work fine.
  51
  52 Before compilation can take place YAZ must be installed. It goes, roughly,
  53 like this:
  54
  55   $ cd yaz-<version>
  56   $ ./configure
  57   $ make
  58   $ su
  59   # make install
  60   $ ^D
  61   $ cd ..
  62
  63 The YAZ proxy uses a configuration file in XML and libxml2 and libxslt
  64 is required in order for the config facility to work. Many systems already
  65 have libxml2/libxslt installed. In that, case remember to get the devel
  66 version of that as well (not just the runtime). Libxml2/libxslt can also be
  67 compiled easily on most systems. See http://www.xmlsoft.org/ for more
  68 information.
  69
  70 Then build YAZ++:
  71
  72   $ cd yaz++-<version>
  73   $ ./configure
  74   $ make
  75
  76 If you do have libxslt installed and configure above does not find it,
  77 use option --with-xslt=PREFIX to specify location of libxslt (which includes
  78 libxml2). The configure script looks for PREFIX/bin/xslt-config.
  79
  80 Installation, Windows
  81 ---------------------
  82
  83 YAZ++ for WIN32 should run on Windows 95/98/2K and Windows NT 4.0.
  84 Yaz++ was built using Microsoft Visual C++ 6.0. Other compilers
  85 should work but makefile/project files will have to be created for
  86 those compilers.
  87
  88   Workspace yazxx.dsw includes the projects
  89     yazxx.dsp       -   builds yazxx.dll
  90     yazclient.dsp   -   builds yazmyclient.exe
  91     yazserver.dsp   -   builds yazmyserver.exe
  92     yazproxy.dsp    -   builds yazproxy.exe
  93
  94 About the proxy
  95 ---------------
  96
  97 For the proxy the actual target is determined in by the OtherInfo
  98 part of the InitRequest. We've defined an OID for this which we call
  99 PROXY. The OID is 1.2.840.10003.10.1000.81.1.
 100
 101   OtherInformation   ::= [201] IMPLICIT SEQUENCE OF SEQUENCE{
 102     category           [1]   IMPLICIT InfoCategory OPTIONAL,
 103     information        CHOICE{
 104       characterInfo            [2]  IMPLICIT InternationalString,
 105       binaryInfo               [3]  IMPLICIT OCTET STRING,
 106       externallyDefinedInfo    [4]  IMPLICIT EXTERNAL,
 107       oid                      [5]  IMPLICIT OBJECT IDENTIFIER}}
 108 --
 109   InfoCategory ::= SEQUENCE{
 110       categoryTypeId   [1]   IMPLICIT OBJECT IDENTIFIER OPTIONAL,
 111       categoryValue    [2]   IMPLICIT INTEGER}
 112
 113 The InfoCategory is present with categoryTypeId set to the PROXY OID
 114 and categoryValue set to 0. The information in OtherInformation uses
 115 characterInfo to represent the target using the form target[:port][/db].
 116
 117 For clients that don't set the PROXY OtherInformation, a default
 118 target can be specified using option -t for proxy.
 119
 120 Example:
 121   We start the proxy so that it listens on port 9000. The default
 122   target is Bell Labs Library unless it is overridden by a client in
 123   the InitRequest.
 124
 125      $ ./yaz-proxy -t z3950.bell-labs.com/books @:9000
 126
 127   The client is started and talks to the proxy without specifying
 128   a target. Hence this client will talk to the Bell Labs server.
 129
 130      $ ./yaz-client localhost:9000
 131
 132   The client is started and it specifies the actual target itself.
 133
 134      $ ./yaz-client -p localhost:9000 bagel.indexdata.dk/gils
 135
 136   For ZAP the equivalent would be
 137      proxy=localhost:9000
 138      target=bagel.indexdata.dk/gils
 139   Simple, huh!
 140
 141
 142 ZOOM-C++
 143 --------
 144
 145 The ZOOM library in this distribution implements the ZOOM C++ binding
 146 described on the ZOOM web-site at
 147         http://zoom.z3950.org/bind/cplusplus/index.html
 148 It provides a simple but powerful API for constructing Z39.50 client
 149 applications.  See the documentation in doc/zoom.xml for much more
 150 information.