Search Results control_document

Overview

APPS.PO_DOCUMENT_CONTROL_PUB is a public PL/SQL package body within the Oracle E-Business Suite Procurement module that centralizes the execution of document-level control actions against purchasing documents. Its primary purpose is to enforce a controlled, API-driven mechanism for changing the state of purchase orders, purchase agreements, and releases — most notably cancellation — while preserving transactional integrity, auditing information, and the calling application's message list. Rather than permitting direct DML against purchasing tables, Oracle exposes this package so that forms, concurrent programs, and custom extensions can invoke a sanctioned, validated control operation that maintains the who-columns and message context consistently across the application tier. The header comment, dated 2006, identifies the package as a long-standing shipped object whose behavior is governed by profile options and FND_API conventions.

Key Procedures and Functions

• CONTROL_DOCUMENT — The sole documented public procedure. It performs a control action (identified by p_action) against a specified document, and currently supports only the CANCEL action. The procedure resolves any missing identifiers from supplied numbers, giving precedence to an ID when both an ID and a number are passed. It derives the execution granularity from which of the final document, line, and shipment (line location) identifiers are populated — shipment level when all three are present, line level when only header and line identifiers are present, and header level when only the document identifier is present. On successful completion the document is updated at the determined entity level, and it is printed when the document is a PO, PA, or RELEASE and the print flag is set to Y. The procedure returns FND_API.G_RET_STS_SUCCESS on success, G_RET_STS_ERROR on a handled failure, and G_RET_STS_UNEXP_ERROR on an unexpected error. All changes are committed only when the commit flag is set to FND_API.G_TRUE. The API message list is appended on error and the document is left unchanged in that event. The procedure assumes the caller has already initialized the message list when the initialize-message-list flag is false.

Tables Accessed

• PO_DOCUMENT_TYPES — Read to validate the document type and subtype supplied by the caller, ensuring the control action is applied to a recognized purchasing document classification.
• PO_HEADERS / PO_HEADERS_ALL — The primary target of header-level control changes; updated with the control-related columns and the standard who-columns when a cancellation is applied.
• PO_LINES — Updated when the control action executes at line level or shipment level, propagating the state change to the affected lines.
• PO_RELEASES_ALL — Accessed to support the release document type, since releases are controlled and updated through their own base table.
• PLITBLM — The PL/SQL message retrieval table used to manage and return the API message list associated with the call.

Usage Notes

This package is most commonly invoked from the Purchasing forms layer when a user initiates a cancel action on a document, and by concurrent programs or workflow activities that need to programmatically cancel purchasing documents. Because it is classified as a PUBLIC API, custom integrations may also call it directly, provided the caller respects the documented contract: pass p_api_version, set p_init_msg_list appropriately, inspect x_return_status, and only rely on a commit when p_commit is FND_API.G_TRUE. The ETRM metadata records that two other packages reference this object, indicating it is reused internally by higher-level procurement APIs rather than being an isolated utility. Callers should avoid direct DML on the affected tables and should treat the API message list as the authoritative source of error detail; when the procedure returns anything other than success, the document remains unchanged and the transaction can safely be retried or rolled back. The dependency on the AFLOG_ENABLED profile option allows selective debug logging without altering application behavior.