README

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