X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Ffrontend.xml;h=297c5f3b06ed17a528fd4f25dee4fad36380e329;hb=6ba14eb5dc7229aa17977882024a475b6d258368;hp=391ca9dbb5b49a0bed07d96899c9bf480cd43f73;hpb=3b3deb4d093d747360a5eb0e02c6b4e9c8a89b84;p=yaz-moved-to-github.git diff --git a/doc/frontend.xml b/doc/frontend.xml index 391ca9d..297c5f3 100644 --- a/doc/frontend.xml +++ b/doc/frontend.xml @@ -1,14 +1,12 @@ - - Making an IR Server for Your Database + + Generic server Introduction If you aren't into documentation, a good way to learn how the back end interface works is to look at the backend.h file. Then, look at the small dummy-server in - ztest/ztest.c. Finally, you can have a look at - the seshigh.c file, which is where most of the - logic of the frontend server is located. The backend.h + ztest/ztest.c. The backend.h file also makes a good reference, once you've chewed your way through the prose of this file. @@ -45,7 +43,7 @@ - The Database Frontend + The Database Frontend We refer to this software as a generic database frontend. Your @@ -102,22 +100,22 @@ - The Backend API + The Backend API - The headers files that you need to use the interface are in the - include/yaz directory. They are called - statserv.h and backend.h. They - will include other files from the include/yaz - directory, so you'll probably want to use the -I option of your - compiler to tell it where to find the files. When you run + The header file that you need to use the interface are in the + include/yaz directory. It's called + backend.h. It will include other files from + the include/yaz directory, so you'll + probably want to use the -I option of your compiler to tell it + where to find the files. When you run make in the top-level &yaz; directory, - everything you need to create your server is put the - lib/libyaz.a library. + everything you need to create your server is to link with the + lib/libyaz.la library. - Your main() Routine + Your main() Routine As mentioned, your main() routine can be quite brief. @@ -219,14 +217,14 @@ statserv_options_block *statserv_getcontrol(void); enum oid_proto default_proto; - Either PROTO_SR or - PROTO_Z3950. + Either PROTO_Z3950 or + PROTO_SR. Default is PROTO_Z39_50. int idle_timeout; - Maximum session idletime, in minutes. Zero indicates + Maximum session idle-time, in minutes. Zero indicates no (infinite) timeout. Default is 120 minutes. @@ -304,7 +302,7 @@ void statserv_setcontrol(statserv_options_block *block); - The Backend Functions + The Backend Functions For each service of the protocol, the backend interface declares one or @@ -344,6 +342,7 @@ typedef struct bend_initrequest Z_ReferenceId *referenceId;/* reference ID */ char *peer_name; /* dns host of peer (client) */ + char *implementation_id; char *implementation_name; char *implementation_version; int (*bend_sort) (void *handle, bend_sort_rr *rr); @@ -396,8 +395,9 @@ typedef struct bend_initresult The members peer_name, + implementation_id, implementation_name and - implementation_version holds DNS of client, name + implementation_version holds DNS of client, ID of implementor, name of client (Z39.50) implementation - and version. @@ -651,7 +651,7 @@ typedef enum { } bend_scan_status; typedef struct bend_scan_rr { - int num_bases; /* number of elements in databaselist */ + int num_bases; /* number of elements in database list */ char **basenames; /* databases to search */ oid_value attributeset; Z_ReferenceId *referenceId; /* reference ID */ @@ -672,7 +672,7 @@ typedef struct bend_scan_rr { - Application Invocation + Application Invocation The finished application has the following @@ -680,7 +680,7 @@ typedef struct bend_scan_rr { - appname [-szSiTu -a apdufile -l logfile -v loglevel -c config] + appname [-szSiT1 -u uid -a apdufile -l logfile -v loglevel -c config] [listener ...] @@ -689,14 +689,15 @@ typedef struct bend_scan_rr { - -a file + -a + apdufile Specify a file for dumping PDUs (for diagnostic purposes). The special name "-" sends output to stderr. - -S + -S Don't fork or make threads on connection requests. This is good for debugging, but not recommended for real operation: Although the @@ -705,19 +706,25 @@ typedef struct bend_scan_rr { current users. - -T + -1 + + Like -S but after one session the server + exits. This mode is for debugging only. + + + -T Operate the server in threaded mode. The server creates a thread for each connection rather than a fork a process. Only available on UNIX systems that offers POSIX threads. - -s + -s Use the SR protocol (obsolete). - -z + -z Use the Z39.50 protocol (default). These two options complement each other. You can use both multiple times on the same command @@ -726,11 +733,13 @@ typedef struct bend_scan_rr { concurrently, on different local ports. - -l file + -l + file The logfile. - -c config + -c + config A user option that serves as a specifier for some sort of configuration, e.g. a filename. The argument to this option is transferred to member @@ -738,13 +747,15 @@ typedef struct bend_scan_rr { statserv_options_block. - -v level + -v + level The log level. Use a comma-separated list of members of the set - {fatal,debug,warn,log,all,none}. + {fatal,debug,warn,log,malloc,all,none}. - -u userid + -u + uid Set user ID. Sets the real UID of the server process to that of the given user. It's useful if you aren't comfortable with having the @@ -752,37 +763,58 @@ typedef struct bend_scan_rr { privileged port. - -w dir + -w + dir - Working directory. + The server changes to this directory during before listening + on incoming connections. This option is useful + when the server is operating from the inetd + daemon (see -i). - -i + -i - Use this when running from the inetd server. + Use this to make the the server run from the + inetd server (UNIX only). - - -t minutes + + -install + + Use this to install the server as an NT service + (Windows 2000/NT only). + Control the server by going to the Services in the Control Panel. + + + -remove + + Use this to remove the server from the NT services + (Windows 2000/NT only). + + + -t + minutes Idle session timeout, in minutes. - - -k size + + -k + size Maximum record size/message size, in kilobytes. - + - + A listener specification consists of a transport mode followed by a colon (:) followed by a listener address. The transport mode is - either osi or tcp. + either tcp, unix: or + ssl. - + - For TCP, an address has the form + For TCP and SSL, an address has the form @@ -794,18 +826,9 @@ typedef struct bend_scan_rr { - For osi, the address form is - - - - [t-selector /] hostname | IP-number [: portnumber] - - - - The transport selector is given as a string of hex digits (with an even - number of digits). The default port number is 102 (RFC1006 port). + For UNIX local socket the address is the name local file. - + Examples @@ -813,27 +836,15 @@ typedef struct bend_scan_rr { tcp:dranet.dra.com - osi:0402/dbserver.osiworld.com:3000 - - - - In both cases, the special hostname "@" is mapped to - the address INADDR_ANY, which causes the server to listen on any local - interface. To start the server listening on the registered ports for - Z39.50 and SR over OSI/RFC1006, and to drop root privileges once the - ports are bound, execute the server like this (from a root shell): - + ssl:ssl.enterprise.com:3000 - - my-server -u daemon tcp:@ -s osi:@ + unix:/tmp/yaz - You can replace daemon with another user, eg. your - own account, or a dedicated IR server account. - my-server should be the name of your - server application. You can test the procedure with the - yaz-ztest application. + For TCP/IP and SSL, the special hostname "@" is mapped to + the address INADDR_ANY, which causes the + server to listen on any local interface. @@ -849,7 +860,7 @@ typedef struct bend_scan_rr { sgml-indent-step:1 sgml-indent-data:t sgml-parent-document: "yaz.xml" - sgml-local-catalogs: "../../docbook/docbook.cat" + sgml-local-catalogs: nil sgml-namecase-general:t End: -->