Общая информация
Прикладной программный интерфейс АСР «Гидра» выполнен в виде набора 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-таблицей с помощью языка SQL. В АСР «Гидра» из представлений можно делать только выборки (SELECT-запросы), а DDL-операции (запросы INSERT, UPDATE) не разрешаются.
Представления называются по стандартной схеме: <префикс>_V_<код>[_<постфикс>]
(пример: SI_V_SUBJECTS
). Справочник префиксов см. в разделе «Работа с хранимыми процедурами» — он является общим для пакетов и представлений. Постфиксы бывают следующие:
Постфикс |
Пример |
Примечание |
---|---|---|
JR |
|
Расширенное представление (используется, например, в интерфейсе для реестров и журналов). Может присутствовать одновременно со стандартным и/или упрощенным |
SIMPLE |
|
Упрощенное представление. Может присутствовать одновременно со стандартным и/или расширенным |
C |
|
Как правило, обозначает состав (строки) документа |
T |
|
Как правило, обозначает заголовочную часть (шапку) документа, специфичную для данного типа документа. |
Поля (columns) представления именуются в венгерской нотации: <префикс>_<код>
(пример: VC_NAME
). Если поле содержит идентификатор какой-либо сущности, то его наименование оканчивается на ID
(пример: N_USER_ID
— идентификатор абонента).
Стандартные префиксы для наименования полей в представлениях:
Префикс |
Тип данных |
Пример |
Примечание |
---|---|---|---|
N |
NUMBER |
|
Тип |
VC |
VARCHAR2 |
|
Для текстовых полей с максимальной длиной 4000 байт |
D |
DATE |
|
Дата (с точностью до секунды) |
C |
CHAR |
|
Как правило, используется для хранения логических признаков и принимает значения |
CL |
CLOB |
|
Для текстовых полей неограниченной длины |
BL |
BLOB |
|
Для бинарных полей неограниченной длины |
Наименование поля или представления может любым, однако значительная часть их имеет стандартные наименования, связанные с основными сущностями, хранящимися в АСР:
Наименование |
Полное обозначение |
Краткое обозначение |
Пример |
Расшифровка примера |
---|---|---|---|---|
Документ |
DOCUMENT |
DOC |
|
Идентификатор документа |
Договор |
CONTRACT |
— |
|
Идентификатор договора (договор является частным случаем документа) |
Схема докуметооборота |
WORKFLOW |
WFLOW |
|
Идентификатор схемы документа |
Субъект учёта (СУ) |
SUBJECT |
SUBJ |
|
Идентификатор СУ |
Фирма (организация) |
FIRM |
— |
|
Идентификатор фирмы - организации, как правило, оказывающей услуги |
Объект учёта (ОУ) |
OBJECT |
OBJ |
|
Идентификатор ОУ |
Абонент |
USER |
— |
|
Идентификатор абонента (абонент также является субъектом учёта) |
Роль |
ROLE |
— |
|
Идентификатор роли СУ (ОУ, адреса) в документе |
Адрес |
ADDRESS |
ADDR |
|
Идентификатор адреса (обычный адрес, IP-адрес, телефонный номер и т.д.) |
Счёт |
ACCOUNT |
ACC |
|
Идентификатор счёта |
Валюта |
CURRENCY |
CURR |
|
Идентификатор валюты (из справочника валют) |
Сетевая служба |
SERVICE |
SERV |
|
Идентификатор сетевой службы (сетевая служба также является объектом учета) |
Единица измерения |
UNIT |
— |
|
Идентификатор валюты (из справочника единиц измерения) |
Справочная позиция |
— |
REF |
|
Идентификатор произвольной записи из справочника |
Позиция номенклатуры |
GOOD |
— |
|
Идентификатор позиции номенклатуры |
Регион |
REGION |
— |
|
Идентификатор региона |
Запись о сеансе связи |
— |
CDR |
|
Идентификатор CDR (записи о сеансе связи) |
Задание |
JOB |
— |
|
Идентификатор задания |
Существуют также наименования полей и представлений, содержащие указания одновременно на несколько сущностей. Это означает связь между ними. Примеры:
Наименование |
Тип |
Расшифровка |
---|---|---|
|
Представление |
Привязка абонентов к сетевым службам |
|
Представление |
Роли СУ в документах |
|
Представление |
Привязка счетов к СУ |
|
Представление |
Связи документов с документами |
|
Поле |
Идентификатор привязки документа к документу |
|
Представление |
Связи адресов с адресами |
|
Поле |
Идентификатор привязки одного адреса к другому |
Кроме того, существуют стандартные обозначения:
Наименование |
Пример обозначения |
Примечание |
---|---|---|
Код (краткое наименовение) |
|
Краткое наименование сущности, как правило, уникально идентифицирующее её. Используется практически во всех сущностях системы. |
Имя (полное наименовение) |
|
Полное наименование сущности. Используется практически во всех сущностях системы. |
Тип сущности |
|
Если наименование поля содержит |
Номер |
|
Порядковый номер чего-либо (например, номер строки в документе). Как правило, используется для сортировки при выводе. |
Примечание (комментарий) |
|
Используется в большинстве сущностей системы для хранения дополнительной текстовой информации |
Дата начала |
|
Используется для хранения даты начала некоторого периода времени. Может быть как со временем суток, так и без него |
Дата окончания |
|
Используется для хранения даты окончания некоторого периода времени. Может быть как со временем суток, так и без него |
Дата операции |
|
Как правило, обозначает дату совершения финансовой операции. Может быть как со временем суток, так и без него |
Идентификатор строки |
|
Используется для идентификации строки состава документа или вообще строки в некоторой таблице |
Идентификатор родительской строки |
|
Используется для идентификации родительской строки документа в двухуровневых документах |
Сумма |
|
Сумма (как правило, сумма денежных средств с учётом налогов) |
Сумма налогов |
|
|
Сумма без налогов |
|
|
Количество |
|
Как правило, количество товара или объем услуги. Обычно присутствует вместе с указанием единицы измерения ( |
Значение |
|
Используется для хранения некоторого значения, имеющего заранее неизвестный характер (например, доп. параметр) |
Работа с хранимыми процедурами
Общая информация
Хранимые процедуры объединены в пакеты. Пакеты бывают двух типов — обычные (привилегированные) и сервисные (вспомогательные). Обычные пакеты используются для добавления, модификации и редактирования данных в БД, поэтому для пользования ими требуются, как правило, расширенные права доступа. Сервисные пакеты содержат вспомогательные процедуры, связанные с извлечением и/или преобразованием информации из БД.
Пакеты называются по стандартной схеме: <префикс>_<код>_PKG
для обычных пакетов (пример: SI_SUBJECTS_PKG
) и <префикс>_<код>_PKG_S
— для сервисных (пример: SI_SUBJECTS_PKG_S
).
Стандартные префиксы для названий пакетов (также являются стандартными и для представлений):
Префикс |
Пример |
Примечание |
---|---|---|
ACC |
|
Взаимодействие с бухгалтерским программным обеспечением (БПО) |
AP |
|
Функциональность, специфическая для приложений (личный кабинет и т.д.) |
EX |
|
Взаимодействие с внешними системами (AAA, телефония, LDAP, DHCP и т.д.) |
RPT |
|
Представления для отчетов |
SI |
|
Работа с СУ, ОУ, базовыми справочниками |
SD |
|
Работа с документами |
SR |
|
Работа со справочниками номенклатуры и регионов |
SS |
|
Системные пакеты и представления |
Вызов хранимой процедуры состоит из двух частей — <наименование пакета>.<наименование процедуры>
.
Аргументы процедуры в АСР "Гидра", так же, как и поля в представлениях, именуются в венгерской нотации — префикс наименования аргумента обозначает его тип данных . Таблица соответствия:
Префикс |
Тип данных |
Пример |
Примечание |
---|---|---|---|
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;
Константы
При использовании представлений и хранимых процедур часто необходимо использовать предопределенные константы. Обычно они применяются для указания типа и состояния документов, СУ или ОУ, указания единицы измерения, ставки налога и т.д. Константа состоит из кода и значения (почти всегда значение числовое).
Все используемые системой константы описаны в специальном сервисном пакете SS_CONSTANTS_PKG_S
, а также доступны в глобальном контексте CONST
и в представлении SS_V_CONSTANTS
.
Для передачи констант в качестве значения аргумента хранимой процедуры рекомендуется использовать обращение через пакет: SS_CONSTANTS_PKG_S.<код константы>
. Пример:
BEGIN -- Аннулировать документ с идентификатором 1577736201 SD_DOCUMENTS_PKG.SD_DOCUMENTS_CHANGE_STATE ( num_N_DOC_ID => 1577736201, num_N_New_DOC_STATE_ID => SS_CONSTANTS_PKG_S.DOC_STATE_Canceled); END;
Для SQL-запросов к представлениям необходимо применять обращение через контекст: SYS_CONTEXT('CONST', '<код константы>')
. Пример:
-- Подсчитать количество актуальных инвойсов в системе SELECT COUNT(*) FROM SD_V_DOCUMENTS WHERE N_DOC_TYPE_ID = SYS_CONTEXT('CONST', 'DOC_TYPE_Invoice') AND N_DOC_STATE_ID = SYS_CONTEXT('CONST', 'DOC_STATE_Actual');