10
Replication Management API Reference

This chapter is an addendum to the release 8.1.6 Oracle8i Replication Management API Reference and describes changes in the replication management API in release 8.1.7. This chapter also includes documentation additions.

This chapter contains these topics:

• Changes to the DBMS_REPCAT_INSTANTIATE Package

• Changes to the DBMS_REPCAT_RGT Package

• Documentation Additions

Changes to the DBMS_REPCAT_INSTANTIATE Package

The following section describes changes to the DBMS_REPCAT_INSTANTIATE package in release 8.1.7.

The offline_dirpath Parameter Added to INSTANTIATE_OFFLINE_REPAPI

The DBMS_REPCAT_INSTANTIATE.INSTANTIATE_OFFLINE_REPAPI function includes the new required parameter offline_dirpath. The following section includes documentation for the new parameter and replaces the description of this function in the release 8.1.6 Oracle8i Replication Management API Reference.

Updated Description of the INSTANTIATE_OFFLINE_REPAPI Function

The DBMS_REPCAT_INSTANTIATE.INSTANTIATE_OFFLINE_REPAPI 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.

Offline instantiation is an ideal solution when the remote snapshot site has limited network connectivity. 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 username of the connected user and the refresh_template_name and site_id parameters. The file 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,
  offline_dirpath			         IN	   VARCHAR2   := NULL,
  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 10-1 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. The following is an example of a URL: sess_iiop://myserver:2481:RNDM/etc/repapi This URL has the following parts: myserver is the host name. 2481 is the Internet Inter-ORB Protocol (IIOP) listener port number. RNDM is the SID for the database. /etc/repapi is the published name for the object.
ssl	1 indicates that the snapshots use secure sockets layer (SSL) to communicate with the master site. 0 indicates that SSL is not used. Note: Use of SSL is not supported in this release of Oracle.
offline_dirpath	The directory where the offline instantiation file is saved. If offline_dirpath is omitted, then the file is saved to the path specified by the UTL_FILE_DIR initialization parameter. If neither offline_dirpath nor UTL_FILE_DIR are specified, then an error is raised.
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 10-2 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 10-3 INSTANTIATE_OFFLINE_REPAPI Function Returns

0

1

Changes to the DBMS_REPCAT_RGT Package

The following section describes changes to the DBMS_REPCAT_RGT package in release 8.1.7.

The offline_dirpath Parameter Required in INSTANTIATE_OFFLINE_REPAPI

The offline_dirpath parameter is required in the DBMS_REPCAT_RGT.INSTANTIATE_OFFLINE_REPAPI function in release 8.1.7. The following section includes documentation for this parameter and replaces the description of this function in the release 8.1.6 Oracle8i Replication Management API Reference.

Updated Description of the INSTANTIATE_OFFLINE_REPAPI Function

The DBMS_REPCAT_RGT.INSTANTIATE_OFFLINE_REPAPI 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.

Offline instantiation is an ideal solution when the remote snapshot site has limited network connectivity. 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 parameters. The file 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 

Syntax

DBMS_REPCAT_RGT.INSTANTIATE_OFFLINE_REPAPI(
  refresh_template_name   IN   VARCHAR2,
  site_id                 IN   VARCHAR2,
  user_name               IN   VARCHAR2   := USER,
  master                  IN   VARCHAR2   := NULL,
  url                     IN   VARCHAR2   := NULL,
  ssl                     IN   NUMBER     := 0,
  offline_dirpath			         IN	   VARCHAR2   := NULL,
  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 10-4 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.
user_name	The name of the user for whom the instantiation file is being generated.
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. The following is an example of a URL: sess_iiop://myserver:2481:RNDM/etc/repapi This URL has the following parts: myserver is the host name. 2481 is the Internet Inter-ORB Protocol (IIOP) listener port number. RNDM is the SID for the database. /etc/repapi is the published name for the object.
ssl	1 indicates that the snapshots use secure sockets layer (SSL) to communicate with the master site. 0 indicates that SSL is not used. Note: Use of SSL is not supported in this release of Oracle.
offline_dirpath	The directory where the offline instantiation file is saved. If offline_dirpath is omitted, then the file is saved to the path specified by the UTL_FILE_DIR initialization parameter. If neither offline_dirpath nor UTL_FILE_DIR are specified, then an error is raised.
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 10-5 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 10-6 INSTANTIATE_OFFLINE_REPAPI Function Returns

0

1

Documentation Additions

This section provides additional documentation about the replication management API that was not included in the release 8.1.6 Oracle8i Replication Management API Reference.

Switching Master Sites that are Running Different Releases of Oracle

The following describes the required actions if you switch the master site for a snapshot site to a different master site that is running a different release of Oracle. This additional documentation is added to the description for the DBMS_REPCAT.SWITCH_SNAPSHOT_MASTER procedure.

If min_communication is true for the snapshot and the new master is an Oracle7 master, regenerate replication support for the snapshot with min_communication set to false.

If generate_80_compatible is false for the snapshot and the new master is a release lower than Oracle8i (Oracle7 or Oracle8), regenerate replication support for the snapshot with generate_80_compatible set to true.

You can set both parameters for a snapshot in one call to DBMS_REPCAT.GENERATE_SNAPSHOT_SUPPORT.