Документация по АСР «Гидра»
Page tree

Versions Compared

Old Version 48

changes.mady.by.user Egor Semchenko

Saved on

compared with

New Version Current

changes.mady.by.user Artem Efimenko

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

ais_name
не предоставляет приложениям возможности прямого доступа к таблицам БД. Для извлечения информации из БД используются представления (views) и процедуры сервисных пакетов, а для добавления, модификации и удаления — только хранимые процедуры. Программная документация расположена во вложенных в данный раздел страницах. Документация генерируется автоматически на основании заголовков PL/SQL-пакетов в БД. Самая актуальная версия ее всегда находится в БД работающей у вас системы. Для ее просмотра достаточно установить, например, Oracle SQL Developer, подключиться к БД и в ней посмотреть заголовки пакетов (packages). В БД все объявления процедур, типов данных имеются в открытом виде. Также доступны представления (views) в исходном коде.

...

Представления называются по стандартной схеме: <префикс>_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

CL_PRICE_ORDER

Для текстовых полей неограниченной длины

BL

BLOB

BL_FILE

Для бинарных полей неограниченной длины

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

ais_name
:

Наименование

Полное обозначение

Краткое обозначение

Пример

Расшифровка примера

Документ

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

Идентификатор абонента (абонент также является субъектом учёта)

Адрес

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

Идентификатор региона

Доп. параметр

VALUE(S)

—

N_DOC_VALUE_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

Поле

Идентификатор привязки одного адреса к другому

SI_V_SUBJ_VALUES

Представление

Дополнительные параметры СУ

SI_SUBJ_VALUE_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

Используется для хранения некоторого значения, имеющего заранее неизвестный характер (например, доп. параметр)

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

...

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

Префикс

Пример

Примечание

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

Системные пакеты и представления

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

Аргументы процедуры в

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

Префикс

Тип данных

Пример

Примечание

num

NUMBER

num_N_SUBJECT_ID

Тип NUMBER используется в АСР для всех внутренних идентификаторов

vch

VARCHAR2

vch_VC_CODE

Для текстовых полей с максимальной длиной 4000 байт

dt

DATE

dt_D_BEGIN

Дата (с точностью до секунды)

b

CONST.BOOL

b_DisableTriggers

CONST.BOOL — собственный тип данных

ais_name
. Фактически — 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)

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

ais_name
стараются, по возможности, сохранять обратную совместимость, но при добавлении новых аргументов в объявление процедуры порядок их следования не сохраняется. Вызов процедуры с именованными аргументами позволяет сохранить обратную совместимость, так как в этом случае порядок их передачи не имеет значения.

...

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

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

...

  • Code Block
    languagesql
    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
    languagesql
    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
    languagesql
    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'));


Приложения, постоянно взаимодействующие с

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

...

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

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

...

Code Block
languagesql
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.

...