YAZ This extension offers a PHP interface to the YAZ toolkit that implements the Z39.50 protocol for information retrieval. With this extension you can easily implement a Z39.50 origin (client) that searches or scans Z39.50 targets (servers) in parallel. YAZ is available at &url.yaz;. You can find news information, example scripts, etc. for this extension at &url.yaz-phpyaz;. The module hides most of the complexity of Z39.50 so it should be fairly easy to use. It supports persistent stateless connections very similar to those offered by the various SQL APIs that are available for PHP. This means that sessions are stateless but shared amongst users, thus saving the connect and initialize phase steps in most cases. Compile YAZ and install it. Build PHP with your favourite modules and add option --with-yaz. Your task is roughly the following: gunzip -c yaz-1.6.tar.gz|tar xf - gunzip -c php-4.0.X.tar.gz|tar xf - cd yaz-1.6 ./configure --prefix=/usr make make install cd ../php-4.0.X ./configure --with-yaz=/usr/bin make make install PHP/YAZ keeps track of connections with targets (Z-Associations). A positive integer represents the ID of a particular association. The script below demonstrates the parallel searching feature of the API. When invoked with no arguments it prints a query form; else (arguments are supplied) it searches the targets as given in in array host. $num_hosts = count ($host); if (empty($term) || count($host) == 0) { echo '<form method="get"> <input type="checkbox" name="host[]" value="bagel.indexdata.dk/gils"> GILS test <input type="checkbox" name="host[]" value="localhost:9999/Default"> local test <input type="checkbox" checked="1" name="host[]" value="z3950.bell-labs.com/books"> BELL Labs Library <br> RPN Query: <input type="text" size="30" name="term"> <input type="submit" name="action" value="Search"> '; } else { echo 'You searced for ' . htmlspecialchars($term) . '<br>'; for ($i = 0; $i < $num_hosts; $i++) { $id[] = yaz_connect($host[$i]); yaz_syntax($id[$i],"sutrs"); yaz_search($id[$i],"rpn",$term); } yaz_wait(); for ($i = 0; $i < $num_hosts; $i++) { echo '<hr>' . $host[$i] . ":"; $error = yaz_error($id[$i]); if (!empty($error)) { echo "Error: $error"; } else { $hits = yaz_hits($id[$i]); echo "Result Count $hits"; } echo '<dl>'; for ($p = 1; $p <= 10; $p++) { $rec = yaz_record($id[$i],$p,"string"); if (empty($rec)) continue; echo "<dt><b>$p</b></dt><dd>"; echo ereg_replace("\n", "<br>\n",$rec); echo "</dd>"; } echo '</dl>'; } } yaz_addinfo Returns additional error information int yaz_addinfo int id Returns additional error message for target (last request). An empty string is returned if last operation was a success or if no additional information was provided by the target. yaz_close Closes a YAZ connection int yaz_close int id Closes the Z-association given by id. The id is a target ID as returned by a previous yaz_connect command. yaz_connect Prepares for a connection and Z-association to a Z39.50 target. int yaz_connect string zurl string authentication This function returns a positive ID on success; zero on failure. Yaz_connect prepares for a connection to a Z39.50 target. The zurl argument takes the form host[:port][/database]. If port is omitted 210 is used. If database is omitted Default is used. This function is non-blocking and doesn't attempt to establish a socket - it merely prepares a connect to be performed later when yaz_wait is called. yaz_errno Returns error number int yaz_errno int id Returns error for target (last request). A positive value is returned if the target returned a diagnostic code; a value of zero is returned if no errors occurred (success); negative value is returned for other errors (such as when the target closed connection, etc). yaz_errno should be called after network activity for each target - (after yaz_wait returns) to determine the success or failure of the last operation (e.g. search). yaz_error Returns error description string yaz_error int id Returns error message for target (last request). An empty string is returned if last operation was a success. yaz_error returns an english text message corresponding to the last error number as returned by yaz_errno. yaz_hits Returns number of hits for last search int yaz_hits int id Yaz_hits returns number of hits for last search. yaz_element Specifies Element-Set Name for retrieval int yaz_element int id string elementset This function is used in conjunction with yaz_search and yaz_present to specify the element set name for records to be retrieved. Most servers support F (full) and B (brief). Returns true on success; false on error. yaz_database Specifies the databases within a session int yaz_database int id string databases This function specifies one or more databases to be used in search, retrieval, etc. - overriding databases specified in call to yaz_connect. Multiple databases are separated by a plus sign +. This function allows you to use different sets of databases within a session. Returns true on success; false on error. yaz_range Specifies the maximum number of records to retrieve int yaz_range int id int start int number This function is used in conjunction with yaz_search to specify the maximum number of records to retrieve (number) and the first record position (start). If this function is not invoked (only yaz_search) start is set to 1 and number is set to 10. Returns true on success; false on error. yaz_record Returns a record int yaz_record int id int pos string type Returns record at position or empty string if no record exists at given position. The yaz_record function inspects a record in the current result set at the position specified. If no database record exists at the given position an empty string is returned. The argument, type, specifies the form of the returned record. If type is "string" the record is returned in a string representation suitable for printing (for XML and SUTRS). If type is "array" the record is returned as an array representation (for structured records). yaz_search Prepares for a search int yaz_search int id string type string query yaz_search prepares for a search on the target with given id. The type represents the query type - only "rpn" is supported now in which case the third argument specifies a Type-1 query (RPN). Like yaz_connect this function is non-blocking and only prepares for a search to be executed later when yaz_wait is called. The RPN query is a textual represenation of the Type-1 query as defined by the Z39.50 standard. However, in the text representation as used by YAZ a prefix notation is used, that is the operater precedes the operands. The query string is a sequence of tokens where white space is ignored is ignored unless surrounded by double quotes. Tokens beginning with an at-character (@) are considered operators, otherwise they are treated as search terms. Syntax Description @and query1 query2 intersection of query1 and query2 @or query1 query2 union of query1 and query2 @not query1 query2 query1 and not query2 @set name result set reference @attrset set query specifies attribute-set for query. This construction is only allowed once - in the beginning of the whole query @attr set type=value query applies attribute to query. The type and value are integers specifying the attribute-type and attribute-value respectively. The set, if given, specifies the attribute-set. The following illustrates valid query constructions: computer Matches documents where "computer" occur. No attributes are specified. "donald knuth" Matches documents where "donald knuth" occur. @attr 1=4 art Attribute type is 1 (Bib-1 use), attribute value is 4 Title), so this should match documents where "art" occur in the title. @attrset gils @and @attr 1=4 art @attr 1=1003 "donald knuth" The query as a whole uses the GILS attributeset. The query matches documents where "art" occur in the title and in which "donald knuth" occur in the author. yaz_present Prepares for retrieval (Z39.50 present). int yaz_present This function prepares for retrieval of records after a successful search. The yaz_range should be called prior to this function to specify the range of records to be retrieved. yaz_syntax Specifies the preferred record syntax for retrieval. int yaz_syntax int id string syntax The syntax is specified as an OID (Object Identifier) in a raw dot-notation (like 1.2.840.10003.5.10) or as one of the known registered record syntaxes (sutrs, usmarc, grs1, xml, etc.). This function is used in conjunction with yaz_search and yaz_present to specify the preferred record syntax for retrieval. yaz_scan Prepares for a scan int yaz_scan int id string type string startterm array flags This function prepares for a Z39.50 Scan Request. Argument id specifies target ID. Starting term point for the scan is given by startterm. The form in which is the starting term is specified is given by type. Currently type rpn is supported. The optional flags specifies additional information to control the behaviour of the scan request. Three indexes are currently read from the flags: number (number of terms requested), position (preferred position of term) and stepSize (preferred step size). To actually tranfer the Scan Request to the target and receive the Scan Response, yaz_wait must be called. Upon completion of yaz_wait call yaz_error and yaz_scan_result to handle the response. The syntax of startterm is similar to the RPN query as described in yaz_search. The startterm consists of zero or more @attr-operator specifications, then followed by exactly one token. function scan_titles($id, $starterm) { yaz_scan($id,"rpn", "@attr 1=4 " . $starterm); yaz_wait(); $errno = yaz_errno($id); if ($errno == 0) { $ar = yaz_scan_result($id,&$options); echo 'Scan ok; '; $ar = yaz_scan_result($id, &$options); while(list($key,$val)=each($options)) { echo "$key = $val  "; } echo '<br><table><tr><td>'; while(list($key,list($k, $term, $tcount))=each($ar)) { if (empty($k)) continue; echo "<tr><td>$term</td><td>"; echo $tcount; echo "</td></tr>"; } echo '</table>'; } else { echo "Scan failed. Error: " . yaz_error($id) . "<br>"; } } yaz_scan_result Returns Scan Response result array yaz_scan_result int id array & result Given a target ID this function returns and array with terms as received from the target in the last Scan Response. This function returns an array (0..n-1) where n is the number of terms returned. Each value is a pair where first item is term, second item is result-count. If the result is given it will be modified to hold additional information taken from the Scan Response: number (number of entries returned), stepsize (Step-size), position (position of term), status (Scan Status). yaz_ccl_conf Configure CCL parser int yaz_ccl_conf int id array config This function configures the CCL query parser for a target with definitions of access points (CCL qualifiers) and their mapping to RPN. To map a specific CCL query to RPN afterwards call the yaz_ccl_parse function. Each index of the array config is the name of a CCL field and the corresponding value holds a string that specifies a mapping to RPN. The mapping is a sequence of attribute-type, attribute-value pairs. Attribute-type and attribute-value is separated by an equal sign (=). Each pair is separated by white space. In the example below, the CCL parser is configured to support three CCL fields: ti, au and isbn. Each field is mapped to their BIB-1 equivalent. It is assumed that variable $id is a target ID. $field["ti"] = "1=4"; $field["au"] = "1=1"; $field["isbn"] = "1=7"; yaz_ccl_conf($id,$field); yaz_ccl_parse Invoke CCL Parser int yaz_ccl_parse int id string query array &result This function invokes the CCL parser. It converts a given CCL FIND query to an RPN query which may be passed to the yaz_search function to perform a search. To define a set of valid CCL fields call yaz_ccl_conf prior to this function. If the supplied query was successfully converted to RPN, this function returns true, and the index rpn of the supplied array result holds a valid RPN query. If the query could not be converted (because of invalid syntax, unknown field, etc.) this function returns false and three indexes are set in the resulting array to indicate the cause of failure: errorcodeCCL error code (integer), errorstringCCL error string, and errorposapproximate position in query of failure (integer is character position). yaz_itemorder Prepares for Z39.50 Item Order with an ILL-Request package int yaz_itemorder array args This function prepares for an Extended Services request using the Profile for the Use of Z39.50 Item Order Extended Service to Transport ILL (Profile/1). See this and the specification. The args parameter must be a hash array with information about the Item Order request to be sent. The key of the hash is the name of the corresponding ASN.1 tag path. For example, the ISBN below the Item-ID has the key item-id,ISBN. The ILL-Request parameters are: protocol-version-num transaction-id,initial-requester-id,person-or-institution-symbol,person transaction-id,initial-requester-id,person-or-institution-symbol,institution transaction-id,initial-requester-id,name-of-person-or-institution,name-of-person transaction-id,initial-requester-id,name-of-person-or-institution,name-of-institution transaction-id,transaction-group-qualifier transaction-id,transaction-qualifier transaction-id,sub-transaction-qualifier service-date-time,this,date service-date-time,this,time service-date-time,original,date service-date-time,original,time requester-id,person-or-institution-symbol,person requester-id,person-or-institution-symbol,institution requester-id,name-of-person-or-institution,name-of-person requester-id,name-of-person-or-institution,name-of-institution responder-id,person-or-institution-symbol,person responder-id,person-or-institution-symbol,institution responder-id,name-of-person-or-institution,name-of-person responder-id,name-of-person-or-institution,name-of-institution transaction-type delivery-address,postal-address,name-of-person-or-institution,name-of-person delivery-address,postal-address,name-of-person-or-institution,name-of-institution delivery-address,postal-address,extended-postal-delivery-address delivery-address,postal-address,street-and-number delivery-address,postal-address,post-office-box delivery-address,postal-address,city delivery-address,postal-address,region delivery-address,postal-address,country delivery-address,postal-address,postal-code delivery-address,electronic-address,telecom-service-identifier delivery-address,electronic-address,telecom-service-addreess billing-address,postal-address,name-of-person-or-institution,name-of-person billing-address,postal-address,name-of-person-or-institution,name-of-institution billing-address,postal-address,extended-postal-delivery-address billing-address,postal-address,street-and-number billing-address,postal-address,post-office-box billing-address,postal-address,city billing-address,postal-address,region billing-address,postal-address,country billing-address,postal-address,postal-code billing-address,electronic-address,telecom-service-identifier billing-address,electronic-address,telecom-service-addreess ill-service-type requester-optional-messages,can-send-RECEIVED requester-optional-messages,can-send-RETURNED requester-optional-messages,requester-SHIPPED requester-optional-messages,requester-CHECKED-IN search-type,level-of-service search-type,need-before-date search-type,expiry-date search-type,expiry-flag place-on-hold client-id,client-name client-id,client-status client-id,client-identifier item-id,item-type item-id,call-number item-id,author item-id,title item-id,sub-title item-id,sponsoring-body item-id,place-of-publication item-id,publisher item-id,series-title-number item-id,volume-issue item-id,edition item-id,publication-date item-id,publication-date-of-component item-id,author-of-article item-id,title-of-article item-id,pagination item-id,ISBN item-id,ISSN item-id,additional-no-letters item-id,verification-reference-source copyright-complicance retry-flag forward-flag requester-note forward-note There are also a few parameters that are part of the Extended Services Request package and the ItemOrder package: package-name user-id contact-name contact-phone contact-email itemorder-item yaz_wait Wait for Z39.50 requests to complete int yaz_wait This function carries out networked (blocked) activity for outstanding requests which have been prepared by the functions yaz_connect, yaz_search, yaz_present, yaz_scan and yaz_itemorder. yaz_wait returns when all targets have either completed all requests or aborted (in case of errors).