%KDS

Clé de recherche sous forme de structure

Utilise une structure de données comme clé pour CHAIN, SETLL, READE et consorts, en entier ou sur les premiers niveaux de clé seulement.

Syntaxe

%KDS(structure)
%KDS(structure : nombre-de-zones)

structure: La structure de données qui contient les zones de la clé, dans l'ordre des zones clés du fichier. On la déclare volontiers avec likerec(format : *key).
nombre-de-zones: Facultatif : le nombre de zones de clé à utiliser, en partant de la première (clé partielle). Par défaut, toute la structure.
Résultat: Pas de valeur au sens strict : la fonction ne s'emploie que comme clé dans les opérations de fichier.

À quoi ça sert

Avec une clé composée (ville + numéro, par exemple), la forme parenthésée chain (ville : numero) devient vite pénible. %KDS range les zones de la clé dans une structure : on la remplit, on la passe, on la réutilise pour SETLL puis READE.

Le nombre de zones permet aussi de lire par « début de clé » : toute une ville, quel que soit le numéro.

Exemple 1 : Structure likerec *key, clé complète puis partielle

**free
// %KDS : chercher avec une structure de cles, entiere ou partielle.
ctl-opt dftactgrp(*no) actgrp(*new) alwnull(*usrctl);

dcl-f clientv keyed;
dcl-ds lg likerec(clientvr : *input);
dcl-ds cle likerec(clientvr : *key);

// Cle complete (VILLE + NUMCLI) : tous les champs de la structure servent
cle.ville  = 'Lyon';
cle.numcli = 500;
chain %kds(cle) clientvr lg;
if %found(clientv);
  snd-msg 'Cle complete : ' + %trim(lg.nom);
endif;

// Cle partielle : les 1 premiers champs seulement (VILLE)
cle.ville = 'Montpellier';
setll %kds(cle : 1) clientvr;
reade %kds(cle : 1) clientvr lg;
dow not %eof(clientv);
  snd-msg 'Montpellier : ' + %char(lg.numcli) + ' ' + %trim(lg.nom);
  reade %kds(cle : 1) clientvr lg;
enddo;

*inlr = *on;

Résultat réel, compilé et exécuté sur IBM i 7.5 :

Cle complete : Petit Atelier
Montpellier : 100 Dupont SA
Montpellier : 300 Leroy SARL

likerec(clientvr : *key) crée une structure avec les zones VILLE et NUMCLI. Avec deux zones, le CHAIN cherche Lyon 500. Avec %KDS(cle : 1), seule la ville sert de clé : le READE parcourt les clients de Montpellier (100 et 300).

Exemple 2 : Une structure écrite à la main

**free
// %KDS : seuls l'ordre et le type des zones comptent, pas leurs noms.
ctl-opt dftactgrp(*no) actgrp(*new) alwnull(*usrctl);

dcl-f clientv keyed;
dcl-ds lg likerec(clientvr : *input);

// Structure ecrite a la main : ville puis numero, comme l'index CLIENTV
dcl-ds recherche qualified;
  lieu   char(20);
  numero packed(5:0);
end-ds;

recherche.lieu   = 'Lyon';
recherche.numero = 200;
chain %kds(recherche) clientvr lg;
snd-msg 'Lyon 200 : ' + %trim(lg.nom) + ' (trouve = ' + %char(%found(clientv)) + ')';

// Meme structure, mais un numero qui n'existe pas dans cette ville
recherche.numero = 300;
chain %kds(recherche) clientvr lg;
snd-msg 'Lyon 300 : trouve = ' + %char(%found(clientv));

// Un seul niveau de cle : toutes les lignes de Lyon,
recherche.lieu = 'Lyon';
setll %kds(recherche : 1) clientvr;
reade %kds(recherche : 1) clientvr lg;
dow not %eof(clientv);
  snd-msg 'Lyon : ' + %char(lg.numcli) + ' ' + %trim(lg.nom);
  reade %kds(recherche : 1) clientvr lg;
enddo;

*inlr = *on;

Résultat réel, compilé et exécuté sur IBM i 7.5 :

Lyon 200 : Martin et fils (trouve = 1)
Lyon 300 : trouve = 0
Lyon : 200 Martin et fils
Lyon : 500 Petit Atelier

Les noms des zones n'ont aucune importance (lieu, numero) ; seuls comptent leur ordre et leur type. La recherche de Lyon 200 réussit, Lyon 300 échoue, et le parcours avec une seule zone liste les deux clients de Lyon.

Le piège

Seuls l'ordre et le type des zones comptent, pas leur nom. Une structure écrite à la main dans le mauvais ordre (le numéro avant la ville) est refusée à la compilation, avec des messages RNF7072 (« KFLD est NUMERIC pour la séquence… mais la zone clé est CHAR »). Quand deux zones ont le même type, une inversion passerait à la compilation : d'où l'intérêt de likerec(… : *key), qui reprend les zones clés du fichier.

Pensez aussi à renseigner la structure avant chaque recherche : elle garde les valeurs de la précédente.