33.15. Режим совместимости с Informix

Этот оператор закрывает текущее подключение. Фактически это синоним команды DISCONNECT CURRENT в ECPG:

$CLOSE DATABASE;                /* закрыть текущее подключение */
EXEC SQL CLOSE DATABASE;

Из-за различий в подходах ECPG и ESQL/C Informix (т. е. другого разделения на чисто грамматические преобразования и вызовы нижележащей библиотеки времени выполнения), в ECPG нет оператора FREE имя_курсора. Это связано с тем, что в ECPG команда DECLARE CURSOR не сводится к вызову функции в библиотеке времени выполнения, которая бы принимала имя курсора. Это значит, что курсоры SQL в библиотеке ECPG не требуют обслуживания, оно требуется только на уровне сервера PostgreSQL.

Команда FREE имя_оператора является синонимом команды DEALLOCATE PREPARE имя_оператора.

Число полей в дескрипторе SQLDA.

Указатель на свойства по полям.

Не используется, заполняется нулями.

Размер структуры в памяти.

Указатель на следующую структуру SQLDA, если набор результатов содержит больше одной записи.

Неиспользуемый указатель, содержит NULL. Сохраняется для совместимости с Informix.

Тип поля. Соответствующие константы представлены в sqltypes.h

Длина данных поля.

Указатель на данные поля. Этот указатель имеет тип char *, но он указывает на данные в двоичном формате. Например:

int intval;

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

Указатель на индикатор NULL. Если возвращается командами DESCRIBE или FETCH, это всегда действительный указатель. Если передаётся на вход команде EXECUTE ... USING sqlda;, NULL вместо указателя означает, что значение этого поля отлично от NULL. Чтобы обозначить NULL в поле, необходимо корректно установить этот указатель и sqlitype. Например:

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

Имя поля, в виде строки с завершающим 0.

Зарезервировано в Informix, значение PQfformat() для данного поля.

Тип данных индикатора NULL. При получении данных с сервера это всегда SQLSMINT. Когда SQLDA используется в параметризованном запросе, данные индикатора обрабатываются в соответствии с указанным здесь типом.

Длина данных индикатора NULL.

Расширенный тип поля, результат функции PQftype().

Не используются.

Совпадает с sqldata, если sqllen превышает 32 Кбайта.

Складывает два значения типа decimal.

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

Эта функция получает указатель на первый операнд типа decimal (arg1), указатель на второй операнд типа decimal (arg2) и указатель на переменную типа decimal, в которую будет записана сумма (sum). В случае успеха эта функция возвращает 0. ECPG_INFORMIX_NUM_OVERFLOW возвращается в случае переполнения, а ECPG_INFORMIX_NUM_UNDERFLOW в случае антипереполнения. При любых других ошибках возвращается -1, а в errno устанавливается код errno из pgtypeslib.

Сравнивает два значения типа decimal.

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

Эта функция получает указатель на первое значение типа decimal (arg1), указатель на второе значение типа decimal (arg2) и возвращает целое, отражающее результат сравнения этих чисел.

• 1, если значение, на которое указывает arg1, больше значения, на которое указывает var2

• -1, если значение, на которое указывает arg1, меньше значения, на которое указывает arg2

• 0, если значение, на которое указывает arg1, равно значению, на которое указывает arg2

Копирует значение типа decimal.

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

Функция принимает в первом аргументе (src) указатель на значение decimal, которое должно быть скопировано, а во втором аргументе (target) принимает указатель на структуру типа decimal для скопированного значения.

Преобразует значение из представления ASCII в тип decimal.

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

Эта функция получает указатель на строку, содержащую строковое представление числа, которое нужно преобразовать, (cp), а также его длину len. В np передаётся указатель на переменную типа decimal, в которую будет помещён результат преобразования.

Допустимыми являются, например следующие форматы: -2, .794, +3.44, 592.49E07 или -32.84e-4.

В случае успеха эта функция возвращает 0. При переполнении или антипереполнении возвращается ECPG_INFORMIX_NUM_OVERFLOW или ECPG_INFORMIX_NUM_UNDERFLOW, соответственно. Если разобрать ASCII-представление не удаётся, возвращается ECPG_INFORMIX_BAD_NUMERIC или ECPG_INFORMIX_BAD_EXPONENT, если не удаётся разобрать компонент экспоненты.

Преобразует значение double в значение типа decimal.

int deccvdbl(double dbl, decimal *np);

Данная функция принимает в первом аргументе (dbl) переменную типа double, которая должна быть преобразована. Во втором аргументе (np) она принимает указатель на переменную decimal, в которую будет помещён результат операции.

Эта функция возвращает 0 в случае успеха, либо отрицательное значение, если выполнить преобразование не удалось.

Преобразует значение int в значение типа decimal.

int deccvint(int in, decimal *np);

Данная функция принимает в первом аргументе (in) переменную типа int, которая должна быть преобразована. Во втором аргументе (np) она принимает указатель на переменную decimal, в которую будет помещён результат операции.

Эта функция возвращает 0 в случае успеха, либо отрицательное значение, если выполнить преобразование не удалось.

Преобразует значение long в значение типа decimal.

int deccvlong(long lng, decimal *np);

Данная функция принимает в первом аргументе (lng) переменную типа long, которая должна быть преобразована. Во втором аргументе (np) она принимает указатель на переменную decimal, в которую будет помещён результат операции.

Эта функция возвращает 0 в случае успеха, либо отрицательное значение, если выполнить преобразование не удалось.

Делит одну переменную типа decimal на другую.

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

Эта функция получает указатели на переменные (n1 и n2) и вычисляет частное n1/n2. В result передаётся указатель на переменную, в которую будет помещён результат операции.

В случае успеха возвращается 0, а при ошибке — отрицательное значение. В случае переполнения или антипереполнения данная функция возвращает ECPG_INFORMIX_NUM_OVERFLOW или ECPG_INFORMIX_NUM_UNDERFLOW, соответственно. При попытке деления на ноль возвращается ECPG_INFORMIX_DIVIDE_ZERO.

Перемножает два значения типа decimal.

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

Эта функция получает указатели на переменные (n1 и n2) и вычисляет произведение n1*n2. В result передаётся указатель на переменную, в которую будет помещён результат операции.

В случае успеха возвращается 0, а при ошибке — отрицательное значение. В случае переполнения или антипереполнения данная функция возвращает ECPG_INFORMIX_NUM_OVERFLOW или ECPG_INFORMIX_NUM_UNDERFLOW, соответственно.

Вычитает одно значение типа decimal из другого.

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

Эта функция получает указатели на переменные (n1 и n2) и вычисляет разность n1-n2. В result передаётся указатель на переменную, в которую будет помещён результат операции.

В случае успеха возвращается 0, а при ошибке — отрицательное значение. В случае переполнения или антипереполнения данная функция возвращает ECPG_INFORMIX_NUM_OVERFLOW или ECPG_INFORMIX_NUM_UNDERFLOW, соответственно.

Преобразует переменную типа decimal в представление ASCII (в строку C char*).

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

Эта функция получает указатель на переменную типа decimal (np), которая будет преобразована в текстовое представление. Аргумент cp указывает на буфер, в который будет помещён результат операции. Аргумент right определяет, сколько должно выводиться цифр правее десятичной точки. Результат будет округлён до этого числа десятичных цифр. Значение right, равное -1, указывает, что выводиться должны все имеющиеся десятичные цифры. Если длина выходного буфера, которую задаёт len, недостаточна для помещения в него текстового представления, включая завершающий нулевой байт, в буфере сохраняется один знак * и возвращается -1.

Эта функция возвращает -1, если буфер cp слишком мал, либо ECPG_INFORMIX_OUT_OF_MEMORY при нехватке памяти.

Преобразует переменную типа decimal в тип double.

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

Эта функция получает указатель (np) на значение decimal, которое нужно преобразовать, и указатель (dblp) на переменную double, в которую будет помещён результат операции.

В случае успеха возвращается 0, или отрицательное значение, если выполнить преобразование не удалось.

Преобразует переменную типа decimal в тип integer.

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

Эта функция получает указатель (np) на значение decimal, которое нужно преобразовать, и указатель (ip) на целочисленную переменную, в которую будет помещён результат операции.

В случае успеха возвращается 0, или отрицательное значение, если выполнить преобразование не удалось. В случае переполнения возвращается ECPG_INFORMIX_NUM_OVERFLOW.

Заметьте, что реализация ECPG отличается от реализации Informix. В Informix целое ограничивается диапазоном -32767 .. 32767, тогда как в ECPG ограничение зависит от архитектуры (-INT_MAX .. INT_MAX).

Преобразует переменную типа decimal в тип long.

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

Эта функция получает указатель (np) на значение decimal, которое нужно преобразовать, и указатель (lngp) на переменную типа long, в которую будет помещён результат операции.

В случае успеха возвращается 0, или отрицательное значение, если выполнить преобразование не удалось. В случае переполнения возвращается ECPG_INFORMIX_NUM_OVERFLOW.

Заметьте, что реализация ECPG отличается от реализации Informix. В Informix длинное целое ограничено диапазоном -2 147 483 647 .. 2 147 483 647, тогда как в ECPG ограничение зависит от архитектуры (-LONG_MAX .. LONG_MAX).

Преобразует дату в строку C char*.

int rdatestr(date d, char *str);

Эта функция принимает два аргумента. В первом (d) передаётся дата, которую нужно преобразовать, а во втором указатель на целевую строку. Результат всегда выводится в формате yyyy-mm-dd, так что для этой строки нужно выделить минимум 11 байт (включая завершающий нулевой байт).

Эта функция возвращает 0 в случае успеха, а в случае ошибки — отрицательное значение.

Заметьте, что реализация ECPG отличается от реализации Informix. В Informix формат вывода можно изменить переменными окружения, а в ECPG он фиксирован.

Разбирает текстовое представление даты.

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

Эта функция получает текстовое представление (str) даты, которую нужно преобразовать, и указатель на переменную типа date (d). Для данной функции нельзя задать маску формата. Она использует стандартную маску формата Informix, а именно: mm/dd/yyyy. Внутри эта функция вызывает rdefmtdate. Таким образом, rstrdate не будет быстрее, и если у вас есть выбор, используйте функцию rdefmtdate, которая позволяет явно задать маску формата.

Эта функция возвращает те же значения, что и rdefmtdate.

Выдаёт текущую дату.

void rtoday(date *d);

Эта функция получает указатель на переменную (d) типа date, в которую будет записана текущая дата.

Внутри эта функция вызывает PGTYPESdate_today.

Извлекает значения дня, месяца и года из переменной типа date.

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

Эта функция получает дату d и указатель на 3 коротких целочисленных значения mdy. Имя переменной указывает на порядок значений: в mdy[0] записывается номер месяца, в mdy[1] — номер дня, а в mdy[2] — год.

В текущем состоянии эта функция всегда возвращает 0.

Внутри эта функция вызывает PGTYPESdate_julmdy.

Преобразует символьную строку в значение типа date по маске формата.

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

Эта функция принимает указатель на переменную типа date (d), в которую будет помещён результат операции, маску формата для разбора даты (fmt) и строку C char*, содержащую текстовое представление даты (str). Ожидается, что текстовое представление будет соответствовать маске формата. Однако это соответствие не обязательно должно быть точным. Данная функция анализирует только порядок элементов и ищет в нём подстроки yy или yyyy, обозначающие позицию года, подстроку mm, обозначающую позицию месяца, и dd, обозначающую позицию дня.

Эта функция возвращает следующие значения:

• 0 — Функция выполнена успешно.

• ECPG_INFORMIX_ENOSHORTDATE — Дата не содержит разделителей между днём, месяцем и годом. С таким форматом входная строка должна быть длиной ровно 6 или 8 байт, но это не так.

• ECPG_INFORMIX_ENOTDMY — Строка формата не определяет корректно последовательный порядок года, месяца и дня.

• ECPG_INFORMIX_BAD_DAY — Во входной строке отсутствует корректное указание дня.

• ECPG_INFORMIX_BAD_MONTH — Во входной строке отсутствует корректное указание месяца.

• ECPG_INFORMIX_BAD_YEAR — Во входной строке отсутствует корректное указание года.

В реализации этой функции вызывается PGTYPESdate_defmt_asc. Примеры вводимых строк приведены в таблице в её описании.

Преобразует переменную типа date в текстовое представление по маске формата.

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

Эта функция принимает дату для преобразования (d), маску формата (fmt) и строку, в которую будет помещено текстовое представление даты (str).

В случае успеха возвращается 0, а в случае ошибки — отрицательное значение.

Внутри эта функция вызывает PGTYPESdate_fmt_asc, примеры форматов можно найти в её описании.

Образует значение даты из массива 3 коротких целых, задающих день, месяц и год даты.

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

Эта функция получает в первом аргументе массив из 3 коротких целых (mdy), а во втором указатель на переменную типа date, в которую будет помещён результат операции.

В настоящее время эта функция всегда возвращает 0.

В реализации этой функции вызывается PGTYPESdate_mdyjul.

Возвращает число, представляющее день недели для заданной даты.

int rdayofweek(date d);

Эта функция принимает в единственном аргументе переменную d типа date и возвращает целое число, выражающее день недели для этой даты.

• 0 — Воскресенье

• 1 — Понедельник

• 2 — Вторник

• 3 — Среда

• 4 — Четверг

• 5 — Пятница

• 6 — Суббота

В реализации этой функции вызывается PGTYPESdate_dayofweek.

Получает текущее время.

void dtcurrent(timestamp *ts);

Эта функция получает текущее время и сохраняет его в переменной типа timestamp, на которую указывает ts.

Разбирает время из текстового представления в переменную типа timestamp.

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

Эта функция получает строку (str), которую нужно разобрать, и указатель на переменную типа timestamp, в которую будет помещён результат операции (ts).

Эта функция возвращает 0 в случае успеха, а в случае ошибки — отрицательное значение.

Внутри эта функция вызывает PGTYPEStimestamp_from_asc. Примеры вводимых строк приведены в таблице в её описании.

Разбирает время из текстового представления в переменную типа timestamp по маске формата.

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

Эта функция получает строку (inbuf), которую нужно разобрать, маску формата (fmtstr) и указатель на переменную timestamp, в которой будет содержаться результат операции (dtvalue).

В реализации этой функции используется PGTYPEStimestamp_defmt_asc. Список допустимых кодов формата приведён в её описании.

Эта функция возвращает 0 в случае успеха, а в случае ошибки — отрицательное значение.

Вычитает одно значение времени из другого и возвращает переменную типа interval.

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

Эта функция вычитает значение timestamp, на которое указывает ts2, из значения timestamp, на которое указывает ts1, и сохраняет результат в переменной типа interval, на которую указывает iv.

В случае успеха возвращается 0, а в случае ошибки — отрицательное значение.

Преобразует переменную типа timestamp в строку C char*.

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

Эта функция получает указатель (ts) на переменную типа timestamp, которую нужно преобразовать, и строку (output) для сохранения результата операции. Она преобразует ts в текстовое представление согласно стандарту SQL, то есть по маске YYYY-MM-DD HH:MM:SS.

В случае успеха возвращается 0, а в случае ошибки — отрицательное значение.

Преобразует переменную типа timestamp в строку C char* по маске формата.

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

Эта функция получает в первом аргументе (ts) указатель на переменную типа timestamp, а в последующих указатель на буфер вывода (output), максимальную длину строки, которую может принять буфер (str_len), и маску формата, с которой будет выполняться преобразование (fmtstr).

В случае успеха возвращается 0, а в случае ошибки — отрицательное значение.

Внутри эта функция использует PGTYPEStimestamp_fmt_asc. Примеры допустимых масок формата можно найти в её описании.

Преобразует переменную типа interval в строку C char*.

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

Эта функция получает указатель (i) на переменную типа interval, которую нужно преобразовать, и строку (str) для сохранения результата операции. Она преобразует i в текстовое представление согласно стандарту SQL, то есть по маске YYYY-MM-DD HH:MM:SS.

В случае успеха возвращается 0, а в случае ошибки — отрицательное значение.

Преобразует длинное целое в текстовое представление по маске формата.

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

Эта функция принимает значение типа long (lng_val), маску формата (fmt) и указатель на выходной буфер (outbuf). Она преобразует длинное целое в его текстовое представление согласно заданной маске формата.

Маску формата можно составить из следующих символов, определяющих формат:

• * (звёздочка) — если в данной позиции будет пусто, заполнить её звёздочкой.

• & (амперсанд) — если в данной позиции будет пусто, заполнить её нулём.

• # — заменить ведущие нули пробелами.

• < — выровнять число в строке по левой стороне.

• , (запятая) — сгруппировать числа, содержащие четыре и более цифр, в группы по три цифры через запятую.

• . (точка) — этот символ отделяет целую часть числа от дробной.

• - (минус) — с отрицательным числом должен выводиться знак минус.

• + (плюс) — с положительным числом должен выводиться знак плюс.

• ( — это символ заменяет знак минус перед отрицательным числом. Сам знак минус выводиться не будет.

• ) — этот символ заменяет минус и выводится после отрицательного числа.

• $ — символ денежной суммы.

Приводит строку к верхнему регистру.

void rupshift(char *str);

Эта функция получает указатель на строку и приводит в ней каждый символ в нижнем регистре к верхнему регистру.

Возвращает число символов в строке, не считая завершающих пробелов.

int byleng(char *str, int len);

Эта функция принимает в первом аргументе (str) строку фиксированной длины, а во втором (len) её длину. Она возвращает число значимых символов, то есть длину строки без завершающих пробелов.

Копирует строку фиксированной длины в строку с завершающим нулём.

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

Эта функция принимает строку фиксированной длины (src), которую нужно скопировать, её длину (len) и указатель на целевой буфер в памяти (dest). Учтите, что для буфера, на который указывает dest, необходимо выделить как минимум len+1 байт. Данная функция копирует в новую область не больше len байт (меньше, если в исходной строке есть завершающие пробелы) и добавляет завершающий 0.

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

Эта функция определена, но не реализована на данный момент!

int rtypalign(int offset, int type);

Эта функция определена, но не реализована на данный момент!

int rtypmsize(int type, int len);

Эта функция определена, но не реализована на данный момент!

int rtypwidth(int sqltype, int sqllen);

Эта функция определена, но не реализована на данный момент!

Присваивает переменной NULL.

int rsetnull(int t, char *ptr);

Эта функция получает целое, определяющее тип переменной, и указатель на саму переменную, приведённый к указателю C char*.

Определены следующие типы:

• CCHARTYPE — для переменной типа char или char*

• CSHORTTYPE — для переменной типа short int

• CINTTYPE — для переменной типа int

• CBOOLTYPE — для переменной типа boolean

• CFLOATTYPE — для переменной типа float

• CLONGTYPE — для переменной типа long

• CDOUBLETYPE — для переменной типа double

• CDECIMALTYPE — для переменной типа decimal

• CDATETYPE — для переменной типа date

• CDTIMETYPE — для переменной типа timestamp

Примеры вызова этой функции:

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

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

Проверяет содержимое переменной на NULL.

int risnull(int t, char *ptr);

Эта функция получает тип проверяемой переменной (t), а также указатель на неё (ptr). Заметьте, что этот указатель нужно привести к char*. Список возможных типов переменных приведён в описании функции rsetnull.

Примеры использования этой функции:

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

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

Функции возвращают это значение, если при вычислении происходит переполнение. Внутри оно представляется числом -1200 (определение Informix).

Функции возвращают это значение, если при вычислении происходит антипереполнение. Внутри оно представляется числом -1201 (определение Informix).

Функции возвращают это значение при попытке деления на ноль. Внутри оно представляется числом -1202 (определение Informix).

Функции возвращают это значение, если при разборе даты встретилось некорректное указание года. Внутри оно представляется числом -1204 (определение Informix).

Функции возвращают это значение, если при разборе даты встретилось некорректное указание месяца. Внутри оно представляется числом -1205 (определение Informix).

Функции возвращают это значение, если при разборе даты встретилось некорректное указание дня. Внутри оно представляется числом -1206 (определение Informix).

Функции возвращают это значение, если процедуре разбора даты требуется короткая запись даты, но строка даты имеет неподходящую длину. Внутри оно представляется числом -1209 (определение Informix).

Функции возвращают это значение, если при форматировании даты происходит ошибка. Внутри оно представляется числом -1210 (определение Informix).

Функции возвращают это значение, если им не хватает памяти для выполнения операций. Внутри оно представляется числом -1211 (определение Informix).

Функции возвращают это значение, если процедура разбора должна была получить маску формата (например, mmddyy), но не все поля были записаны правильно. Внутри оно представляется числом -1212 (определение Informix).

Функции возвращают это значение, если процедура разбора не может получить числовое значение из текстового представления, потому что оно некорректно, либо если процедура вычисления не может произвести операцию с числовыми переменными из-за недопустимого значения минимум одной из этих переменных. Внутри оно представляется числом -1213 (определение Informix).

Функции возвращают это значение, если процедура разбора не может воспринять экспоненту в числе. Внутри оно представляется числом -1216 (определение Informix).

Функции возвращают это значение, если процедура разбора не может разобрать дату. Внутри оно представляется числом -1218 (определение Informix).

Функции возвращают это значение, если процедуре разбора передаются посторонние символы, которая она не может разобрать. Внутри оно представляется числом -1264 (определение Informix).