Obtenir des informations à partir d'enregistrements correspondants

La méthode fetch a quatre arguments :

• flag
• offset

  Ensemble, les arguments flag et offset définissent la position de départ du bloc d’enregistrements à récupérer. L’argument flag est une chaîne de caractères et doit être l’un des suivants :

  • start
  • current
  • end

  Les indicateurs start et end font référence au premier et au dernier enregistrement du jeu de résultats. L’indicateur current fait référence à la position du dernier enregistrement récupéré lors de l’appel précédent à la méthode fetch. Si la méthode fetch n’a pas été appelée, current fait référence au premier enregistrement du jeu de résultats.

  L’argument offset est un entier. Il ajuste la position de départ par rapport à la valeur de l’argument flag. Une valeur positive pour offset indique un début après la position spécifiée par flag et une valeur négative indique un début avant la position spécifiée par flag.

  Par exemple, appeler fetch avec un flag de start et un offset de 3 renverra les enregistrements à partir du quatrième enregistrement du jeu de résultats. Spécifier un flag de end et un offset de -8 renverra les enregistrements à partir du neuvième enregistrement en partant de la fin du jeu de résultats.

  Pour récupérer l’enregistrement suivant après le dernier renvoyé lors de l’appel précédent à fetch, il convient de passer un flag de current et un offset de 1.

• count

  L’argument count spécifie le nombre maximum d’enregistrements à récupérer.

  Passer une valeur count de 0 est valide. Cela amène fetch à modifier l’enregistrement en cours sans récupérer réellement les données.

  L’utilisation d’une valeur négative pour count est également valide. Cela amène fetch à renvoyer tous les enregistrements du jeu de résultats à partir de la position de départ (spécifiée par flag et offset).

• columns

  L’argument facultatif columns est utilisé pour spécifier quelles colonnes doivent être incluses dans les enregistrements renvoyés. L’argument peut être soit une chaîne, soit une référence à un tableau de chaînes. Dans sa forme la plus simple, chaque chaîne contient un seul nom de colonne, ou plusieurs noms de colonnes séparés par des points-virgules ou des virgules.

  La valeur de l’argument columns peut être autre chose que de simples noms de colonnes. Voir Spécification des colonnes pour plus de détails.

Par exemple :

1. Récupérer le premier enregistrement à partir du début du jeu de résultats :

   $parties = new IMuModule('eparties', $session) ;  $columns = 'NamFirst,NamLast' ;  $result = $parties->fetch('start', 0, 1, $columns) ; 

   L’argument columns peut également être spécifié sous la forme d’une référence à un tableau :

   $parties = new IMuModule('eparties', $session) ;  $columns = array ( 'NamFirst', 'NamLast' ) ;  $result = $parties->fetch('start', 0, 1, $columns) ; 

2. Récupérer tous les résultats d’un jeu de résultats :

   $parties = new IMuModule('eparties', $session) ;  $columns = array ( 'NamFirst', 'NamLast' ) ;  $result = $parties->fetch('start', 0, -1, $columns) ; 

3. Définir l’enregistrement en cours sur l’enregistrement suivant du jeu de résultats sans récupérer de données :

   $parties->fetch('current', 1, 0) ; 

4. Récupérer le dernier enregistrement à partir de la fin du jeu de résultats :

   $parties = new IMuModule('eparties', $session) ;  $columns = array ( 'NamFirst', 'NamLast' ) ;  $result = $parties->fetch('end', 0, 1, $columns) ; 

La méthode fetch retourne les enregistrements demandés dans un objet IMuModuleFetchResult. Il est composé de trois membres :

• count

  Le nombre d’enregistrements retournés par la requête fetch.

• hits

  Nombre estimé de résultats dans le jeu de résultats. Ce nombre est renvoyé pour chaque fetch car l’estimation peut diminuer à mesure que les enregistrements du jeu de résultats sont traités par la méthode fetch.

• rows

  Une référence à un tableau contenant le jeu d’enregistrements demandés. Chaque élément du tableau rows est lui-même une référence à une table de hachage. Chaque table de hachage contient des entrées pour chaque colonne demandée.

Par exemple, les propriétés count et hits sont récupérées et tous les enregistrements renvoyés sont parcourus à l’aide de la propriété rows :

$columns = array ( 'NamFirst', 'NamLast' ); $result = $parties->fetch('start', 0, 2, $columns); $count = $result->count; $hits = $result->hits; print("Count: $count\n"); print("Hits: $hits\n"); print("Rows:\n"); foreach ($result->rows as $row) { $rowNum = $row['rownum']; $irn = $row['irn']; $firstName = $row['NamFirst']; $lastName = $row['NamLast']; printf(" %d. %s, %s (%d)\n", $rowNum, $lastName, $firstName, $irn); }

Cela génère des résultats similaires à ceux qui suivent :

Count: 2 Hits: 4 Rows: 1. ECCLES-SMITH, Kate (100573) 2. SMITH, Ian (100301)

Il s’agit par exemple de simples noms de colonnes du type déjà mentionné :

 NamFirst 

Les valeurs des colonnes atomiques sont renvoyées sous forme de chaînes :

$columns = array ( 'NamFirst' ); $result = $parties->fetch('start', 0, 1, $columns); foreach ($result->rows as $row) { $first = $row['NamFirst']; // ⋯ } 

Les tables imbriquées sont des colonnes qui contiennent une liste de valeurs. Elles sont spécifiées de la même manière que les colonnes atomiques :

 NamRoles_tab 

Les valeurs des tables imbriquées sont renvoyées sous forme de tableau. Chaque membre du tableau est une chaîne de caractères qui correspond à une ligne de la table imbriquée :

$columns = array ( 'NamRoles_tab' ); $result = $parties->fetch('start', 0, 1, $columns); foreach ($result->rows as $row) { $roles = $row['NamRoles_tab']; foreach ($roles as $role) { // ⋯ } } 

Un fichier joint est un lien entre un enregistrement d’un module et un enregistrement du même module ou d’un autre module. Les colonnes d’un enregistrement joint peuvent être spécifiées en spécifiant d’abord la colonne de fichier joint, puis la colonne à récupérer à partir de l’enregistrement joint :

 SynSynonymyRef_tab.SummaryData 

Plusieurs colonnes peuvent être spécifiées à partir de l’enregistrement joint :

 SynSynonymyRef_tab.(NamFirst,NamLast) 

Les valeurs renvoyées pour les colonnes provenant d’enregistrements joints dépendent du type de la colonne de fichier joint. Si la colonne de fichier joint est atomique, les valeurs de la colonne sont renvoyées sous forme de tableau associatif. Si la colonne de fichier joint est une table imbriquée, les valeurs sont renvoyées sous forme de tableau. Chaque membre du tableau est un tableau associatif contenant les valeurs de colonne demandées pour chaque enregistrement joint :

$columns = array ( 'SynSynonymyRef_tab.(NamFirst,NamLast)' ); $result = $parties->fetch('start', 0, 1, $columns); foreach ($result->rows as $row) { $synonymies = $row['SynSynonymyRef_tab']; foreach ($synonymies as $synonymy) { $first = $synonymy['NamFirst']; $last = $synonymy['NamLast']; // ⋯ } } 

Un fichier joint inversé permet de spécifier des colonnes provenant d’autres enregistrements du même module ou d’autres modules auxquels l’enregistrement en cours est rattaché par l’intermédiaire d’une colonne spécifiée.

Par exemple :

1. Récupérez la colonne TitMainTitle (Titre principal) pour tous les enregistrements Catalogue qui ont l’enregistrement Personnes / Organisations en cours joint à leur colonne CreCreatorRef_tab (Créateur) :

    <ecatalogue :CreCreatorRef_tab>. TitMainTitle 

2. Récupérez la colonne NarTitle (Titre) pour tous les enregistrements Narrations qui ont l’enregistrement Narration en cours joint à leur colonne HieChildNarrativesRef_tab (Narrations enfants) :

    <enarratives :HieChildNarrativesRef_tab>. NarTitle 

Plusieurs colonnes peuvent être spécifiées à partir de l’enregistrement de fichier joint inversé :

 <ecatalogue:CreCreatorRef_tab>.(TitMainTitle,TitObjectCategory) 

Les fichiers joints inversés sont renvoyés sous forme de tableau. Chaque membre du tableau est un tableau associatif contenant les valeurs de colonne demandées pour chaque enregistrement du module spécifié (le module Catalogue dans l’exemple ci-dessous) qui a l’enregistrement en cours joint à la colonne spécifiée (la colonne CreCreatorRef_tab dans l’exemple ci-dessous) :

$columns = array ( '<ecatalogue:CreCreatorRef_tab>.(TitMainTitle,TitObjectCategory)' ); $result = $parties->fetch('start', 0, 1, $columns); foreach ($result->rows as $row) { $objects = $row['ecatalogue:CreCreatorRef_tab']; foreach ($objects as $object) { $title = $object['TitMainTitle']; $category = $object['TitObjectCategory']; // ⋯ } } 

Un ensemble de colonnes de table imbriquées peut être regroupé en les spécifiant entre crochets.

Par exemple, pour regrouper les Contributeurs et leur rôle à partir du module Narrations :

 [NarContributorRef_tab.SummaryData,NarContributorRole_tab] 

Chaque ensemble de lignes correspondantes des tables imbriquées fournies est renvoyé sous la forme d’une seule ligne dans les résultats. Par défaut, le groupe reçoit le nom group1, group2 et ainsi de suite. Ce nom de groupe peut être changé en préfixant les colonnes groupées avec un nom alternatif :

 contributors=[NarContributorRef_tab.SummaryData,NarContributorRole_tab] 

Les tables imbriquées groupées sont renvoyées sous forme de tableau. Chaque membre du tableau est un tableau associatif contenant les lignes correspondantes des tables imbriquées :

$columns = array ( '[NarContributorRef_tab.SummaryData,NarContributorRole_tab]' ); $result = $narratives->fetch('start', 0, 1, $columns); foreach ($result->rows as $row) { $groupedRows = $row['group1']; foreach ($groupedRows as $groupedRow) { /* NarContributorRef_tab is an attachment column. */ $contributor = $groupedRow['NarContributorRef_tab']; $summary = $contributor['SummaryData']; $role = $groupedRow['NarContributorRole_tab']; // ⋯ } } 

Les colonnes virtuelles sont des colonnes qui n’existent pas réellement dans la table EMu à laquelle on accède. Au lieu de cela, le serveur IMu interprète la requête concernant la colonne et génère une réponse adaptée. Certaines colonnes virtuelles ne peuvent être utilisées que dans certains modules, comme indiqué ci-dessous :

Les colonnes virtuelles suivantes peuvent être utilisées dans n’importe quel module EMu :

• insertedTimeStamp

  Renvoie la date et l'heure d'insertion de l'enregistrement au format YYYY-MM-DDThh:mm:ss, par exemple 1999-12-31T23:59:59 Ce format est similaire au format de date ISO8601, à l’exception de l’indicateur de fuseau horaire qui n’est pas inclus.

• modifiedTimeStamp

  Renvoie la date et l'heure de modification de l'enregistrement au format YYYY-MM-DDThh:mm:ss.

$columns = array ( 'insertedTimeStamp', 'modifiedTimeStamp' ); $result = $parties->fetch('start', 0, 1, $columns); foreach ($result->rows as $row) { $inserted = $row['insertedTimeStamp']; $modified = $row['modifiedTimeStamp']; # ⋯ } 

Les colonnes virtuelles suivantes peuvent être utilisées dans n’importe quel module EMu, à l’exception du module Multimédia :

• application

  Renvoie des informations sur le multimédia d’application préféré associé à un enregistrement.

  Note: Actuellement, le multimédia d’application préféré correspond à la première entrée de la liste renvoyée par la colonne virtuelle applications. Toutefois, les futures versions d’EMu pourraient permettre de désigner d’autres multimédias comme préférés ; dans ce cas, la colonne application renverra les informations relatives au multimédia d’application préféré plutôt qu’au premier de la liste.

• applications

  Renvoie des informations sur tous les multimédias d’application associés à un enregistrement.

• audio

  Renvoie des informations sur le multimédia audio préféré associé à un enregistrement.

• audios

  Renvoie des informations sur tous les multimédias audio associés à un enregistrement.

• image

  Renvoie des informations sur le multimédia image préféré associé à un enregistrement.

• images

  Renvoie des informations sur tous les multimédias image associés à un enregistrement.

• multimedia

  Renvoie des informations sur tous les multimédia associés à un enregistrement.

• video

  Renvoie des informations sur le multimédia video préféré associé à un enregistrement.

• videos

  Renvoie des informations sur tous les multimédias video associés à un enregistrement.

Pour plus d’informations, consultez Multimédia.

Les colonnes virtuelles suivantes ne peuvent être utilisées que dans le module Multimédia :

• master

  Retourne des informations sur le fichier multimédia principal.

• resolutions (résolutions)

  Renvoie des informations sur toutes les résolutions multimédia.

• resource (ressource)

  Renvoie des informations minimales sur le fichier multimédia principal, notamment un descripteur de fichier ouvert pointant vers une copie temporaire de ce fichier multimédia.

• resources (ressources)

  Identique à la colonne virtuelle ressource, sauf que des informations et des descripteurs de fichiers sont fournis pour tous les fichiers multimédias.

• supplementary (supplémentaire)

  Renvoie des informations sur tous les fichiers multimédias supplémentaires.

• thumbnail (vignette)

  Renvoie des informations sur le multimédia vignette.

Pour plus d’informations, consultez Multimédia.

La colonne virtuelle suivante ne peut être utilisée que dans le module Narrations :

• trails

  Renvoie des informations sur la position de l’enregistrement actuel dans la hiérarchie du module Narrations.

La colonne virtuelle suivante ne peut être utilisée que dans le module Descriptions des collections :

• extUrlFull_tab

Un ensemble Fetch permet de préenregistrer un groupe de colonnes sous un nom unique. Ce nom peut ensuite être passé à la méthode fetch pour récupérer les colonnes spécifiées.

Les ensembles Fetch sont utiles si la méthode fetch est appelée plusieurs fois avec le même ensemble de colonnes, car :

• Les colonnes requises n’ont pas besoin d’être spécifiées à chaque fois que la méthode fetch est appelée. Ceci est utile pour maintenir l'état.
• Chaque fois que la méthode fetch est appelée, le serveur IMu doit analyser les colonnes fournies et les comparer au schéma EMu. Pour les ensembles de colonnes complexes, en particulier ceux impliquant plusieurs références ou références inverses, cela peut prendre du temps.

La méthode de classe IMuModule addFetchSet est utilisée pour enregistrer un ensemble de colonnes. Cette méthode prend deux arguments :

• name

  Le nom à utiliser pour l’ensemble de colonnes. La valeur de cet argument peut être passée à n’importe quel appel à la méthode fetch et l’ensemble des colonnes spécifié par l’argument columns sera renvoyé.

• columns

  L’ensemble des colonnes à associer à l’argument name.

La méthode de classe IMuModule addFetchSets est similaire, sauf que plusieurs ensembles peuvent être enregistrés en même temps.

Les résultats sont renvoyés comme si vous aviez fourni les colonnes directement à la méthode fetch.

Par exemple :

1. Ajouter un ensemble Fetch unique en utilisant la méthode addFetchSet:

   $columns = array ( 'NamFirst', 'NamLast', 'NamRoles_tab' ) ;  $parties->addFetchSet('person_details', $columns) ; 

2. Ajouter plusieurs ensembles Fetch à l’aide de la méthode addFetchSets :

   $sets = array ( 'person_details' => array('NamFirst', 'NamLast', 'NamRoles_tab'), 'organisation_details' => array('NamOrganisation', 'NamOrganisationAcronym') ) ;  $module->addFetchSets($sets) ; 

3. Récupérer un ensemble Fetch à l’aide de la méthode fetch :

   $result = $parties->fetch('start', 0, 1, 'person_details') ; foreach ($result->rows as $row) { $first = $row['NamFirst'] ; $last = $row[] ��'NamLast'] ; $roles = $row['NamRoles_tab'] ; foreach ($roles as $role) { // ⋯ } } 

Avertissement

Le nom du set fetch doit être la seule valeur transmise comme argument columns de la méthode Fetch. Cela pourrait être modifié dans une future version de l’API IMu.

Les colonnes peuvent être renommées dans les résultats renvoyés en les préfixant d’un autre nom :

 first_name=NamFirst 

La valeur de la colonne spécifiée est désormais renvoyée sous le nom alternatif :

$columns = array ( 'first_name=NamFirst' ); $result = $parties->fetch('start', 0, 1, $columns); foreach ($result->rows as $row) { $first = $row['first_name']; # ⋯ } 

D’autres noms peuvent également être fournis pour d’autres spécifications de colonnes :

 roles=NamRoles_tab 

 synonyms=SynSynonymyRef_tab.(NamFirst,NamLast) 

 objects=<ecatalogue:CreCreatorRef_tab>.(TitMainTitle,TitObjectCategory) 

D’autres noms peuvent également être utilisés pour toutes les colonnes spécifiées entre parenthèses ou crochets :

 SynSynonymyRef_tab.(first_name=NamFirst,last_name=NamLast) 

 contributors=[contributor=NarContributorRef_tab.SummaryData,role=NarContributorRole_tab] 

D’autres noms peuvent également être fournis dans les ensembles Fetch :

$columns = array ( 'first_name=NamFirst', 'last_name=NamLast', 'roles=NamRoles_tab' ); $parties->addFetchSet('person_details', $columns);