Search Results lock_document

Overview

PO_DOCUMENT_LOCK_GRP is a PL/SQL group package owned by the APPS schema in Oracle E-Business Suite, classified under the ETRM (E-Business Suite Technical Reference Manual) as an API of type GRP (Group). Its business function is to acquire document-level locks across the full hierarchy of a Purchasing document — the header together with all associated lines, shipments, and distributions. The package is defined with AUTHID CURRENT_USER, meaning its SQL executes with the privileges of the invoking schema rather than the definer, which is consistent with standard Oracle EBS API security practice for application-level packages.

The locking behavior exists to protect the referential integrity of a Purchasing document while concurrent operations attempt to modify it. By locking the header and every subordinate entity in a single, controlled call, the package prevents partial updates and race conditions that would otherwise arise when multiple forms, concurrent programs, or interface processes touch the same document simultaneously. The header comment block carries the identifier POXGLOKS.pls 120.0.12020000.2, with a final revision dated 2013/02/10, reflecting maintenance aligned with the 12.1.1 and 12.2.2 release streams.

Key Procedures and Functions

The ETRM metadata documents a single procedure name, LOCK_DOCUMENT, exposed through two distinct overloaded signatures. No other procedures or functions are documented for this package.

• LOCK_DOCUMENT (single-document overload) — The original lock entry point. It accepts a document type and document identifier along with the standard API parameters (p_api_version, p_init_msg_list, and the x_return_status output). Its purpose is to lock one identified document, spanning the header and all applicable lines, shipments, and distributions.
• LOCK_DOCUMENT (set-based overload) — Introduced under Bug 14254141 ("Cancel Refactoring Project"). This variant operates against a set of documents rather than a single one. The documents to be locked are staged in the session global temporary table PO_SESSION_GT, keyed by po_sesiongt_key, and the caller additionally supplies user and login identifiers for audit attribution alongside the standard API parameters. This design allows bulk locking of multiple documents within one session context.

The package therefore presents a single logical capability — locking a Purchasing document and its dependent entities — with both single-record and set-based invocation modes.

Tables Accessed

The package references its tables through APPS synonyms. The core Purchasing document hierarchy is represented by PO_HEADERS, PO_LINES, PO_LINE_LOCATIONS (shipments), and PO_DISTRIBUTIONS, each of which participates in the lock scope described in the package comments. PO_RELEASES covers the release/blanket agreement dimension of the document structure. Requisition-side entities are also referenced — PO_REQUISITION_HEADERS, PO_REQUISITION_LINES, and PO_REQ_DISTRIBUTIONS — indicating that the locking logic extends to requisition documents or their downstream purchasing artifacts. PO_SESSION_GT serves as the session-scoped staging table for the set-based overload, holding the document identifiers to be locked under the supplied key. PO_ONLINE_REPORT_TEXT is referenced for online report output, consistent with the p_online_report_id parameter present in the set-based signature.

Usage Notes

PO_DOCUMENT_LOCK_GRP is an internal group API rather than a standalone user-facing entry point. It is typically invoked in three contexts: from Oracle Purchasing forms when a user opens or begins editing a document and the form must secure the document against concurrent modification; from concurrent programs that process documents in batch and require deterministic lock acquisition; and from custom or extension code that performs programmatic updates to Purchasing documents and must respect the same locking contract. The ETRM records that five other packages reference this group, confirming its role as a shared locking primitive within the Purchasing module. Callers should follow the standard EBS API conventions: initialize the message list where required, check x_return_status after every call, and supply valid session and user context when using the set-based overload so that PO_SESSION_GT is populated correctly before invocation. Because the package locks the complete document hierarchy, callers should expect it to be a heavyweight operation and should invoke it deliberately rather than in tight loops.