NSFDB2FastCopy

Function : Backup

NSFDB2FastCopy - Copy the NSFDB2 database specified and reconnects the copy of the DB2 data as an NSFDB2 database.

#include <nsfdb.h>
STATUS LNPUBLIC NSFDB2FastCopy(

    const char far*srcDB2Database,
    const char far*tgtDB2Database,
    const char far*sourceNSF,
    const char far*targetNSF,
    const char far*groupName,
    const char far*loadParameter,
    DWORD  WaitTime,
    DWORD  flags,
    DWORD  flags2);

Description :

This function efficiently copies the NSFDB2 database specified by sourceNSF
and reconnects the copy of the DB2 data as an NSFDB2 database named targetNSF . This function will only work locally on a Domino server supporting NSFDB2 databases.

Algorithm Federation setup If srcDB2Database is specified, federation is set up as follows: Verify targetNSF actually exists in altDB2Database Get Group and User schema from the CATALOG table in altDB2Database. Note:
The group schema is the DB2 schema used by the core NSFDB2 tables. The user schema is the DB2 schema being used by Domino Access Views; an optional feature of the NSFDB2 database used to expose Notes data in relational form. If user schema already exists in live DB2 database (used by DAVs), detect DAV naming conflict and correct this later. Create a DB2 Federation wrapper named DominoARPWrapper if it doesn't already exist. This Federation wrapper will persist until all threads are done executing NSFDB2FastCopy. Create Federation server named DominoARPServer_altDB2Database to altDB2Database . Keep a reference count on this to allow for parallel copies of NSFDB2 data from the same scratch DB2 database on separate threads. Need to generate two DB2 "schema identifiers", used to create NICKNAMES to tables in altDB2Database. DB2GenerateNSFIdentifier will be used in coming up with the root nickname (e.g. SOURCENSF2). A second schema (e.g. SOURCENSF2_DAV) will be created to map DAV table data. A NICKNAME (i.e. mapping) will be created for each NSFDB2 table under the root schema generated above (e.g. SOURCENSF2.NSFNOTE). Another NICKNAME will be generated for each DAV table using the second schema defined above (e.g. SOURCENSF2_DAV.MYDAV). The reason we are using two schemas is that there is nothing precluding someone defining a DAV that is named identically to one of our base NSFDB2 tables.

Else , If altDB2Database is not specified, obtain the group schema, user schema, tablespace name, NSFID, etc., for sourceNSF from the live DB2 database.

Determine NSFDB2 container, create if necessary: Take sourceNSF offline if not in altDB2Database. If targetNSF exists, return an error unless DB2BACKUP_COPY_REPLACE is passed in flags. If DB2BACKUP_COPY_ISOLATE is passed as flags, generate a new NSFDB2 group (tablespace container).
Else If groupName is specified, return an error if it does not exist; otherwise, place targetNSF's data in groupName. Else if targetNSF exists, use targetNSF's existing NSFDB2 grouping Else targetNSF will be placed into the next available NSFDB2 group, generating an NSFDB2 group if the current NSFDB2 group is full. -end if-

If DB2BACKUP_COPY_CLOSE is set in flags, mark groupName closed so additional NSFDB2 databases aren't added to the group schema (groupName). else, existing DB2 container (groupName) is used. If targetNSF did not exist, or it is being moved, call DbCreateExtended3() to create a shell of the NSFDB2 database in the target NSFDB2 group (tablespace)

Perform insert or DB2 load The target tablespace may be resized by this function to accommodate the additional NSFDB2 data. This will make our internal load/insert mechanism perform optimally. If we determine that targetNSF is being created in a new NSFDB2 group (tablespace), Basic DB2 LOAD parameters are created: Messages generated by DB2 LOAD will be placed in a file named cliload.txt in the current directory. If DB2BACKUP_COPY_NONRECOVERABLE is not passed in flags, the load is marked as recoverable. The DB2 LOADCOPY file will be placed in the DB2Directory field, as specified in the server doc, unless loadParameter is specified. See the description for loadParameter. Pass DB2BACKUP_COPY_NONRECOVERABLE for the load to be done as non-recoverable (i.e. if you intend to perform a tablespace backup immediately after calling this function). Delete table data associated with existing targetNSF, if applicablee. (assumes
DB2BACKUP_COPY_REPLACE passed in flags) For each table in the list of federated tables for which a NICKNAME was created (both in the user & group schema ) If the table doesn't for the targetNSF: create it in the proper group or user schema (e.g. some NIF tables and DAV tables may not exist if targetNSF was created) Check for indexes on source table (in live or scratch DB2 database) and create them now. (TBD) Check to see if the table has generated columns. If so, we need a LOAD modifier to indicate we wish to have those columns generated. An error will be produced if you use the load modifier and the table doesn't have generated columns. Remove the NSFIDCHECK constraint if it exists. Generate an SQL statement inserting only those columns that exist in both the source and target tables, explicitly providing the correct NSFID column value. If copying the NSFDB2 database to a new NSFDB2 group (tablespace), or to an existing NSFDB2 group (tablespace) where targetNSF is the only member: Set the proper statement attributes such that an INSERT/ full SELECT can be done into the table for targetNSF from all rows in sourceNSF containing sourceNSF's NSFID Else if copying to an existing NSFDB2 group (tablespace), do not do INSERT via CLI LOAD; use normal SQL INSERT. DB2 Load cannot be used on a table with existing data since the table will be placed temporarily into a READ-ONLY state, which would affect other NSFDB2 databases already in the NSFDB2 group (tablespace) Readd NSFIDCHECK with the proper NSFID.
Reconnect and bring targetNSF online. If DB2BACKUP_DELETE_ON_COPY is passed as flags, the operation is effectively a move. Delete NSFDB2 data previously associated with sourceNSF. Otherwise, bring sourceNSF online. Drop NICKNAMES of federated objects that were created. Also drop the federation server if the reference count on it is zero.

Parameters : Input : srcDB2Database - [optional] Must be used to identify the scratch/alternate DB2 database created as a result of the alternate recovery procedure . If not NULL, this specifies the name of the scratch DB2 database containing sourceNSF. Requires that federation is enabled for DB2 database. NULL indicates sourceNSF is in the DB2 database currently being used by Domino.

tgtDB2Database - [ignored]: Not supported. Ignored for Domino V7.

sourceNSF - Full path, relative to Domino server's data directory, of the NSFDB2 database to be copied or moved.

targetNSF - The name of the Notes database used as the target of the copy or move operation. An error will be returned if targetNSF already exists unless DB2BACKUP_COPY_REPLACE is specified to prevent unintentionally erasing existing NSFDB2 data.
targetNSF will be placed into an NSFDB2 group as follows: If groupName is not specified and targetNSF exists will be placed into its current NSFDB2 group. An error will be returned if targetNSF and sourceNSF are in the same group; as this would effectively a delete and rename operation. If groupName is not specified and targetNSF does not exist, targetNSF will be created in its own NSFDB2 group. This will be necessary to avoid conflicts in our internal row identifier. If targetNSF does not exist and groupName is specified, the targetNSF will be placed into that group. If groupName does not exist, the NSFDB2 group will be created, which will include the new DB2 tablespace. Note: An error will be returned if targetNSF and sourceNSF are identical unless either of the following is true: sourceNSF is coming from altDB2Database groupName is specified and it is different from the NSFDB2 group currently being used by sourceNSF. DB2BACKUP_COPY_ISOLATE is specified, forcing targetNSF to be placed in a new group by itself.

groupName - [optional] - Specifies the NSFDB2 group that targetNSF is to be placed. This must be an existing NSFDB2 group (tablespace) name. This parameter is ignored if targetNSF already exists unless targetNSF = schemNSF. This parameter is also ignored if DB2BACKUP_COPY_ISOLATE is specified.

loadParameter - This api function uses the DB2 load facility in such a way that the load is recoverable unless DB2BACKUP_NONRECOVERABLE is specified as in flags. loadParamete will be the directory for which you want the DB2 copy files to be placed for a recoverable load. Passing NULL in this parameter will result in the current directory being used to place the loadCopyFiles. The copy files are required for a rollforward operation. DB2 will require the copy files be present during a rollforward operation if a recoverable load was performed. The files must exist or be restored to this directory for rollforward recovery. The copy location can be overriden by the DB2 registry variable DB2LOADREC during actual recovery if necessary. Recommendation: loadParameter should match the LOGPATH setting of your database configuration. This will make management and archival of the DB2 archive logs and COPY files easier. The space required for the load copy files would be commensurate to the size of the NSFDB2 database being copied or moved.

WaitTime - The amount of time in milliseconds to wait for targetNSF to be taken offline. Requires DB2BACKUP_COPY_REPLACE to be specified in flags.

flags - See DB2BACKUP_xxx.

flags2 - (for future use)

Output : (routine) - Return status from this call -- indicates either success or what the error is. The return codes include: NOERROR

ERR_DB2NSF_NOFEDERATION - Federation not enabled for DB2 database.

ERR_DB2NSF_IDENTIFIER_CONFLICT - An attempt was made to copy NSFDB2 data from altDB2Database where an internal identifier conflict was detected with NSFDB2 data in the live DB2 database. This most probably cause of this error is an attemp to copy NSFDB2 data from an altDB2Database where the backup image for the database (or tablespace backup) originated from a different DB2 database.

ERR_DB2NSF_TABLESPACE_MISSING - Returned if the groupName specified does not exist.

ERR_DB2NSF_CLI_ERROR - Internal DB2/CLI error.

ERR_DB2NSF_NOTDB2BACKED - The database specified by sourceDB is not a NSFDB2 database.

ERR_DB2NSF_SCHEMA_INUSE - The targetNSF already exists. To override use the flag DB2BACKUP_REPLACE.

ERR_DB2NSF_SRC_AND_DESTINATION - sourceDB and renameSrcTo cannot be identical. See Notes above.

ERR_DBINUSE - The database specified by sourceDB is active can could not be taken offline within the time specified by WaitTime. Calling thread should reattempt operation. Calling thread really should be using NSFTakeDatabaseOffline and not proceeding until that completes successfully.

ERR_DB2NSF_NOT_ENABLED_FOR_DB2 - The Domino server is not enabled for DB2.