33.15. Mode de Compatibilité Informix

Cet ordre ferme la connexion courante. En fait, c'est un synonyme du DISCONNECT CURRENT d'ECPG:

$CLOSE DATABASE;                /* ferme la connexion courante */
EXEC SQL CLOSE DATABASE;
       

En raison des différences sur la façon dont ECPG fonctionne par rapport à l'ESQL/C d'Informix (c'est à dire quelles étapes sont purement des transformations grammaticales et quelles étapes s'appuient sur la librairie sous-jacente), il n'y a pas d'ordre FREE nom_curseur dans ECPG. C'est parce que, dans ECPG, DECLARE CURSOR ne génère pas un appel de fonction à la librairie qui utilise le nom du curseur. Ce qui implique qu'il n'y a pas à gérer les curseurs SQL à l'exécution dans la librairie ECPG, seulement dans le serveur PostgreSQL.

FREE nom_requete est un synonyme de DEALLOCATE PREPARE nom_requete.

Le nombre de champs dans le descripteur SQLDA.

Un pointeur vers les propriétés par champ.

Inutilisé, rempli d'octets à zéro.

La taille de la structure allouée.

Un pointeur vers la structure SQLDA suivante si le jeu de résultat contient plus d'un enregistrement.

Pointeur inutilisé, contient NULL. Gardé pour la compatibilité Informix.

Type du champ. Les constantes sont dans sqltypes.h

La longueur du champ de données. Length of the field data.

Un pointeur vers le champ de données. Ce pointeur est de type char*, la donnée pointée par lui est en format binaire. Par exemple:

int intval;

switch (sqldata->sqlvar[i].sqltype)
{
    case SQLINTEGER:
        intval = *(int *)sqldata->sqlvar[i].sqldata;
        break;
  ...
}
       

Un pointeur vers l'indicateur NULL. Si retourné par DESCRIBE ou FETCH alors c'est toujours un pointeur valide. Si utilisé comme valeur d'entrée pour EXECUTE ... USING sqlda; alors une valeur de pointeur NULL signifie que la valeur pour ce champ est non nulle. Sinon, un pointeur valide et sqlitype doivent être positionnés correctement. Par exemple:

if (*(int2 *)sqldata->sqlvar[i].sqlind != 0)
    printf("value is NULL\n");
       

Le nom du champ. Chaîne terminée par 0.

Réservé dans Informix, valeurs de PQfformat() pour le champ.

Type de l'indicateur de données NULL. C'est toujours SQLSMINT quand les données sont retournées du serveur. Quand la SQLDA est utilisée pour une requête paramétrique, la donnée est traitée en fonction du type de donnée positionné.

Longueur de l'indicateur de données NULL.

Type étendu du champ, résultat de PQftype().

Inutilisé.

C'est égal à sqldata si sqllen est plus grand que 32KB.

Ajoute deux valeurs décimales.

int decadd(decimal *arg1, decimal *arg2, decimal *sum);
       

La fonction reçoit un poiteur sur la première opérande de type decimal (arg1), un pointeur sur la seconde opérande de type decimal (arg2) et un pointeur sur la valeur de type decimal qui contiendra la somme (sum). En cas de succès, la fonction retourne 0. ECPG_INFORMIX_NUM_OVERFLOW est retourné en cas de dépassement et ECPG_INFORMIX_NUM_UNDERFLOW en cas de soupassement. -1 est retourné pour les autres échecs et errno est positionné au nombre correspondant errno de pgtypeslib. pgtypeslib.

Compare deux variables de type decimal.

int deccmp(decimal *arg1, decimal *arg2);
       

La fonction reçoit un pointeur vers la première valeur decimal (arg1), un pointeur vers la seconde valeur decimal (arg2) et retourne une valeur entière qui indique quelle elle la plus grosse valeur.

Copie une valeur decimal.

void deccopy(decimal *src, decimal *target);
       

La fonction reçoin un pointeur vers la valeur decimal qui doit être copiée comme premier argument (src) et un pointeur vers la structure de type decimale cible (target) comme second argument.

Convertit une valeur de sa représentation ASCII vers un type decimal.

int deccvasc(char *cp, int len, decimal *np);
       

La fonction reçoit un pointeur vers une chaîne qui contient la représentation chaîne du nombre à convertir (cp) ainsi que sa longueur len. np est un pointeur vers la valeur decimal dans laquelle sauver le résultat de l'opération.

Voici quelques formats valides: -2, .794, +3.44, 592.49E07 ou -32.84e-4.

La fonction retourne 0 en cas de succès. Si un dépassement ou un soupassement se produisent, ECPG_INFORMIX_NUM_OVERFLOW ou ECPG_INFORMIX_NUM_UNDERFLOW est retourné. Si la représentation ASCII n'a pas pu être interprétée, ECPG_INFORMIX_BAD_NUMERIC est retourné ou ECPG_INFORMIX_BAD_EXPONENT si le problème s'est produit lors de l'analyse de l'exposant.

Convertit une valeur de type double vers une valeur de type decimal.

int deccvdbl(double dbl, decimal *np);
       

La fonction reçoit la variable de type double qui devrait être convertie comme premier argument (dbl). Comme second argument (np), la fonction reçoit un pointeur vers la variable decimal qui recevra le résultat de l'opération.

La fonction retourne 0 en cas de succès et une valeur négative si la conversion a échoué.

Convertit une valeur de type int vers une valeur de type decimal.

int deccvint(int in, decimal *np);
       

La fonction reçoit la variable de type int à convertir comme premier argument (in). Comme second argument (np), la fonction reçoit un pointeur vers la variable decimal qui recevra le résultat de l'opération.

La fonction retourne 0 en cas de succès et une valeur négative si la conversion a échoué.

Convertit une valeur de type long vers une valeur de type decimal.

int deccvlong(long lng, decimal *np);
       

La fonction reçoit la variable de type long à convertir comme premier argument (lng). Comme second argument (np), la fonction reçoit un pointeur vers la variable decimal qui recevra le résultat de l'opération.

La fonction retourne 0 en cas de succès et une valeur négative si la conversion a échoué.

Divise deux variables de type decimal.

int decdiv(decimal *n1, decimal *n2, decimal *result);
       

La fonction reçoit des pointeurs vers les deux variables qui sont le premier (n1) et le second (n2) opérandes et calcule n1/n2. result est un pointeur vers la variable qui recevra le résultat de l'opération.

En cas de succès, 0 est retourné, et une valeur négative si la division échoue. En cas de dépassement ou de soupassement, la fonction retourne ECPG_INFORMIX_NUM_OVERFLOW ou ECPG_INFORMIX_NUM_UNDERFLOW respectivement. Si une tentative de division par zéro se produit, la fonction retourne ECPG_INFORMIX_NUM_OVERFLOW.

Multiplie deux valeurs decimal.

int decmul(decimal *n1, decimal *n2, decimal *result);
       

La fonction reçoit des pointeurs vers les deux variables qui sont le premier (n1) et le second (n2) opérandes et calcule n1/n2. result est un pointeur vers la variable qui recevra le résultat de l'opération.

En cas de succès, 0 est retourné, et une valeur négative si la division échoue. En cas de dépassement ou de soupassement, la fonction retourne ECPG_INFORMIX_NUM_OVERFLOW ou ECPG_INFORMIX_NUM_UNDERFLOW respectivement.

Soustrait une valeur decimal d'une autre.

int decsub(decimal *n1, decimal *n2, decimal *result);
       

La fonction reçoit des pointeurs vers les deux variables qui sont le premier (n1) et le second (n2) opérandes et calcule n1/n2. result est un pointeur vers la variable qui recevra le résultat de l'opération.

En cas de succès, 0 est retourné, et une valeur négative si la division échoue. En cas de dépassement ou de soupassement, la fonction retourne ECPG_INFORMIX_NUM_OVERFLOW ou ECPG_INFORMIX_NUM_UNDERFLOW respectivement.

Convertit une variable de type decimal vers sa représentation ASCII sous forme de chaîne C char*.

int dectoasc(decimal *np, char *cp, int len, int right)
       

La fonction reçoit un pointeur vers une variable de type decimal (np) qu'elle convertit vers sa représentation textuelle. cp est le tampon qui devra contenir le résultat de l'opération. Le paramètre right spécifie combien de chiffers après la virgule doivent être inclus dans la sortie. Le résultat sera arrondi à ce nombre de chiffres décimaux. Positionner right à -1 indique que tous les chiffres décimaux disponibles devraient être inclus dans la sortie. Si la longueur du tampon de sortie, qui est indiquée par len n'est pas suffisante pour contenir toute la représentation en incluant le caractère NUL final, seul un caractère unique * est stocké dans le résultat, et -1 est retourné.

La fonction retourne -1 si le tampon cp était trop petit ou ECPG_INFORMIX_OUT_OF_MEMORY si plus de mémoire n'était disponible.

Convertit une variable de type decimal vers un double.

int dectodbl(decimal *np, double *dblp);
       

La fonction reçoit un pointeur vers la valeur decimal à convertir (np) et un pointeur vers la variable double qui devra recevoir le résultat de l'opération (dblp).

La fonction retourne 0 en cas de succès et une valeur négative si la conversion a échoué.

Convertit une variable de type decimal vers un integer.

int dectoint(decimal *np, int *ip);
       

La fonction reçoit un pointeur vers la valeur decimal à convertir (np) et un pointeur vers la variable integer qui devra recevoir le résultat de l'opération (ip).

La fonction retourne 0 en cas de succès et une valeur négative si la conversion a échoué. Si un dépassement s'est produit, ECPG_INFORMIX_NUM_OVERFLOW est retourné.

Notez que l'implémentation d'ECPG diffère de celle d'Informix™. Informix™ limite un integer entre -32767 et 32767, alors que la limite de l'implémentation d'ECPG dépend de l'architecture (-INT_MAX .. INT_MAX).

Convertit une variable de type decimal vers un long integer.

int dectolong(decimal *np, long *lngp);
       

La fonction reçoit un pointeur vers la valeur decimal à convertir (np) et un pointeur vers la variable long qui devra recevoir le résultat de l'opération (lngp).

La fonction retourne 0 en cas de succès et une valeur négative si la conversion a échoué. Si un dépassement s'est produit, ECPG_INFORMIX_NUM_OVERFLOW est retourné.

Notez que l'implémentation d'ECPG diffère de celle d'Informix™. Informix™ limite un integer entre --2,147,483,647 à 2,147,483,647 alors que la limite de l'implémentation d'ECPG dépend de l'architecture (-LONG_MAX .. LONG_MAX).

Convertit une date vers une chaîne char* C.

int rdatestr(date d, char *str);
       

La fonction reçoit deux arguments, le premier est la date à convertir (d) et le second est un pointeur vers la chaîne cible. Le format de sortie est toujours yyyy-mm-dd, vous aurez donc à allouer au moins 11 octets (en incluant le terminateur NUL) pour la chaîne.

La fonction retourne 0 en cas de succès et une valeur négative si la conversion a échoué.

Notez que l'implémentation d'ECPG diffère de celle de Informix™. Dans Informix™ le format peut être modifié par le positionnement de variable d'enregistrement. Dans ECPG par contre, vous ne pouvez pas changer le format de sortie.

Convertit la représentation textuelle d'une date.

int rstrdate(char *str, date *d);
       

La fonction reçoit la représentation textuelle d'une date à convertir (str) et un pointeur vers une variable de type date (d). Cette fonction ne vous permet pas de fournir un masque de formatage. Il utilise le format par défaut d'Informix™ qui est mm/dd/yyyy. En interne, cette fonction est implémentée au travers de rdefmtdate. Par conséquent, rstrdate n'est pas plus rapide et si vous avez le choix, vous devriez opter pour rdefmtdate, qui vous permet de spécifier le masque de formatage explicitement.

La fonction retourne les mêmes valeurs que rdefmtdate.

Récupère la date courante.

void rtoday(date *d);
       

La fonction reçoit un poiteur vers une variable de type date (d) qu'elle positionne à la date courante.

En interne, cette fonction utilise la fonction PGTYPESdate_today.

Extrait les valeurs pour le jour, le mois et l'année d'une variable de type date.

int rjulmdy(date d, short mdy[3]);
       

La fonction reçoit la date d et un pointeur vers un tableau de 3 entiers courts mdy. Le nom de la variable indique l'ordre séquentiel: mdy[0] contiendra le numéro du mois, mdy[1] contiendra le numéro du jour, et mdy[2] contiendra l'année.

La fonction retourne toujours 0 pour le moment.

En interne, cette fonction utilise la fonction PGTYPESdate_julmdy.

Utilise un masque de formatage pour convertir une chaîne de caractère vers une valeur de type date.

int rdefmtdate(date *d, char *fmt, char *str);
       

La fonction reçoit un pointeur vers une valeur date qui devra contenir le résultat de l'opération (d), le masque de formatage à utiliser pour traiter la date (fmt) et la chaîne de caractère char* C qui contient la représentation textuelle de la date (str). La représentation textuelle doit correspondre au masque de formatage. La fonction n'analyse qu'en ordre séquentiel et recherche les littéraux yy ou yyyy qui indiquent la position de l'année, mm qui indique la position du mois et dd qui indique la position du jour.

La fonction retourne les valeurs suivantes:

En interne, cette fonction est implémentée en utilisant la fonction PGTYPESdate_defmt_asc. Voyez la référence à cet endroi pour la table d'exemples.

Convertit une variable de type date vers sa représentation textuelle en utilisant un masque de formatage.

int rfmtdate(date d, char *fmt, char *str);
       

La fonction reçoin une date à convertir (d), le masque de formatage (fmt) et la chaîne qui contiendra la représentation textuelle de la date (str).

La fonction retourne 0 en cas de succès et une valeur négative

En interne, cette fonction utilise la fonction PGTYPESdate_fmt_asc, voyez la référence pour des exemples.

Crée une valeur date à partir d'un tableau de 3 entiers courts qui spécifient le jour, le mois et l'année de la date.

int rmdyjul(short mdy[3], date *d);
       

La fonction reçoit le tableau des 3 entiers courst (mdy) et un pointeur vers une variable de type date qui contiendra le résultat de l'opération.

La fonction retourne toujours 0 à l'heure actuelle.

En interne la fonction est implémentée en utilisante la fonction PGTYPESdate_mdyjul.

Retourne un nombre représentant le jour de la semaine pour une valeur de date.

int rdayofweek(date d);
       

La fonction reçoit la variable date d comme seul argument et retourne un entier qui indique le jour de la semaine pour cette date.

En intere, cette fonction est implémentée en utilisant la fonction PGTYPESdate_dayofweek.

Récupère le timestamp courant.

void dtcurrent(timestamp *ts);
       

La fonction récupère le timestamp courant et l'enregistre dans la variable timestamp vers laquelle ts pointe.

Convertit un timestamp de sa représentation textuelle vers une variable timestamp.

int dtcvasc(char *str, timestamp *ts);
       

La fonction reçoit la chaîne à traiter (str) et un pointeur vers la variable timestamp qui contiendra le résultat de l'opération (ts).

La fonction retourne 0 en cas de succès et une valeur négative

En interne, cette fonction utilise la fonction PGTYPEStimestamp_from_asc. Voyez la référence pour un tableau avec des exemples de formats.

Convertit un timestamp de sa représentation textuelle vers une variable timestamp en utilisant un masque de formatage.

dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue)
       

La fonction reçoit la chaîne à traiter (inbuf), le masque de formatage à utiliser (fmtstr) et un pointeur vers la variable timestamp qui contiendra le résultat de l'opération (dtvalue).

Cette fonction est implémentée en utilisant la fonction PGTYPEStimestamp_defmt_asc. Voyez la documentation à cet endroit pour la liste des spécificateurs de formats qui peuvent être utilisés.

La fonction retourne 0 en cas de succès et une valeur négative

Soustrait un timestamp d'un autre et retourne une variable de type interval.

int dtsub(timestamp *ts1, timestamp *ts2, interval *iv);
       

La fonction soustrait la variable timestamp vers laquelle ts2 pointe de la variable timestamp vers laquelle ts1 pointe et stockera le résultat dans la variable intervalle vers laquelle iv pointe.

En cas de succès, la fonction retourne 0, et une valeur négative si une erreur s'est produite.

Convertit une variable timestamp vers une chaîne char* C.

int dttoasc(timestamp *ts, char *output);
       

La fonction reçoit un pointeur vers une variable timestamp à convertir (ts) et la chaîne qui devra contenir le résultat de l'opération (output). Elle convertit ts vers sa représentation textuelle comme spécifié par le standard SQL, qui est YYYY-MM-DD HH:MM:SS.

En cas de succès, la fonction retourne 0, et une valeur négative si une erreur s'est produite.

Convertit une variable timestamp vers un char* C en utilisant un masque de formatage.

int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr);
       

La fonction reçoit un pointeur vers le timestamp à convertir comme premier argument (ts), un pointeur vers le tampon de sortie (output), la longueur maximale qui a été allouée pour le tampon de sortie (str_len) et le masque de formatage à utiliser pour la conversion (fmtstr).

En cas de succès, la fonction retourne 0, et une valeur négative si une erreur s'est produite.

En interne, cette fonction utilise la fonction PGTYPEStimestamp_fmt_asc. Voyez la référence pour des informations sur les spécifications de masque de formatage qui sont utilisables.

Convertit une variable interval en chaîne char* C.

int intoasc(interval *i, char *str);
       

La fonction reçoit un pointeur vers la variable interval à convertir (i) et la chaîne qui contiendra le résultat de l'opération (str). Elle convertit i vers sa représentation textuelle suivant le standard SQL, qui est YYYY-MM-DD HH:MM:SS.

En cas de succès, la fonction retourne 0, et une valeur négative si une erreur s'est produite.

Convertit une valeur long integer vers sa représentation textuelle en utilisant un masque de formatage.

int rfmtlong(long lng_val, char *fmt, char *outbuf);
       

La fonction reçoit la valeur long lng_val, le masque de formatage fmt et un pointeur vers le tampon de sortie outbuf. Il convertit la valeur long vers sa représentation textuelle en fonction du masque de formatage.

Le masque de formatage peut être composé des caractères suivants de spécification:

Passe une chaîne en majuscule.

void rupshift(char *str);
       

La fonction reçoit un pointeur vers une chaîne et convertit tous ses caractères en majuscules.

Retourne le nombre de caracères dans une chaîne sans compter les blancs finaux.

int byleng(char *str, int len);
       

La fonction attend une chaîne de longueur fixe comme premier argument (str) et sa longueur comme second argument (len). Elle retourne le nombre de caractères significatifs, c'est à dire la longueur de la chaîne sans ses blancs finaux.

Copie une chaîne de longueur fixe vers une chaîne terminée par un NUL.

void ldchar(char *src, int len, char *dest);
       

La fonction reçoit la chaîne de longueur fixe à copier (src), sa longueur (len) et un pointeur vers la mémoire destinataire (dest). Notez que vous aurez besoin de réserver au moins len+1 octets pour la chaine vers laquelle pointe dest. Cette fonction copie au plus len octets vers le nouvel emplacement (moins si la chaîne source a des blancs finaux) et ajoute le terminateur NUL.

int rgetmsg(int msgnum, char *s, int maxsize);
       

Cette fonction existe mais n'est pas implémentée pour le moment!

int rtypalign(int offset, int type);
       

Cette fonction existe mais n'est pas implémentée pour le moment!

int rtypmsize(int type, int len);
       

Cette fonction existe mais n'est pas implémentée pour le moment!

int rtypwidth(int sqltype, int sqllen);
       

Cette fonction existe mais n'est pas implémentée pour le moment!

Set a variable to NULL.

int rsetnull(int t, char *ptr);
       

La fonction reçoit un entier qui indique le type de variable et un pointeur vers la variable elle même, transtypé vers un pointeur char*.

The following types exist:

Voici un exemple d'appel à cette fonction:

$char c[] = "abc       ";
$short s = 17;
$int i = -74874;

rsetnull(CCHARTYPE, (char *) c);
rsetnull(CSHORTTYPE, (char *) &s);
rsetnull(CINTTYPE, (char *) &i);

       

Teste si une variable est NULL.

int risnull(int t, char *ptr);
       

Cette fonction reçoit le type d'une variable à tester (t) ainsi qu'un pointeur vers cette variable (ptr). Notez que ce dernier doit être transtypé vers un char*. Voyez la fonction rsetnull pour une liste de types de variables possibles.

Voici un exemple de comment utiliser cette fonction:

$char c[] = "abc       ";
$short s = 17;
$int i = -74874;

risnull(CCHARTYPE, (char *) c);
risnull(CSHORTTYPE, (char *) &s);
risnull(CINTTYPE, (char *) &i);

       

Les fonctions retournent cette valeur si un dépassement s'est produit dans un calcul. En interne, elle est définie à -1200 (la définition Informix™).

Les fonctions retournent cette valeur si un soupassement s'est produit dans un calcul. En interne, elle est définie à -1201 (la définition Informix™).

Les fonctions retournent cette valeur si une division par zéro a été tentée. En interne, elle est définie à -1202 (la définition Informix™).

Les fonctions retournent cette valeur si une mauvaise valeur pour une année a été trouvée lors de l'analyse d'une date. En interne elle est définie à -1204 (la définition Informix™).

Les fonctions retournent cette valeur si une mauvaise valeur pour un mois a été trouvée lors de l'analyse d'une date. En interne elle est définie à -1205 (la définition Informix™).

Les fonctions retournent cette valeur si une mauvaise valeur pour un jour a été trouvée lors de l'analyse d'une date. En interne elle est définie à -1206 (la définition Informix™).

Les fonctions retournent cette valeur si une routine d'analyse a besoin d'une représentation courte de date mais que la chaîne passée n'était pas de la bonne longueur. En interne elle est définie à -1206 (la définition Informix™).

Les fonctions retournent cette valeur si une erreur s'est produite durant un formatage de date. En interne, elle est définie à -1210 (la définition Informix™).

Les fonctions retournent cette valeur si elles se sont retrouvées à court de mémoire durant leur fonctionnement. En interne, elle est définie à -1211 (la définition Informix™).

Les fonctions retournent cette valeur si la routine d'analyse devait recevoir un masque de formatage (comme mmddyy) mai que tous les champs n'étaient pas listés correctement. En interne, elle est définie à -1212 (la définition Informix™).

Les fonctions retournent cette valeur soit parce qu'une routine d'analyse ne peut pas analyser la représentation textuelle d'une valeur numérique parce qu'elle contient des erreurs, soit parce qu'une routine ne peut pas terminer un calcul impliquant des variables numeric parce qu'au moins une des variables numeric est invalide. En interne, elle est définie à -1213 (la définition Informix™).

Les fonctions retournent cette valeur si elles n'ont pas réussi à analyser l'exposant de la représentation textuelle d'une valeur numérique. En interne, elle est définie à -1216 (la définition Informix™).

Les fonctions retournent cette valeur si une chaîne de date invalide leur a été passée. En interne, elle est définie à -1218 (la définition Informix™).

Les fonctions retournent cette valeur si trop de caractères ont été trouvés dans la représentation textuelle d'un format date. En interne, elle est définie à -1264 (la définition Informix™).