README.txt

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