dams Tue Feb 13 01:16:50 2001 EDT
Modified files:
/phpdoc/fr/functions yaz.xml
Log:
Added new functions
Index: phpdoc/fr/functions/yaz.xml
diff -u phpdoc/fr/functions/yaz.xml:1.9 phpdoc/fr/functions/yaz.xml:1.10
--- phpdoc/fr/functions/yaz.xml:1.9 Wed Feb 7 01:13:38 2001
+++ phpdoc/fr/functions/yaz.xml Tue Feb 13 01:16:49 2001
@@ -8,7 +8,7 @@
Cette extension offre à PHP l'interface avec les produits
<productname>YAZ</productname>, qui implémentent le protocole
Z39.50. Avec cette extension, vous pouvez facilement implémenter
- un client Z39.50 qui fouille des serveurs Z39.50 en paralelle.
+ un client Z39.50 qui analyse ou scanne des serveurs Z39.50 en paralelle.
</para>
<para>
<productname>YAZ</productname> est disponible à <ulink
@@ -32,7 +32,7 @@
</para>
<para>
<informalexample>
- <programlisting role="php">
+ <programlisting>
gunzip -c yaz-1.6.tar.gz|tar xf -
gunzip -c php-4.0.X.tar.gz|tar xf -
cd yaz-1.6
@@ -50,17 +50,15 @@
<sect1 id="yaz.example">
<title>Exemple</title>
<para>
- PHP/YAZ conserve les connexions aux serveurs. Un entier positif représente
- l'ID d'une connexion particulière.
+ PHP/YAZ conserve les connexions aux serveurs. Un entier positif
+ représente l'ID d'une connexion particulière.
</para>
<para>
Le script ci-dessous montre comment effectuer une recherche paralelle.
Lorsqu'il est appelé sans paramètre, ce script affiche la
requête. Sinon, il effectue la recherche sur les serveurs.
- </para>
- <para>
<example>
- <title>YAZ</title>
+ <title>Recherche paralelle, utilisant YAZ</title>
<programlisting role="php">
<?php
$num_hosts = count ($host);
@@ -75,7 +73,7 @@
<input type="checkbox" checked="1"
name="host[]" value="z3950.bell-labs.com/books">
BELL Labs Library
- <br>
+ <br>
RPN Query:
<input type="text" size="30" name="term">
<input type="submit" name="action" value="Search">
@@ -149,9 +147,11 @@
</funcprototype>
</funcsynopsis>
<para>
- <function>yaz_close</function> ferme une connexion à un hôte YAZ.
- L'application ne peut plus utiliser l'identifiant de connexoin
- <parameter>id</parameter>.
+ <function>yaz_close</function> ferme une connexion à un
+ hôte YAZ. L'application ne pourra plus utiliser
+ l'identifiant de connexion <parameter>id</parameter>.
+ <parameter>id</parameter> est un identifiant d'hôte, retourné
+ par <function>yaz_connect</function>.
</para>
</refsect1>
</refentry>
@@ -167,14 +167,20 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>yaz_connect</function></funcdef>
- <paramdef>string <parameter>zurl</parameter></paramdef>
+ <paramdef>string
+ <parameter>zurl</parameter>
+ </paramdef>
+ <paramdef>string
+ <parameter><optional>authentication</optional></parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
- <function>yaz_connect</function> prépare une connexion à un serveur
- Z39.50 target. <parameter>zurl</parameter> est de la forme
- host[:port][/database]. Si port est omis, 210 est utilisé. Si
- database est omis, Default est utilisé. Cette fonction n'est pas
bloquante,
+ <function>yaz_connect</function> prépare une connexion
+ à un serveur Z39.50. <parameter>zurl</parameter> est de la forme
+ "<literal>host[:port][/database]</literal>". Si port est omis, 210 est
+ utilisé. Si <literal>database</literal> est omis,
+<literal>default</literal>
+ est utilisé. <function>yaz_connect</function> n'est pas bloquante,
et ne tente pas d'établir une socket. En fait, elle ne fait que
préparer la connexion pour exécution ultérieure
par <function>yaz_wait</function>.
@@ -273,10 +279,10 @@
</funcsynopsis>
<para>
<function>yaz_range</function> est à utiliser en conjonction
- avec <function>yaz_search</function> pour spécifier le type
- d'éléments à lire. La pluspart des serveurs
- supporte <literal>F</literal> (full, tous), et <literal>B</literal>
- (brief, bref).
+ avec <function>yaz_search</function> et <function>yaz_present</function>
+ pour spécifier le type d'éléments à lire.
+ La plupart des serveurs supporte <literal>F</literal> (full, tous), et
+ <literal>B</literal> (brief, bref).
</para>
<para>
<function>yaz_range</function> retourne <literal>TRUE</literal> en
@@ -284,6 +290,29 @@
</para>
</refsect1>
</refentry>
+ <refentry id="function.yaz-present">
+ <refnamediv>
+ <refname>yaz_present</refname>
+ <refpurpose>
+ Prépare à la lecture (Z39.50 present).
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>yaz_present</function></funcdef>
+ <void/>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>yaz_present</function> prépare PHP à la lecture des
+ résultats, après une recherche. <function>yaz_range</function>
+ doit être appelée avant celle-ci pour spécifier la plage
+ de résultat à lire.
+ </para>
+ </refsect1>
+ </refentry>
<refentry id="function.yaz-range">
<refnamediv>
<refname>yaz_range</refname>
@@ -311,7 +340,8 @@
et <parameter>number</parameter> vaudra 10.
</para>
<para>
- Retourne <literal>TRUE</literal> en cas de succès;
<literal>FALSE</literal> en cas d'erreur.
+ <function>yaz_range</function> retourne <literal>TRUE</literal> en
+ cas de succès; <literal>FALSE</literal> en cas d'erreur.
</para>
</refsect1>
</refentry>
@@ -370,23 +400,25 @@
représente le type de requête : seul RPN est supporté
actuellement, et dans ce cas, le troisième argument est un
préfixe de notation de requête utilisé par YAZ.
- Comme pour <function>yaz_connect</function>, <function>yaz_search</function>
n'est pas
- bloquante, et ne fait que préparer la recherche pour exécution
- ultérieure, avec <function>yaz_wait</function>.
+ Comme pour <function>yaz_connect</function>, <function>yaz_search</function>
+ n'est pas bloquante, et ne fait que préparer la recherche pour
+ exécution ultérieure, avec <function>yaz_wait</function>.
</para>
</refsect1>
<refsect1>
<title>Requêtes RPN</title>
<para>
- Les requêtes RPN sont des représentation textuelles des
requêtes
- de type Type-1, comme définit dans le standard Z39.50. Cependant,
- dans la représentation textuelle utilisée par YAZ, une notation
- à préfixage est utilisée, c'est à dire que
l'opérateur précéde
- l'opérande. La chaîne de requête est une séquence de
mots
- reservés, où les espaces sont ignorés, à moins
qu'ils n'ai été
- mis entre guillemets doubles. Les mots reservés qui commencent par
- un arobase (<literal>@</literal>) sont considérés comme des
opérateurs
- et traités comme tels.
+ Les requêtes RPN sont des représentation textuelles des
+ requêtes de type Type-1, comme définit dans le standard
+ Z39.50. Cependant, dans la représentation textuelle utilisée
+ par YAZ, une notation à préfixage est utilisée,
+ c'est à dire que l'opérateur précéde
+ l'opérande. La chaîne de requête est une
+ séquence de mots reservés, où les espaces sont
+ ignorés, à moins qu'ils n'ai été
+ mis entre guillemets doubles. Les mots reservés qui commencent
+ par un arobase (<literal>@</literal>) sont considérés
+ comme des opérateurs et traités comme tels.
</para>
<table>
<title>Opérateurs RPN</title>
@@ -448,13 +480,14 @@
<screen>@attr 1=4 php</screen>
</informalexample>
L'attribut est de type 1 (Bib-1 use), sa valeur est 4 (Title, titre) :
- cette requête recherche les documents où le mot "php" est dans le
titre.
+ cette requête recherche les documents où le mot "php"
+ est dans le titre.
</para>
<para>
<informalexample>
-<screen>@attrset gils @and @attr 1=4 php @attr 1=1003 "Rasmus Lerdorf"</screen>
+ <screen>@attrset gils @and @attr 1=4 php @attr 1=1003 "Rasmus Lerdorf"</screen>
</informalexample>
- Cette requête utilise tout le jeu d'attrbuts GILS. Elle recherche
+ Cette requête utilise tout le jeu d'attributs GILS. Elle recherche
les documents dont le titre contient "php", et qui contiennent le
nom "Rasmus Lerdorf" comme auteur.
</para>
@@ -479,30 +512,352 @@
<para>
<function>yaz_syntax</function> est utilisée conjointement avec
<function>yaz_search</function> pour spécifier la méthode
- de lecture des lignes.
+ de lecture des lignes. La syntaxe est spécifiée comme un OID
+ (Identifiant d'Objet), en notation brute, séparée par des
+ points (i.e. <literal>1.2.840.10003.5.10</literal>), ou bien avec une
+ des valeurs prédéfinies : sutrs, usmarc, grs1, xml, etc...
+ <function>yaz_syntax</function> doit être utilisée en
+conjonction avec
+ <function>yaz_search</function> et <function>yaz_present</function>
+ pour spécifier la méthode de lecture des résultats.
</para>
</refsect1>
</refentry>
+ <refentry id="function.yaz-scan">
+ <refnamediv>
+ <refname>yaz_scan</refname>
+ <refpurpose>Prépare un scan</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>yaz_scan</function></funcdef>
+ <paramdef>int <parameter>id</parameter></paramdef>
+ <paramdef>string <parameter>type</parameter></paramdef>
+ <paramdef>string <parameter>startterm</parameter></paramdef>
+ <paramdef>array
+ <parameter><optional>flags</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>yaz_scan</function> prépare une requête "Z39.50 Scan
+Request".
+ <parameter>id</parameter> spécifie l'hôte cible. Le point de
+départ
+ est donné avec <parameter>startterm</parameter>. La forme de
+spécification
+ du point de départ est donné par <parameter>type</parameter>.
+Actuellement,
+ le type <literal>rpn</literal> est supporté. Le paramètre optionnel
+ <parameter>flags</parameter> donne des informations supplémentaires pour
+ contrôler le comportement de la requête de scan. Actuellement, trois
+index
+ sont lus dans ce paramètre : <literal>number</literal> (nombre de termes
+ requis), <literal>position</literal> (position préférée du
+terme) et
+ <literal>stepSize</literal> (taille du pas préferée).
+ Pour rééllement envoyer la requête de recherche à
+l'hôte, et recevoir
+ la réponse, <function>yaz_wait</function> doit être appelée.
+A la fin de
+ <function>yaz_wait</function>, <function>yaz_error</function> et
+ <function>yaz_scan_result</function> auront les résultats.
+ </para>
+ <para>
+ La syntaxe de <parameter>startterm</parameter> est similaire aux requêtes
+ RPN, décrites dans <function>yaz_search</function>.
+ <parameter>startterm</parameter> est constitué de zéro ou plus
+ spécifications, avec les opérateurs <literal>@attr</literal>,
+suivi par
+ exactement un token.
+ </para>
+ <para>
+ <example>
+ <title>Fonction PHP qui scanne les titres</title>
+ <programlisting>
+ 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 "Echec du scan. Erreur: " . yaz_error($id) . "<br>";
+ }
+ }
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id="function.yaz-scan-result">
+ <refnamediv>
+ <refname>yaz_scan_result</refname>
+ <refpurpose>Retourne le résultat d'un scan</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>array <function>yaz_scan_result</function></funcdef>
+ <paramdef>int <parameter>id</parameter></paramdef>
+ <paramdef>array &
+ <parameter><optional>result</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>yaz_scan_result</function> retourne un tableau contenant
+ les termes recu de l'hôte <parameter>id</parameter>, lors
+ de la dernière requête de scan. Le tableau commence à
+l'index 0.
+ Chaque valeur est une paire, où le premier élément est le
+terme,
+ et le second est un compte de résultat. Si
+ <parameter>result</parameter> est fourni, il sera rempli avec
+ les informations générales de la requête de scan :
+ <literal>number</literal> (numbre d'entrée retournées),
+ <literal>stepsize</literal> (taille du pas),
+ <literal>position</literal> (position du terme),
+ <literal>status</literal> (Statut du Scan).
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id="function.yaz-ccl-conf">
+ <refnamediv>
+ <refname>yaz_ccl_conf</refname>
+ <refpurpose>Configure l'analyseur CCL</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>yaz_ccl_conf</function></funcdef>
+ <paramdef>int <parameter>id</parameter></paramdef>
+ <paramdef>array <parameter>config</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>yaz_ccl_conf</function> configure l'analyseur CCL
+ de requete de l'hôte <parameter>id</parameter>, avec
+ les définitions de points d'accès (CCL qualifiers) et leur
+ équivalent en RPN. Pour cabler une requête spécifique vers un
+ appel RPN, utilisez <function>yaz_ccl_parse</function>.
+ Chaque index du tableau <parameter>config</parameter> est un
+ nom de champs CCL et la valeur correspondante contient une chaîne
+ spécifiant le code RPN. Ce code est une séquence de paires
+ "attribut-type, attribute-value". Les "attribut-type" et
+ "attribut-value" sont séparé par le signe égal
+(<literal>=</literal>).
+ Chaque paire est séparé par un espace ("<literal>=</literal>").
+ </para>
+ <para>
+ <example>
+ <title>Exemple de configuration CCL</title>
+ <simpara>
+ Dans l'exemple ci-dessous, l'analyseur CCL est configuré pour
+ supporter trois champs CCL : <literal>ti</literal>, <literal>au</literal> et
+ <literal>isbn</literal>. Chaque champs correspond à leur équivalent
+ équivalent BIB-1. On suppose que chaque variable <literal>$id</literal>
+est
+ un hôte de destination.
+ </simpara>
+ <programlisting role="php">
+<?php
+ $field["ti"] = "1=4";
+ $field["au"] = "1=1";
+ $field["isbn"] = "1=7";
+ yaz_ccl_conf($id,$field);
+?<
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id="function.yaz-ccl-parse">
+ <refnamediv>
+ <refname>yaz_ccl_parse</refname>
+ <refpurpose>Appelle l'analyseur CCL</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>yaz_ccl_parse</function></funcdef>
+ <paramdef>int <parameter>id</parameter></paramdef>
+ <paramdef>string <parameter>query</parameter></paramdef>
+ <paramdef>array &<parameter>result</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>yaz_ccl_parse</function> appelle l'analyseyr CCL.
+ Il convertit une requête CCL FIND en une requête RPN qui peut
+être
+ passée à <function>yaz_search</function> pour effectuer une
+recherche.
+ Pour définir un champs CCL valide, utilisez la fonction
+ <function>yaz_ccl_conf</function> avant celle-ci.
+ Si la requête <parameter>query</parameter> a pu être convertie en
+ RPN, <function>yaz_ccl_parse</function> retourne <literal>TRUE</literal>,
+ et l'index <literal>rpn</literal> du tableau <parameter>result</parameter>
+ contient une requête RPN valide. Si la requête n'a pas pu être
+convertie,
+ (pour n'importe quelle raison, comme syntaxe invalide, champs inconnu...),
+ <function>yaz_ccl_parse</function> retourne <literal>FALSE</literal>.
+ Trois index sont alors créé dans le tableau de résultat :
+ <literal>errorcode</literal> (code d'erreur CCL, un entier),
+ <literal>errorstring</literal> (message d'erreur CCL), et
+ <literal>errorpos</literal> position estimée de l'erreur dans la
+ requête (entier, position en nombre de caractères).
+ </para>
+ </refsect1>
+ </refentry>
+ <refentry id="function.yaz-itemorder">
+ <refnamediv>
+ <refname>yaz_itemorder</refname>
+ <refpurpose>
+ Prépare une requête Z39.50 Item Order avec le package ILL-Request
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>yaz_itemorder</function></funcdef>
+ <paramdef>array <parameter>args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>yaz_itemorder</function> prépare une requête de type
+"Extended Services"
+ en utilisant le "Profile" avec "Use of Z39.50 Item Order Extended Service to
+ Transport ILL (Profile/1)" (Note du Traducteur : mailes moi de l'aide!).
+Reportez vous
+ <ulink url="http://www.nlc-bnc.ca/iso/ill/stanprf.htm">ici</ulink>
+ ou aux
+ <ulink url="http://www.nlc-bnc.ca/iso/ill/document/standard/z-ill-1a.pdf">
+ spécification</ulink>.
+ Le paramètre <parameter>args</parameter> doit être un tableau
+associatif,
+ contenant les informations "Item Order" à envoyer. L'index du tableau est
+ le nom ASN.1 correspondant au tag path. Par exemple, le numéro ISBN sous
+ l'Item-ID est la clé item-id,ISBN.
+ </para>
+ <para>
+ Les paramètres de ILL-Request sont :
+ </para>
+ <literallayout>
+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
+ </literallayout>
+ <para>
+ Il y a quelques paramètres du package Extended Services Request
+ et ItemOrder :
+ </para>
+ <literallayout>
+package-name
+user-id
+contact-name
+contact-phone
+contact-email
+itemorder-item
+ </literallayout>
+ </refsect1>
+ </refentry>
<refentry id="function.yaz-wait">
<refnamediv>
<refname>yaz_wait</refname>
- <refpurpose>Exécute une requête</refpurpose>
+ <refpurpose>Attend l'exécution d'une requête</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>yaz_wait</function></funcdef>
- <paramdef>int <parameter>id</parameter></paramdef>
- <paramdef>string <parameter>syntax</parameter></paramdef>
+ <void/>
</funcprototype>
</funcsynopsis>
<para>
- <function>yaz_wait</function> exécute les requêtes
préparée par les fonctions
- <function>yaz_connect</function>, <function>yaz_search</function>.
- <function>yaz_wait</function> fonctionne en mode bloquant.
- <function>yaz_wait</function> se termine lorsque toutes les requêtes
- se sont terminées (succès ou erreur).
+ <function>yaz_wait</function> exécute les requêtes
+ préparée par les fonctions
+ <function>yaz_search</function>, <function>yaz_present</function>,
+ <function>yaz_scan</function> et <function>yaz_itemorder</function>.
+ <function>yaz_wait</function> se termine lorsque tous les hôtes
+ ont terminé leurs requêtes (éventuellement en cas d'erreur).
</para>
</refsect1>
</refentry>
