Aller au contenu

%UCS2

Convertir en Unicode

Convertit une chaîne de caractères en chaîne Unicode (UCS-2), à deux octets par caractère, ou une zone graphique en Unicode.

Syntaxe

%UCS2(expression)
expression
Une zone ou une expression caractère (simple ou variable), ou une zone graphique.
Résultat
Une valeur UCS-2 : deux octets par caractère, longueur mesurée en caractères.

À quoi ça sert

Les échanges avec le monde extérieur (services web, XML, JSON, bases Unicode, Java) se font en Unicode, alors que les données classiques sont en EBCDIC. %UCS2 fait le passage, et %CHAR permet de revenir.

Une zone Unicode compte toujours deux octets par caractère, ce qui garantit qu'aucun accent ni caractère spécial n'est perdu à l'intérieur du traitement.

Exemple 1 : Aller-retour et caractère non convertible

**free
// %UCS2 : convertir du texte caractere en Unicode (UCS-2), et le convertir en retour.
ctl-opt dftactgrp(*no) actgrp(*new);

dcl-s ville   varchar(20) inz('Montpellier');
dcl-s villeU  varucs2(20);
dcl-s fixeU   ucs2(20);
dcl-s retour  varchar(20);
dcl-s cyrilU  ucs2(3) inz(u'041604300440');
dcl-ds octet qualified;
  car  char(1);
  code uns(3) overlay(car);
end-ds;

villeU = %ucs2(ville);
snd-msg 'Longueur en caracteres  : ' + %char(%len(villeU));
snd-msg 'Taille de la zone       : ' + %char(%size(villeU)) + ' octets';
fixeU = %ucs2(ville);
snd-msg 'Meme texte en ucs2(20)  : ' + %char(%len(fixeU)) + ' caracteres (complete de blancs)';

retour = %char(villeU);
snd-msg 'Retour en caracteres    : [' + retour + ']';
snd-msg 'Egalite apres retour    : ' + %char(retour = ville);

// Un caractere absent de la page de codes du travail est remplace au retour.
retour = %char(cyrilU);
octet.car = %subst(retour : 1 : 1);
snd-msg 'Texte cyrillique, longueur : ' + %char(%len(retour));
snd-msg 'Code du premier caractere  : ' + %char(octet.code);

*inlr = *on;

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

Longueur en caracteres  : 11
Taille de la zone       : 42 octets
Meme texte en ucs2(20)  : 20 caracteres (complete de blancs)
Retour en caracteres    : [Montpellier]
Egalite apres retour    : 1
Texte cyrillique, longueur : 3
Code du premier caractere  : 63

« Montpellier » fait 11 caractères, donc 22 octets ; la zone varucs2(20) en occupe 42 (20 caractères de 2 octets, plus la longueur). Affecté à un ucs2(20) fixe, le texte est complété de blancs jusqu'à 20 caractères. Le retour par %CHAR redonne le texte d'origine.

Le cas du texte cyrillique montre le risque : ces trois lettres ne sont pas dans la page de codes du travail. Le programme ne plante pas, il les remplace par le caractère de substitution, de code 63 (x'3F'). Le texte est faussé sans erreur.

Le piège

Le retour en caractères peut perdre de l'information sans erreur. Un caractère qui n'existe pas dans la page de codes du travail est remplacé par le caractère de substitution (code 63), sans message. Dans l'exemple, un texte cyrillique de trois lettres revient avec le même nombre de caractères, dont le premier porte le code 63.

Deuxième piège : une zone ucs2(n) est de longueur fixe et complétée de blancs ; %LEN renvoie n, pas la longueur du texte. Pour suivre la longueur réelle, déclarer la zone en varucs2.