ARCHIVE JOURNAL

The ARCHIVE JOURNAL utility offloads, to one or more archive journal files, the entries in one or more disk journal files.
idmscu19
The ARCHIVE JOURNAL utility offloads, to one or more archive journal files, the entries in one or more disk journal files.
The options you can choose depend upon the type of recovery being performed and whether or not the DC/UCF system is active.
This article describes the following information:
2
2
Authorization
To
You need this privilege
On
Archive one or more journal files
USE
The DMCL
Syntax
  ►►─── ARCHIVE JOURNAL ────────────────────────────────────────────────────────►  ►─┬────────────────────────┬─────────────────────────────────────────────────►    └─ BUFFERS buffer-count ─┘  ►─┬────────────────────────────────┬─────────────────────────────────────────►◄    ├─ ALL ──────────────────────────┤    ├─ AUTO ◄────────────────────────┤    ├─ AUTOALL ──────────────────────┤    ├─ FULL ─────────────────────────┤    ├─ READ ─┬─────────────────────┬─┤    │        └─ journal-file-name ─┘ │    ├─ REPORT ───────────────────────┤    └─ RESTART journal-file-name ────┘  
Parameters
  • BUFFERS
    Specifies the number of buffer pages to be used during condense processing.
    Condense processing involves copying the before image of unfinished transactions back to the disk journal file after it is offloaded. Condense processing of journal segments takes place when
    both
    of the following apply:
    • You specify AUTO
      and
    • The DC/UCF system is active or after an abnormal system termination
    The buffer is used for storing before images of unfinished transactions before copying the images back to the disk journal file.
    The buffer page size is equal to the block size of the disk journal file.
  • buffer-count
    An integer in the range 2 through 32,767. The default is 5.
  • ALL
    Specifies that all non-empty disk journal files are to be offloaded, starting with the file containing the oldest entries.
    This option is not allowed while the DC/UCF system is active or after an abnormal system shutdown, unless you are beginning a section recovery of the entire system.
    After offloading the journal files, they are marked as empty.
    Before images of unfinished transactions
    are not
    rewritten or condensed after offloading the journal files. These before images are needed if you need to recover from an abnormal shutdown.
  • AUTO
    Directs the ARCHIVE JOURNAL utility to select a single file to offload:
    • While the DC/UCF system is active or after an abnormal system termination, the oldest full disk journal file is selected.
      After offloading the file, it is condensed.
      After condensing the selected file, a new, empty journal segment is created.
      If no full disk journal file exists, no file is offloaded or condensed.
    • After a normal DC/UCF system shutdown, the oldest non-empty disk journal file is selected.
      After offloading the file, it is marked as empty.
  • AUTOALL
    • While the DC/UCF system is active or after an abnormal systemshutdown, the oldest full disk journal file is offloaded. The file is condensed after it is offloaded and a new empty journal segment is created.
    • After a normal DC/UCF shutdown, specifies that all non-empty disk journal files are to be offloaded, starting with the file containing the oldest entries.
      After offloading the journal files, they are marked as empty.
  • FULL
    Directs the ARCHIVE JOURNAL utility to offload all full disk journal files associated with the database, starting with the file containing the oldest entries. After offloading each file, it is marked as empty.
    Before images of unfinished transactions
    are not
    condensed and rewritten. These before images are needed if you need to recover from an abnormal shutdown.
    This option is not allowed while the DC/UCF system is active or after an abnormal system shutdown, unless you are beginning a section recovery of the entire system.
  • READ
    Directs the ARCHIVE JOURNAL utility to offload a single disk journal file without condensing it or marking it as empty afterwards.
    If you do not specify a file name, the oldest non-empty disk journal file is offloaded.
  • journal-file-name
    The name of the disk journal file to be read.
  • REPORT
    Displays information about all disk journal files. No archiving or condensing of the journal files is performed.
  • RESTART
    Directs the ARCHIVE JOURNAL utility to restart an archive journal operation that terminated abnormally. If the operation failed:
    • While a disk journal file was being
      offloaded
      , the offload operation is restarted.
    • While a disk journal file was being
      condensed
      , the condense operation is restarted.
  • journal-file-name
    The name of the disk journal file being offloaded at the time of the abend.
Usage
Summary of offload parameter options
In summary, if the DC/UCF system is
not
active, one or more disk journals may be processed, and after a file is offloaded, it is marked empty.
If the DC/UCF system is active, only the oldest full disk journal file is processed (as if the AUTO option is specified). After the file has been offloaded it is condensed and a new journal segment is created.
Parameter
While DC/UCF Active or After Abnormal Termination
After Normal Shutdown
ALL
Not Allowed
All non-empty disk journal files, beginning with the oldest file, are offloaded.
Offloaded files are marked as empty.
AUTOALL
Oldest full disk journal file is offloaded.
Condenses offloaded file, then creates a new, empty journal segment.
All non-empty disk journal files, beginning with the oldest file, are offloaded.
Offloaded files are marked as empty.
AUTO
Oldest full disk journal file is offloaded.
Condenses offloaded file, then creates a new, empty journal segment.
Oldest non-empty disk journal file is offloaded and marked as empty.
FULL
Not Allowed
All full disk journal files, beginning with the oldest file, are offloaded.
How to submit the ARCHIVE JOURNAL statement
You submit the ARCHIVE JOURNAL statement to CA IDMS/DB only through the batch command facility. You must run the batch command facility in local mode.
You normally specify AUTO
Normally, you archive journal files as they become full. For this purpose, specify AUTO.
The other options are used only in special circumstances, such as recovering damaged files.
Use with two-phase commit feature
ARCHIVE JOURNAL automatically preserves journal records for incomplete or unforgotten distributed transaction records when condensing a journal file.
Obtaining a status report
ARCHIVE JOURNAL always produces a report showing the status of disk journal files. Specify the REPORT option if you only want to obtain the report and you do not want to archive or condense journal information.
Use with change tracking
If the CV whose journals are being archived uses change tracking to record changes to its database environment, the JCL used to archive its journal files should reference the CV's SYSTRK files and should not include file assignments for the journal files. This ensures that any changes made to the journal files in use by the CV are known to the ARCHIVE JOURNAL utility so that it operates on the correct set of files.
For more information about change tracking and the use of SYSTRK files, see Change Tracking in the
CA IDMS System Operations Section
.
Performance consideration
A reduction in run-time for the ARCHIVE JOURNAL utility might occur if you process the journals using the QSAM access method. To invoke QSAM against the journals specify QSAMAREA=ARCHIVE.JOURNAL in the SYSIDMS file used by the ARCHIVE JOURNAL utility.
JCL Considerations
When you submit an ARCHIVE JOURNAL statement through the batch command facility, the JCL to execute the facility must include statements to define:
  • The disk journal files or the CV's SYSTRK files if change tracking is in use by the CV
  • The archive journal files.
For more information about the generic JCL used to execute the batch command facility, see the section for your operating system in this section.
Example
While your DC/UCF system is active, you can initiate a job that will offload full disk journal files. To do this, specify the AUTO option of the ARCHIVE JOURNAL statement:
archive journal auto;
Sample Output
After successful completion of the ARCHIVE JOURNAL statement submitted with the AUTO option, the CA IDMS Batch Command Facility produces the following listing:
 IDMSBCF                                              IDMS Batch Command Facility                            mm/dd/yy   PAGE 1  ARCHIVE JOURNAL ;      JOURNAL DISK FILES STATUS REPORT  FILENAME          SEGMENT  LORBN HIRBN   FULL  ACTIVE    STATUS    CV ACTIVE  SYSJRNL2               77     10  1000    NO     YES    NON-AJNL     YES                         75      8     9  SYSJRNL1               76     10  1000    YES    NO     NON-AJNL     YES                         74      8     9  WILL SELECT SYSJRNL1           FOR OFFLOADING  PERCENTAGE DISTRIBUTION PER PAGE  PERCENT      NO OF PAGES   0-10                430  11-20                 15  21-30                185  31-40                 15  41-50                  5  51-60                160  61-70                  3  71-80                 29  81-90                  3  91-100               145  DISK BLOCKS OFFLOADED                     990  TAPE BLOCKS WRITTEN THIS SEGMENT           32  TOTAL TAPE BLOCKS WRITTEN                  32  END OF JOURNAL ARCHIVE     yyyy-mm-dd-hh.ss.mm.ffffff  Status = 0  AutoCommit will COMMIT transaction  Command Facility ended with no errors or warnings
More Information
  • For more information about journaling procedures, see the
    CA IDMS Database Administration Section
    .
  • For more information about system generation journal parameters, see the
    CA IDMS System Generation Section
    .