Общая информация
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. Вызов процедуры создания физического лица:
| Code Block |
|---|
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. Редактирование существующего физического лица:
| Code Block |
|---|
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, АСР "Гидра" использует и собственный механизм работы с сообщениями. Он применяется в случаях, когда использование встроенного механизма невозможно, в частности, при массовых обработках или при необходимости вывести информационное сообщение либо предупреждение не нарушая ход выполнения процедуры и не выполняя откат транзакции. Чтобы выводить такие сообщения, следует после выполнения хранимой процедуры сделать выборку всех записей из специальной временной таблицы:
| Code Block |
|---|
SELECT * FROM TT_MESSAGE_LOGS; |
Если количество извлеченных из этой таблицы сообщений больше нуля, то необходимо вывести их все пользователю и/или в лог, после чего очистить таблицу:
| Code Block |
|---|
DELETE FROM TT_MESSAGE_LOGS; |
