View figure.There are three parameters related to user archiving in the database PARMS file: Submit_routine, Cancel_routine, and Uarchive_enabled. Setting Uarchive_enabled to "Y" tells Control Center to use the user archive command when a database archive is required (switching logmodes from Y to L; or, after certain single user mode tools are executed, the Add DBEXTENTS tool). If this field is set to "N", then normal database archiving is used in these implicit archive situations. Parameters Submit_routine and Cancel_routine name REXX execs that are invoked by the Control Center service machine when a user archive command or a database cancel command, respectively, is received.
Sample execs ($execs) have been provided on the code disk. These can be modified according to your type of user archive. These $execs have been provided as samples to help implement user archiving:
The above execs will be referenced in the discussion of a sample user archive implementation which follows below.
The following paragraphs explain the flow of events when the UARCHIVE command is received:
Control Center changes the database STATUS to UARCHIVEDOWN. Next, a log archive is taken if logmode=L. The database then comes down and Control Center checks the Submit_routine field for a valid name. If there is no name, or the name is invalid, Control Center issues an error message and exits. The database remains down; the database status is still UARCHIVEDOWN; an internal global variable remains NONE. This variable is called UARCSTAT and is used to respond to the database when it comes back up after a user archive and requests a response to whether the user archive was successful or not. The four values it can have are NONE (initial setting), RUNNING (when the user archive command is sent to the database), SUCCESSFUL (when the message is received from the disconnected server machine that the archive was successful) and FAILED (when the message sent by the service machine designates a failed user archive). The DBA would then have to correct the problem after determining the cause. This will be elaborated upon later.
If the submit routine exists, Control Center sets the UARCSTAT global variable to RUNNING, invokes the routine, then updates the ARCHIST and ARCHLOG files with archive starting information. The sample submit routine provided with the product (UARCSUB $EXEC) sends a message to the database to execute a TELL command to a disconnected server ID (support machine) to start a backup job. A support machine is used here so that the Control Center service machine is free to attend to database servicing. The support machine will receive any information or messages from the backup product since it is the ID which interfaces directly with the backup product.
The database then awaits a response from the server ID or DBA about the success or failure of the archive (the response corresponds to the messages in the message file). Two messages (UARC001I and UARC002E) are included in the DATABASE MESSAGES file which cause Control Center to react to a successful or failed user archive notification.
If the response signifies a successful archive (UARC001I), the UARCSTAT global variable is set to SUCCESSFUL; if it signifies a failure (UARC002E), the global is set to FAILED. The database is then brought back up; Control Center responds 1 or 0 (good or bad) to the database's inquiry about whether the user archive was successful, and normal operations resume. The global variable is then set to NONE and the database status to NORMAL.
The following is a list of steps to be followed when setting up the user archiving facility:
100 ARCHIVE 00000 00:00:00 UNUSED UARCH1 100 LOG 00000 00:00:00 UNUSED VM1201 200 ARCHIVE 97008 19:01:52 UNUSED UARCH2 200 LOG 97009 07:54:28 UNUSED VM1202 300 ARCHIVE 97009 15:41:43 UNUSED UARCH3 300 LOG 00000 00:00:00 UNUSED VM1203
The key point is that there must be one entry for each ARCHIVE series so that a proper FILEDEF can be done by Control Center (the tape ID can be a dummy volid, as shown above).
| Note: | It is strongly suggested that a regular TAPES file be set up to ensure that, in certain cases when a database archive is initiated, the TAPES file is set up to handle the archive. This would also allow for interleaving user and regular archives which could occur if the Uarchive_enabled switch was set to "N" and a database-initiated archive took place. |
The following diagram depicts four disconnected server machines. The backup product may be SYBACK, VMBACKUP, DDR, or any other product. All interfacing to the backup product is actually done through a Control Center support machine. This is done to make the management of the backup jobs much simpler. Depending on the product, the Control Center support machine may receive many messages and/or files from the backup product. Additionally, there is only one machine to authorize to the backup product.
The following must be done to or on the Control Center service machine:
Create from provided templates the UARCSUB and UARCCAN execs. The templates have commented sections of code explaining where the updates should be made. Shown below are the lines in these execs which must be updated. Replace support_id with the name of the support machine ID:
if uarchive then 'CP SEND' dbname 'TELL support_id UARCHIVE START BACKUP' else 'CP SEND' dbname 'TELL support_id UARCHIVE START RESTORE'
Note that the first word (UARCHIVE) in the message to the support machine must match the keyword identified in the support machine's SQLMSTR PROFILE - this is covered again in the support machine section below.
For each database that will be user archived, the database PARMS file must be updated to specify a "submit-routine" matching the name of the UARCSUB $EXEC you create. Also update the PARMS file to specify the "cancel-routine" and indicate "Y" or "N" for "uarchive-enabled".
There is no code or change required on the database server ID. Control Center, with the UARCSUB and UARCCAN execs, will in effect TELL the database how to start the user archive/backup process. The service machine tells the database server with the CP SEND command. CP SEND is a SCIF command (see UARCSUB and UARCCAN templates for examples). Deviating from this format can lead to several problems, so be advised to follow the format in the UARCSUB and UARCCAN templates.
The following is required for the Support Machine:
The support machine runs Control Center code, but is not responsible for any databases using the SCIF facility. After installation, you will have a disconnected service machine that can be used to perform User archives, Automated DBSPACE Maintenance, Table Reorganization and Redefinition, DBSPACE Reorganization, and other DB or non-DB-related jobs.
Give the database machine an authority level of 4. (The Backup Product Server (the server controlling user archive) only needs an authority level of 1. It should already be there from the USER ALL 3 statement. Check to be sure.)
This line must be added to the SQLMSTR PROFILE file:
MESSAGE UARCHIVE 4 ( EXEC SPBSTART .US .NO .MS
This MESSAGE line must be added before any other MESSAGE-type lines, not at the bottom of the profile. The UACHIVE word matches the word specified in the UARCSUB and UARCCAN execs. The specific lines from the UARCSUB exec are shown below:
if uarchive then 'CP SEND' dbname 'TELL support_id UARCHIVE START BACKUP' else 'CP SEND' dbname 'TELL support_id UARCHIVE START RESTORE'
The first word of the TELL command (in this case UARCHIVE) must match the word added to the support machine's SQLMSTR PROFILE. Note also that the word support_id in the code above should be replaced with the ID of your support machine.
If the backup product sends a file to the support machine (as is the case with VMBACKUP), then in the SQLMSTR PROFILE, you will need to add this line:
READER FROM userid AT nodeid 1 ( EXEC SPBEND .US .NO .SP .FN .FT
Replace userid and nodeid with appropriate values for your backup product machine (VMBACKUP AT VMSYSTM1). For example, when VMBACKUP sends the support machine a file, then the SPBEND routine will be performed. Be sure to add this READER line before any other READER-type lines in the support machine's SQLMSTR PROFILE. Otherwise, the other READER-type lines will be invoked because the sequence of processing is from top to bottom.
Make the SPBSTART and SPBEND execs available to the support machine through links or by placing code on the A-disk. Samples of the SPBSTART and SPBEND execs have been included with Control Center on the code disk. An optional exec, SPBANLZ $EXEC, has also been provided. It is used to do automatic verification based on a scan of the output report provided by VMBACKUP, and is included as a sample. The support machine will require read access to the database's code disk in order to access the SQLFDEF file.
If the backup tool is VMBACKUP, set up the VMBACKUP TEMPLATE file with the name of the submit and restore VMBACKUP template names for each database machine (see Figure 249). This file is read by the support machine to obtain a template name for a given database. Template names must match the template names set up in VMBACKUP.
The support machine will need the authority within VMBACKUP to submit and cancel VMBACKUP jobs.
If the backup product is VMBACKUP, the following is required for the VMBACKUP Machine:
Give the support machine the authority to submit and cancel backup jobs.
Create backup and restore templates for each database machine. The names of these templates should match the names specified in the VMBACKUP TEMPLATE file on the support machine's A-disk.
Try to minimize the messaging that the support machine receives from VMBACKUP. The support machine should only receive messages and files for those backup/restore jobs that it submits, not for all jobs run by VMBACKUP.
Other backup products will need similar steps to be taken.
The following diagram is a summary of the components of the example user archive presented in this appendix:
The following sample execs support the logic explained above in the suggested architecture of a user archive driven by Control Center using VMBACKUP as the tool:
| Disclaimer |
|---|
|
The following execs (and template) are provided as sample code only and are not part of the official product; thus, they are not supported. |
The submit routine is used when the Submit_routine field in the PARMS file has an entry with the name of the exec and a DBA submits a SQLEND UARCHIVE request or a database CANCEL request, or when an internal function causes a database to take an archive and the Uarchive_enabled field is set to "Y". Note that the exec does a CP SEND to the database machine which in turn issues a TELL command to the support machine to start a backup or restore, depending on the setting of the database mode.
The cancel routine is used when the Cancel_routine field in the PARMS file has an entry with the name of the exec and a DBA submits a database CANCEL request. Note that the exec does a CP SEND to the database machine which in turn issues a TELL command to the support machine to cancel a backup or restore, depending on the setting of the database mode. The actual implementation of the cancel user archive or recovery would be done by some means in the support machine.
This is a sample of an exec that runs on the Control Center support machine and responds to the START BACKUP message sent by the database. Note that message UARC003I need not be in the DATABASE MESSAGES file since it is used only for informational purposes. It will be logged in the service machine's log and in either the RECOVERY or ARCHHIST log. If the message ends in W instead of I, it will also be sent to Control Center administrators.
Additional messages may be added to provide more detailed status information in the logs. It is suggested to use the UARCnnnI format when so doing.
| Important: |
|---|
|
Do not change the ID or text of messages UARC001I and UARC002E. |
SPBEND is a sample of an exec that runs on the Control Center support machine when the console file from VMBACKUP is received after a backup is done. The filename of the console is the template name (the database in our scenario); the filetype is VMBACKUP. The primary logic used here is to scan the report for error indications, and then, if no error messages appear, to call a specially tailored exec, SPBANLZ, which compares the list of minidisks backed up to the list of minidisks in the SQLFDEF file of the database (excepting the log FILEDEFs, since the logs are not backed up). If any errors or inconsistencies are found, the UARC002E error message is sent to the database. If no problems are found, then the UARC001I successful message is sent back.
This template is a file used to determine what the VMBACKUP-required template name is on the VMBACKUP machine for a backup and restore series. Each database supported by this machine would have an entry in this file which corresponds to the name of the file on the VMBACKUP machine. The file is a description of the minidisks which are to be backed up by the VMBACKUP tool. This template is not supplied on the code disk but is presented here as a sample template when using VMBACKUP as the backup product. The fields which must be present are those pointed to by the arrow.
Figure 249. Sample of a VMBACKUP template on the Support Machine
VMBACKUP TEMPLATE: /*****************************************************/ /* VMBACKUP TEMPLATES TABLE */ /* ------------------------ */ /* USED BY SUPPORT MACHINE */ /* */ /* */ /* BACKUP RESTORE */ /* DATABASE TEMPLATE TEMPLATE */ /* -------- -------- -------- */ ---> dbname backup_tname restore_tname |
SPBANLZ is a sample of an exec which verifies the success of the VMBACKUP by scanning the console file from VMBACKUP and comparing the disks dumped with the disks defined in the database SQLFDEF file.
View figure.