The `dbms_preload` package announces that a table will be read shortly, so that the platform can fetch it while the connection is idle instead of when the question is asked. It is the one thing a script knows which the platform cannot work out for itself: what its next step is going to read.
Announcing is safe on any connection. Where fetching ahead is switched off, or where the platform behind the table does not support it, the announcement is recorded and nothing else happens, so a script which runs against several kinds of connection needs no condition around the call.
An announcement changes the order in which things are fetched and nothing else. It does not lift the bounds which keep fetching ahead out of the way: an announced table still waits until the connection is idle, still spends only the reserved part of the request rate of the platform, still leaves the daily allowance which is kept for questions actually asked, and still stops the moment the connection is used for anything else. Announcing a table during a heavy statement therefore does not make that statement slower.
From release 27.0 onward, fetching ahead has to be on for an announcement to lead to anything. It is on by default in the products a person works in directly: both Query Tools, Invantive Data Loader, Invantive Runtime, Invantive Business for Windows, Invantive Control for Excel, Invantive Composition and Invantive Data Hub. Elsewhere it is off unless something says otherwise: on a database in Invantive Cloud that is a setting of the database, and on any connection the setting `preemptive-loading` in the connection string, in a provider file, or in a `set` statement. What became of an announcement is reported per announcement in the Data Dictionary view `SystemPreemptiveLoadHints`, which names the action in words, its message code and the moment in UTC; the most common outcome on a connection where nothing was switched on says exactly that.
## `announce`: Announce that a table will be read shortly.
Tell the platform that a table is expected to be read within a number of seconds, so that it is fetched while the connection is idle. The expectation counts in full within the period named and falls away over the period after that, so an announcement which turns out to be wrong stops influencing the order shortly after it stops being credible.
Parameters:
- `catalog` (string, optional): Catalog of the table. Left empty, a table of that name in any catalog is meant.
- `schema` (string, optional): Schema of the table. Left empty, a table of that name in any schema is meant.
- `table_name` (string, required): Name of the table which will be read.
- `partition` (string, optional): Partition which will be read. Required when the partition scope is `One`.
- `within_sec` (decimal, optional): Number of seconds within which the table will be read. Sixty when left empty.
- `maximum_number_of_rows` (decimal, optional): Number of rows which will be read, or empty when the whole table will be. Naming it turns fetching a large table into fetching what is about to be looked at, which is one call instead of hundreds.
- `partition_scope` (string, optional): Which partitions will be read: `One` for the partition named, `Selected` for the partitions the connection has selected, or `All` for every partition of the data container. Left empty it is `One` when a partition is named and `Selected` when none is. A value which is none of the three is refused, and so is `One` without a partition.
- `data_container_alias` (string, optional): Alias of the data container which is to answer, as written in the connection. Needed once a connection holds two data containers of the same platform, since the same table then exists twice. Left empty, every data container which offers the table is meant.
A partition which the data container does not have is reported on the announcement rather than fetched, so a mistyped administration is visible instead of silently ignored.
Example, in which a load announces the ledger it will read of one administration and the first rows of the item file of every administration:
```sql
begin
dbms_preload.announce
( 'ExactOnlineREST'
, 'Incremental'
, 'TransactionLinesIncremental'
, '102673'
, 300
, null
, 'One'
, 'eol'
);
dbms_preload.announce
( 'ExactOnlineREST'
, 'Incremental'
, 'ItemsIncremental'
, null
, 600
, 1000
, 'All'
, 'eol'
);
end;
```