Using SYNCHRONIZE for Form Refresh in Oracle Forms • Vinish.Dev

When you change properties, update display-only fields in a loop, or start a time-consuming task, the Oracle Forms UI may not repaint immediately. Users then see “frozen” values or stale visuals, even though your code has already updated them. The SYNCHRONIZE built-in tells the Forms runtime to process the pending UI events right now—so the screen reflects your changes without performing a data re-query.

This tutorial explains what SYNCHRONIZE actually does, when it helps, when it does not, and how to use it safely with practical code patterns.

On This Page
Show More

What SYNCHRONIZE Really Does

SYNCHRONIZE forces the Forms runtime to process its message/event queue immediately.
Think of it as a polite “UI flush”:

It refreshes visuals (e.g., display items, progress bars, canvas and item property changes).
It does not fetch new records or run queries.
It does not commit or rollback anything.
It does not jump triggers forward; it simply lets the UI thread catch up.

Key mental model: Use SYNCHRONIZE when the UI must update because of your code’s recent property or value changes, not when data needs to be fetched again from the database.

Common Situations Where SYNCHRONIZE Helps

Progress/Status updates inside loops
Show a percentage or step number while a long loop runs.
Immediate repaint after property changes
You’ve called SET_ITEM_PROPERTY, SET_CANVAS_PROPERTY, or changed visual attributes and want the user to see it now.
After launching a long task
Display a “Please wait” message or spinner, then call SYNCHRONIZE so it becomes visible before the heavy work starts.
Tabbed/canvas switches
Change tab pages or stacked canvases and force the UI to show the new layout instantly.

When NOT to Use SYNCHRONIZE

Refreshing data from the database → use EXECUTE_QUERY (or LAST_RECORD/FIRST_RECORD with caution).
Committing data → use COMMIT or DO_KEY('COMMIT_FORM').
Discarding changes → use CLEAR_FORM (with the right parameter) or an explicit ROLLBACK.
Navigating to other forms → use CALL_FORM, OPEN_FORM, or NEW_FORM.

Opinion: Overusing SYNCHRONIZE as a “make it work” band-aid can hide design issues (e.g., heavy logic running in UI triggers). Use it deliberately.

Syntax at a Glance

SYNCHRONIZE;

No arguments. It is safe to call repeatedly, but avoid calling it in extremely tight loops unless the UI truly needs to repaint on every iteration.

Pattern 1: Show a “Please Wait” Message Before Heavy Work

DECLARE
  v_steps NUMBER := 5;
BEGIN
  -- Make the message visible first.
  :blk.status_msg := 'Processing… please wait.';
  SET_ITEM_PROPERTY('BLK.STATUS_MSG', VISIBLE, PROPERTY_TRUE);
  SYNCHRONIZE; -- Force repaint so the user sees the message now.

  -- Start the heavy work.
  FOR i IN 1..v_steps LOOP
    -- Your long-running step here
    -- e.g., call a stored proc, generate files, etc.
  END LOOP;

  :blk.status_msg := 'Done.';
  SYNCHRONIZE;
EXCEPTION
  WHEN OTHERS THEN
    :blk.status_msg := 'Failed: '||SQLERRM;
    SYNCHRONIZE;
    RAISE;
END;

Why this works: Without SYNCHRONIZE, the status message may not appear until the heavy loop finishes.

Pattern 2: Live Progress Bar or Percentage in a Loop

DECLARE
  v_total NUMBER := 100;
BEGIN
  FOR i IN 1..v_total LOOP
    -- Do a small unit of work…
    :blk.progress_pct := TO_CHAR(ROUND(i*100/v_total))||'%';
    SYNCHRONIZE; -- Let the UI repaint the progress now.
  END LOOP;
  :blk.progress_pct := '100%';
  SYNCHRONIZE;
END;

Tip: Repainting on each iteration can be costly. For big loops, refresh every N steps:

IF MOD(i, 10) = 0 THEN SYNCHRONIZE; END IF;

Pattern 3: Forcing Canvas/Tab Repaint After Property Changes

BEGIN
  -- Switch to another tab page and show a busy icon/label.
  SET_TAB_PAGE_PROPERTY('TAB_CANVAS', CURRENT_TAB_PAGE, 3);
  SET_ITEM_PROPERTY('BLK.BUSY_LABEL', VISIBLE, PROPERTY_TRUE);
  SYNCHRONIZE; -- Make the user see the new page and label immediately.

  -- Time-consuming query or computation here…

  SET_ITEM_PROPERTY('BLK.BUSY_LABEL', VISIBLE, PROPERTY_FALSE);
  SYNCHRONIZE;
END;

Pattern 4: Combine with EXECUTE_QUERY Carefully

If you truly need fresh data and an immediate repaint, you often want:

BEGIN
  :blk.status_msg := 'Refreshing…';
  SYNCHRONIZE;        -- show message first
  EXECUTE_QUERY;      -- actually fetch data
  :blk.status_msg := NULL;
  SYNCHRONIZE;        -- clear message immediately after
END;

Important: SYNCHRONIZE alone never refreshes records—EXECUTE_QUERY does.

Pattern 5: WebUtil Operations With Visual Feedback

When uploading/downloading files or performing client-side tasks via WebUtil, show progress text so the form does not look frozen:

BEGIN
  :blk.info := 'Uploading file…';
  SYNCHRONIZE;

  -- e.g., CLIENT_TEXT_IO or WebUtil file transfer call here

  :blk.info := 'Upload complete.';
  SYNCHRONIZE;
END;

Placement Guidance (Triggers and Blocks)

WHEN-BUTTON-PRESSED / KEY-… triggers
Ideal for showing a message/spinner and then calling heavy logic.
POST-QUERY / PRE-QUERY
Usually avoid SYNCHRONIZE here unless you change visuals unrelated to the current fetch. Let query flow stay clean.
WHEN-VALIDATE-ITEM / WHEN-VALIDATE-RECORD
Keep validation quick. If you must display progress, reconsider design. SYNCHRONIZE inside validation can feel odd to users.
Timers (WHEN-TIMER-EXPIRED)
For background-ish UI updates, timers plus SYNCHRONIZE can help repaint in stages without locking the UI.

Performance and Safety Tips

Throttle updates. If you update a label inside a 10,000-row loop, repaint every 20–50 iterations, not each time.
Update only what matters. Avoid toggling visibility or setting the same value repeatedly.
Avoid as a crutch. If you need SYNCHRONIZE “everywhere,” move heavy logic to server-side PL/SQL or break it into smaller tasks.
Mind user perception. A short “Please wait” text plus a SYNCHRONIZE goes a long way to reduce anxiety during long operations.

Troubleshooting: “SYNCHRONIZE Did Nothing”

You expected fresh data. Call EXECUTE_QUERY.
Item remains hidden. Ensure ENABLED, VISIBLE, and canvas stacking are correct; then SYNCHRONIZE.
Property change on the wrong item. Double-check block/item names and current canvas.
Loop completes too fast to see changes. For very fast loops, insert a tiny SYNCHRONIZE at key milestones or a short SLEEP (if appropriate) purely for UX.

Alternatives and Complements

EXECUTE_QUERY – Fetch fresh rows from base tables.
SET_ITEM_PROPERTY / SET_CANVAS_PROPERTY – Change what the user will see.
Timers (CREATE_TIMER) – Stage UI changes without blocking.
Built-ins like SHOW_ALERT / MESSAGE – Communicate state; pair with SYNCHRONIZE so alerts/messages appear before heavy work.

Best Practices Checklist

Show a status message, then SYNCHRONIZE, then start heavy work.
For progress updates, change the display item and call SYNCHRONIZE at controlled intervals.
After canvas/tab switches, call SYNCHRONIZE to guarantee repaint.
Don’t mistake SYNCHRONIZE for data refresh or commit.
Use it sparingly and purposefully to improve perceived responsiveness.

Conclusion

SYNCHRONIZE is a lightweight but powerful tool to keep your Oracle Forms UI honest. It flushes pending UI work—so status text, progress indicators, and property changes appear when users expect them—without touching your data or transaction state. Use it before or during long operations, after visual changes, and in loops where the user needs live feedback. Combine it thoughtfully with EXECUTE_QUERY, property changes, and timers, and you will deliver forms that feel faster, clearer, and more professional.