README.txt

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