DBMS_REPCAT_INSTANTIATE, 2 of 2

DBMS_REPCAT_INSTANTIATE Package

Summary of Subprograms

Table 39-1 DBMS_REPCAT_INSTANTIATE Package Subprograms

Subprogram	Description
DROP_SITE_INSTANTIATION Procedure	Public procedure that removes the target site from the `DBA_REPCAT_TEMPLATE_SITES` view.
INSTANTIATE_OFFLINE Function	Public function that generates a script at the master site that is used to create the snapshot environment at the remote snapshot site while offline.
INSTANTIATE_OFFLINE_ REPAPI Function	Public function that generates a binary file at the master site that is used to create the snapshot environment at a RepAPI remote snapshot site while offline.
INSTANTIATE_ONLINE Function	Public function that generates a script at the master site that is used to create the snapshot environment at the remote snapshot site while online.

For more information about the DBMS_REPCAT_INSTANTIATE package, see the following file:

ORACLE_HOME/rdbms/admin/dbmsrint.sql

DROP_SITE_INSTANTIATION Procedure

This procedure drops a template instantiation at a target site. This procedure removes all related metadata at the master site and disables the specified site from refreshing its snapshots. You must execute this procedure as the user who originally instantiated the template. To see who instantiated the template, query the ALL_REPCAT_TEMPLATE_SITES view.

Syntax

DBMS_REPCAT_INSTANTIATE.DROP_SITE_INSTANTIATION(
     refresh_template_name  IN   VARCHAR2,
     site_name              IN   VARCHAR2);

Table 39-2 DROP_SITE_INSTANTIATION Procedure Parameters

Parameter	Description
refresh_template_name	The name of the deployment template to be dropped.
site_name	Identifies the Oracle server site where you want to drop the specified template instantiation (if you specify a `SITE_NAME`, do not specify a `REPAPI_SITE_ID`).

INSTANTIATE_OFFLINE Function

This function generates a file at the master site that is used to create the snapshot environment at the remote snapshot site while offline. This generated file is an offline instantiation file and should be used at remote snapshot sites that are not able to remain connected to the master site for an extended amount of time.

This is an ideal solution where the remote snapshot site is a laptop. Use the packaging tool in Replication Manager to package the generated file and data into a single file that can be posted on an FTP site or loaded to a CD-ROM, floppy disk, and so on.

See Also:
Oracle8i Replication and Replication Manager online help for more information.

The script generated by this function is stored in the USER_REPCAT_TEMP_OUTPUT temporary view and is used by several Oracle tools, including Replication Manager, during the distribution of deployment templates. The number returned by this function is used to retrieve the appropriate information from the USER_REPCAT_TEMP_OUTPUT view.

The user who executes this public function becomes the "registered" user of the instantiated template at the specified site.

Note:
This function is used in performing an offline instantiation of a deployment template.
This function should not be confused with the procedures in the DBMS_OFFLINE_OG package (used for performing an offline instantiation of a master table) or with the procedures in the DBMS_OFFLINE_SNAPSHOT package (used for performing an offline instantiation of a snapshot). See these respective packages for more information on their usage.

Syntax

DBMS_REPCAT_INSTANTIATE.INSTANTIATE_OFFLINE(
     refresh_template_name   IN   VARCHAR2,
     site_name               IN   VARCHAR2, 
     runtime_parm_id         IN   NUMBER    := -1e-130,
     next_date               IN   DATE      := SYSDATE,
     interval                IN   VARCHAR2  := 'SYSDATE + 1',
     use_default_gowner      IN   BOOLEAN   := TRUE)
     return NUMBER;

Table 39-3 INSTANTIATE_OFFLINE Function Parameters

Parameter	Description
refresh_template_name	The name of the deployment template to be instantiated.
site_name	The name of the remote site that is instantiating the deployment template.
runtime_parm_id	If you have defined runtime parameter values using the `INSERT_RUNTIME_PARMS` procedure, specify the ID used when creating the runtime parameters (the ID was retrieved by using the `GET_RUNTIME_PARM_ID` function).
next_date	The next refresh date value to be used when creating the refresh group.
interval	The refresh interval to be used when creating the refresh group.
use_default_gowner	If TRUE, then any snapshot object groups created are owned by the default user PUBLIC. If FALSE, then any snapshot object groups created are owned by the user performing the instantiation.

Table 39-4 INSTANTIATE_OFFLINE Function Exceptions

Exception	Description
miss_refresh_ template	The deployment template name specified is invalid or does not exist.
dupl_template_site	The deployment template has already been instantiated at the snapshot site. A deployment template can be instantiated only once at a particular snapshot site.
not_authorized	The user attempting to instantiate the deployment template is not authorized to do so.

Returns

Table 39-5 INSTANTIATE_OFFLINE Function Returns

Return Value	Description
<system-generated number>	Specifies the generated system number for the `output_id` when you select from the `USER_REPCAT_TEMP_OUTPUT` view to retrieve the generated instantiation script.

INSTANTIATE_OFFLINE_REPAPI Function

This function generates a file at the master site that is used to create the snapshot environment at a remote RepAPI snapshot site while offline. This offline instantiation file should be used at remote RepAPI sites that are not able to remain connected to the master site for an extended amount of time.

This is an ideal solution where the remote snapshot site is a laptop running Oracle8i Lite (which includes RepAPI). The generated file can be posted on an FTP site or loaded to a CD-ROM, floppy disk, and so on.

The file generated by this function is stored at the master site in the directory specified by the parameter OFFLINE_DIRPATH. The file is named based on the USER_NAME, REFRESH_TEMPLATE_NAME, and SITE_ID and is identified with the file type extension .oli. For example, an offline instantiation for the user SCOTT of the template named MYTEMPLATE at site 1234 is named the following:

scott_mytemplate_1234.oli.

This is a public function to generate an offline instantiation file for the connected user.

Syntax

DBMS_REPCAT_INSTANTIATE.INSTANTIATE_OFFLINE_REPAPI(
  refresh_template_name   IN   VARCHAR2,
  site_id                 IN   VARCHAR2   := NULL,
  master                  IN   VARCHAR2   := NULL,
  url                     IN   VARCHAR2   := NULL,
  ssl                     IN   NUMBER     := 0,
  trace_vector            IN   NUMBER     := DBMS_REPCAT_RGT.NO_TRACE_DUMP,
  resultset_threshold     IN   NUMBER     := DBMS_REPCAT_INSTANTIATE.
                                             RESULTSET_THRESHOLD,
  lob_threshold           IN   NUMBER     := DBMS_REPCAT_INSTANTIATE.
                                             LOB_THRESHOLD);

Table 39-6 INSTANTIATE_OFFLINE_REPAPI Function Parameters (Page 1 of 2)

Parameter	Description
refresh_template_name	The name of the deployment template to be instantiated.
site_id	A temporary name assigned to this offline instantiation. This temporary name is part of the offline instantiation file name. If the default `NULL` value is used, Oracle generates a number for this temporary name. It may be useful to specify a name if you want the offline instantiation file name to indicate its intended snapshot site. The `site_id` must be unique. That is, no two offline instantiation files can have the same `site_id`. This temporary name is always overwritten by the RepAPI client when the deployment template is instantiated. Oracle Corporation recommends that you use the default `NULL` value for this parameter.
master	An optional alias used for the server by the RepAPI client. If specified, then the RepAPI client must always refer to the server by this alias.
url	The published URL at the master site for access to the database. If specified, then the RepAPI client must always refer to the server by this URL.
ssl	1 indicates that the snapshots use secure sockets layer (SSL) to communicate with the master site. 0 indicates that SSL is not used.
trace_vector	The trace level for debugging.
resultset_threshold	The maximum size of non-LOB row data sent during the snapshot refresh process.
lob_threshold	The maximum size of LOB row data sent during the snapshot refresh process.

Table 39-7 INSTANTIATE_OFFLINE_REPAPI Function Exceptions

Exception	Description
miss_refresh_template	The template does not exist.
miss_user	The username does not exist in the database.
miss_template_site	The template has not been instantiated for the user and site.

Returns

Table 39-8 INSTANTIATE_OFFLINE_REPAPI Function Returns

Return Value	Description
0	An error was encountered.
1	No errors were encountered.

INSTANTIATE_ONLINE Function

This function generates a script at the master site that is used to create the snapshot environment at the remote snapshot site while online. This generated script should be used at remote snapshot sites that are able to remain connected to the master site for an extended amount of time, as the instantiation process at the remote snapshot site may be lengthy (depending on the amount of data that is populated to the new snapshots).

The user who executes this public function becomes the "registered" user of the instantiated template at the specified site.

Syntax

DBMS_REPCAT_INSTANTIATE.INSTANTIATE_ONLINE(
     refresh_template_name   IN   VARCHAR2,
     site_name               IN   VARCHAR2, 
     runtime_parm_id         IN   NUMBER    := -1e-130,
     next_date               IN   DATE      := SYSDATE,
     interval                IN   VARCHAR2  := 'SYSDATE + 1',
     use_default_gowner      IN   BOOLEAN   := TRUE)
     return NUMBER;

Table 39-9 INSTANTIATE_ONLINE Function Parameters

Parameter	Description
refresh_template_name	The name of the deployment template to be instantiated.
site_name	The name of the remote site that is instantiating the deployment template.
runtime_parm_id	If you have defined runtime parameter values using the `INSERT_RUNTIME_PARMS` procedure, specify the ID used when creating the runtime parameters (the ID was retrieved by using the `GET_RUNTIME_PARM_ID` function).
next_date	Specifies the next refresh date value to be used when creating the refresh group.
interval	Specifies the refresh interval to be used when creating the refresh group.
use_default_gowner	If TRUE, then any snapshot object groups created are owned by the default user PUBLIC. If FALSE, then any snapshot object groups created are owned by the user performing the instantiation.

Table 39-10 INSTANTIATE_ONLINE Function Exceptions

Exception	Description
miss_refresh_ template	The deployment template name specified is invalid or does not exist.
dupl_template_site	The deployment template has already been instantiated at the snapshot site. A deployment template can be instantiated only once at a particular snapshot site.
not_authorized	The user attempting to instantiate the deployment template is not authorized to do so.

Returns

Table 39-11 INSTANTIATE_ONLINE Function Returns

Return Value	Description
<system-generated number>	Specifies the generated system number for the output_id when you select from the `USER_REPCAT_TEMP_OUTPUT` view to retrieve the generated instantiation script.