Page History

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

Основной прикладной программный интерфейс

Далее следует установить драйвер Oracle для применяемого языка программирования. Например, для PHP это OCI8 Extensions, для Python — cx_Oracle, для Ruby — ruby-oci8.

Руководства по работе с Oracle для PHP: 1 , 2 , для Python: 1 , 2 , :

• Python:
  • High performance Python applications with Oracle Database
  • cx_Oracle module documentation by Anthony Tuininga
• Ruby on Rails:

...

• • Developing Ruby applications with Oracle Database
  • Ruby on Rails on Oracle: A Simple Tutorial by Richard Monson-Haefel
  • Ruby on Rails with Oracle FAQ by Casimir Saternos
• PHP:
  • Oracle Database and PHP
  • The Underground PHP and Oracle Manual by Christopher Jones and Alison Holloway
  • Кэш соединений OCI8 с Oracle из PHP

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

С точки зрения клиентского приложения, работа с представлением аналогична работе с обычной RDBMS-таблицей с помощью языка SQL. В АСР «Гидра» из представлений можно делать только выборки (SELECT-запросы), а DDLDML-операции (запросы INSERT, UPDATE) не разрешаются.

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

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

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

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

Существуют также наименования полей и представлений, содержащие указания одновременно на несколько сущностей. Такая запись обозначает связь между ними. Примеры:

Кроме того, существуют и другие распространенные стандартные обозначения:

Anchor
stored_procedures stored_procedures

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

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

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

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

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

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

Аргументы процедуры в АСР "Гидра"

Язык PL/SQL позволяет вызывать процедуры с именованными аргументами (см. примеры ниже). Этим можно и нужно пользоваться. Разработчики

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

Процедуры с наименованием вида _PUT находятся в привилегированных пакетах. Как правило, они предназначены сразу и для создания, и для редактирования записи. У таких процедур первый аргумент - аргумент — идентификатор создаваемой/редактируемой записи с типом вызова IN OUT, поэтому числовую константу передавать в него нельзя. Если при вызове такой процедуры в первый аргумент передать значение NULL, то создастся новая запись, а в этот аргумент запишется значение идентификатора вновь созданной записи. Если же в процедуру _PUT передать идентификатор существующей записи, то она будет модифицирована. Для модификации существующей записи нужно передавать как параметры с новыми значениями модифицируемой сущности, так и все остальные параметры процедуры с текущими значениями параметров модифицируемой сущности.

Пример 1. Вызов процедуры создания физического лица:

DECLARE
  num_N_PERSONSUBJECT_ID_Created  NUMBER := NULL; -- пустой идентификатор говорит о том, что требуется создать новое физлицо
BEGIN
  SI_PERSONS_PKG.SI_PERSONS_PUT (
     num_N_PERSONSUBJECT_ID => num_N_PERSONSUBJECT_ID_Created,
     ...);
  -- При успешном выполнении процедуры в переменную num_N_PERSONSUBJECT_ID_Created запишется идентификатор вновь созданной записи.
  -- Значение идентификатора выдается системой автоматически.
END;

Пример 2. Редактирование существующего физического лица:

DECLARE
  num_N_PERSONSUBJECT_ID_Edit  NUMBER := 123455601; -- необходимо указать идентификатор существующего физлица, иначе при вызове будет ошибка.
BEGIN
  SI_PERSONS_PKG.SI_PERSONS_PUT (
     num_N_PERSONSUBJECT_ID => num_N_PERSONSUBJECT_ID_Edit,
     ...);
END;

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

После вызова хранимой процедуры (либо группы процедур), которая изменяет данные в БД, необходимо зафиксировать (commit) либо откатить (rollback) транзакцию. Ответственность за это лежит на вызывающем приложении.

...

Помимо встроенного механизма исключений Oracle, АСР "Гидра"  

SELECT * FROM TT_V_MESSAGE_LOGS;

Если количество извлеченных из этой таблицы сообщений больше нуля, то необходимо вывести их все пользователю и/или в лог, после чего очистить таблицу:

DELETE FROM TT_MESSAGE_LOGS;

Константы

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

Все используемые системой константы описаны в специальном сервисном пакете SS_CONSTANTS_PKG_S, а  (публичный синоним CONST). Этот же пакет содержит функцию GET_CONST, возвращающую значение константы по ее коду. Все константы также доступны в глобальном контексте CONST и в представлении SS_V_CONSTANTS.Для передачи констант в качестве значения аргумента хранимой процедуры

• В PL/SQL-коде для передачи значений констант рекомендуется использовать обращение через пакет:

...

• CONST.<код константы>

...

• Code Block

...

• language sql title Пример использования констант в PL/SQL

  BEGIN -- Аннулировать документ с идентификатором 1577736201 SD_DOCUMENTS_PKG.SD_DOCUMENTS_CHANGE_STATE ( num_N_DOC_ID => 1577736201, num_N_New_DOC_STATE_ID =>

...

• CONST.DOC_STATE_Canceled); END;

  
  

• Для SQL-запросов

...

• , которые выполняются вне PL/SQL, рекомендуется использовать функцию CONST.GET_CONST('<код константы>'): она возвращает числовое (тип NUMBER) значение константы и в случае ошибки в названии константы вызывает исключение вида PLS-00302: component 'DOC_TYPE_CHARGEDOG' must be declared.

  Code Block
  language sql title Пример использования констант в SQL через функцию CONST.GET_CONST
  -- Подсчитать количество актуальных актов начислений в системе SELECT COUNT(*) FROM SD_V_DOCUMENTS WHERE N_DOC_TYPE_ID = CONST.GET_CONST('DOC_TYPE_ChargeLog') AND N_DOC_STATE_ID = CONST.GET_CONST('DOC_STATE_Actual');

  
  Также в SQL-запросах можно применять обращение через контекст SYS_CONTEXT('CONST', '<код константы>').

...

• Обратите внимание, функция SYS_CONTEXT всегда возвращает строковое значение. Чтобы при ее использовании не столкнуться с проблемами преобразования типов, результат следует явно приводить к числовому типу с помощью функции TO_NUMBER. Передача в данную функцию некорректного кода константы не приведёт к ошибке: в таком случае она возвращает NULL.

  Code Block

...

• language sql title Пример использования констант в SQL через функцию SYS_CONTEXT

  -- Подсчитать количество актуальных

...

• актов начислений в системе SELECT COUNT(*) FROM SD_V_DOCUMENTS WHERE N_DOC_TYPE_ID = TO_NUMBER(SYS_CONTEXT('CONST', 'DOC_TYPE_

...

• ChargeLog')) AND N_DOC_STATE_ID = TO_NUMBER(SYS_CONTEXT('CONST', 'DOC_STATE_Actual'));

  
  

Приложения, постоянно взаимодействующие с АСР «Гидра»

SELECT *
FROM   SS_V_CONSTANTS;

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

Справочники

Чтобы получить, например, название типа документа в текстовом представлении по его числовому идентификатору, удобно использовать процедуры из пакета SI_REF_PKG_S. Пример:

SQL> -- Подcчитать, сколько сейчас актуальных документов в разрезе типа документа
SQL> SELECT N_DOC_TYPE_ID,
  2         SI_REF_PKG_S.GET_NAME_BY_ID(N_DOC_TYPE_ID) VC_DOC_TYPE,
  3         COUNT(*) N_COUNT
  4  FROM   SD_V_DOCUMENTS
  5  WHERE  N_DOC_STATE_ID = TO_NUMBER(SYS_CONTEXT('CONST', 'DOC_STATE_Actual'))
  6  GROUP BY N_DOC_TYPE_ID
  7  ORDER BY N_COUNT DESC;

N_DOC_TYPE_ID VC_DOC_TYPE                                N_COUNT
------------- --------------------------------------------------
         5002 Платёжное поручение                          69950
         4002 Кассовый ордер                                9328
         1002 Договор на оказание услуг                     2817
         3002 Инвойс                                        1177
         6002 Счёт                                           515
         7002 Приказ по ценам                                171
        11002 Банковская выписка                              74
         9002 Базовый договор                                 25
        13002 Доп. соглашение                                 15
        20002 Заявка                                           6
        12002 Приказ по временным интервалам                   3
         8002 Отказ в обслуживании                             1

12 rows selected

Получение диапазона значений справочника

Для получения всего диапазона значений заданного справочника можно воспользоваться следующим SQL-запросом:

SELECT N_REF_ID,
       VC_CODE,
       VC_NAME
FROM   SI_V_REF
WHERE  N_REF_TYPE_ID = SI_REF_PKG_S.GET_ID_BY_CODE('<vch_VC_REF_NAME>')

<vch_VC_REF_NAME> — код справочника (например, REF_TYPE_Address_Type).

Получение значения справочной записи

Для получения значения конкретной справочной записи можно воспользоваться следующим SQL-запросом:

SELECT SI_REF_PKG_S.GET_ID_BY_CODE('<vch_VC_REF_CODE>')
FROM   DUAL

<vch_VC_REF_CODE> — код справочной записи (например, ADDR_TYPE_Subnet).

Начало работы

Для корректной работы в АСР «Гидра» в 

BEGIN
  MAIN.INITSS_AUTHENTICATION_PKG.LOGIN(
     vch_VC_IP        => '127.0.0.1',    -- IP-адрес, с которого выполняется вход в систему
     vch_VC_USERLOGIN      => 'Payment_RPC',  -- Логин пользователя АСР «Гидра» на приложение
     vch_VC_PASSPASSWORD      => 'secret123',    -- Пароль пользователя на приложение
     vch_VC_APP_CODE  => 'NETSERV_HID',  -- Код приложения в АСР «Гидра»
     vch_VC_CLN_APPID => 'my app info'); -- Информационная строка приложения (название, версия и т. д.)
END;

Если не вызвать эту процедуру в начале работы, то другие процедуры могут выполняться некорректно или выдавать ошибки.

В сторонних приложениях, в которых возможен интенсивный вызов SS_AUTHENTICATION_PKG.LOGIN (чаще 1 раза в минуту), для предотвращения сильного роста таблицы с сессиями следует использовать инициализацию сессии в сочетании с SS_AUTHENTICATION_PKG.SWITCH_CONTEXT. Пример:

BEGIN
  SS_AUTHENTICATION_PKG.SWITCH_CONTEXT(
    vch_VC_CLN_SESSIONID  => 'my external id');
EXCEPTION 
  WHEN ERRORS_PKG_S.SESSION_DOES_NOT_EXIST OR
       ERRORS_PKG_S.SESSION_CLOSED         OR
       ERRORS_PKG_S.MULTIPLE_SESSIONS      
  THEN
    SS_AUTHENTICATION_PKG.LOGIN(
      vch_VC_IP            => '127.0.0.1',
      vch_VC_LOGIN         => 'rpc',
      vch_VC_PASSWORD      => 'password',
      vch_VC_APP_CODE      => 'NETSERV_HID',
      vch_VC_CLN_SESSIONID => 'my external id',
      vch_VC_CLN_APPID     => 'my app info');
END;
/

В версии 5.0 коды и определения ошибок перенесены в специальный пакет ERRORS_PKG_S из SS_AUTHENTICATION_PKG.

Описание исключений:

• ERRORS_PKG_S.SESSION_ALREADY_EXISTS — исключение, возникающее при вызове SS_AUTHENTICATION_PKG.LOGIN и передаче аргумента vch_VC_CLN_SESSIONID. Если сессия с идентификатором, переданным в vch_VC_CLN_SESSIONID существует, генерируется данное исключение. Процедура SWITCH_CONTEXT данное исключение не выбрасывает и его можно не обрабатывать.
• ERRORS_PKG_S.SESSION_DOES_NOT_EXIST — исключение, возникающие тогда, когда процедура SWITCH_CONTEXT не смогла подобрать переданную сессию.
• ERRORS_PKG_S.SESSION_CLOSED — исключение, возникающее, когда сессия с переданным идентификатором уже была закрыта заданием, закрывающим старые сессии.
• ERRORS_PKG_S.MULTIPLE_SESSIONS — исключение, возникающее при обнаружении нескольких сессий с заданным идентификатором.