README

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