README

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