%LEFT

Les n premiers caractères

Extrait le début d'une chaîne, sur le nombre de caractères demandé.

Syntaxe

%LEFT(chaîne : longueur)

chaîne: Le texte dont on garde le début : zone caractère, graphique ou UCS-2, littéral ou expression.
longueur: Le nombre de caractères à garder, de 0 à la longueur de la chaîne. Une valeur supérieure à la longueur de la chaîne est une erreur.
Résultat: Une valeur du même type que la chaîne, de la longueur demandée. Avec 0, une chaîne vide.

À quoi ça sert

Dans la plupart des programmes, on veut le début d'une valeur : les deux premiers chiffres d'un code postal pour le département, un préfixe de référence, les quatre premières lettres d'une ville. %LEFT(x : n) le dit plus clairement que %SUBST(x : 1 : n).

Exemple 1 : Département, préfixe, début de nom

**free
// %LEFT : les n premiers caracteres d'une chaine.
ctl-opt dftactgrp(*no) actgrp(*new);

dcl-s codePostal varchar(5)  inz('34000');
dcl-s reference  varchar(13) inz('CLI-2026-0042');
dcl-s ville      char(20)    inz('Montpellier');
dcl-s dept       char(2);

dept = %left(codePostal : 2);
snd-msg 'Departement : [' + dept + ']';
snd-msg 'Prefixe     : [' + %left(reference : 3) + ']';
snd-msg 'Ville (4)   : [' + %left(ville : 4) + ']';
snd-msg 'Ville (8)   : [' + %left(ville : 8) + ']';
snd-msg 'Zero        : [' + %left(reference : 0) + ']';

*inlr = *on;

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

Departement : [34]
Prefixe     : [CLI]
Ville (4)   : [Mont]
Ville (8)   : [Montpell]
Zero        : []

Les deux premiers caractères de 34000 donnent le département 34, les trois premiers de CLI-2026-0042 le préfixe CLI. Avec une longueur de 0, on obtient une chaîne vide.

Sur la ville déclarée en char(20), un %LEFT de 8 renvoie Montpell : il coupe simplement, sans se soucier des mots.

Exemple 2 : Longueur trop grande

**free
// %LEFT : longueur trop grande, erreur d'execution et troncature sure.
ctl-opt dftactgrp(*no) actgrp(*new);

dcl-s ville   varchar(20) inz('Lyon');
dcl-s villeFixe char(10)    inz('Lyon');
dcl-s nb      int(10);

nb = 8;
monitor;
  snd-msg 'Varchar : [' + %left(ville : nb) + ']';
on-error *all;
  snd-msg 'Varchar : erreur, statut ' + %char(%status);
endmon;

// Sur une zone fixe de 10, la limite est 10 et non la longueur utile.
nb = 10;
snd-msg 'Fixe 10 : [' + %left(villeFixe : nb) + ']';
nb = 12;
monitor;
  snd-msg 'Fixe 12 : [' + %left(villeFixe : nb) + ']';
on-error *all;
  snd-msg 'Fixe 12 : erreur, statut ' + %char(%status);
endmon;

// Troncature sure : on borne la longueur demandee avec %MIN.
nb = 8;
snd-msg 'Borne   : [' + %left(ville : %min(nb : %len(ville))) + ']';

*inlr = *on;

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

Varchar : erreur, statut 100
Fixe 10 : [Lyon      ]
Fixe 12 : erreur, statut 100
Borne   : [Lyon]

Demander 8 caractères d'un varchar qui en contient 4 provoque une erreur d'exécution, statut 100. Le monitor l'intercepte. Sur une zone fixe de 10 caractères, 10 est accepté et rend la zone entière avec ses blancs, 12 est refusé.

Pour couper sans risque, on borne la longueur avec %MIN(n : %LEN(zone)) : la chaîne entière est alors renvoyée si elle est plus courte que demandé.

Le piège

%LEFT ne complète pas et ne tronque pas silencieusement. Si la longueur dépasse celle de la chaîne, le programme s'arrête en erreur (statut 100, message RNX0100). Si la valeur est une constante connue à la compilation, c'est le compilateur qui refuse, avec le message RNF0203 (« THE SECOND PARAMETER … FOR %LEFT or %RIGHT IS TOO BIG », ou « … IS NOT VALID » pour une valeur négative).

Sur une zone fixe, la limite est la longueur déclarée (10 pour un char(10)), pas la longueur du texte : %LEFT(zone : 10) réussit et ramène les blancs de fin. Pour un texte de longueur inconnue, bornez toujours avec %MIN.