Общая информация
API АСР "Гидра" выполнен в виде набора PL/SQL пакетов (packages) СУБД Oracle 10g. Чтобы использовать API, необходимо установить Oracle Instant Client (версии Basic или Basic Light подойдут. После этого нужно настроить файл tnsnames.ora для подключения к БД.
Далее следует установить драйвер Oracle для применяемого языка программирования. Например, для PHP это OCI8 Extensions , для Python — cx_Oracle , для Ruby — ruby-oci8
Руководства по работе с Oracle из PHP: 1 , 2
АСР «Гидра» не предоставляет приложениям возможности прямого доступа к таблицам БД. Для извлечения информации из БД используются представления (views ) и сервисные процедуры, а для добавления, модификации и удаления — только хранимые процедуры.
Работа с представлениями
С точки зрения клиентского приложения, работа с представлением аналогична работе с обычной RDBMS-таблицей. В АСР «Гидра» из представлений можно делать только выборки (SELECT-запросы); DDL-операции (запросы INSERT, UPDATE) не разрешаются.
Представления называются по стандартной схеме: <префикс>_V_<код> (пример: SI_V_SUBJECTS).
Поля (columns) представления именуются в венгерской нотации: <префикс>_<код> (пример: VC_NAME). Если поле содержит идентификатор какой-либо сущности, то его наименование оканчивается на ID (пример: N_USER_ID — идентификатор абонента).
Стандартные префиксы для наименования полей в представлениях:
Префикс |
Тип данных |
Пример |
Примечание |
|---|---|---|---|
N |
NUMBER |
|
Тип |
VC |
VARCHAR2 |
|
Для текстовых полей с максимальной длиной 4000 байт |
D |
DATE |
|
Дата (с точностью до секунды) |
C |
CHAR |
|
Как правило, используется для хранения логических признаков и принимает значения |
CL |
CLOB |
|
Для текстовых полей неограниченной длины |
BL |
BLOB |
|
Для бинарных полей неограниченной длины |
Наименование поля или представления может любым, однако значительная часть их имеет стандартные наименования, связанные с основными сущностями, хранящимися в АСР:
Наименование |
Полное обозначение |
Краткое обозначение |
Пример |
Расшифровка примера |
|---|---|---|---|---|
Документ |
DOCUMENT |
DOC |
N_DOC_ID |
Идентификатор документа |
Договор |
CONTRACT |
— |
N_CONTRACT_ID |
Идентификатор договора (договор является частным случаем документа) |
Схема докуметооборота |
WORKFLOW |
WFLOW |
N_WORKFLOW_ID |
Идентификатор схемы документа |
Субъект учёта (СУ) |
SUBJECT |
SUBJ |
N_SUBJECT_ID |
Идентификатор СУ |
Фирма (организация) |
FIRM |
— |
N_FIRM_ID |
Идентификатор фирмы - организации, как правило, оказывающей услуги |
Объект учёта (ОУ) |
OBJECT |
OBJ |
N_OBJECT_ID |
Идентификатор ОУ |
Абонент |
USER |
— |
N_USER_ID |
Идентификатор абонента (абонент также является субъектом учёта) |
Роль |
ROLE |
— |
N_DOC_ROLE_ID |
Идентификатор роли СУ (ОУ, адреса) в документе |
Адрес |
ADDRESS |
ADDR |
N_ADDRESS_ID |
Идентификатор адреса (обычный адрес, IP-адрес, телефонный номер и т.д.) |
Счёт |
ACCOUNT |
ACC |
N_ACCOUNT_ID |
Идентификатор счёта |
Валюта |
CURRENCY |
CURR |
N_CURRENCY_ID |
Идентификатор валюты (из справочника валют) |
Сетевая служба |
SERVICE |
SERV |
N_SERVICE_ID |
Идентификатор сетевой службы (сетевая служба также является объектом учета) |
Единица измерения |
UNIT |
— |
N_UNIT_ID |
Идентификатор валюты (из справочника единиц измерения) |
Справочная позиция |
— |
REF |
N_REF_ID |
Идентификатор произвольной записи из справочника |
Позиция номенклатуры |
GOOD |
— |
N_GOOD_ID |
Идентификатор позиции номенклатуры |
Регион |
REGION |
— |
N_REGION_ID |
Идентификатор региона |
Запись о сеансе связи |
— |
CDR |
N_CDR_ID |
Идентификатор CDR (записи о сеансе связи) |
Задание |
JOB |
— |
N_JOB_ID |
Идентификатор задания |
Существуют также наименования полей и представлений, содержащие указания одновременно на несколько сущностей. Это означает связь между ними. Примеры:
Наименование |
Тип |
Расшифровка |
|---|---|---|
SI_V_SUBJ_SERVICES |
Представление |
Привязка абонентов к сетевым службам |
SI_V_DOC_SUBJECTS |
Представление |
Роли СУ в документах |
SI_V_SUBJ_ACCOUNTS |
Представление |
Привязка счетов к СУ |
SD_V_DOC_DOCUMENTS |
Представление |
Связи документов с документами |
N_DOC_DOCUMENT_ID |
Поле |
Идентификатор привязки документа к документу |
SI_V_ADDR_ADDRESSES |
Представление |
Связи адресов с адресами |
N_ADDR_ADDRESS_ID |
Поле |
Идентификатор привязки одного адреса к другому |
Кроме того, существуют стандартные обозначения:
Наименование |
Пример обозначения |
Примечание |
|---|---|---|
Код (краткое наименовение) |
VC_CODE |
Краткое наименование сущности, как правило, уникально идентифицирующее её. Используется практически во всех сущностях системы. |
Имя (полное наименовение) |
VC_NAME |
Полное наименование сущности. Используется практически во всех сущностях системы. |
Тип сущности |
N_DOC_TYPE_ID |
Если наименование поля содержит |
Номер |
VC_DOC_NO, N_LINE_NO |
Порядковый номер чего-либо (например, номер строки в документе). Как правило, используется для сортировки при выводе. |
Примечание (комментарий) |
VC_REM |
Используется в большинстве сущностей системы для хранения дополнительной текстовой информации |
Дата начала |
D_BEGIN |
Используется для хранения даты начала некоторого периода времени. Может быть как со временем суток, так и без него |
Дата окончания |
D_END |
Используется для хранения даты окончания некоторого периода времени. Может быть как со временем суток, так и без него |
Дата операции |
D_OPER |
Как правило, обозначает дату совершения финансовой операции. Может быть как со временем суток, так и без него |
Идентификатор строки |
N_LINE_ID |
Используется для идентификации строки состава документа или вообще строки в некоторой таблице |
Идентификатор родительской строки |
N_PAR_LINE_ID |
Используется для идентификации родительской строки документа в двухуровневых документах |
Сумма |
N_SUM |
Сумма (как правило, сумма денежных средств с учётом налогов) |
Сумма налогов |
N_SUM_TAX |
|
Сумма без налогов |
N_SUM_WO_TAX |
|
Количество |
N_QUANT |
Как правило, количество товара или объем услуги. Обычно присутствует вместе с указанием единицы измерения ( |
Значение |
N_VALUE, VC_VALUE |
Используется для хранения некоторого значения, имеющего заранее неизвестный характер (например, доп. параметр) |
Работа с хранимыми процедурами
Общая информация
Хранимые процедуры объединены в пакеты. Пакеты бывают двух типов — обычные (привилегированные) и сервисные (вспомогательные). Обычные пакеты используются для добавления, модификации и редактирования данных в БД, поэтому для пользования ими требуются, как правило, расширенные права доступа. Сервисные пакеты содержат вспомогательные процедуры, связанные с извлечением и/или преобразованием информации из БД.
Пакеты называются по стандартной схеме: <префикс>_<код>_PKG для обычных пакетов (пример: SI_SUBJECTS_PKG) и <префикс>_<код>_PKG_S — для сервисных (пример: SI_SUBJECTS_PKG_S).
Вызов хранимой процедуры состоит из двух частей — <наименование пакета>.<наименование процедуры>.
Аргументы процедуры в АСР "Гидра", так же, как и поля в представлениях, именуются в венгерской нотации — префикс наименования аргумента обозначает его тип данных . Таблица соответствия:
Префикс |
Тип данных |
Пример |
Примечание |
|---|---|---|---|
num |
NUMBER |
|
Тип |
vch |
VARCHAR2 |
|
Для текстовых полей с максимальной длиной 4000 байт |
dt |
DATE |
|
Дата (с точностью до секунды) |
b |
MAIN.BOOL |
|
|
clb |
CLOB |
|
Для текстовых полей неограниченной длины |
blb |
BLOB |
|
Для бинарных полей неограниченной длины |
rc |
RECORD |
|
Структура . Как правило, поля соответствуют строке таблицы БД. |
tbl |
Nested table |
|
Массив данных (PL/SQL collection ) |
Процедуры создания/редактирования записи в БД
Процедуры с наименованием вида _PUT находятся в привилегированных пакетах. Как правило, они предназначены сразу и для создания, и для редактирования записи. У таких процедур первый аргумент - идентификатор создаваемой/редактируемой записи с типом вызова IN OUT, поэтому числовую константу передавать в него нельзя. Если при вызове такой процедуры в первый аргумент передать значение NULL, то создастся новая запись, а в этот аргумент запишется значение идентификатора вновь созданной записи. Если же в процедуру _PUT передать идентификатор существующей записи, то она будет модифицирована.
Пример 1. Вызов процедуры создания физического лица:
DECLARE
num_N_PERSON_ID_Created NUMBER := NULL; -- пустой идентификатор говорит о том, что требуется создать новое физлицо
BEGIN
SI_PERSONS_PKG.SI_PERSONS_PUT (
num_N_PERSON_ID => num_N_PERSON_ID_Created,
...);
-- При успешном выполнении процедуры в переменную num_N_PERSON_ID_Created запишется идентификатор вновь созданной записи.
-- Значение идентификатора выдается системой автоматически.
END;
Пример 2. Редактирование существующего физического лица:
DECLARE
num_N_PERSON_ID_Edit NUMBER := 123455601; -- необходимо указать идентификатор существующего физлица, иначе при вызове будет ошибка.
BEGIN
SI_PERSONS_PKG.SI_PERSONS_PUT (
num_N_PERSON_ID => num_N_PERSON_ID_Edit,
...);
END;
Транзакции, исключения и сообщения
После вызова хранимой процедуры (либо группы процедур), которая изменяет данные в БД, необходимо зафиксировать (commit) либо откатить (rollback) транзакцию. Ответственность за это лежит на вызывающем приложении.
При вызове из приложения хранимой процедуры может возникнуть исключительная ситуация (exception). В этом случае Oracle выполняет автоматический откат транзакции. Вызывающему приложению в обязательном порядке следует перехватывать возникшие исключения и выводить их пользователю и/или в лог. Вместе с сообщением Oracle передаёт и стек вызова, который следует тоже выводить в лог.
Помимо встроенного механизма исключений Oracle, АСР "Гидра" использует и собственный механизм работы с сообщениями. Он применяется в случаях, когда использование встроенного механизма невозможно, в частности, при массовых обработках или при необходимости вывести информационное сообщение либо предупреждение не нарушая ход выполнения процедуры и не выполняя откат транзакции. Чтобы выводить такие сообщения, следует после выполнения хранимой процедуры сделать выборку всех записей из специальной временной таблицы:
SELECT * FROM TT_MESSAGE_LOGS;
Если количество извлеченных из этой таблицы сообщений больше нуля, то необходимо вывести их все пользователю и/или в лог, после чего очистить таблицу:
DELETE FROM TT_MESSAGE_LOGS;