X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fcomstack.xml;h=9ae8df09538d89a092cbf93bc1c553b493e2073c;hp=671788a5854eab64040cb7d8c3e517f3c6d00c24;hb=33c05384cfbca55da4ff97e5b2047b16596c72f7;hpb=e1f879d00e75be3b5b9f3ecc22b34cc0c1c61aec diff --git a/doc/comstack.xml b/doc/comstack.xml index 671788a..9ae8df0 100644 --- a/doc/comstack.xml +++ b/doc/comstack.xml @@ -1,7 +1,7 @@ - - The COMSTACK Module + + The COMSTACK Module - Synopsis (blocking mode) + Synopsis (blocking mode) @@ -52,7 +52,7 @@ if (buf) - Introduction + Introduction The &comstack; @@ -87,7 +87,7 @@ if (buf) - Common Functions + Common Functions Managing Endpoints @@ -277,7 +277,7 @@ if (buf) - Client Side + Client Side int cs_connect(COMSTACK handle, void *address); @@ -305,7 +305,7 @@ if (buf) - Server Side + Server Side To establish a server under the inetd server, you @@ -378,7 +378,7 @@ if (buf) - Addresses + Addresses The low-level format of the addresses are different depending on the @@ -465,7 +465,7 @@ if (buf) - Diagnostics + Diagnostics All functions return -1 if an error occurs. Typically, the functions @@ -510,169 +510,7 @@ if (buf) provided. - - Enabling OSI Communication - - Installing Xtimosi - - Although you will have to down-load Peter Furniss' XTI/mOSI - implementation for yourself, we've tried to make the integration as - simple as possible. - - - - The latest version of xtimosi will generally be under - - - - ftp://pluto.ulcc.ac.uk/ulcc/thinosi/xtimosi/ - - - - When you have down-loaded and unpacked the archive, it will (we assume) - have created a directory called xtimosi. - We suggest that you place this directory in the same - directory where you unpacked the &yaz; - distribution. This way, you shouldn't have to fiddle with the - makefiles of &yaz; beyond uncommenting a few lines. - - - - Go to xtimosi/src, and type "make libmosi.a/". - This should generally create the library, ready to use. - - - - - The currently available release of xtimosi has some inherent - problems that make it disfunction on certain platforms - eg. the - Digital OSF/1 workstations. It is supposedly primarily a - compiler problem, and we hope to see a release that is generally - portable. While we can't guarantee that it can be brought to work - on your platform, we'll be happy to talk to you about problems - that you might see, and relay information to the author of the - software. There are some signs that the gcc - compiler is more likely to produce a fully functional library, but this - hasn't been verified (we think that the problem is limited to the use - of hexadecimal escape-codes used in strings, which are silently - ignored by some compilers). - - - A problem has been encountered in the communication with - ISODE-based applications. If the ISODE presentation-user calls - PReadRequest() with a timeout value different - from OK or NOTOK, - he will get an immediate TIMEOUT abort when receiving large (>2041 - bytes, which is the SPDU-size that the ISODE likes to work with) packages - from an xtimosi-based implementation (probably most - other implementations as well, in fact). It seems to be a flaw in the - ISODE API, and the workaround (for ISODE users) is to either not - use an explicit timeout (switching to either blocking or - nonblocking mode), or to check that the timer really has expired - before closing the connection. - - - - - The next step in the installation is to modify the makefile in the toplevel - &yaz; - directory. The place to change is in the top of the file, and is - clearly marked with a comment. - - - - Now run make in the &yaz; toplevel directory (do a - make clean first, if the system has been previously - made without OSI support). Use the &yaz; - yaz-ztest and yaz-client - demo programs to verify that OSI communication works OK. Then, you can go - ahead and try to talk to other implementations. - - - - - Our interoperability experience is limited to version - 7 of the Nordic SR-Nett package, which has had several - protocol errors fixed from the earlier releases. If you have - problems or successes in interoperating with other - implementations, we'd be glad to hear about it, or to help - you make things work, as our resources allow. - - - - - If you write your own applications based on &yaz;, and you wish to - include OSI support, the procedure is equally simple. You should - include the xmosi.h header file in addition to - comstack.h. xmosi.h - will define the manifest constant mosi_type, which you - should pass to the cs_create() function. In - addition, you should use the function mosi_strtoaddr() - rather than tcpip_strtoaddr() when you need to - prepare an address. - - - - When you link your application, you should include (after the - libyaz.a library) the libmosi.a - library, and the librfc.a library provided with - &yaz; (for OSI transport). - - - As always, it can be very useful, if not essential, to have a look at the - example applications to see how things are done. - - - - OSI Transport - - - Xtimosi requires an implementation of the OSI transport service under - the X/OPEN XTI API. We provide an implementation of the RFC1006 - encapsulation of OSI/TP0 in TCP/IP (through the Berkeley Sockets API), - as an independent part of &yaz; (it's found under the - rfc1006 directory). - If you have access to an OSI transport provider under XTI, - you should be able to make that work too, although it may require - tinkering with the mosi_strtoaddr() function. - - - - Presentation Context Management - - - To simplify the implementation, we use Peter Furniss' alternative (PRF) - option format - for the Control of the presentation negotiation phase. This format - is enabled by default when you - compile xtimosi. - - - - The current version of &yaz; does not support - presentation-layer negotiation of response record formats. The primary - reason is that we have had access to no other SR or Z39.50 - implementations over OSI that used this - method. Secondarily, we believe that the EXPLAIN facility is a superior - mechanism for relaying target capabilities in this respect. This is not to - say that we have no intentions of supporting presentation context - negotiation - we have just hitherto given it a lower priority than other - aspects of the protocol. - - - One thing is certain: The addition of this capability to &yaz; should - have only a minimal impact on existing applications, and on the - interface to the software in general. Most likely, we will add an extra - layer of interface to the processing of EXPLAIN records, which will - convert back and forth between oident records (see - section Object Identifiers) and direct or - indirect references, given the current association setup. Implementations - based on any of the higher-level interfaces will most likely not have to - be changed at all. - - - - Summary and Synopsis + Summary and Synopsis #include <comstack.h>