Forms Library: General bits and pieces

This is just a post to document a standard utility functions that I like to create in a Oracle Forms library, if equivalents are not already available. Suggestions or critiques are welcome.

“No warranty is express or implied about the suitability of this code for any purpose.”

I’ll only create those things which I find become generally useful for a particular site. If something’s not used, get rid of it. That said, most of these things I’ve created because I use them frequently.

PROCEDURE assert (truth IN BOOLEAN, module IN VARCHAR2) IS
BEGIN
  IF truth THEN
    NULL;
  ELSE --truth may be null or false
    PKG_MESSAGE.error('Assertion failed in ' || module);
  END IF;
END assert;

PROCEDURE check_package_failure IS
-- (this is generated automatically by Oracle Forms when a block
-- relation is created)
-- This should be called after various builtins that, instead of
-- doing the honourable thing (raising an exception), set
-- FORM_SUCCESS. These builtins are*:
--  CALL_FORM CALL_QUERY CANCEL_QUERY CLEAR_BLOCK CLEAR_FORM
--  CLEAR_ITEM CLEAR_RECORD COUNT_QUERY DELETE_RECORD DOWN
--  DO_KEY DUPLICATE_ITEM DUPLICATE_RECORD EDIT_TEXTITEM ENTER
--  ENTER_QUERY EXECUTE_QUERY EXECUTE_TRIGGER EXIT_FORM
--  FETCH_RECORDS FIRST_RECORD FORMS_DDL GO_BLOCK GO_FORM
--  GO_ITEM GO_RECORD HOST INSERT_RECORD LAST_RECORD
--  LIST_VALUES LOCK_RECORD LOGON LOGON_SCREEN LOGOUT
--  NEW_FORM NEXT_BLOCK NEXT_ITEM NEXT_FORM NEXT_KEY
--  NEXT_RECORD NEXT_SET OPEN_FORM PREVIOUS_BLOCK
--  PREVIOUS_FORM PREVIOUS_ITEM PREVIOUS_BLOCK UP
-- * if you notice any builtins missing from, or that should not be
--    included in this list - please let me know!
BEGIN
  IF NOT ( Form_Success ) THEN
    RAISE Form_Trigger_Failure;
  END IF;
END check_package_failure;

PROCEDURE msg (text IN VARCHAR2) IS
-- just a convenient wrapper for PKG_DEBUG.msg
BEGIN
  PKG_DEBUG.msg(text);
END msg;

PKG_DEBUG definition

Form-level trigger: pre-select

msg(:SYSTEM.LAST_QUERY);

Form-level trigger: on-error

msg('on-error ' || ERROR_TYPE || '-' || ERROR_CODE || ' ' || ERROR_TEXT);
-- add handlers here for errors that we don't want to spit the dummy on (i.e. handle gracefully)
CASE
WHEN ERROR_TYPE||'-'||ERROR_CODE IN
  ('FRM-41105' --"You cannot query records without a saved parent record."
  ) THEN
  -- the default message is a little obtuse - give a standard response
  MESSAGE('That function is not allowed here.', ACKNOWLEDGE);
  RAISE FORM_TRIGGER_FAILURE;

WHEN ERROR_TYPE||'-'||ERROR_CODE IN
  ('FRM-40202' --"Field must be entered."
  ,'FRM-40203' --"Field must be entered completely."
  ,'FRM-40207' --"Must be in range x to y"
  ,'FRM-40209' --"Field must be of form x."
  ,'FRM-40212' --"Invalid value for field x."
  ,'FRM-40356' --"Invalid number in example record. Query not issued."
  ,'FRM-40357' --"Invalid string in example record. Query not issued."
  ,'FRM-40358' --"Invalid date in example record. Query not issued."
  ,'FRM-40359' --"Invalid date or time in example record. Query not issued."
  ,'FRM-40501' --"ORACLE error: unable to reserve record for update or delete."
  ,'FRM-40654' --"Record has been updated by another user. Re-query to see change."
  ,'FRM-40657' --"Record changed or deleted by another user."
  ,'FRM-41106' --"You cannot create records without a parent record."
  ) THEN
  -- show the error message in a popup and raise FTF
  PKG_FORM.error(ERROR_TEXT);

WHEN ERROR_TYPE||'-'||ERROR_CODE
  BETWEEN 'FRM-50000' AND 'FRM-51000' THEN
  -- almost all the FRM-5xxxx errors are to do with data format issues, e.g. date
  -- fields, numbers, etc
  PKG_FORM.error(ERROR_TEXT);

WHEN ERROR_TYPE||'-'||ERROR_CODE IN
  ('FRM-40100' --"At first record."
  ,'FRM-40102' --"Record must be entered or deleted first."
  ,'FRM-40110' --"At first block."
  ,'FRM-40111' --"At last block."
  ,'FRM-40200' --"Field is protected against update."
  ,'FRM-40201' --"Field is full. Can't insert character."
  ,'FRM-40401' --"No changes to save."
  ,'FRM-40405' --"No changes to apply."
  ,'FRM-41026' --"Field does not understand operation." (e.g. F9 on item with no list)
  ,'FRM-41050' --"You cannot update this record."
  ,'FRM-41051' --"You cannot create records here."
  ) THEN
  -- just display the default error message on the status bar (or popup if >1 message in quick succession)
  MESSAGE(ERROR_TEXT, ACKNOWLEDGE);
  RAISE FORM_TRIGGER_FAILURE;
ELSE
  PKG_DEBUG.on_error;
END CASE;

Form-level trigger: on-message

msg('on-message ' || MESSAGE_TYPE || '-' || MESSAGE_CODE || ' ' || MESSAGE_TEXT);
-- trap some messages and replace with more user-friendly message
CASE
WHEN MESSAGE_TYPE||'-'||MESSAGE_CODE IN
  ('FRM-40350' --"Query caused no records to be retrieved."
  ) THEN
PKG_FORM.note('No matching receipts found.', 'Search Results');
WHEN MESSAGE_TYPE||'-'||MESSAGE_CODE IN
  ('FRM-41800' --"List of Values not available for this field."
  ,'FRM-40400' --"Transaction complete: %s records applied and saved."
  ) THEN
  -- the default message is user-friendly enough to show on the status bar
  MESSAGE(MESSAGE_TEXT, ACKNOWLEDGE);
ELSE
  PKG_DEBUG.on_message;
END CASE;

Jeffrey Kemp 4 August 2010

Forms / forms-common-code / tips-&-tricks /

About Jeffrey Kemp

Application Designer & Developer at Oracle specialising in Oracle APEX (Application Express), Oracle SQL and PL/SQL. Oracle ACE Alumni ♠️. Piano player, father, husband, Christian. The views expressed on this blog are my own and do not necessarily reflect the views of Oracle.