REVISED AND EXTENDED FOR OAUG SPRING 2000
Copyright 1999,2000 by Brad Goodwin
Oracle Corporation
Зачем нам нужна библиотека CUSTOM
В прошлом, когда организации хотели создать для себя набор бизнес приложений или заменить существующий, у них были в основном следующий выбор:
- Купить готовое приложение в надежде, что оно удовлетворит большинство нужд организации
- Самостоятельно разработать приложение от начала до конца
Этот выбор был взаимоисключающим, и каждый из вариантов имел как достоинства, так и недостатки. Готовые приложения - идеальны, если могут удовлетворить всем требованиям компании. С другой стороны, самостоятельно разработанные приложения обеспечивают любую функциональность, какую только не пожелаешь за счет стоимости внутреннего владения приложением, которое включает затраты не только на написание кода, но и поддержку и обеспечение пользовательского приложения.
Начиная с 13 выпуска Oracle Applications Smart Client, была представлена новая возможность для расширения функциональности приложений, называемая "CUSTOM library". Библиотека CUSTOM представляет собой средство для улучшения и расширения функциональности Oracle Applications без изменения кода приложений. Библиотека CUSTOM может служить для определения функций 'zoom' (механизм перехода из формы ввода в другую форму) и усилить действия бизнес правил.
Библиотека CUSTOM это:
- Механизм, позволяющий выполнить расширение функциональности Oracle Applications без изменения кода Oracle
- PL/SQL библиотека в Oracle Forms, которая позволяет вам получить полный набор средств, предоставляемых инструментами пакета Oracle Developer 2000 suite и встроить свой код непосредственно в код Oracle Applications
- Поддерживаемое, обновляемое, отдельное хранилище пользовательского кода
В общих чертах, библиотека CUSTOM позволяет вам менять свойства, функциональность и управление выполнением форм так, как будто бы вы на самом деле изменяли исходный код формы.
Как работает библиотека CUSTOM
Библиотека CUSTOM работает, посылая "события" из каждой формы Oracle Applications в библиотеку, которая автоматически присоединяется во время выполнения. Определенный пользователем код, который находится в библиотеке CUSTOM, может затем осуществить какое-либо действие, основанное на этих событиях.
ВНИМАНИЕ: Не изменяйте никакой компонент модуля Oracle Applications (ни напрямую, ни с помощью библиотеки CUSTOM library) без полного понимания логики процессов и нижележащей структуры базы данных компонента.
Подробности библиотеки CUSTOM
Библиотека CUSTOM доступна из любой формы Oracle Applications, разработанной с помощью Oracle Forms. Она впервые появилась в Oracle Applications выпуске Production 13 Smart Client, и без существенных изменений продолжает входить в последующие выпуски Oracle Applications версий 10SC, 10.7 NCA и Release 11.
Библиотека CUSTOM в действительности представляет собой пару файлов: CUSTOM.pll и CUSTOM.plx. Расширение '.plx' - это скомпилированная версия файла '.pll'. В версиях 10SC и 10.7NCA эти файлы находились в папке $AU_TOP/res/plsql. Библиотека CUSTOM, которую вы изменили, должна заменить библиотеку CUSTOM в этой папке, которая поставляется по умолчанию, для того чтобы ваш код заработал. Примите во внимание,что если обе версии файла, '.pll' и '.plx', находятся в одной и той же папке, то Oracle Forms будет использовать файл '.plx'. Файл '.plx' создается только тогда, когда вы используете генератор Oracle Forms (Используя параметр COMPILE_ALL, установленный в значение Yes), а не тогда, когда вы компилируете и сохраняете форму используя Oracle Forms Designer.
Некоторые правила использования библиотеки CUSTOM
Так как существует только единственная библиотека, которую вызывают все формы, будьте внимательны к коду, который вы размещаете в этой библиотеке. Все ограничения и требования, которые существуют для стандартной библиотеки, также применимы и к библиотеке USTOM. К тому же, накладываются дополнительные ограничения:
- Вы не можете использовать SQL запросы в библиотеке CUSTOM (вызывайте вместо этого процедуры пакетов, размещенных на сервере или используйте группы записей (record group)Oracle Forms).
- Вы не можете изменить спецификацию пакета CUSTOM.
- Вы не можете присоединить библиотеку APPCORE к библиотеке CUSTOM (потому что CUSTOM присоединена к APPCORE), и вы не можете вызывать процедуры пакета APPCORE (которые обычно имеют префикс "APP"). Например, функция APP_ITEM_PROPERTY недоступна из библиотеки CUSTOM. Вы должны вместо нее вызывать функцию Oracle Forms SET_ITEM_PROPERTY.
- Используйте библиотеку FNDSQF, если нужно воспользоваться функциями безопасности, гибких полей и сообщений.
- Не используйте CALL_FORM или OPEN_FORM из библиотеки CUSTOM, вместо этого используйте пакет FND_FUNCTION.
Все эти правила (а также еще немного другие) описаны в документе
Release 10 Oracle Applications Coding Standards, глава 12 (часть #A42530) и
Release 11 Oracle Applications Developers Guide, глава 25 (часть # A58187).
Библиотека CUSTOM может включаться и выключаться динамически пользователем, для этого нужно выбрать пункт меню Справка->Диагностика->Пользовательский код->Выключен. Вы можете лишить пользователя возможности выключения библиотеки, установив значение профиля 'Diagnostics' в 'No'(этот профиль также контролирует доступ к большинству других пунктов меню 'Диагностика').
Когда нужно использовать библиотеку CUSTOM
Есть три способа использования библиотеки CUSTOM. Каждый из этих методов программируется различным образом.
- Zoom: Функция Zoom открывает другую форму и передает в нее параметры.
- Логика общего назначения: Добавляет ваш код к логике Oracle Applications для определенных общих событий формы, такие как WHEN-NEW-FORM-INSTANCE или WHEN-VALIDATE-RECORD.
- Логика для специфических событий приложения: Добавляет ваш код к коду Oracle Applications или заменяет его для определенных, особенных событий формы, что позволяет реализовать определенные бизнес-правила.
- Пользовательские пункты для специального меню: Добавляет пункты меню в специальное меню Oracle Applications, например такие, которые открывают пользовательскую форму.
Программирование функции Zoom
Функция Zoom позволяет пользователю "перепрыгивать" из одного окна в другое с помощью одного нажатия кнопки на панели инструментов. Например, вы можете сделать доступ к форме "Поставщики" из формы "Ввод заказа на приобретение". Вы можете включить Zoom таким образом, что когда пользователь переносит курсор в блок заголовка Заказа на приобретение, то на панели инструментов "загорается" кнопка Zoom и если ее нажать, происходит переход в форму ввода поставщика. Если вы не поместите код активации функции Zoom в библиотеке CUSTOM, кнопка Zoom не будет доступной.
Как только курсор переходит из одного блока формы в другой, форма вызывает функцию ZOOM_AVAILABLE библиотеки CUSTOM (с помощью APPCORE). Если эта функция возвращает TRUE, тогда пункт меню Zoom и кнопка на панели задач становятся доступными, если она возвращает FALSE, тогда они будут недоступны. Если пункт меню Zoom доступен, то когда пользователь выполняет Zoom, форма вызывает код события ZOOM в библиотеке CUSTOM. Вы должны написать код для этого события, которое основывается на текущей форме и блоке.
Для того, чтобы написать код для функции Zoom, нужно сделать следующее:
1. В Oracle Forms Designer откройте файл $AU_TOP/res/plsql/CUSTOM.pll (или у себя на машине копию этого файла) затем перейдите в тело пакета. Добавьте код в функцию CUSTOM.ZOOM_AVAILABLE, который устанавливает, в какой форме и в каком блоке вы хотите разрешить использование функции Zoom.
FUNCTION zoom_available RETURN BOOLEAN IS
form_name VARCHAR2(30) := NAME_IN('system.current_form');
block_name VARCHAR2(30) := NAME_IN('system.cursor_block');
BEGIN
--Кнопка Zoom разрешена для формы ввода PO:
IF (form_name = 'POXPOEPO'
AND block_name = 'PO_HEADERS') THEN
RETURN TRUE;
ELSE
RETURN FALSE;
END IF;
END zoom_available;
2. Добавьте код для события ZOOM в процедуру CUSTOM.EVENT. В этой процедуре укажите форму и блок в которых вы хотите разрешить пользователю использовать функцию Zoom.
Внимание: Версия Oracle Applications с символьным режимом всегда имеет возможность вызвать функцию Zoom, что упрощает перемещение из одного окна в другое и позволяет пользователю избежать громоздких нажатий клавиш в меню. В отличие от версий с символьным режимом, версии 10SC, 10.7NCA и 11 не поставляются с предопределенной логикой Zoom. Большинство функций Zoom, которые были определены в версиях с символьным режимом, были включены в версии 10SC, 10.7NCA и 11 в виде клавиш или новых окон.
PROCEDURE event(event_name VARCHAR2) IS
form_name VARCHAR2(30) := NAME_IN('system.current_form');
block_name VARCHAR2(30) := NAME_IN('system.cursor_block');
BEGIN
IF (event_name = 'ZOOM') THEN
IF (form_name = ' POXPOEPO'
AND block_name = 'PO_HEADERS') THEN
FND_FUNCTION.EXECUTE(FUNCTION_NAME=>'AP_APXVDMVD',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y',
OTHER_PARAMS=>'');
END IF;
END IF;
END event;
Программирование для событий общего назначения
Библиотека CUSTOM получает вызовы событий двух различных типов: общего назначения и события, специфические для продукта (приложения).
События общего назначения - одинаковы для всех форм Oracle Applications. Специфические события зарезервированы для будущего использования приложениями и специфичны для каждого приложения.
События общего назначения библиотеки CUSTOM в версии Release 10 Smart Client:
- WHEN-NEW-FORM-INSTANCE
- WHEN-NEW-BLOCK-INSTANCE
- EXPORT
- WHEN-NEW-RECORD-INSTANCE
- WHEN-NEW-ITEM-INSTANCE
- WHEN-VALIDATE-RECORD
- ZOOM
Новые события в Release 11:
- WHEN-FORM-NAVIGATE
- SPECIALn (где n - число)
SPECIAL позволяет вам задать пользовательский код, который выполняется, когда пользователь выбирает пункт из меню Special.
В действительности у вас есть почти безграничные возможности изменения поведения окон Oracle Applications с использованием этого метода. Некоторые примеры вещей, которые могут быть реализованы с помощью библиотеки CUSTOM, включают:
- Изменение свойств поля формы, т.е. скрытие полей формы, изменение цвета и т.д.
- Добавление дополнительной и перекрестной проверки полей
- Изменение LOV или выражения Where заданных по умолчанию
- Автоматическая инициализация полей, основанная на вычислениях, производимых на стороне сервера
- Запись журнала аудита напрямую в файл
- Вызов новых форм, которые взаимодействуют с базовыми формами
- Манипуляция полями обязательными для заполнения в зависимости от контекста
- Манипуляция взаимно исключающими полями
- Установка значений по умолчанию
- Установка вычислений для добавленных полей
- Базовая обработка событий
- Обновление запрещенных для редактирования полей
- Вызов процедур, расположенных на сервере, которые затем запускают программу PL/SQL
Например, ваша компания требует, чтобы наименования поставщиков всегда вводились заглавными буквами. Библиотека CUSTOM позволяет вам добавить код для реализации этого без изменения исходного кода Oracle:
PROCEDURE event(event_name VARCHAR2) IS
form_name VARCHAR2(30) := NAME_IN(’system.current_form’);
BEGIN
IF (event_name = ’WHEN-NEW-FORM-INSTANCE’) THEN
IF (form_name = ’APXVDMVD’) THEN
/* Переводим свойство поля наименования поставщика в uppercase */
set_item_property(‘VNDR.VENDOR_NAME_MIR’,
CASE_RESTRICTION, UPPERCASE);
END IF;
END IF;
END event;
Другой пример: В Oracle Applications системный администратор может назначить или удалить полномочия для какого нибудь пользователя.
Во многих организациях требуется, чтобы такие широкие права не предоставлялись одному лицу. Простой и эффективный способ решить эту проблему – воспользоваться библиотекой CUSTOM. Нижеприведенный код работает с окном определения полномочий пользователя библиотеки Application Object Library. Этот код проверяет, запросил ли пользователь свои собственные полномочия, и если это так, запрещает редактирование всего блока с полномочиями.
PROCEDURE event(event_name VARCHAR2) IS
form_name VARCHAR2(30) := name_in('system.current_form');
block_name VARCHAR2(30) := name_in('system.current_block');
new_state number;
BEGIN
IF form_name = 'FNDSCAUS' THEN
IF event_name = 'WHEN-NEW-BLOCK-INSTANCE' THEN
IF block_name = 'USER_RESP' THEN
IF (fnd_profile.value('USERNAME') = name_in('USER.user_name')) THEN
new_state := property_false;
ELSE
new_state := property_true;
END IF;
set_block_property(block_name, insert_allowed, new_state);
set_block_property(block_name, update_allowed, new_state);
END IF;
END IF;
END IF;
END event;
Другой пример: У некоторых организаций есть несколько экземпляров Oracle Applications: тестовый, для разработчиков, промышленный, иногда даже несколько промышленных баз данных. Для пользователей, которые переключаются между разными экземплярами Oracle Applications, трудно определить, к какому именно экземпляру они присоединились. Следующий код, расположенный в библиотеке CUSTOM, изменяет заголовок, добавляя строку соединения к текущему экземпляру Oracle Applications. (К сожалению, этот код работает только с версией 10SC)
PROCEDURE event (event_name varchar2) IS
BEGIN
IF (event_name = 'WHEN-NEW-FORM-INSTANCE') then
set_window_property(FORMS_MDI_WINDOW, TITLE,
'Oracle Applications Instance: (' ||
upper(get_application_property(CONNECT_STRING)) || ')');
END IF;
END;
END event;
Другой пример: Хотите, чтобы обязательные поля были подсвечены, чтобы пользователь мог быстро определить, какие поля обязательные для заполнения? Фрагмент кода, приведенный ниже, показывает, как выполнить это для любой формы. Поместите этот код в процедуру EVENT библиотеки CUSTOM.
Внимание: Подсвеченные обязательные поля в версии 11.5 уже является стандартом
set_item_property('person.last_name',VISUAL_ATTRIBUTE,'SELECTED_DATA');
set_item_property('person.d_person_type_id',VISUAL_ATTRIBUTE,'SELECTED_DATA');
set_item_property('person.sex',VISUAL_ATTRIBUTE,'SELECTED_DATA');
set_item_property('person.employee_number',VISUAL_ATTRIBUTE,'SELECTED_DATA');
set_item_property('person.national_identifier',VISUAL_ATTRIBUTE,'SELECTED_DATA');
set_item_property('person.date_of_birth',VISUAL_ATTRIBUTE,'SELECTED_DATA');
Взяв за основу этот пример, вы можете добавить окно диалога для информирования пользователя, какие поля являются обязательными, и даже запретить пользователю сохранять свою работу, пока все обязательные поля не будут заполнены:
IF name_in('person.last_name') IS NULL
OR name_in('person.d_person_type_id') IS NULL
OR name_in('person.sex') is null
OR name_in('person.national_identifier') IS NULL
OR name_in('person.date_of_birth') IS NULL THEN
fnd_message.set_string('Вы не заполнили все обязательные поля: Фамилия, Пол, Тип персоны, ИНН, Дата рождения');
fnd_message.show;
END IF;
-- Предотвращаем сохранение формы
RAISE form_trigger_failure;
Другой пример: Надо спрятать поле?
set_item_property('person.d_home_office',DISPLAYED,PROPERTY_FALSE);
(Но пожалуйста, имейте ввиду, что метка поля останется видимой. ...По крайней мере, если вы не поместите код, который скроет ее каким-нибудь графическим объектом)
Программирование событий, специфичных для продукта
События, специфичные для приложения, были редкостью до релиза 11. Первым модулем, который стал использовать эти события, был Oracle HR, затем остальные модули тоже начали следовать этому примеру.
В некоторых формах приложение Oracle HR создало дополнительные точки обработки событий, которые передаются в библиотеку CUSTOM. Это такие события:
- WHEN–CREATE–RECORD
- POST–QUERY
- KEY–DELREC
- PRE–UPDATE
- PRE–INSERT
- PRE–DELETE
- POST–INSERT
- POST–UPDATE
- POST–DELETE
- POST–FORMS–COMMIT
- WHEN–BUTTON–PRESSED
- NAVIGATE (Событие NAVIGATE передается в библиотеку CUSTOM перед открытием нового окна.
21 форма Oracle HR и 12 форм Oracle Training Administration были изменены для обработки этих дополнительных событий. Они описаны в документе Release 11 Oracle Applications Product Update Notes (part #A57984).
Кастомизация формы ввода заказов
Хотя это напрямую не относится к
библиотеке CUSTOM, форма Oracle для ввода заказов на продажу имеет специфичную особенность, она ссылается на
форму CUSTOM. Форма CUSTOM позволяет клиентам определить внешний вид формы ввода заказов, но, поскольку эти визуальные аспекты хранятся в отдельном файле fmx, отдельно от функциональной логики, пользовательский код сохраняется при обновлении формы на новую версию.
Форма CUSTOM содержит презентационный слой формы ввода заказов, который может быть изменен с помощью Developer/2000 Forms Designer. Главная форма (OEXOEMOE), которая ссылается на объекты пользователя в форме CUSTOM (OEXOECOE), выполняется в нормальной среде выполнения приложения.
Когда вы редактируете форму CUSTOM, вы можете выбрать вариант кастомизации из следующих возможных:
- Спрятать элемент (текстовый элемент, кнопку, флажок, выпадающий список, радио группу) Внимание: не скрывайте от пользователя обязательные для ввода поля или поля, которые не заполняются по умолчанию каким-нибудь значением. Например, не прячьте поле «Тип Заказа».
- Показать спрятанные элементы
- Изменить размер элемента
- Изменить порядок следования элементов
- Переместить элемент из одного региона в другой
- Переместить элемент из многострочного блока за пределы блока и наоборот
- Редактировать метки полей
- Увеличить ил уменьшить количество строк, отображающихся в многострочном блоке
- Изменить размер окна
- Установить кнопку по умолчанию
Эти возможности доступны только в форме ввода Заказов на продажу.
Расширенное программирование пользовательского кода
Заметьте, что не все события форм Oracle посылаются в библиотеку CUSTOM (такие, как WHENCHECKBOX-CHANGED и много других). Это означает, что вы должны всегда проверять, запускается ли ваш код одним из поддерживаемых триггеров событий, описанных ранее.
Но что делать, если необходимый вам триггер события отсутствует в официальном списке?
Или вам необходимо добавить кучу пользовательского кода в форму? Библиотека CUSTOM может (и должна) использоваться, если базовый код просто должен быть изменен, так как это помещает большинство вашего пользовательского кода в библиотеку CUSTOM и минимизируется изменения кода, которые должны быть обновлены, когда базовая форма обновляется или накатывается патч.
У одной из компаний в моей области были проблемы у пользователей Дебиторов, которые выполняли слепые запросы в форме детальной информации счетов, что инициализировало сканирование всей таблицы, имеющей 6 миллионов записей (которая затем была присоединена еще к 8 таблицам …). Не нужно быть администратором БД, чтобы понять, что это приводит к большой нагрузке на базу данных, даже если только несколько пользователей работают одновременно. Эта компания хотела, чтобы любые запросы в форме детальной информации счетов всегда включали некоторые дополнительные критерии поиска, так чтобы результирующий набор был меньше и эти индексы могли быть использованы оптимизатором для быстрого выполнения запроса. Событием, которое должно было быть перехвачено было событие WHEN-BUTTON-PRESSED в окне поиска. Библиотека CUSTOM была превосходным хранилищем требуемого кода, но определение формы должно было быть изменено для передачи определенного пользователем события ‘CUSTOM_FIND’ в библиотеку CUSTOM. Ниже приведен код.
PROCEDURE event(event_name VARCHAR2) IS
query_fields VARCHAR2(100);
BEGIN
-- Обычно библиотека CUSTOM не получает событие WHEN-BUTTON-PRESSED event.
-- Мы изменили кнопку "FIND" окна поиска в форме
-- AR Account Details Find screen's "FIND" для передачи
-- этого события. См C:\apps10\au10\res\plsql\ARXCOQIT.PLL,
-- в процедуре ARXCOQIT_FIND, которая запускается
-- когда на форме нажата кнопка FIND.
-- Мы добавили вызов custom.event(‘CUSTOM_FIND’)
IF (event_name = 'CUSTOM_FIND') THEN
-- Пользователь ввел критерии поиска в какое-нибудь поле?
query_fields := NAME_IN('CQIT_FIND.trx_number')||
NAME_IN('CQIT_FIND.name')||
NAME_IN('CQIT_FIND.number')||
NAME_IN('CQIT_FIND.sales_order')||
NAME_IN('CQIT_FIND.purchase_order');
-- Если нет, тогда информируем пользователя об ошибке
IF query_fields IS NULL THEN
fnd_message.set_string('Чтобы избежать серъезной потери производительности, вам необходимо указать хотя бы один критерий поиска.');
fnd_message.error;
-- Запрещаем выполнение запроса
COPY( 'FALSE' ,'parameter.g_query_find' );
END IF;
END IF;
END event;
Новое в версии 11i
Библиотека CUSTOM осталась практически без изменений в версии 11i, за исключением новой функциональности, которая упрощает развертывание приложения. Три новые особенности:
- Дополнительные списки значений (LOV) в каждой форме. В каждой форме Applications теперь есть дополнительные LOV, доступные для использования в библиотеке CUSTOM: APPCORE_ZOOM LOV. Вы можете использовать этот список, если у вас в форме определено несколько функций ZOOM. Этот LOV может быть использован для показа всплывающего окна со списком всех форм, доступных для перехода, пользователь может выбрать из этого списка форму, в которую он хочет перейти.
- Клиентские визуальные атрибуты. Библиотека CUSTOM теперь имеет возможность изменять визуальные атрибуты объектов формы (такие как кнопки, поля и т.д.) в процессе выполнения.
- Сняты некоторые предыдущие ограничения для программирования. Теперь вы можете вызывать любую хранимую процедуру Applications, потому что переменные пакета теперь хранятся локально в сессии базы данных. (Осталось ограничение, касающееся того, что вы не можете использовать выражения SQL или DML в библиотеке CUSTOM.)
Некоторые процедуры APPCORE стали доступны для использования в библиотеке CUSTOM, в новой библиотеке APPCORE2. Библиотека APPCORE2 дублирует большинство процедур APPCORE:
- APP_ITEM_PROPERTY2
- APP_DATE2
- APP_SPECIAL2
Для использования этих процедур, присоедините APPCORE2 к вашей библиотеке CUSTOM. Изменилось только название библиотеки; процедуры и функции в библиотеке APPCORE2 имеют те же самые наименования, что их копии в APPCORE.
Заключение
Библиотека CUSTOM обеспечивает гибкий механизм, позволяющий клиентам расширять приложение в управляемом и контролируемом окружении при сохранении стандартного кода приложения. Возможность включать или отключать код библиотеки CUSTOM обеспечивает техническую поддержку для приложения, даже если возникают какие-то проблемы, потому что это позволяет установить источник возникновения проблемы: вызвана она кодом пользователя или стандартным кодом Oracle.
Об авторе
Brad Goodwin (
bgoodwin@us.oracle.com) – технический специалист по Oracle e-Business Suite в Портланд, штат Орегон. За тринадцать лет работы в Oracle десять из них потратил на работу над технической архитектурой и компонентами Oracle Applications.
Библиография
White Paper: “GUIDELINES FOR THE ADDITION OF USER DEFINED BUSINESS
RULES WITHIN THE ORACLE APPLICATIONS,” Andrew McGhee, HRMS Product
Support Manager, Oracle Corporation, Bracknell, UK, April 1998
Release 11 Oracle Applications Developers Guide, chapter 25 (part # A58187)
Release 10SC Oracle Applications Coding Standards, chapter 12 (part #A42530)
Release 11 Oracle Applications Product Update Notes (part #A57984)
