Debian package
[yazpp-moved-to-github.git] / 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.