ecpg peut fonctionner en mode compatible avec Informix. Dans ce mode, ecpg tente de se comporter comme le précompilateur Informix™ pour Informix™ E/SQL. Dans les grandes lignes, cela permet d'utiliser le signe dollar à la place de la primitive EXEC SQL pour introduire des commandes SQL embarquées :
$int j = 3; $CONNECT TO :dbname; $CREATE TABLE test(i INT PRIMARY KEY, j INT); $INSERT INTO test(i, j) VALUES (7, :j); $COMMIT;
Il existe deux modes de compatibilité : INFORMIX et INFORMIX_SE.
Lors de l'édition de liens pour des programmes qui utilisent ce mode de compatibilité, il est nécessaire de lier les programmes avec libcompat, fournie avec ecpg.
En dehors de la syntaxe expliquée précédemment, le mode de compatibilité Informix™ ajoute à ecpg quelques fonctions pour la saisie, la sortie et la transformation de données ainsi que des instructions SQL embarquées connues d'E/SQL.
Le mode de compatibilité Informix™ est très fortement connecté à la bibliothèque pgtypeslib d'ecpg. pgtypeslib fait correspondre les types de données SQL aux types de données internes du programme C hôte ; la plupart des fonctions supplémentaires du mode de compatibilité Informix™ permettent d'opérer sur ces types. L'étendue de la compatibilité est toutefois limitée. L'idée n'est pas de mimer le comportement d'Informix™ ; cela permet de réaliser plus ou moins les mêmes opérations et fournit des fonctions de même nom et de même comportement de base, mais il n'est pas question de replacer au pied levé une utilisation d'Informix™. De plus, certains types de données sont différents. Ainsi, les types datetime et interval de PostgreSQL™ ne gèrent pas les échelles telles que YEAR TO MINUTE, par exemple ; ecpg ne les supportent donc pas non plus.
ferme la connexion en cours. En fait, il s'agit d'un synonyme de la commande ecpg DISCONNECT CURRENT :
$CLOSE DATABASE; /* ferme la connexion actuelle */
EXEC SQL CLOSE DATABASE;
additionne deux valeurs de type decimal.
int decadd(decimal *arg1, decimal *arg2, decimal *sum);
La fonction reçoit un pointeur vers le premier opérande de type decimal (arg1), un pointeur vers le second opérande de type decimal (arg2) et un pointeur vers une valeur de type decimal destinée à contenir la somme (sum). En cas de succès, la fonction renvoie 0. ECPG_INFORMIX_NUM_OVERFLOW est renvoyé dans le cas d'un dépassement de tampon, et ECPG_INFORMIX_NUM_UNDERFLOW dans le cas d'un soupassement. -1 est renvoyé s'il s'agit d'une autre erreur et errno est configuré avec le numéro errno respectif dans pgtypeslib.
compare deux variables de type decimal.
int deccmp(decimal *arg1, decimal *arg2);
La fonction reçoit un pointeur vers la première valeur de type decimal (arg1), un pointeur vers la seconde (arg2) et renvoie un entier qui indique la plus grande valeur.
1, si la valeur pointée par arg1 est plus grande que la valeur pointée par var2 ;
-1, si la valeur pointée par arg1 est plus petite que la valeur pointée par arg2
0, si les valeurs pointées par arg1 et arg2 sont identiques.
copie une valeur de type decimal.
void deccopy(decimal *src, decimal *target);
La fonction prend en premier argument un pointeur vers la valeur de type decimal à copier (src) et un pointeur vers la structure cible de type decimal (target) comme second argument.
convertit une valeur de sa représentation ASCII en valeur de type decimal.
int deccvasc(char *cp, int len, decimal *np);
La fonction reçoit un pointeur vers la chaîne contenant le représentation textuelle du nombre à convertir (cp) ainsi que sa longueur len. np est un pointeur vers la valeur de type decimal qui sauvegarde le résultat de l'opération.
Quelques formats valides : -2, .794, +3.44, 592.49E07 ou -32.84e-4.
La fonction renvoie 0 en cas de succès. Si un dépassement ou un soupassement survient, ECPG_INFORMIX_NUM_OVERFLOW ou ECPG_INFORMIX_NUM_UNDERFLOW, respectivement, est renvoyé. Si la représentation ASCII ne peut être analysée, ECPG_INFORMIX_BAD_NUMERIC est renvoyé (ou ECPG_INFORMIX_BAD_EXPONENT si le problème survient lors de l'analyse de l'exposant).
convertit une valeur de type double en une valeur de type decimal.
int deccvdbl(double dbl, decimal *np);
La fonction prend la variable de type double à convertir en premier argument (dbl) et comme second argument (np) un pointeur vers la variable décimale amenée à contenir le résultat de l'opération.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
convertit une valeur de type int en une valeur de type decimal.
int deccvint(int in, decimal *np);
La fonction prend la variable de type int à convertir comme premier argument (in) et comme second argument (np) un pointeur vers la variable de type decimal aménée à contenir le résultat de l'opération.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
convertit une valeur de type long en une valeur de type decimal.
int deccvlong(long lng, decimal *np);
La fonction prend la variable de type long à convertir comme premier argument (lng) et comme second argument (np) un pointeur vers la variable de type decimal amenée à contenir le résultat de l'opération.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
effectue la division entre deux variables de type decimal.
int decdiv(decimal *n1, decimal *n2, decimal *result);
La fonction reçoit des pointeurs vers les variables représentant le premier opérande (n1) et le second (n2) et calcule n1/n2. Le résultat (result) est un pointeur vers la variable amenée à contenir le résultat de l'opération.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur. Si un dépassement ou un soupassement survient, ECPG_INFORMIX_NUM_OVERFLOW ou ECPG_INFORMIX_NUM_UNDERFLOW, respectivement, est renvoyé. En cas de tentative de division par zéro, la fonction renvoie ECPG_INFORMIX_DIVIDE_ZERO.
effectue la multiplication de deux valeurs décimales.
int decmul(decimal *n1, decimal *n2, decimal *result);
La fonction reçoit des pointeurs vers les variables représentant le premier opérande (n1) et le second (n2) et calcule n1/n2. Le résultat (result) est un pointeur vers la variable amenée à contenir le résultat de l'opération.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur. Si un dépassement ou un soupassement survient, ECPG_INFORMIX_NUM_OVERFLOW ou ECPG_INFORMIX_NUM_UNDERFLOW, respectivement, est renvoyé.
soustrait une valeur de type decimal à une autre.
int decsub(decimal *n1, decimal *n2, decimal *result);
La fonction reçoit des pointeurs vers les variables représentant le premier opérande (n1) et le second (n2) et calcule n1-n2. Le résultat (result) est un pointeur vers la variable amenée à contenir le résultat de l'opération.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur. Si un dépassement ou soupassement survient, ECPG_INFORMIX_NUM_OVERFLOW ou ECPG_INFORMIX_NUM_UNDERFLOW, respectivment, est renvoyé.
convertit une variable de type decimal en sa représentation ASCII dans une 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 dans sa représentation textuelle. cp est le tampon de stockage du résultat de l'opération. Le paramètre right indique le nombre de chiffres à inclure à droite du point décimal dans le résultat. Le résultat est arrondi à ce nombre de chiffres décimaux. Configurer right à -1 indique que tous les chiffres décimaux disponibles doivent être inclus dans la sortie. Si la longueur du tampon de sortie, indiquée par len, n'est pas suffisante pour contenir la représentation textuelle, seul le caractère * est stocké dans le résultat et -1 est renvoyé.
Cette fonction renvoie -1 si le tampon cp est trop petit ou ECPG_INFORMIX_OUT_OF_MEMORY si la mémoire disponible est épuisée.
convertit une variable de type decimal en double.
int dectodbl(decimal *np, double *dblp);
La fonction reçoit un pointeur vers la valeur du type decimal à convertir (np) et un pointeur vers la variable de type double de stockage du résultat de l'opération (dblp).
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
convertit une variable de type decimal en integer.
int dectoint(decimal *np, int *ip);
La fonction reçoit un pointeur vers la valeur du type decimal à convertir (np) et un pointeur vers la variable de type integer de stockage du résultat de l'opération (ip).
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur. Si un dépassement survient, ECPG_INFORMIX_NUM_OVERFLOW est renvoyé.
L'implantation d'ecpg diffère de celle d'Informix™. Informix™ limite un entier à la plage -32767 .. 32767 alors que les limites de l'implantation d'ecpg dépendent de l'architecture (-INT_MAX .. INT_MAX).
convertit une variable de type decimal en long integer.
int dectolong(decimal *np, long *lngp);
Cette fonction reçoit un pointeur vers la valeur du type decimal à convertir (np) et un pointeur vers la variable de type long de stockage du résultat de l'opération (lngp).
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur. Si un dépassement survient, ECPG_INFORMIX_NUM_OVERFLOW est renvoyé.
L'implantation d'ecpg diffère de celle d'Informix™. Informix™ limite un entier long à la plage -2.147.483.647 .. 2.147.483.647 alors que les limites de l'implantation d'ecpg dépendent de l'architecture (-LONG_MAX .. LONG_MAX).
convertit une date en une chaîne C de type char*.
int rdatestr(date d, char *str);
La fonction prend 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. Il est donc nécessaire d'allouer au minimum 11 octets (ce qui inclut le terminateur NUL) pour la chaîne.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
L'implantation d'ecpg diffère de celle d'Informix™. Dans Informix™, le format peut être modifié en configurant les variables d'environnement. EN revanche, avec ecpg, le format de sortie ne peut pas être modifié.
analyse la représentation textuelle d'une date.
int rstrdate(char *str, date *d);
La fonction reçoit la représentation textuelle de la date à convertir (str) et un pointeur vers une variable de type date (d). Cette fonction ne permet pas de préciser un masque de formatage. Elle utilise le masque de formatage d'Informix™, mm/dd/yyyy. En interne, cette fonction est implantée via rdefmtdate. Du coup, rstrdate n'est pas plus rapide et si c'est possible, il est préférable d'opter pour rdefmtdate qui permet d'expliciter le masque de formatage.
Cette fonction renvoie les mêmes valeurs que rdefmtdate.
récupère la date courante.
void rtoday(date *d);
La fonction reçoit un pointeur 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 du jour, du mois et de l'année à partir 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 trois valeurs de type short integer, mdy. Le nom de la variable indique l'ordre séquentiel : mdy[0] contient le numéro du mois, mdy[1] contient le numéro du jour et mdy[2] contient l'année.
Cette fonction renvoie toujours 0 actuellement.
En interne, cette fonction utilise la fonction PGTYPESdate_julmdy.
utilise un masque de formatage pour convertir une chaîne de caractères en une valeur de type date.
int rdefmtdate(date *d, char *fmt, char *str);
La fonction reçoit un pointeur vers la valeur de type date de stockage du résultat de l'opération (d), le masque de formatage à utiliser pour analyser la date (fmt) et la chaîne C char* contenant la représentation textuelle de la date (str). La représentation textuelle doit correspondre au masque de formatage. Il n'est toutefois pas nécessaire d'avoir une correspondance caractère par caractère entre la chaîne et le masque de formatage. La fonction n'analyse que l'ordre séquentiel et recherche les constantes yy ou yyyy pour la position de l'année, mm pour la position du mois et dd pour la position du jour.
La fonction renvoie les valeurs suivantes :
0 - la fonction a terminé avec succès ;
ECPG_INFORMIX_ENOSHORTDATE - la date ne contient pas de délimiteur entre le jour, le mois et l'année. Dans ce cas, la taille de la chaîne en entrée doit être de six ou huit octets exactement mais elle ne l'est pas ;
ECPG_INFORMIX_ENOTDMY - la chaîne de formatage n'indique pas correctement l'ordre séquentiel de l'année, du mois et du jour ;
ECPG_INFORMIX_BAD_DAY - la chaîne en entrée ne contient pas de jour valide ;
ECPG_INFORMIX_BAD_MONTH - la chaîne en entrée ne contient pas de mois valide ;
ECPG_INFORMIX_BAD_YEAR - la chaîne en entrée ne contient pas d'année valide.
En interne, cette fonction est codée pour utiliser la fonction PGTYPESdate_defmt_asc. La référence présente un tableau d'exemples de saisie.
convertit une variable de type date en sa représentation textuelle en utilisant un masque de formatage.
int rfmtdate(date d, char *fmt, char *str);
La fonction reçoit la date à convertir (d), le masque de formatage (fmt) et la chaîne de stockage de la représentation textuelle de la date (str).
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
En interne, cette fonction utilise la fonction PGTYPESdate_fmt_asc. La référence présente divers exemples.
crée une valeur de type date à partir d'un tableau de trois entiers indiquant le jour, le mois et l'année de la date.
int rmdyjul(short mdy[3], date *d);
La fonction reçoit le tableau de trois entiers courts (mdy) et un pointeur vers une variable de type date pour stocker le résultat de l'opération.
Actuellement, la fonction renvoie toujours 0.
En interne, cette fonction utilise la fonction PGTYPESdate_mdyjul.
renvoie un numéro représentant le jour de la semaine pour une valeur de type date.
int rdayofweek(date d);
La fonction prend comme seul argument la variable de type date d et renvoie un entier qui indique le jour de la semaine pour cette date.
0 - Dimanche
1 - Lundi
2 - Mardi
3 - Mercredi
4 - Jeudi
5 - Vendredi
6 - Samedi
En interne, cette fonction utilise la fonction PGTYPESdate_dayofweek.
récupère le timestamp courant.
void dtcurrent(timestamp *ts);
La fonction récupère la valeur du timestamp courant et la sauvegarde dans la variable de type timestamp pointée par ts.
analyse une variable de type timestamp à partir d'une représentation textuelle en un standard ANSI pour en faire une variable de type timestamp.
int dtcvasc(char *str, timestamp *ts);
La fonction reçoit la chaîne à analyser (str) et un pointeur vers la variable de type timestamp pour stocker le résultat de l'opération (ts).
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
En interne, cette fonction utilise la fonction PGTYPEStimestamp_from_asc. Cette référence présente un tableau d'exemples de saisie.
analyse une variable de type timestamp à partir de sa représentation textuelle dans le standard ANSI en utilisant un masque de formatage pour en faire une variable de type timestamp.
dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue)
La fonction reçoit la chaîne à analyser (inbuf), le masque de formatage à utiliser (fmtstr) et un pointeur vers une variable de type timestamp pour stocker le résultat de l'opération (ts).
Cette fonction utilise la fonction PGTYPEStimestamp_defmt_asc. Voir la documentation pour une liste des spécificateurs de format utilisables.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
soustrait une variable de type timestamp à une autre et renvoie une variable de type interval.
int dtsub(timestamp *ts1, timestamp *ts2, interval *iv);
La fonction soustrait la variable timestamp pointée par ts2 à la variable timestamp pointée par ts1 et stocke le résultat dans la variable interval pointée par iv.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
convertit une variable de type timestamp en une chaîne C de type char*.
int dttoasc(timestamp *ts, char *output);
La fonction reçoit un pointeur vers la variable de type timestamp à convertir (ts) et la chaîne de stockage du résultat de l'opération, output. Elle convertit ts en sa représentation textuelle dans le standard SQL ANSI, définie comme YYYY-MM-DD HH:MM:SS.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
convertit une variable de type timestamp en une chaîne C de type char* en utilisant un masque de formatage.
int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr);
La fonction reçoit un pointeur vers la variable de type timestamp à convertir (ts) et la chaîne de stockage du résultat de l'opération, output, la longueur maximale allouée au tampon de sortie (str_len) et le masque de formatage à utiliser pour la conversion (fmtstr).
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
En interne, cette fonction utilise la fonction PGTYPEStimestamp_fmt_asc. Cette référence fournit les informations concernant les spécificateurs de format de masque utilisables.
convertit une variable de type timestamp en une chaîne C de type char*.
int intoasc(interval *i, char *str);
La fonction reçoit un pointeur vers la variable de type timestamp à convertir (i) et la chaîne de stockage du résultat de l'opération, str. Elle convertit i en sa représentation textuelle dans le standard SQL ANSI, définie comme YYYY-MM-DD HH:MM:SS.
La fonction renvoie 0 en cas de succès et une valeur négative en cas d'erreur.
convertit un entier long en 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 lng_val de type long, le masque de formatage fmt et un pointeur vers un tampon de sortie outbuf. Elle convertit la valeur de type long en sa représentation textuelle selon le masque de formatage.
Le masque de formatage est composé de caractères de spécification de formats à prendre parmi :
* (astérisque) - remplace une position autrement vide par une astérisque ;
& (esperluette, perluette ou « et commercial ») - remplace une position autrement vide par un zéro ;
# - remplace les zéros de début de chaîne par des espaces ;
< - justifie le nombre à gauche dans la chaîne ;
, (virgule) - groupe les nombres de plus de quatre chiffres en groupes de trois chiffres séparés par des virgules ;
. (point) - sépare la partie décimale de la partie entière ;
- (moins) - apparaît si le nombre est négatif ;
+ (plus) - apparaît si le nombre est positif ;
( - remplace le signe moins devant le nombre négatif. Le signe moins n'apparaît pas ;
) - remplace le signe moins et est affiché derrière la valeur négative ;
$ - représente le symbole monétaire.
convertit une chaîne en majuscules.
void rupshift(char *str);
La fonction reçoit un pointeur vers la chaîne et transforme chaque caractère minuscule en majuscule.
renvoie le nombre de caractères dans une chaîne sans compter les espaces en fin de chaîne.
int byleng(char *str, int len);
La fonction attend une chaîne de longueur fixe comme premier argument (str) et sa longueur comme deuxième argument (len). Elle renvoie le nombre de caractères significatifs, c'est-à-dire la longueur de la chaîne sans les espaces de fin de chaîne.
copie une chaîne de longueur fixe dans une chaîne terminée par NUL.
void ldchar(char *src, int len, char *dest);
La fonction reçoit une chaîne de longueur fixe à copier (src), sa longueur (len) et un pointeur vers la chaîne de destination (dest). Il est nécessaire de réserver au moins len+1 octets pour la chaîne vers laquelle dest pointe. La fonction copie au maximum len octets vers le nouvel emplacement (moins si la chaîne source contient des espaces en fin de chaîne) et ajoute le terminateur de chaîne NUL.
int rgetmsg(int msgnum, char *s, int maxsize);
Cette fonction existe mais elle n'est pas codée actuellement !
int rtypalign(int offset, int type);
Cette fonction existe mais elle n'est pas codée actuellement !
int rtypmsize(int type, int len);
Cette fonction existe mais elle n'est pas codée actuellement !
int rtypwidth(int sqltype, int sqllen);
Cette fonction existe mais elle n'est pas codée actuellement !
initialise une variable à NULL.
int rsetnull(int t, char *ptr);
La fonction reçoit un entier qui indique le type de la variable et un pointeur vers la variable elle-même qui est convertie en un pointeur de chaîne C, type char*.
Les types suivants existent :
CCHARTYPE - pour une variable de type char ou char* ;
CSHORTTYPE - pour une variable de type short int ;
CINTTYPE - pour une variable de type int ;
CBOOLTYPE - pour une variable de type boolean ;
CFLOATTYPE - pour une variable de type float ;
CLONGTYPE - pour une variable de type long ;
CDOUBLETYPE - pour une variable de type double ;
CDECIMALTYPE - pour une variable de type decimal ;
CDATETYPE - pour une variable de type date ;
CDTIMETYPE - pour une variable de type timestamp.
Exemple d'appel de la 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);
La fonction reçoit le type de la variable à tester (t) ainsi qu'un pointeur vers cette variable (ptr). Ce dernier a besoin d'être converti en char*. Voir la fonction rsetnull pour une liste des types de variable possibles.
Exemple d'utilisation de la fonction :
$char c[] = "abc "; $short s = 17; $int i = -74874; risnull(CCHARTYPE, (char *) c); risnull(CSHORTTYPE, (char *) &s); risnull(CINTTYPE, (char *) &i);
Toutes les constantes qui suivent décrivent des erreurs et toutes sont négatives. Dans les descriptions des différentes constantes se trouve la valeur de la constante dans l'implantation actuelle. Il est toutefois préférable de ne pas compter sur ce nombre. Cela dit on peut se reposer sur le fait que toutes les valeurs sont négatives.
Les fonctions renvoient cette valeur si un dépassement survient lors d'un calcul. En interne, elle vaut -1200 (définition Informix™).
Les fonctions renvoient cette valeur si un soupassement survient lors d'un calcul. En interne, elle vaut -1201 (définition Informix™).
Les fonctions renvoient cette valeur si une tentative de division par zéro est observée. En interne, elle vaut -1202 (définition Informix™).
Les fonctions renvoient cette valeur si une mauvaise valeur pour l'année est trouvée lors de l'analyse d'une date. En interne, elle vaut -1204 (définition Informix™).
Les fonctions renvoient cette valeur si une mauvaise valeur pour le mois est trouvée lors de l'analyse d'une date. En interne, elle vaut -1205 (définition Informix™).
Les fonctions renvoient cette valeur si une mauvaise valeur pour le jour est trouvée lors de l'analyse d'une date. En interne, elle vaut -1206 (définition Informix™).
Les fonctions renvoient cette valeur si une routine d'analyse nécessite une représentation courte de date mais qu'elle n'obtient pas une chaîne de la bonne longueur. En interne, elle vaut -1209 (définition Informix™).
Les fonctions renvoient cette valeur en cas de problème lors de la conversion de la date. En interne, elle vaut -1210 (définition Informix™).
Les fonctions renvoient cette valeur en cas de manque de mémoire. En interne, elle vaut -1211 (définition Informix™).
Les fonctions renvoient cette valeur si une routine d'analyse attend un masque de formatage (comme mmddyy) mais que certains champs n'ont pas été indiqués correctement. En interne, elle vaut -1212 (définition Informix™).
Les fonctions renvoient cette valeur si une routine d'analyse ne peut pas créer la représentation textuelle d'une valeur numérique, parce qu'elle contient des erreurs, ou si une routine ne peut terminer un calcul impliquant des variables numériques parce que l'une d'elle, au moins, est invalide. En interne, elle vaut -1213 (définition Informix™).
Les fonctions renvoient cette valeur en cas de mauvais exposant. En interne, elle vaut -1216 (définition Informix™).
Les fonctions renvoient cette valeur en cas de mauvaise valeur. En interne, elle vaut -1218 (définition Informix™).
Les fonctions renvoient cette valeur en cas de caractères superflus. En interne, elle vaut -1264 (définition Informix™).
Bibliothèque pgtypes
