Coder Legion - Recent posts tagged low-code

End-to-End Payment Gateway Configuration in Oracle APEX

Fri, 12 Jun 2026 19:09:44 +0000

Every tutorial I found did the same thing. They showed you how to build the form, how to generate the payment URL, how to redirect the user to the gateway. And then they stopped.

The implicit assumption was: the user pays, the gateway redirects them back, you're done. But that is exactly where things fell apart for me.

The gateway called back to my server, my APEX app received the redirect, and the user landed on a broken, sessionless page. No context. No confirmation. Just a dead URL that APEX didn't know what to do with. I had successfully taken a payment and completely failed to handle it.

This article is about that part. The part nobody covers.

What We're Actually Building

We're building an end-to-end payment flow inside Oracle APEX, with a focus on the callback and redirect handling. Specifically:

A PL/SQL package that initiates the payment and processes the callback
An ORDS REST handler that acts as the gateway's callback endpoint
A secure redirect back into APEX after payment preserving session, handling failures, and blocking replay attacks

I'll use a credit top-up flow as the concrete example throughout, since that's the real implementation this is drawn from. The patterns apply to any payment use case.

The gateway used here is BML Connect. I'll keep credential details out of it, here what matters is the pattern, not the provider.

The Problem With "Just Redirect"

When you initiate a payment, you send the user off to the gateway's hosted page. At that point, your APEX session is still alive but the user has left your app.

When the payment completes, the gateway needs to tell your system two things:

Server-to-server: a backend callback (sometimes called a webhook or IPN) that posts the payment result to your server regardless of what the browser does.
Browser redirect: the user's browser is sent back to a URL you specified at initiation time.

The naive approach is to make both of these the same URL and to just point them at an APEX page. The problem is that by the time the browser redirect fires, your original APEX session may be gone, invalid, or simply unknown to the incoming request. APEX has no idea who this user is. It generates a new session. Your confirmation page has no data. The user is confused.

There's also a another issue: if you redirect straight to an APEX page URL with the result in query parameters, a user can bookmark that URL and replay it. Or worse, tamper with the parameters before the page loads. You need validation to happen before the user ever sees the confirmation page.

The solution is to put an ORDS REST handler between the gateway and APEX. The handler validates everything server-side, then constructs a controlled redirect back into your app.

Architecture Overview

The ORDS handler does two jobs: it processes the callback (validation, DB update) and then emits an HTML meta-refresh that sends the browser to the right APEX page. Your APEX page only ever loads after the work is done.

Step 1: Setting Up the ORDS REST Handler

In APEX, navigate to SQL Workshop → RESTful Services (or use the ORDS module definitions directly).

Create a module, a template, and a GET handler. The structure you need:

Setting	Value
Module Base Path	`/api/v1/topup/`
Template	`callback/bml`
Method	GET
Source Type	PL/SQL

BML Connect sends the callback as a GET request with query parameters. Other gateways use POST check your gateway's documentation and create the handler accordingly. If your gateway sends POST, set the method to POST and read parameters from the request body instead.

The full ORDS URL your handler will be reachable at:

https://<your-ords-base-url>/ords/<your_schema>/api/v1/topup/callback/bml

This is the URL you register with your gateway as the redirect/callback URL at payment initiation time.

For each parameter the gateway will send back (BML sends transactionId, state, signature, localId), you don't need to declare them explicitly in ORDS as they're available as bind variables in your PL/SQL source using the colon prefix: :transactionId, :state, etc.

Step 2: The Payment Package

Before the handler, we need the PL/SQL that does the real work. Keep the handler thin and all logic lives in a package.

Package Spec

CREATE OR REPLACE PACKAGE PKG_PAYMENT AS

    FUNCTION GENERATE_LOCAL_REF (
        p_entity_code IN VARCHAR2
    ) RETURN VARCHAR2;

    PROCEDURE INITIATE_PAYMENT (
        p_entity_id    IN  NUMBER,
        p_amount       IN  NUMBER,
        p_performed_by IN  NUMBER,
        p_payment_id   OUT NUMBER,
        p_local_ref    OUT VARCHAR2,
        p_payment_url  OUT VARCHAR2
    );

    PROCEDURE PROCESS_CALLBACK (
        p_transaction_id IN  VARCHAR2,
        p_state          IN  VARCHAR2,
        p_signature      IN  VARCHAR2,
        p_local_id       IN  VARCHAR2,
        p_result_code    OUT NUMBER,
        p_result_msg     OUT VARCHAR2,
        p_session_id     OUT VARCHAR2
    );

    PROCEDURE RECONCILE_PAYMENT (
        p_payment_id   IN  NUMBER,
        p_performed_by IN  NUMBER,
        p_result_code  OUT NUMBER,
        p_result_msg   OUT VARCHAR2
    );

END PKG_PAYMENT;
/

Signature Verification

This is the first thing that happens when the gateway calls back. The gateway signs its response using HMAC-SHA1 with a secret key you both share. You recompute the signature on your side and compare. If they don't match, you reject the callback immediately so no DB updates, nothing.

FUNCTION VERIFY_SIGNATURE (
    p_transaction_id IN VARCHAR2,
    p_state          IN VARCHAR2,
    p_signature      IN VARCHAR2,
    p_secret_key     IN VARCHAR2
) RETURN BOOLEAN AS
    v_raw      VARCHAR2(4000);
    v_hash_raw RAW(8000);
    v_hash_b64 VARCHAR2(512);
BEGIN
    -- Concatenate the fields the gateway signed
    v_raw := p_transaction_id || p_state;

    -- Recompute HMAC-SHA1
    v_hash_raw := DBMS_CRYPTO.MAC(
        src => UTL_RAW.CAST_TO_RAW(v_raw),
        typ => DBMS_CRYPTO.HMAC_SH1,
        key => UTL_RAW.CAST_TO_RAW(p_secret_key)
    );

    -- Base64-encode and compare
    v_hash_b64 := UTL_RAW.CAST_TO_VARCHAR2(
        UTL_ENCODE.BASE64_ENCODE(v_hash_raw)
    );

    RETURN (v_hash_b64 = p_signature);

EXCEPTION
    WHEN OTHERS THEN
        RETURN FALSE;
END VERIFY_SIGNATURE;

A few things worth noting here:

The exact fields that go into the signature string depend on your gateway. BML uses transactionId || state. Check your gateway's documentation carefully.
For UAT/sandbox environments, gateways sometimes send dummy or null signatures. You'll want a UAT bypass in your code so check your config table for whether you're in test mode, and skip verification if the incoming signature matches a known test value.

Generating a Local Reference

Before calling the gateway, generate a unique local reference that belongs to your system. This is crucial beacause you'll use it to look up the payment record when the callback arrives, rather than trusting the gateway's transaction ID alone.

FUNCTION GENERATE_LOCAL_REF (
    p_entity_code IN VARCHAR2
) RETURN VARCHAR2 AS
    v_seq NUMBER;
BEGIN
    SELECT YOUR_SEQUENCE.NEXTVAL INTO v_seq FROM DUAL;
    RETURN 'PAY-'
        || UPPER(TRIM(p_entity_code))
        || '-'
        || TO_CHAR(SYSDATE, 'YYYYMMDDHHMMSS')
        || '-'
        || LPAD(TO_CHAR(v_seq), 4, '0');
END GENERATE_LOCAL_REF;

This gives you something like PAY-AGENCY001-20240615143022-0047. Timestamp plus sequence means it's unique even under concurrent load.

Initiating the Payment

This procedure does three things: validates the request, creates a PENDING record in your database, then calls the gateway API to get a payment URL.

The PENDING record is created before you call the gateway. This is intentional. If the API call fails, you still have a record of the attempt. If the gateway somehow calls back before your code finishes (rare, but possible), the record exists to receive it.

PROCEDURE INITIATE_PAYMENT (
    p_entity_id    IN  NUMBER,
    p_amount       IN  NUMBER,
    p_performed_by IN  NUMBER,
    p_payment_id   OUT NUMBER,
    p_local_ref    OUT VARCHAR2,
    p_payment_url  OUT VARCHAR2
) AS
    v_local_ref      VARCHAR2(128);
    v_payment_id     NUMBER;
    v_api_key        VARCHAR2(512);
    v_api_url        VARCHAR2(500);
    v_return_url     VARCHAR2(500);
    v_amount_minor   NUMBER;  -- amount in minor units (e.g. laari, cents)
    v_req            VARCHAR2(32767);
    v_resp           VARCHAR2(32767);
    v_http_req       UTL_HTTP.REQ;
    v_http_resp      UTL_HTTP.RESP;
    v_raw_chunk      RAW(2000);
    v_gateway_txn_id VARCHAR2(255);
    v_pay_url        VARCHAR2(1000);
    v_err_msg        VARCHAR2(4000);
BEGIN
    -- Validate your business rules here
    -- (entity status, account type, amount > 0, etc.)
    IF p_amount <= 0 THEN
        RAISE_APPLICATION_ERROR(-20063, 'Amount must be greater than zero.');
    END IF;

    -- Load gateway config from a config table (never hardcode credentials)
    SELECT API_KEY, API_BASE_URL, RETURN_URL
    INTO   v_api_key, v_api_url, v_return_url
    FROM   PAYMENT_GATEWAY_CONFIG
    WHERE  GATEWAY = 'BML' AND IS_ACTIVE = 'Y';

    -- Generate your local reference
    v_local_ref    := GENERATE_LOCAL_REF('YOUR_ENTITY_CODE');
    v_amount_minor := ROUND(p_amount * 100);  -- convert to minor currency units

    -- Create PENDING record and capture the ID via RETURNING
    INSERT INTO PAYMENT_TRANSACTION (
        ENTITY_ID, AMOUNT, PAYMENT_REFERENCE,
        STATUS, GATEWAY, PROCESSED_BY,
        INITIATED_AT, APEX_SESSION_ID
    ) VALUES (
        p_entity_id, p_amount, v_local_ref,
        'PENDING', 'BML', p_performed_by,
        SYSTIMESTAMP,
        SYS_CONTEXT('APEX$SESSION', 'APP_SESSION')  -- store session now
    ) RETURNING ID INTO v_payment_id;

    COMMIT;  -- commit the PENDING record before calling the gateway

    -- Build and send the API request
    v_req := '{'
        || '"localId":"'     || v_local_ref       || '",'
        || '"amount":'       || TO_CHAR(v_amount_minor) || ','
        || '"currency":"MVR",'
        || '"redirectUrl":"' || v_return_url       || '"'
        || '}';

    BEGIN
        v_http_req := UTL_HTTP.BEGIN_REQUEST(
            url    => v_api_url || '/public/transactions',
            method => 'POST'
        );
        UTL_HTTP.SET_HEADER(v_http_req, 'Authorization',  v_api_key);
        UTL_HTTP.SET_HEADER(v_http_req, 'Content-Type',   'application/json');
        UTL_HTTP.SET_HEADER(v_http_req, 'Content-Length', TO_CHAR(LENGTHB(v_req)));
        UTL_HTTP.WRITE_TEXT(v_http_req, v_req);

        v_http_resp := UTL_HTTP.GET_RESPONSE(v_http_req);
        v_resp      := '';
        BEGIN
            LOOP
                UTL_HTTP.READ_RAW(v_http_resp, v_raw_chunk, 2000);
                v_resp := v_resp || UTL_RAW.CAST_TO_VARCHAR2(v_raw_chunk);
            END LOOP;
        EXCEPTION WHEN UTL_HTTP.END_OF_BODY THEN
            UTL_HTTP.END_RESPONSE(v_http_resp);
        END;

        -- Parse the gateway response
        APEX_JSON.PARSE(v_resp);
        v_gateway_txn_id := APEX_JSON.GET_VARCHAR2(p_path => 'id');
        v_pay_url        := APEX_JSON.GET_VARCHAR2(p_path => 'url');

    EXCEPTION WHEN OTHERS THEN
        BEGIN UTL_HTTP.END_RESPONSE(v_http_resp);
        EXCEPTION WHEN OTHERS THEN NULL;
        END;

        -- Log the error against the PENDING record
        v_err_msg := SUBSTR('Gateway API error: ' || SQLERRM
            || ' | Response: ' || SUBSTR(v_resp, 1, 500), 1, 4000);

        UPDATE PAYMENT_TRANSACTION
        SET GATEWAY_RAW_RESPONSE = v_err_msg
        WHERE ID = v_payment_id;
        COMMIT;

        RAISE_APPLICATION_ERROR(-20064,
            'Could not connect to payment gateway. Your reference is '
            || v_local_ref);
    END;

    -- Store the gateway's transaction ID
    UPDATE PAYMENT_TRANSACTION
    SET GATEWAY_TXN_ID = v_gateway_txn_id
    WHERE ID = v_payment_id;
    COMMIT;

    -- Return to the caller (your APEX page process)
    p_payment_id  := v_payment_id;
    p_local_ref   := v_local_ref;
    p_payment_url := v_pay_url;

EXCEPTION
    WHEN OTHERS THEN
        ROLLBACK;
        RAISE;
END INITIATE_PAYMENT;

Notice SYS_CONTEXT('APEX$SESSION', 'APP_SESSION') stored at insert time. The APEX session ID is captured at the moment the user initiates payment while they're still logged in. This is what we'll use later to redirect them back into the correct session.

On your APEX page, the process that calls this looks like:

DECLARE
    v_payment_id  NUMBER;
    v_local_ref   VARCHAR2(128);
    v_payment_url VARCHAR2(1000);
BEGIN
    PKG_PAYMENT.INITIATE_PAYMENT(
        p_entity_id    => :P_ENTITY_ID,
        p_amount       => :P_AMOUNT,
        p_performed_by => :APP_USER_ID,
        p_payment_id   => v_payment_id,
        p_local_ref    => v_local_ref,
        p_payment_url  => v_payment_url
    );

    -- Store the URL in session state, then redirect via a branch
    :P_PAYMENT_URL := v_payment_url;
END;

Then use an APEX branch with a redirect to &P_PAYMENT_URL. to send the user to the gateway.

Step 3: Processing the Callback

This is the core of what everyone gets wrong. When the payment is done, the gateway hits your ORDS handler URL. That request has no APEX session. It's a plain HTTP request landing on an ORDS endpoint. You have to validate it, update your database, and then figure out where to send the browser.

The PROCESS_CALLBACK Procedure

PROCEDURE PROCESS_CALLBACK (
    p_transaction_id IN  VARCHAR2,
    p_state          IN  VARCHAR2,
    p_signature      IN  VARCHAR2,
    p_local_id       IN  VARCHAR2,
    p_result_code    OUT NUMBER,
    p_result_msg     OUT VARCHAR2,
    p_session_id     OUT VARCHAR2
) AS
    v_secret_key VARCHAR2(512);
    v_payment_id NUMBER;
    v_status     PAYMENT_TRANSACTION.STATUS%TYPE;
    v_session_id PAYMENT_TRANSACTION.APEX_SESSION_ID%TYPE;
    v_raw_resp   VARCHAR2(4000);
    v_sig_valid  BOOLEAN;
    v_is_uat     VARCHAR2(1);
BEGIN
    -- Load config
    SELECT SECRET_KEY,
           CASE WHEN API_BASE_URL LIKE '%uat%' THEN 'Y' ELSE 'N' END
    INTO   v_secret_key, v_is_uat
    FROM   PAYMENT_GATEWAY_CONFIG
    WHERE  GATEWAY = 'BML';

    -- -------------------------------------------------------
    -- Step 1: Verify the signature
    -- -------------------------------------------------------
    IF v_is_uat = 'Y' AND (
        p_signature IS NULL OR p_signature = 'null'
    ) THEN
        v_sig_valid := TRUE;  -- UAT bypass for test environments
    ELSE
        v_sig_valid := VERIFY_SIGNATURE(
            p_transaction_id, p_state, p_signature, v_secret_key);
    END IF;

    IF NOT v_sig_valid THEN
        p_result_code := 1;
        p_result_msg  := 'Signature verification failed';

        -- Log the attempt — a sig failure in production is worth investigating
        INSERT INTO AUDIT_LOG (
            ENTITY_TYPE, ACTION, PERFORMED_AT, NOTES
        ) VALUES (
            'PAYMENT', 'CALLBACK_SIG_FAIL', SYSTIMESTAMP,
            'Sig fail | txnId:' || p_transaction_id
            || ' | state:' || p_state
        );
        COMMIT;
        RETURN;
    END IF;

    -- -------------------------------------------------------
    -- Step 2: Look up the payment record
    -- -------------------------------------------------------
    -- Primary lookup: your local reference (more reliable)
    -- Fallback: gateway transaction ID
    BEGIN
        IF p_local_id IS NOT NULL AND p_local_id != 'null' THEN
            BEGIN
                SELECT ID, STATUS, APEX_SESSION_ID
                INTO   v_payment_id, v_status, v_session_id
                FROM   PAYMENT_TRANSACTION
                WHERE  PAYMENT_REFERENCE = p_local_id;
            EXCEPTION
                WHEN NO_DATA_FOUND THEN
                    SELECT ID, STATUS, APEX_SESSION_ID
                    INTO   v_payment_id, v_status, v_session_id
                    FROM   PAYMENT_TRANSACTION
                    WHERE  GATEWAY_TXN_ID = p_transaction_id;
            END;
        ELSE
            SELECT ID, STATUS, APEX_SESSION_ID
            INTO   v_payment_id, v_status, v_session_id
            FROM   PAYMENT_TRANSACTION
            WHERE  GATEWAY_TXN_ID = p_transaction_id;
        END IF;
    EXCEPTION
        WHEN NO_DATA_FOUND THEN
            p_result_code := 2;
            p_result_msg  := 'Payment record not found';
            RETURN;
    END;

    -- Always return the session ID, even if we bail out below
    p_session_id := v_session_id;

    -- -------------------------------------------------------
    -- Step 3: Idempotency guard
    -- -------------------------------------------------------
    -- Gateways can and do fire callbacks more than once.
    -- If this record is already processed, return silently.
    IF v_status != 'PENDING' THEN
        p_result_code := 3;
        p_result_msg  := 'Already processed: ' || v_status;
        RETURN;
    END IF;

    -- -------------------------------------------------------
    -- Step 4: Apply the result
    -- -------------------------------------------------------
    v_raw_resp := 'transactionId=' || p_transaction_id
               || '&state='        || p_state
               || '&localId='      || NVL(p_local_id, 'NULL')
               || '&signature='    || NVL(p_signature, 'null');

    IF p_state = 'CONFIRMED' THEN
        -- Your business logic: credit the account, issue the policy,
        -- record the transaction, write the audit log.
        -- In my implementation (top-up flow):
        APPLY_TOPUP_SUCCESS(
            p_payment_id     => v_payment_id,
            p_gateway_txn_id => p_transaction_id,
            p_signature      => NVL(p_signature, 'null'),
            p_raw_response   => v_raw_resp
        );
        COMMIT;
        p_result_code := 0;
        p_result_msg  := 'OK';
    ELSE
        -- Any non-CONFIRMED state: mark as cancelled
        UPDATE PAYMENT_TRANSACTION
        SET STATUS               = 'CANCELLED',
            GATEWAY_TXN_ID       = p_transaction_id,
            GATEWAY_SIGNATURE    = p_signature,
            GATEWAY_RAW_RESPONSE = v_raw_resp,
            COMPLETED_AT         = SYSTIMESTAMP
        WHERE ID = v_payment_id;
        COMMIT;
        p_result_code := 0;
        p_result_msg  := 'CANCELLED';
    END IF;

EXCEPTION
    WHEN OTHERS THEN
        ROLLBACK;
        p_result_code := 4;
        p_result_msg  := SQLERRM;
END PROCESS_CALLBACK;

The "Apply Success" Procedure

This is where your actual business logic goes. The callback procedure doesn't care what the business logic is, it just calls this after validation passes. I'm showing my full top-up implementation so you can see what a complete version looks like:

PROCEDURE APPLY_TOPUP_SUCCESS (
    p_payment_id     IN NUMBER,
    p_gateway_txn_id IN VARCHAR2,
    p_signature      IN VARCHAR2,
    p_raw_response   IN VARCHAR2
) AS
    v_payment        PAYMENT_TRANSACTION%ROWTYPE;
    v_account_id     CREDIT_ACCOUNT.ID%TYPE;
    v_balance_before CREDIT_ACCOUNT.CURRENT_BALANCE%TYPE;
    v_balance_after  CREDIT_ACCOUNT.CURRENT_BALANCE%TYPE;
BEGIN
    -- Lock the payment record first
    SELECT * INTO v_payment
    FROM PAYMENT_TRANSACTION
    WHERE ID = p_payment_id
    FOR UPDATE;

    -- Guard: if somehow called twice, bail out
    IF v_payment.STATUS != 'PENDING' THEN
        RETURN;
    END IF;

    -- Lock and read the credit account
    SELECT ID, CURRENT_BALANCE INTO v_account_id, v_balance_before
    FROM CREDIT_ACCOUNT
    WHERE ID = v_payment.CREDIT_ACCOUNT_ID
    FOR UPDATE;

    v_balance_after := v_balance_before + v_payment.AMOUNT;

    -- Credit the account
    UPDATE CREDIT_ACCOUNT
    SET CURRENT_BALANCE = v_balance_after,
        UPDATED_AT      = SYSTIMESTAMP
    WHERE ID = v_account_id;

    -- Mark payment as completed
    UPDATE PAYMENT_TRANSACTION
    SET STATUS               = 'COMPLETED',
        GATEWAY_TXN_ID       = p_gateway_txn_id,
        GATEWAY_SIGNATURE    = p_signature,
        GATEWAY_RAW_RESPONSE = p_raw_response,
        COMPLETED_AT         = SYSTIMESTAMP
    WHERE ID = p_payment_id;

    -- Write the ledger entry
    INSERT INTO CREDIT_LEDGER (
        ACCOUNT_ID, TRANSACTION_TYPE, AMOUNT,
        BALANCE_BEFORE, BALANCE_AFTER,
        REFERENCE_TYPE, REFERENCE_ID,
        DESCRIPTION, TRANSACTION_DATE
    ) VALUES (
        v_account_id, 'TOPUP', v_payment.AMOUNT,
        v_balance_before, v_balance_after,
        'PAYMENT', p_payment_id,
        'Top-up via ' || v_payment.GATEWAY
        || ' | Ref: ' || v_payment.PAYMENT_REFERENCE
        || ' | GW Txn: ' || p_gateway_txn_id,
        SYSTIMESTAMP
    );

    -- Write the audit entry
    INSERT INTO AUDIT_LOG (
        ENTITY_TYPE, ENTITY_ID, ACTION,
        FIELD_NAME, OLD_VALUE, NEW_VALUE,
        PERFORMED_AT, NOTES
    ) VALUES (
        'CREDIT_ACCOUNT', v_account_id, 'TOPUP',
        'CURRENT_BALANCE',
        TO_CHAR(v_balance_before, 'FM999,999,990.00'),
        TO_CHAR(v_balance_after,  'FM999,999,990.00'),
        SYSTIMESTAMP,
        'Payment ID: ' || p_payment_id
        || ' | Amount: ' || TO_CHAR(v_payment.AMOUNT, 'FM999,999,990.00')
    );

END APPLY_TOPUP_SUCCESS;

Your version of this procedure should looks different based on what you're building. Policy issuance, order fulfillment, subscription activation or any business case you may have, the shape is the same though.

Step 4: The ORDS Handler - Where Everything Comes Together

This is the PL/SQL source you paste into your ORDS GET handler. It calls the package, then uses the result to construct and emit a redirect.

DECLARE
    v_result_code  NUMBER;
    v_result_msg   VARCHAR2(4000);
    v_session_id   VARCHAR2(128);
    v_redirect_url VARCHAR2(2000);
    v_base         VARCHAR2(500) := 'https://<your-ords-base-url>/ords/f';
    v_app_id       VARCHAR2(10)  := '<your_app_id>';
BEGIN
    PKG_PAYMENT.PROCESS_CALLBACK(
        p_transaction_id => :transactionId,
        p_state          => :state,
        p_signature      => :signature,
        p_local_id       => :localId,
        p_result_code    => v_result_code,
        p_result_msg     => v_result_msg,
        p_session_id     => v_session_id
    );

    -- Use the stored session ID — fall back to 0 if somehow null
    v_session_id := NVL(v_session_id, '0');

    IF v_result_code = 0 AND :state = 'CONFIRMED' THEN
        -- Success: redirect to confirmation page, restoring the original session
        v_redirect_url := v_base
            || '?p=' || v_app_id
            || ':' || '<your_success_page_number>'
            || ':' || v_session_id           -- restored session
            || '::NO::P_REF:' || :localId;
    ELSE
        -- Failure or cancellation: redirect to error/cancelled page
        v_redirect_url := v_base
            || '?p=' || v_app_id
            || ':' || '<your_failure_page_number>'
            || ':' || v_session_id
            || '::NO::P_REF:' || NVL(:localId, 'UNKNOWN')
            || ',P_ERR:' || SUBSTR(v_result_msg, 1, 200);
    END IF;

    HTP.p('<!DOCTYPE html>
           <html>
           <head>
               <meta http-equiv="refresh" content="0; url=' || v_redirect_url || '">
           </head>
           <body><p>Redirecting...</p></body>
           </html>');

EXCEPTION
    WHEN OTHERS THEN
        -- Even if everything explodes, send the user somewhere sensible
        HTP.p('<!DOCTYPE html>
               <html>
               <head>
                   <meta http-equiv="refresh" content="0; url='
                   || v_base || '?p=' || v_app_id
                   || ':<your_failure_page_number>:0::NO::P_REF:UNKNOWN,P_ERR:HANDLER_ERROR">
               </head>
               <body><p>Redirecting...</p></body>
               </html>');
END;

A few things to unpack here.

Why HTP.p instead of OWA_UTIL.REDIRECT_URL

You might expect to use OWA_UTIL.REDIRECT_URL to issue an HTTP 302 redirect. On a standard ORDS setup it works fine. On Oracle Autonomous Database (ADB), it doesn't. The redirect header gets dropped silently, no error, no warning, just nothing happens.

The fix is to emit an HTML page with a meta http-equiv="refresh" tag instead. Zero seconds means the browser redirects immediately. It's not the cleanest HTTP pattern, but it's the one that actually works reliably on ADB.

The Session Segment in the APEX URL

The APEX URL format is:

f?p=<app_id>:<page>:<session>:<request>:<debug>:<clear_cache>:<items>:<values>

The session segmentat position 3 is what APEX uses to tie the request to an existing session. When you store SYS_CONTEXT('APEX$SESSION', 'APP_SESSION') at initiation time and put it back in this segment at redirect time, APEX reconnects the user to their original session. Their authentication context, their application items, their navigation state is all of it is still there.

If you pass 0 here, APEX creates a new anonymous session. The user arrives on the page without any session context which is fine for a public-facing page, and completely broken for anything that requires authentication.

What Happens If the Session Has Expired

APEX sessions expire based on your session timeout setting. If the user took a very long time to complete payment, or the gateway took a long time to call back, the original session may be gone.

APEX handles this and it will redirect the user to your login page. For most applications that's acceptable. If your authentication is SSO or you need a smoother experience, you can set your success/failure pages to have public access and handle re-authentication there.

The EXCEPTION Block

The outer EXCEPTION WHEN OTHERS is not optional. If your package raises an unhandled exception like a DB connection issue, an unexpected null, anything without the exception block, ORDS returns a raw error response to the browser. The user sees a JSON error blob or a blank page. With the block, they at least land on your failure page and can try again or contact support.

Step 5: Reconciliation (For When Callbacks Don't Arrive)

Callbacks fail. Networks hiccup. Gateways have outages. If a callback never arrives, your record stays PENDING forever and the user's balance never gets credited.

The fix is a reconciliation procedure that polls the gateway's status API for any PENDING records older than a threshold.

PROCEDURE RECONCILE_PAYMENT (
    p_payment_id   IN  NUMBER,
    p_performed_by IN  NUMBER,
    p_result_code  OUT NUMBER,
    p_result_msg   OUT VARCHAR2
) AS
    v_payment    PAYMENT_TRANSACTION%ROWTYPE;
    v_api_key    VARCHAR2(512);
    v_api_url    VARCHAR2(500);
    v_secret_key VARCHAR2(512);
    v_http_req   UTL_HTTP.REQ;
    v_http_resp  UTL_HTTP.RESP;
    v_buffer     VARCHAR2(32767);
    v_resp       VARCHAR2(32767);
    v_state      VARCHAR2(64);
    v_signature  VARCHAR2(512);
BEGIN
    SELECT * INTO v_payment
    FROM PAYMENT_TRANSACTION
    WHERE ID = p_payment_id;

    IF v_payment.STATUS != 'PENDING' THEN
        p_result_code := 3;
        p_result_msg  := 'Status is already: ' || v_payment.STATUS;
        RETURN;
    END IF;

    IF v_payment.GATEWAY_TXN_ID IS NULL THEN
        p_result_code := 2;
        p_result_msg  := 'No gateway transaction ID. Cannot reconcile.';
        RETURN;
    END IF;

    SELECT API_KEY, API_BASE_URL, SECRET_KEY
    INTO   v_api_key, v_api_url, v_secret_key
    FROM   PAYMENT_GATEWAY_CONFIG
    WHERE  GATEWAY = 'BML';

    BEGIN
        v_http_req := UTL_HTTP.BEGIN_REQUEST(
            url    => v_api_url || '/public/transactions/' || v_payment.GATEWAY_TXN_ID,
            method => 'GET'
        );
        UTL_HTTP.SET_HEADER(v_http_req, 'Authorization', v_api_key);
        UTL_HTTP.SET_HEADER(v_http_req, 'Accept', 'application/json');

        v_http_resp := UTL_HTTP.GET_RESPONSE(v_http_req);
        v_resp      := '';
        BEGIN
            LOOP
                UTL_HTTP.READ_TEXT(v_http_resp, v_buffer, 32767);
                v_resp := v_resp || v_buffer;
            END LOOP;
        EXCEPTION WHEN UTL_HTTP.END_OF_BODY THEN
            UTL_HTTP.END_RESPONSE(v_http_resp);
        END;

        APEX_JSON.PARSE(v_resp);
        v_state     := APEX_JSON.GET_VARCHAR2(p_path => 'state');
        v_signature := APEX_JSON.GET_VARCHAR2(p_path => 'signature');

    EXCEPTION WHEN OTHERS THEN
        BEGIN UTL_HTTP.END_RESPONSE(v_http_resp);
        EXCEPTION WHEN OTHERS THEN NULL;
        END;
        p_result_code := 4;
        p_result_msg  := 'Gateway status API error: ' || SQLERRM;
        RETURN;
    END;

    IF v_state = 'CONFIRMED' THEN
        APPLY_TOPUP_SUCCESS(
            p_payment_id     => p_payment_id,
            p_gateway_txn_id => v_payment.GATEWAY_TXN_ID,
            p_signature      => v_signature,
            p_raw_response   => 'RECONCILED:' || SUBSTR(v_resp, 1, 3800)
        );
        INSERT INTO AUDIT_LOG (
            ENTITY_TYPE, ENTITY_ID, ACTION,
            PERFORMED_BY, PERFORMED_AT, NOTES
        ) VALUES (
            'PAYMENT', p_payment_id, 'MANUAL_RECONCILE',
            p_performed_by, SYSTIMESTAMP,
            'Reconciled via gateway status API. State: ' || v_state
        );
        COMMIT;
        p_result_code := 0;
        p_result_msg  := 'CONFIRMED — credited';

    ELSIF v_state IN ('CANCELLED', 'REFUNDED') THEN
        UPDATE PAYMENT_TRANSACTION
        SET STATUS       = 'CANCELLED',
            COMPLETED_AT = SYSTIMESTAMP
        WHERE ID = p_payment_id;
        INSERT INTO AUDIT_LOG (
            ENTITY_TYPE, ENTITY_ID, ACTION,
            PERFORMED_BY, PERFORMED_AT, NOTES
        ) VALUES (
            'PAYMENT', p_payment_id, 'MANUAL_RECONCILE',
            p_performed_by, SYSTIMESTAMP,
            'Reconciled. State: ' || v_state
        );
        COMMIT;
        p_result_code := 0;
        p_result_msg  := v_state;
    ELSE
        p_result_code := 0;
        p_result_msg  := 'Still PENDING at gateway (state: ' || v_state || ')';
    END IF;

EXCEPTION WHEN OTHERS THEN
    ROLLBACK;
    p_result_code := 4;
    p_result_msg  := SQLERRM;
END RECONCILE_PAYMENT;

Wire this up to a scheduled DBMS_SCHEDULER job that runs every 30 minutes, targeting any PENDING records older than 30 minutes with a gateway transaction ID:

BEGIN
    FOR r IN (
        SELECT ID FROM PAYMENT_TRANSACTION
        WHERE  STATUS       = 'PENDING'
        AND    INITIATED_AT < SYSTIMESTAMP - NUMTODSINTERVAL(30, 'MINUTE')
        AND    GATEWAY_TXN_ID IS NOT NULL
    ) LOOP
        BEGIN
            RECONCILE_PAYMENT(
                p_payment_id   => r.ID,
                p_performed_by => NULL,
                p_result_code  => v_result_code,
                p_result_msg   => v_result_msg
            );
        EXCEPTION WHEN OTHERS THEN
            NULL;  -- continue to the next record
        END;
    END LOOP;
END;

Things That Will Save You Time

Store everything raw. Log the raw response from the gateway against every payment record. When something goes wrong at 2am, you want the raw payload sitting in a column you can query. not a formatted message that lost half the detail.

Dual lookup is not optional. Some gateways send localId reliably, others drop it. Some send the gateway transaction ID first, others send localId first. Build the fallback lookup (local ref → gateway txn ID) from day one. You will need it.

Test your error page. Most developers test the happy path. Deliberately trigger a failed payment in UAT and make sure the user actually lands somewhere useful. A blank page on payment failure is almost as bad as a missing confirmation.

Your callback URL needs to be publicly accessible. If your ORDS instance is behind a firewall or VPN, the gateway can't reach it. Check this before you go to production test the URL with a tool like curl or Postman from outside your network.

Signature verification blocks replay attacks. An attacker who intercepts a callback URL can replay it with a modified state like changing CANCELLED to CONFIRMED, for example. The HMAC signature verification is what stops this. It's not optional for production.

Wrapping Up

The payment initiation is five lines and a redirect. The callback is where you earn your money. validation, session restoration, error handling, reconciliation. None of that appears in the tutorials.

The ORDS handler pattern gives you a controlled chokepoint: every callback from the gateway flows through your PL/SQL, gets validated, hits the database, and only then produces a redirect. The user's browser never sees the payment result directly! your code does, first.

If you're implementing this on ADB, remember: OWA_UTIL.REDIRECT_URL doesn't work (as per my understanding on the time of writing this) use HTP.p with a meta-refresh. If you're on a standard ORDS deployment, either approach works.

The reconciliation job is your safety net for when the callback simply never arrives. It won't happen often, but when it does, your users will not be the ones telling you their payment went through but their account didn't update.

Build the callback handling right once. It's not the exciting part of the feature, but it's the part that determines whether users trust your application with their money.

What exactly is a "program" and what does it include?

Thu, 16 Oct 2025 20:24:57 +0000

In this tutorial, I wanna talk about "program" and "process" terms that are fundamental elements in computer-science. This two terms generally are used exchangeably. But in technically, both are so different. Let's begin with explaining these terms and then deeply see the what it includes:

A program is a file containing a range of information that describes how to construct a "process" at run time [1].
A process is an instance of an executing program [1].

These are the formal definations. If I try to express with my words:

A program (or binary) is a file that includes the machine code + metadata + debug information (if the program compiled with -g flag) and process is a abstraction point that kernel creates and then allocates hardware resources like RAM.

First thing that you should know is the program format. In recently, there are two type of program formats that the compilers generate:

ELF (Executable and Linkable Format)
PE (Portable Executable)

ELF Format

ELF is the standard format for UNIX/Linux systems and PE for Windows. I'm currently on Ubuntu 24.10 (x86_64) so that I will explain and use ELF format. As you guest, I don't know really PE format. But there is a good reference handbook that you can look at. It's "Practical Binary Analysis" written by Dennis Andriesse.

After explained the program formats, right now, let's look at the inside of the program:

In general, any program includes these:

Executable header
Program headers
Sections
Section headers

Every ELF file starts with an executable header, which is just a structured series of bytes telling you that it's and ELF file, what kind of ELF file it is, and where in the files to find all the other contents [2].

You can exactly see the content of this header with readelf command:

$ readelf -h ./copy
ELF Header:
  Magic:   7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00 
  Class:                             ELF64
  Data:                              2's complement, little endian
  Version:                           1 (current)
  OS/ABI:                            UNIX - System V
  ABI Version:                       0
  Type:                              DYN (Position-Independent Executable file)
  Machine:                           Advanced Micro Devices X86-64
  Version:                           0x1
  Entry point address:               0x1160
  Start of program headers:          64 (bytes into file)
  Start of section headers:          17496 (bytes into file)
  Flags:                             0x0
  Size of this header:               64 (bytes)
  Size of program headers:           56 (bytes)
  Number of program headers:         13
  Size of section headers:           64 (bytes)
  Number of section headers:         37
  Section header string table index: 36

In there, first four digits (7f 45) of Magic series define the program format. You will see the probably different series if you are on Windows. Other properties is the self-explaining.

The code and data in an ELF program are logically divided into sections. Each section includes a specific part of your source code. And the sections in the binary are contained in the section header table. Some sections are used to execute the machine instructions and some for other information (like symbol table used by debugger). Let's look at the section headers:

$ readelf --sections --wide ./copy
There are 37 section headers, starting at offset 0x4458:

Section Headers:
  [Nr] Name              Type            Address          Off    Size   ES Flg Lk Inf Al
  [ 0]                   NULL            0000000000000000 000000 000000 00      0   0  0
  [ 1] .interp           PROGBITS        0000000000000318 000318 00001c 00   A  0   0  1
  [ 2] .note.gnu.property NOTE            0000000000000338 000338 000030 00   A  0   0  8
  [ 3] .note.gnu.build-id NOTE            0000000000000368 000368 000024 00   A  0   0  4
  [ 4] .note.ABI-tag     NOTE            000000000000038c 00038c 000020 00   A  0   0  4
  [ 5] .gnu.hash         GNU_HASH        00000000000003b0 0003b0 000028 00   A  6   0  8
  [ 6] .dynsym           DYNSYM          00000000000003d8 0003d8 000180 18   A  7   1  8
  [ 7] .dynstr           STRTAB          0000000000000558 000558 0000d3 00   A  0   0  1
  [ 8] .gnu.version      VERSYM          000000000000062c 00062c 000020 02   A  6   0  2
  [ 9] .gnu.version_r    VERNEED         0000000000000650 000650 000030 00   A  7   1  8
  [10] .rela.dyn         RELA            0000000000000680 000680 0000d8 18   A  6   0  8
  [11] .rela.plt         RELA            0000000000000758 000758 0000d8 18  AI  6  24  8
  [12] .init             PROGBITS        0000000000001000 001000 00001b 00  AX  0   0  4
  [13] .plt              PROGBITS        0000000000001020 001020 0000a0 10  AX  0   0 16
  [14] .plt.got          PROGBITS        00000000000010c0 0010c0 000010 10  AX  0   0 16
  [15] .plt.sec          PROGBITS        00000000000010d0 0010d0 000090 10  AX  0   0 16
  [16] .text             PROGBITS        0000000000001160 001160 00043a 00  AX  0   0 16
  [17] .fini             PROGBITS        000000000000159c 00159c 00000d 00  AX  0   0  4
  [18] .rodata           PROGBITS        0000000000002000 002000 000040 00   A  0   0  4
  [19] .eh_frame_hdr     PROGBITS        0000000000002040 002040 000034 00   A  0   0  4
  [20] .eh_frame         PROGBITS        0000000000002078 002078 0000a8 00   A  0   0  8
  [21] .init_array       INIT_ARRAY      0000000000003d78 002d78 000008 08  WA  0   0  8
  [22] .fini_array       FINI_ARRAY      0000000000003d80 002d80 000008 08  WA  0   0  8
  [23] .dynamic          DYNAMIC         0000000000003d88 002d88 0001f0 10  WA  7   0  8
  [24] .got              PROGBITS        0000000000003f78 002f78 000088 08  WA  0   0  8
  [25] .data             PROGBITS        0000000000004000 003000 000010 00  WA  0   0  8
  [26] .bss              NOBITS          0000000000004020 003010 000010 00  WA  0   0 32
  [27] .comment          PROGBITS        0000000000000000 003010 00002b 01  MS  0   0  1
  [28] .debug_aranges    PROGBITS        0000000000000000 00303b 000030 00      0   0  1
  [29] .debug_info       PROGBITS        0000000000000000 00306b 000472 00      0   0  1
  [30] .debug_abbrev     PROGBITS        0000000000000000 0034dd 000184 00      0   0  1
  [31] .debug_line       PROGBITS        0000000000000000 003661 00017e 00      0   0  1
  [32] .debug_str        PROGBITS        0000000000000000 0037df 00031a 01  MS  0   0  1
  [33] .debug_line_str   PROGBITS        0000000000000000 003af9 00012f 01  MS  0   0  1
  [34] .symtab           SYMTAB          0000000000000000 003c28 000438 18     35  18  8
  [35] .strtab           STRTAB          0000000000000000 004060 00028c 00      0   0  1
  [36] .shstrtab         STRTAB          0000000000000000 0042ec 00016a 00      0   0  1
Key to Flags:
  W (write), A (alloc), X (execute), M (merge), S (strings), I (info),
  L (link order), O (extra OS processing required), G (group), T (TLS),
  C (compressed), x (unknown), o (OS specific), E (exclude),
  D (mbind), l (large), p (processor specific)

The main topic of this tutorial is the sections. So I wanna explain in deeply each one:

.init and .fini: The machine code in these sections are used before/after the main() function in program. Don't forget that we're not writing this sections. Compiler itself creates these to handle low-level (or hardware-specific) works. I don't know actually what both of them do!
.text: It is the main area where we focus on binary analysis and reverse-engineering stuffs and includes the your code in machine instruction representation. If you look at there, you see that it has voluminous area and thousands of lines of machine code even if it is small program.
.bss, .data and .rodata: These sections are writable and used to hold various variable in source code. .bss includes the static and global uninitialized and .data includes the static and global initialized variables. Also .rodata consists of variables defined with const keyword in code.
.dynamic: This is the "road map" for the kernel and dynamic linker when loading and setting up an ELF binary for executions.
.init_array and .fini_array: These contains an array of pointers to functions to use as constructors/destructors. You maybe know that how to create constructor and destructor using compiler specific-tool, line one __attribute__((constructor)) void run_before_main(void);.
.shstrtab, .symtab, .strtab, .dynsym and .dynstr: The .shstrtab section is simply an array of NULL-terminated strings that contain the names of all the sections in binary. The .symtab contains a symbol table and .strtab contains the symbolic names. The .dynsym and .dynstr are analogous to .symtab and .strtab, except that they contain symbols and strings needed for dynamic linking rather than static linking.
.debug_: These sections are used primarily by debugger (GDB) so that it has not include and machine code but just metadata about program that debugger can use later. If you don't compile the program with -g option, these sections will not there.

Below is a part of .text section:

$ objdump -j .text -d ./copy

./copy:     file format elf64-x86-64

(...)

Disassembly of section .text:

0000000000001249 <main>:
    1249:f3 0f 1e fa          endbr64
    124d:55                   push   %rbp
    124e:48 89 e5             mov    %rsp,%rbp
    1251:48 81 ec 40 04 00 00 sub    $0x440,%rsp
    1258:89 bd cc fb ff ff    mov    %edi,-0x434(%rbp)
    125e:48 89 b5 c0 fb ff ff mov    %rsi,-0x440(%rbp)
    1265:64 48 8b 04 25 28 00 mov    %fs:0x28,%rax
    126c:00 00 
    126e:48 89 45 f8          mov    %rax,-0x8(%rbp)
    1272:31 c0                xor    %eax,%eax
    1274:83 bd cc fb ff ff 03 cmpl   $0x3,-0x434(%rbp)
    127b:75 24                jne    12a1 <main+0x58>
    127d:48 8b 85 c0 fb ff ff mov    -0x440(%rbp),%rax
    1284:48 83 c0 08          add    $0x8,%rax
    1288:48 8b 00             mov    (%rax),%rax
    128b:48 8d 15 72 0d 00 00 lea    0xd72(%rip),%rdx        # 2004 <_IO_stdin_used+0x4>

(...)

In here, we see the three columns that show the machine instructions of your program. At left side, you see the addresses of machine instructions. When running the program, stack pointer tracks these addresses. At center, you see the actual machine instructions corresponding to your code. Program counter register tracks this machine instructions. At right side, you see the assembly-level representations. When dealing with reverse-engineering, we inspect these to understand what program does.

Virtual Memory Layout

After discussed the ELF program format, right now, I will explain the virtual memory layout of a process (running program instance). When you run the program, kernel creates a memory layout as below:

I've explained the .text, .data, .bss, .rodata sections previously. Apart from these, you see the stack and heap areas.

Both are the memory areas that kernel uses to execute the machine instructions. Stack area has LIFO (Last-In First-Out) model. When executing the program, kernel pushs/pops the instructions in here. So it grows up to lower address space. Heap area is completely different! It has FIFO (First-In First-Out) model. Kernel uses this memory space for dynamic allocation with malloc()/free() function family. And it grows up to upper address space. The heap address border is claimed by brk() function.

Until here, I wanna give you a general overview about programs and processes. If you want to dive in more, you can check and look at the below references.

[1]. Kerrisk M., The Linux Programming Interface, no starch press, San Francisco, page 113.

[2]. Andriesse D., Practical Binary Analysis, no starch press, San Francisco, page 33.

Understanding embedded flashing and debugging

Tue, 14 Oct 2025 11:07:59 +0000

In embedded world, using IDE (like Keil and STM32Cube IDE) is heavily the preferred choice because of simplifying the all processes. But I think that we, embedded software developers, must learn and know what is going on under the hood!

In this articles, I'll show the all the steps of flashing and debugging a firmware written for stm32f446x series microcontroller. Firstly, I'll introduce the flashing a firmware into microcontroller and then give you how to debug it.

Before giving details, let's talk about what we need:

A Linux terminal (Ubuntu terminal)
A firmware (ended with .elf or .bin)
ARM GCC toolchain (arm-none-eabi- commands)
Open On-Chip Debugger (openocd command)
ST-Link hardware

Please get these before going further according to your system. I'm current on Ubuntu 22.04.

When talking about a embedded firmware, we have two program formats that we use in general. These are .bin and .elf formats. Ended with .bin firmware just contains the pure machine code and it has not debug information, program sections or other stuffs. It is used just for flashing, not for debugging. Beside that .elf firmware contains both pure machine code and other stuffs so that we can flash and debug it.

Please use the firmware ended with .elf

Another important point is the connection type between your host and microcontroller. For ARM Cortex, we have a few options:

openocd
dfu-util
st-flash

I have ST-Link connection so that openocd is preferred way in our case. If you have USB connection, you can use dfu-util. Most of the STM32 microcontrollers support DFU (Device Firmware Update) mode. Don't forget that you can just flash the firmware over USB, not for debugging.

All right, let's dive into flashing.

First of all, open a terminal and type this command:

$ openocd -f interface/stlink.cfg -f target/stm32f4x.cfg

In here, we specified two files. These are interface (which connection type that I use?) and target (what type of microcontroller that I wanna flash and debug). You can see all interface and target files from openocd folder that you've installed.

After typed this command, you get:

Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 2000 kHz
Info : STLINK V2J33M25 (API v2) VID:PID 0483:374B
Info : Target voltage: 3.228402
Info : [stm32f4x.cpu] Cortex-M4 r0p1 processor detected
Info : [stm32f4x.cpu] target has 6 breakpoints, 4 watchpoints
Info : starting gdb server for stm32f4x.cpu on 3333
Info : Listening on port 3333 for gdb connections
[stm32f4x.cpu] halted due to breakpoint, current mode: Thread 
xPSR: 0x61000000 pc: 0x08000530 msp: 0x2001ffd8

You can think that openocd is a bridge between your host and microcontroller. To flash and debug the firmware, we'll use arm-none-eabi-gdb command. It is actually a debugger for ARM Cortex. But we can flash too.

Right now, open a new terminal and type:

$ arm-none-eabi-gdb firmware.elf

After that you are in gdb session and we will make all operations from here. The first thing that we wanna is to connect to somewhere.

From openocd output, we see the "Info : Listening on port 3333 for gdb connections" line. As I said before, openocd is a bridge and created a port 3333 for gdb that we will connect there from gdb session. Let's do it:

(gdb) target remote localhost:3333

After that, you see the first line of main() from the firmware. It's time to flash the firmware and then inspect it:

(gdb) monitor reset halt
(gdb) load

Important note is that before flashing the firmware, resetting the microcontroller and halting the current execution flow is good practice. After these commands, you should see:

Loading section .isr_vector, size 0x1c4 lma 0x8000000
Loading section .text, size 0x1080 lma 0x80001d0
Loading section .rodata, size 0x10 lma 0x8001250
Loading section .init_array, size 0x4 lma 0x8001260
Loading section .fini_array, size 0x4 lma 0x8001264
Loading section .data, size 0x10 lma 0x8001268
Start address 0x80011d0, load size 4716
Transfer rate: 9 KB/sec, 786 bytes/write.

Congrats! You finally flashed the firmware.

In here, you see that many sections written to base address of flash memory (0x08000000). I will not make end-to-end binary analysis but let's explain basically what these sections are:

.isr_vector --> IRS (Interrupt Service Routine) handlers
.text --> machine code that I've written
.rodata --> read-only variable declarations (with const in C)
.init_array, .fini_array --> hardware-level machine code that I've not written
.data --> static or global initialized variables (if exists)
.bss --> static or global uninitialized variables (if exists)

These are the main blocks/sections in any sort of program. You can inspect these in deeply with arm-none-eabi-objdump and arm-none-eabi-readelf commands. But for now, let's go with debugging.

The main purpose of debugging is to track the execution of firmware and, sometimes, extract the any possible information about firmware.

You can look at these information over info commands. Some examples are below:

(gdb) info files
(gdb) info registers
(gdb) info functions
(gdb) info variables
(gdb) info locals
(gdb) info frame
(gdb) info breakpoints
(gdb) info line *addr

With list command, you can see the part of source file from gdb session:

(gdb) list 1
1/**
2 * FreeRTOS 101 - Complete Introductory Program
3 */
4
5#include "main.h"
6
7void TaskLED(void *params)
8{
9while (1) {
10HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_0);

After gaining a overview about the firmware, next step is to track the execution flow. To control the execution flow, we have break, continue, step, next, finish commands:

(gdb) break main                # put the breakpoint at begin of main() function
(gdb) break *0x80001d0   # put the breakpoint at 0x080001d0 address
(gdb) delete                         # delete all breakpoints
(gdb) continue                    # continue the execution flow until any breakpoint
(gdb) next                            # go to next instruction (over functions)
(gdb) step                            # go to next instruction (into functions)
(gdb) finish                          # finish the execution flow

When dealing with embedded systems, we probably want to look at (and set) core and peripheral registers or variables so that we gain the low-level insights about it. For this we have print, x/, set commands. We use print for displaying any variable defined in source code, x/ for displaying registers, set for setting register bits:

(gdb) print initLED                 # display the GPIO initialization structure
(gdb) x/x 0x40023830          # look at RCC AHB1 peripheral clock enable register in hex
(gdb) x/d 0x40023830          # look at RCC AHB1 peripheral clock enable register in decimal
(gdb) x/s 0x40023830          # look at RCC AHB1 peripheral clock enable register in string
(gdb) x/10wx 0x40023830   # look at RCC AHB1 peripheral clock enable with next 9 word (32-bit) registers
(gdb) set {int32_t}0x40023830 |= (1 << 2)   # set the third bit of RCC AHB1 peripheral clock enable register

Well done! This is 80% of debugging.

Until now, I've tried to give you general workflow and commands about flashing and debugging the firmware. But as you guest, this is deep and complex area so that it deserves many articles. For now, I think that it is enough!

The Divooka Way - Part 1: Philosophically, How Exactly is Divooka Different and Useful

Wed, 09 Jul 2025 20:28:58 +0000

Full title: The Divooka Way — Part 1: Philosophically, How Exactly is Divooka Different and Useful Compared to Plain Good Code API
Tags: Visual Programming, Developer Tools, API Design, Software Architecture, Programming Paradigms, NVI, No-Code / Low-Code, Programming Philosophy, Tool Economy
Target Audience: Software Architects, Engine and Tool Developers, Programming Educators and Curriculum Designers, Low-Code/No-Code Platform Researchers, Senior Developers interested in alternative programming models, Developers interested in visual alternatives to traditional code*

Abstract

Traditional programming uses text to represent program logic. Existing visual design platforms offer varying levels of programmability but generally focus on building specific kinds of applications. From a production-use perspective, Divooka represents a significant step forward in how users build and interact with software - by combining tool-building, data handling, and program logic under a single, coherent interface. This unified approach aims to deliver a substantial productivity boost.

Overview

If we already have a really good library - just as we have high-quality commercial software - does it still matter what language or environment we use?

In theory, it shouldn't. In practice, it absolutely does.

Pretty much everything imaginable already exists for C++, often under GNU licenses. But that doesn't mean a Python, C#, or Java developer can easily access or use those resources. Even when libraries are available for a target language, usage may not be straightforward. Licensing, API design, and documentation all come into play.

Still, let's imagine we have a well-written, freely accessible, multi-language-bound, well-documented, and easy-to-use library. Does it then matter how we use it?

That leads us to the core question:

If we already have a really good API, why not just use it in C#, Python, C++, Lua, or Pure?

The Proof of Concept

To explore this, we can approach the question from three distinct perspectives:

The end user
The program designer
Everyday tool development and sharing

From the end user's perspective, assuming the final deliverable is a polished CLI or GUI tool, it typically doesn't matter what language was used - as long as the interface is well-designed. Case closed.

From the program designer's perspective, building anything sophisticated involves significant "dry" work - debugging, iteration, architectural decisions. Productivity depends largely on the quality of the debugger and IDE, and again, it's not strictly tied to the programming language.

But from the perspective of everyday tool use, the question becomes more subtle. What do we mean by "everyday tools"? Broadly speaking, we mean:

Tools built quickly to solve practical problems within days
Tools that are easy to share and use by others
Tools that are easy to iterate, improve, refactor, and eventually package as full software
Tools that are maintainable - so that months later, we can return and still understand what we were doing, without extensive documentation effort

To solve (1), you need extensive libraries.
To solve (2), you need solid dependency and packaging mechanisms.
To solve (3), you need simple syntax and easy refactoring.
To solve (4), you need expressive, self-documenting code - or better yet, self-explanatory program design.

It's in this third category - everyday tools - that Divooka stands out. The features baked into Divooka's graph editor enable rapid development without sacrificing performance or scalability. The editor itself proves how smoothly things can run with minimal setup: just open a graph document, and it works.

The NVI

In Divooka, the primary mode of interaction is the Node Visual Interface (NVI) - distinct from both CLI and GUI paradigms.

Each node represents a functional unit, and the connections represent program or data flow. Unlike CLI, NVI offers "autocomplete" visually - everything is made explicit through connection and layout. Unlike a GUI, an NVI is composed entirely of nodes and avoids complex syntax structures.

At the base is a node canvas, and programs are built using what we call node-driven design - a pattern that breaks software into node blocks, each representing a compositional or procedural component.

The main disadvantage of NVI compared to text-based programming is space inefficiency: nodes occupy screen real estate, reducing information density. But this is offset by improved readability: the visual layout shows the exact dependencies between functional units - something much harder to grasp in linear text code.

NVI becomes more powerful when it supports:

Subgraphs – Logical groups of nodes encapsulated into single blocks. This is more compact than plain functions or classes and more intuitive than managing multiple files.
Extensible node visuals – Nodes can be customized for specific data. For example, a Table node can offer compact entry for 2D data, reducing friction.

The Scripting Interface

At its core, the NVI exposes functionality in two ways:

Nodes represent standalone functional units in a Divooka document.
A framework parses the interconnected nodes and derives behavior from the graph structure.

The key is interface availability - file operations, media I/O, math routines, etc.

The first use case is covered well by scripting languages like Python, Lua, or Jupyter.
The second - interpreting a structured node graph into dynamic program behavior - is where traditional languages fall short, often requiring large, specialized frameworks (e.g., Streamlit for Python).

With Divooka, the same graphical program often needs no changes at all. A simple toggle in the host environment can completely redefine how the program behaves.

Frameworks like Glaze, Novella, Ol'ista, Slide Present, and App Builder (all part of Divooka Explore except App Builder) rely heavily on metadata - information not defined on the graph, but embedded in the document and interpreted by the host system.

This separation - code in the graph, behavior defined by metadata - creates a powerful, data-driven model that enables reuse, variation, and flexibility.

On the Matter of Libraries

Not all useful features are readily available via libraries. And even when they are, compatibility issues, licenses, platform differences, and interoperability challenges often make reuse hard or impossible.

At Methodox, we actively author and maintain a curated library set - toolboxes optimized for Divooka. This represents a major investment, ensuring that as Divooka grows, users have an expanding, well-integrated set of native components tailored for node-driven environments.

Summary

From a scripting standpoint, Divooka may appear unremarkable: libraries are still authored in native code, and Divooka simply provides an interface layer.

But methodologically, Divooka offers a profound shift in how we build and interact with programs. It's as different as using a natural-language model to co-write your software.

Divooka is a high-level, GUI-native, NVI-first programming system. Our belief is that this new format can significantly enhance productivity, readability, and maintainability by making programs smaller, clearer, less error-prone, and more intuitive.