Convert Journal Files Using ^JCONVERT and ^%JREAD

The ^JCONVERT routine is a utility that reads journal files and converts them to a common-format file so that the ^%JREAD utility can read and apply journal transactions to databases on a different system. The ^JCONVERT utility exists on older InterSystems database products as well as all versions of Caché. Use these utilities to move journal data between different system versions that do not have compatible journal files.

For example, if you are converting to a new version of Caché and need to minimize downtime, perform the following steps:

1. Enable journaling on the old system.

2. Run a backup on the old system; this switches to a new journal file on the old system.

3. Continue journaling on the old system.

4. Restore the backup of the old system on the new system and perform any necessary conversions.

5. Stop the old system and run ^JCONVERT on the journal files created on the old system since the backup.

6. Apply the transactions from the old system to the new system using the file created from

^JCONVERT as input to ^%JREAD on the new system.

The ^JCONVERT utility uses the same process as the journal restore utility to select and filter the journal files for processing. You can include a range of journal files as input and create one output file. See the Restore Globals From Journal Files Using ^JRNRESTO section for details on selecting and filtering journal files.

Before converting the journal files, you must choose the record and character translation for the con-verted file. The default is Variable/UTF8, which is compatible with the ^%JREAD utility on all platforms. You can move the files among platforms with binary FTP. However, these files are not easy to view or edit. Answer ^No at the record format prompt for an alternative local format file that you can edit but cannot as easily move to another platform.

CAUTION: If you choose the alternate editable format, you cannot export it as binary data; when you import it, binary data may be misinterpreted as the end of a record.

The alternative format is different for each platform:

Unicode (all platforms): $CHAR(8232) [LSEP] UTF8 UNIX (Linux and OS X): $CHAR(10) [LF] RAW Windows and OpenVMS: $CHAR(13,10) [CRLF] RAW

Unicode format requires a Unicode editor which may or may not exist on all Unicode platforms. This format works with Text Edit on the OS X operating system. If you require arbitrary record format and

character translations, this may be possible, but as this should be a very uncommon condition, contact the InterSystems Worldwide Response Center (WRC) for guidance.

Globals in the journal file are stored with a specific directory reference appended to the global reference.

You can choose either to include the directory reference in the converted file, or exclude it. If you include it, you can always filter it out or change it later during the ^%JREAD procedure.

The directory reference determines where ^%JREAD sets the global on the target system. If you do not include the directory reference, ^%JREAD makes all sets in the current directory. If you do include the directory reference, the utility makes sets in the same directory as on the source system unless translated by a ^%ZJREAD program you supply. If the target system is on a different operating system or the databases reside in different directories on the target system, you must supply a

^%ZJREAD routine to translate the directory reference.

The ^%JREAD routine reads a common journal file format and applies the journal transactions to the databases on the target system. During the import of records, if a ^%ZJREAD routine exists, the utility calls it for each journal transaction allowing you to manipulate the journal records. You can reference the following variables in your ^%ZJREAD routine:

type - Transaction type gref - Global reference value - Global value

%ZJREAD - 1:Apply transaction, 0:Do not apply transaction

If you decide not to apply a transaction, set the variable %ZJREAD to 0 (zero) to skip the record. You can also modify the other variables. For example, you can change the directory specification by mod-ifying gref.

The following is an example ^%ZJREAD routine. It looks for transactions that contain updates to

%SYS(“JOURNAL”, and prevents them from being applied. You can copy this and modify it to suit your needs:

%ZJREAD;

/*The following variables are defined; you can modify them before the transaction gets applied

type - Transaction type gref - Global reference value - Global value

%ZJREAD - 1:Apply transaction, 0:Do not apply transaction */

If gref["SYS(""JOURNAL""" Set %ZJREAD=0 Quit

Sample Run of ^JCONVERT

The following is a sample run of the ^JCONVERT utility:

%SYS>Do ^JCONVERT

Journal Conversion Utility [ Cache Format --> Common Format ]

You must choose the record and character translation for the converted file. The default of Variable/UTF8 is compatible with current ^%JREAD on all platforms and can be moved among platforms with binary FTP. However, these files are not easy to view or edit. Answer No for an alternative local format that can be edited, but not be as easy to move to another platform.

Use Variable/UTF8 record format? <Yes>

Globals in the journal file are stored with a specific directory reference appended to the global reference. You can choose either to include

the directory reference in the converted file, or exclude it. Note that if you include it, you can always filter it out or change it later during the %JREAD procedure. The directory reference determines where ^%JREAD sets the global on the target system. If the directory reference is not included, all sets are made to the current directory. If the directory reference is included, sets will be made to the same directory as on the source system unless translated by a ^%ZJREAD program you supply. If the target system is on a different operating system or the databases reside in different directories on the target system, the ^%ZJREAD program must be used to translate the directory reference.

Include the directory reference? <Yes>

Enter common journal file name: common.jrn Common journal file: common.jrn

Record separator: Variable Character translation: UTF8 Directory reference: Yes

Use current journal filter (ZJRNFILT)? no Use journal marker filter (MARKER^ZJRNFILT)? no

Process all journaled globals in all directories? enter Yes or No, please Process all journaled globals in all directories? yes

Specify range of files to process (names in YYYYMMDD.NNN format) from: <20061201.001> [?] => 20061202.001

through: <20061204.001> [?] =>

Prompt for name of the next file to process? No => No

Provide or confirm the following configuration settings:

Journal File Prefix: =>

Files to dejournal will be looked for in:

C:\MyCache\mgr\journal\

C:\MyCache\mgr\

in addition to any directories you are going to specify below, UNLESS you enter a minus sign ('-' without quotes) at the prompt below, in which case ONLY directories given subsequently will be searched Directory to search: <return when done>

Here is a list of directories in the order they will be searched for files:

C:\MyCache\mgr\journal\

C:\MyCache\mgr\

You may tailor the response to errors by choosing between the alternative actions described below. Otherwise you will be asked to select an action at the time an error actually occurs.

Either Continue despite database-related problems (e.g., a target database is not journaled, cannot be mounted, etc.), skipping affected updates

or Abort if an update would have to be skipped due to a

database-related problem (e.g., a target database is not journaled, cannot be mounted, etc.)

Either Abort if an update would have to be skipped due to a

journal-related problem (e.g., journal corruption, some cases of missing journal files, etc.)

or Continue despite journal-related problems (e.g., journal

corruption, some missing journal files, etc.), skipping affected updates Either Apply sorted updates to databases before aborting

or Discard sorted, not-yet-applied updates before aborting (faster) Would you like to specify error actions now? No => yes

1. Continue despite database-related problems (e.g., a target database is not journaled, cannot be mounted, etc.), skipping affected updates 2. Abort if an update would have to be skipped due to a database-related problem (e.g., a target database is not journaled, cannot be mounted, etc.)

Select option [1 or 2]: 1

1. Abort if an update would have to be skipped due to a journal-related problem (e.g., journal corruption, some cases of missing journal files, etc.)

2. Continue despite journal-related problems (e.g., journal corruption, some missing journal files, etc.), skipping affected updates

Select option [1 or 2]: 2

1. Apply sorted updates to databases before aborting

2. Discard sorted, not-yet-applied updates before aborting (faster) Select option [1 or 2]: 2

Based on your selection, this restore will

** Continue despite database-related problems (e.g., a target database is not journaled, cannot be mounted, etc.), skipping affected updates

** Continue despite journal-related problems (e.g., journal corruption, some missing journal files, etc.), skipping affected updates

** Discard sorted, not-yet-applied updates before aborting (faster)

C:\MyCache\mgr\journal\20061202.001