Convert Journal Files Using ^JCONVERT and ^%JREAD
The ^JCONVERT routine is a utility that reads journal files and converts them to a common file in variable record format. The ^%JREAD utility can then read this file 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 InterSystems IRIS. 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 InterSystems IRIS and need to minimize downtime, perform the following steps:
-
Enable journaling on the old system.
-
Run a backup on the old system; this switches to a new journal file on the old system.
-
Continue journaling on the old system.
-
Restore the backup of the old system on the new system and perform any necessary conversions.
-
Stop the old system and run ^JCONVERT on the journal files created on the old system since the backup.
-
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 Restore Globals From Journal Files Using ^JRNRESTO for details on selecting and filtering journal files.
The converted file is in variable record format. The default character encoding is UTF8, which is compatible with the current ^%JREAD utility on all platforms, and can be moved among platforms with binary FTP. If you answer NO at the Use UTF8 character translation? prompt, no character encoding is applied.
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 modifying 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 [ IRIS Format --> Common Format ]
The converted file will be in variable record format.
The default character translation UTF8 is compatible with current ^%JREAD
on all platforms and can be moved among platforms with binary FTP.
If you answer NO, no character translation will be applied.
Use UTF8 character translation? <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
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: <20231201.001> [?] => 20231202.001
through: <20231204.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:\MyIRIS\mgr\journal\
C:\MyIRIS\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:\MyIRIS\mgr\journal\
C:\MyIRIS\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:\MyIRIS\mgr\journal\20231202.001
13.98% 14.93% 15.95% 17.14% 18.25% 19.27% 20.49% 21.63% 22.65% 23.84%
24.99% 25.97% 27.10% 28.25% 29.31% 30.50% 31.72% 32.84% 33.84% 34.84%
35.84% 36.85% 37.91% 38.99% 40.10% 41.08% 42.03% 42.97% 43.93% 44.94%
45.95% 47.05% 48.11% 49.07% 50.04% 51.02% 52.03% 53.07% 54.14% 55.25%
56.21% 57.17% 58.15% 59.14% 60.18% 61.24% 62.33% 63.28% 64.20% 65.15%
66.10% 67.11% 68.13% 69.05% 69.94% 70.83% 71.61% 72.41% 73.09% 73.85%
74.59% 75.32% 76.06% 76.75% 77.73% 78.70% 79.65% 80.59% 81.53% 82.46%
83.40% 84.33% 85.27% 86.05% 86.59% 87.13% 87.67% 88.23% 88.78% 89.34%
89.89% 90.61% 93.28% 94.38% 97.12% 98.21% 99.93%100.00%
***Journal file finished at 11:31:36
C:\MyIRIS\mgr\journal\20231203.001
14.01% 14.96% 15.98% 17.18% 18.29% 19.31% 20.53% 21.67% 22.69% 23.88%
25.03% 26.01% 27.15% 28.30% 29.36% 30.55% 31.78% 32.90% 33.90% 34.90%
35.91% 36.92% 37.99% 39.06% 40.17% 41.16% 42.11% 43.05% 44.01% 45.03%
46.04% 47.14% 48.20% 49.17% 50.14% 51.11% 52.13% 53.17% 54.25% 55.36%
56.33% 57.29% 58.27% 59.26% 60.30% 61.36% 62.46% 63.40% 64.33% 65.28%
66.23% 67.24% 68.26% 69.19% 70.08% 70.97% 71.76% 72.56% 73.25% 74.01%
74.75% 75.47% 76.22% 76.91% 77.89% 78.87% 79.83% 80.77% 81.70% 82.64%
83.58% 84.52% 85.46% 86.24% 86.78% 87.32% 87.87% 88.42% 88.98% 89.53%
90.09% 90.81% 93.49% 94.59% 97.33% 98.42%100.00%
***Journal file finished at 11:31:37
C:\MyIRIS\mgr\journal\20231204.001
13.97% 14.92% 15.93% 17.12% 18.24% 19.25% 20.47% 21.61% 22.62% 23.82%
24.96% 25.94% 27.07% 28.22% 29.28% 30.46% 31.69% 32.80% 33.80% 34.80%
35.80% 36.81% 37.87% 38.94% 40.05% 41.04% 41.98% 42.92% 43.88% 44.89%
45.90% 47.00% 48.06% 49.02% 49.98% 50.96% 51.97% 53.01% 54.08% 55.19%
56.15% 57.11% 58.08% 59.07% 60.12% 61.17% 62.26% 63.20% 64.13% 65.07%
66.02% 67.03% 68.05% 68.97% 69.86% 70.75% 71.53% 72.33% 73.01% 73.77%
74.51% 75.23% 75.98% 76.67% 77.64% 78.61% 79.56% 80.50% 81.43% 82.37%
83.30% 84.24% 85.17% 85.95% 86.49% 87.03% 87.57% 88.13% 88.68% 89.23%
89.79% 90.51% 93.18% 94.27% 97.01% 98.10% 99.81%100.00%
***Journal file finished at 11:31:38
[journal operation completed]
Converted 26364 journal records
