Page History

Общая информация

Прикладной программный интерфейс АСР «Гидра» выполнен в виде набора 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) не разрешаются.

Wiki Markup

Представления называются по стандартной схеме: {{<префикс>\_V\_<код>\[\_<постфикс>\]}} (пример: {{SI_V_SUBJECTS}}). Справочник префиксов см. в разделе «Работа с хранимыми процедурами» --- он является общим для пакетов и представлений. Постфиксы бывают следующие:

Постфикс	Пример	Примечание
JR	`SI_V_PERSONS_JR`	Расширенное представление (используется, например, в интерфейсе для реестров и журналов). Может присутствовать одновременно со стандартным и/или упрощенным
SIMPLE	`SI_V_OBJ_ADDRESSES_SIMPLE`	Упрощенное представление. Может присутствовать одновременно со стандартным и/или расширенным
C	`SD_V_PRICE_ORDERS_C`	Как правило, обозначает состав (строки) документа
T	`SD_V_PRICE_ORDERS_T`	Как правило, обозначает заголовочную часть (шапку) документа, специфичную для данного типа документа.

Поля (columns) представления именуются в венгерской нотации: <префикс>_<код> (пример: VC_NAME). Если поле содержит идентификатор какой-либо сущности, то его наименование оканчивается на ID (пример: N_USER_ID — идентификатор абонента).

Стандартные префиксы для наименования полей в представлениях:

Префикс	Тип данных	Пример	Примечание
N	NUMBER	`N_SUBJECT_ID`	Тип `NUMBER` используется в АСР для всех внутренних идентификаторов
VC	VARCHAR2	`VC_CODE`	Для текстовых полей с максимальной длиной 4000 байт
D	DATE	`D_BEGIN`	Дата (с точностью до секунды)
C	CHAR	`C_ACTIVE`	Как правило, используется для хранения логических признаков и принимает значения `Y` или `N`
CL	CLOB	`clb_CL_PRICE_ORDER`	Для текстовых полей неограниченной длины
BL	BLOB	`blb_BL_FILE`	Для бинарных полей неограниченной длины

Наименование поля или представления может любым, однако значительная часть их имеет стандартные наименования, связанные с основными сущностями, хранящимися в АСР:

Наименование	Полное обозначение	Краткое обозначение	Пример	Расшифровка примера
Документ	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`	Если наименование поля содержит `TYPE`, то оно всегда является справочной позицией (из SI_V_REF). Пример — тип документа (счёт, приказ по ценам, инвойс...)
Номер	`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_UNIT_ID`)
Значение	`N_VALUE`, `VC_VALUE`	Используется для хранения некоторого значения, имеющего заранее неизвестный характер (например, доп. параметр)

Работа с хранимыми процедурами

Общая информация

Хранимые процедуры объединены в пакеты. Пакеты бывают двух типов — обычные (привилегированные) и сервисные (вспомогательные). Обычные пакеты используются для добавления, модификации и редактирования данных в БД, поэтому для пользования ими требуются, как правило, расширенные права доступа. Сервисные пакеты содержат вспомогательные процедуры, связанные с извлечением и/или преобразованием информации из БД.

Пакеты называются по стандартной схеме: <префикс>_<код>_PKG для обычных пакетов (пример: SI_SUBJECTS_PKG) и <префикс>_<код>_PKG_S — для сервисных (пример: SI_SUBJECTS_PKG_S).

Стандартные префиксы для названий пакетов (также являются стандартными и для представлений):

Префикс	Пример	Примечание
ACC	`ACC_BILLS_PKG`	Взаимодействие с бухгалтерским программным обеспечением (БПО)
AP	`AP_V_USER_OFFICE_GOODS`	Функциональность, специфическая для приложений (личный кабинет и т.д.)
EX	`EX_V_PAYMENTS`	Взаимодействие с внешними системами (AAA, телефония, LDAP, DHCP и т.д.)
RPT	`RPT_V_ACCOUNT_BALANCE`	Представления для отчетов
SI	`SI_SUBJECTS_PKG_S`	Работа с СУ, ОУ, базовыми справочниками
SD	`SD_CONTRACTS_PKG`	Работа с документами
SR	`SR_V_GOODS`	Работа со справочниками номенклатуры и регионов
SS	`SS_JOBS_PKG_S`	Системные пакеты и представления

Вызов хранимой процедуры состоит из двух частей — <наименование пакета>.<наименование процедуры>.

Аргументы процедуры в АСР "Гидра", так же, как и поля в представлениях, именуются в венгерской нотации — префикс наименования аргумента обозначает его тип данных . Таблица соответствия:

Префикс	Тип данных	Пример	Примечание
num	NUMBER	`num_N_SUBJECT_ID`	Тип `NUMBER` используется в АСР для всех внутренних идентификаторов
vch	VARCHAR2	`vch_VC_CODE`	Для текстовых полей с максимальной длиной 4000 байт
dt	DATE	`dt_D_BEGIN`	Дата (с точностью до секунды)
b	MAIN.BOOL	`b_DisableTriggers`	`MAIN.BOOL` — собственный тип данных АСР. Фактически `NUMBER` со значениями 0 или 1
clb	CLOB	`clb_CL_PRICE_ORDER`	Для текстовых полей неограниченной длины
blb	BLOB	`blb_BL_FILE`	Для бинарных полей неограниченной длины
rc	RECORD	`rc_SUBJECT`	Структура . Как правило, поля соответствуют строке таблицы БД.
tbl	Nested table	`tbl_USER_SERVS`	Массив данных (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;

Константы

При использовании представлений и хранимых процедур часто необходимо использовать предопределенные константы. Обычно они применяются для указания типа и состояния документов, СУ или ОУ, указания единицы измерения, ставки налога и т.д. Константа состоит из кода и значения (почти всегда значение числовое).

Все используемые системой константы описаны в специальном сервисном пакете SS_CONSTANTS_PKG_S, а также доступны в глобальном контексте CONST и в представлении SS_V_CONSTANTS.

Для передачи констант в качестве значения аргумента хранимой процедуры рекомендуется использовать обращение через пакет: SS_CONSTANTS_PKG_S.<код константы>. Пример:

Code Block

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', '<код константы>'). Пример:

Code Block

-- Подсчитать количество актуальных инвойсов в системе
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');

Приложения, постоянно взаимодействующие с АСР «Гидра», в целях ускорения работы и сокращения нагрузки на БД могут загружать (кэшировать) сразу все константы при инициализации. Для этого нужно сделать следующий запрос:

Code Block
SELECT * FROM SS_V_CONSTANTS

и сохранить полученные значения, например, в ассоциативном массиве, где ключом будет являться поле VC_NAME, а значением — поле VC_VALUE.

Image Added

Page tree

Versions Compared

Old Version 3

New Version Current

Key

Общая информация

Работа с представлениями

Работа с хранимыми процедурами

Общая информация

Процедуры создания/редактирования записи в БД

Транзакции, исключения и сообщения

Константы