The Apply User Journal Changes command is an alternative to the i5/OS
supplied APYJRNCHG command.
APYJRNCHG is very strict in what it allows:
** The file being applied to must be the same file that was
journaled. You cannot apply to a duplicate of the file.
** If a file is restored, the file must have been being journaled
when it was saved.
When a file is journaled, a special internal identification is used.
The internal ID of the file and the journal entry must match to allow
the apply to take place. The system ensures that the unique ID is
used only once per system. Therefore:
** You cannot save the file being journaled, restore it to a
different library on the same system and expect APYJRNCHG to
work successfully to the duplicate file.
** It is possible to transport the journal receiver from one
system to another and apply the journal changes using
APYJRNCHG. This requires that the original file be restored
on the second system so that the internal ID is the same when
the apply occurs. The Programmers Guide has a detailed
explanation.
The TAA tool APYUSRCHG works with converted journal entries. The
conversion to a data base file must be done by the DSPJRN command
using OUTFILFMT(*TYPE1). Once the conversion has occurred, APYUSRCHG
will allow you to apply journal changes to the original file or a
duplicate file. Several internal checks are made to help provide
integrity (see later discussion), but in general you can use
APYUSRCHG and bypass the major restrictions of the system supplied
command.
To use APYUSRCHG, you must first convert the journal entries to a
data base file using the DSPJRN command. DSPJRN allows you to
control what file/entries you want to be converted, the journal
receivers to be used, the journal entry to start at etc.
*****************
* *
* Journal *
* Receiver *
* *
*****************
*
*
DSPJRN ....... ENTDTALEN(xxx)
*
*
DSPJRN OUTFILE
*************************************************************
* 125 Bytes * Nbr of bytes per ENTDTALEN parm *
* Standard fields ***************************************
* eg File, member, * * *
* RR number ... * Physical record image * *
*************************************************************
A typical command would be to convert all of the journal entries for
the current journal receiver such as:
DSPJRN JRN(JOURNAL(X) ENTDTALEN(500) JRNCDE(R)
OUTPUT(*OUTFILE) OUTFILE(LIB1/JRNOUTP)
The ENTDTALEN parameter is very important. It must be specified to
hold the largest physical record being journaled. If it is less than
the largest physical record length, the APYUSRCHG command will not
apply changes for that file.
The use of JRNCDE(R) only converts the 'record' entries that appear
in the journal. These are the only journal entries processed by
APYUSRCHG. If other entries exist, they will be bypassed by
APYUSRCHG. See the later discussion on the specific entry types
processed.
A typical command to apply all of the changes would be:
APYUSRCHG DSPJRNOUT(JRNOUTP)
A report is printed to QPRINT which describes the number of entries
applied for each file/member. If an error has occurred on a member,
the problem is identified. No further updates to that member will
occur.
Because the records are sorted by relative record number (not by
date), the function is year 2000 ready.
Applying the changes to a duplicate file
----------------------------------------
APYUSRCHG will allow you to apply the changes from one file to a
duplicate of the file. Normally you would create the duplicate with
CRTDUPOBJ or a restore to a different library (See the later
discussion).
Only one file can be applied per use of APYUSRCHG when applying to a
duplicate file. A typical command to do this would be:
APYUSRCHG DSPJRNOUT(JRNOUTP) JRNLDFILE(LIB1/FILEA)
TOFILE(LIB1/FILEA2)
APYUSRCHG typical uses
----------------------
** Assume you started journaling and forgot to save the file
after journaling was started. If the file is restored from a
saved version that occurred before journaling was started, the
APYJRNCHG command cannot be used. APYUSRCHG could be used.
** Assume you have a file that must be online for update 24 hours
a day during the week. It cannot be backed up during the week
because the file is always open for update and you do not want
to use the system SAVWHLACT function. Assume you have many
journal changes. If you backup the file on the weekend, the
recovery time to restore the last backup and apply many
changes could be significant.
** APYUSRCHG can be used to minimize the recovery time. A second
file would be created on the same system which is a duplicate.
This must be done while the first file is static (no one is
updating it) so that the relative record numbers are
synchronized (CRTDUPOBJ would be a good choice). You would
apply the journal changes to the duplicate using APYUSRCHG.
Assume you apply all of the days changes once or twice a day
and then save the duplicate file at night.
With this technique, if the file needs to be recovered, you
only need to apply the last set of changes to the duplicate
with APYUSRCHG and then use CPYF or MOVOBJ to replace the
original file.
** Assume you have a file that must be online for update 24 hours
a day and 7 days a week. The file cannot ever be backed up
because some user always has the file open for update and you
do not want to use the system 'Save While Active' function.
APYUSRCHG can be used to keep a duplicate file on line so that
in the event recovery is needed, it is possible.
A second file would be created on the same system which is a
duplicate of the first. This must be done while the first
file is static (no one is updating) so that the relative
record numbers are synchronized (CRTDUPOBJ is a good choice).
You would apply the journal changes to the duplicate using
APYUSRCHG. Assume you apply all of the days changes once or
twice a day and then save the duplicate file at night.
With this technique, if the file needs to be recovered, you
only need to apply the last set of changes to the duplicate
with APYUSRCHG and then use CPYF or MOVOBJ to replace the
original file.
Note that the system does not support the capability to have
the application available all of the time. There are several
conditions that require either a dedicated system (e.g.
SAVSYS), a re-IPL (reset the address counters) or a down
period (e.g. installing a new release).
** Assume you are journaling many files on your system and/or
using access path journaling. You want to duplicate one or
more of the journaled files on other systems. To do this, you
need to take the journal changes from your system and apply
them on other systems.
You can transmit a journal receiver from your central system
to the remote systems, but the receiver probably contains many
entries for files or access path changes that you do not want
to transmit. If you are using access path journaling, the
receiver can be very large.
You can extract the entries for the files you want duplicated
on other systems with DSPJRN. The smaller file would then be
transmitted to the other systems and APYUSRCHG used. You
might also consider summarizing the entries before
transmission (See the TAA tool SUMJRNENT).
Entry types processed
---------------------
APYUSRCHG will only process the JOCODE = R type journal entries. If
other entries exist, they will be bypassed.
For 'R' type, the typical entries of PT (Add), UP (Update) and DL
(Delete) are processed.
Also processed are:
DR Delete rollback. If you are using commitment
control, this entry will appear if you added a
record and then a rollback occurred. These entries
are treated as DL types.
UR Update rollback. If you are using commitment
control, this entry will appear if you updated or
deleted a record and then a rollback occurred. The
entry contains the record image that must be put
back into the data base. APYUSRCHG will treat this
as a UP type if the record exists and as a PX type
if the record does not exist.
PX Put direct. This entry will appear if you write to
a specific relative record number rather than add at
the end of the file. Both COBOL and RPG can create
this type of entry. RPG requires that the RECNO
file continuation function be used. When PX is
used, it normally means that you have used INZPFM
and initialized the file to a number of deleted
records. To properly handle this record type,
special handling is used by APYUSRCHG.
The UP = Update Before journal entry caused by commitment control is
bypassed by APYUSRCHG.
Making a duplicate of a file
----------------------------
If you are making a duplicate of a file and using APYUSRCHG, you must
be sensitive to the relative record numbers if deleted records exist
in the file. Any SAV command and CRTDUPOBJ will maintain the
existing relative record numbers.
If the duplicate file is on the same system as the original file, you
may need to copy the duplicate back to the original for recovery
purposes.
CPYF requires two parameters be specified to duplicate a file with
the same relative record numbers.
** FROMRCD(1). This ensures that even if a keyed file is
specified that the copy will be in arrival sequence order.
** COMPRESS(*NO). The default for CPYF is to compress out
deleted records. Specifying *NO causes the deleted records to
be copied.
Checking performed by APYUSRCHG
-------------------------------
To prevent errors being caused by APYUSRCHG, several integrity checks
are performed:
** The length of the 'entry data length' in the journal entry
must match the length of the file being applied to. If you
have changed the file format (so it is longer or shorter),
this will prevent the apply. If you did not specify the
ENTDTALEN value correctly on DSPJRN (e.g. you did not allow
enough room for the physical record image), this will also
prevent the apply.
** If an update or delete journal entry exists, the relative
record number of the record must exist in the file.
** If an add (PT) journal entry exists, the relative record
number of the record must not exist. Additions always occur
at the end of the file. After adding the record, the relative
record (RR) number of the journal entry is compared against
the RR number of the record added (the file feedback
information is used). If they differ, an exception is noted
and no more updates occur to the member.
Performance
-----------
To provide good performance for APYUSRCHG, the journal entries are
sorted by relative record number within each member. This allows the
member to be opened only once per use of APYUSRCHG. If an add or
delete journal entry exists, the data base change is made
immediately. All update entries are read in sequence, but only the
last update (it contains the full record image) is used to update the
data base.
Sorting the records in relative record number order not only
minimizes the number of opens and updates, but also causes less
random disk arm movement to process thru the file.
APYUSRCHG is written to handle up to 2000 byte record lengths. If a
record size exceeds this, you can change the code to handle it. The
2000 limit allows most records to be handled properly and still
provides reasonable performance. See the later section on how to
change the program to handle larger values if needed.
One of the major factors that influences the performance of the
APYJRNCHG command is the average number of access path changes that
each entry causes. If you tend to have several updates for the same
relative record and each update causes several access path changes,
the advantage of accumulating the updates can be very significant for
APYUSRCHG versus APYJRNCHG.
Command parameters *CMD
------------------
DSPJRNOUT The qualified name of the data base file that was
specified as the output file for DSPJRN. The
library defaults to *LIBL.
JRNLDFILE The qualified name of the data base file that was
journaled. The default is *ALL. Normally, you will
want to use DSPJRN to subset the files that you want
to apply to. However, if you already have converted
the journal entries with DSPJRN, you can apply one
file at a time with APYUSRCHG.
Note that if you use a specific file name, you enter
the name of the file that was journaled. By
default, this is the file that will be applied to.
If you want to apply to a duplicate file, see the
TOFILE parameter.
JRNLDMBR The member of the JRNLDFILE to be applied to. The
default is *ALL. If an individual file is
specified, either all members of the file or a
specific member will be applied to. *ALL may be
used if the file has only a single member.
TOFILE The file to be applied to. The default is
*JRNLDFILE. Specifying a file allows you to use the
journal entries that occurred from one file to be
applied to a duplicate file. If a file is named,
JRNLDFILE cannot be *ALL.
Only a single file can be named, therefore each use
of applying to a duplicate file requires a separate
APYUSRCHG command to be run.
TOMBR The member to be applied to. The default is
*JRNLDMBR. If a specific entry is used, the
JRNLDFILE parameter cannot be *ALL.
If you are applying to a duplicate file, one or all
members can be applied to in a single execution of a
APYUSRCHG command. The default of *JRNLDMBR when
JRNLDMBR(*ALL) is specified may be used if the file
has only a single member.
SORTED A *YES/*NO value that defaults to *NO. The Reformat
Utility is used to sort the journal entries to
minimize the number of updates (if multiple updates
to the same RR number have occurred) and to minimize
disk arm movement. If you have already sorted the
entries, you can bypass this step. The sequence
that the entries should be sorted is (the field
names refer to the values in the DSPJRN output
format):
JOLIB
JOOBJ
JOMBR
JOCTRR
Since the Reformat Utility defaults to sort
duplicates in arrival sequence order, multiple
updates to the same RR number will be in sequence.
If you sort the records, you must ensure this
sequence.
Restrictions
------------
** The file and member to be applied to must exist. It is
possible to apply to a duplicate file without the original
file or member existing.
** A physical file may not exceed 2000 bytes in record length.
If you have files that exceed this length, you can change the
program to allow for it. See the later section.
** APYUSRCHG only does a forward apply. It cannot be used to
'back down' the data base such as with the RMVJRNCHG command.
** Just like the APYJRNCHG command, APYUSRCHG is totally
dependent on consistent relative record numbers to apply. If
you reorganize the file or copy it without COMPRESS(*NO), the
relative record numbers are likely to change. Although some
logical errors will be found by APYUSRCHG, you must be careful
in how you are performing the apply.
The APYJRNCHG command prevents the apply from crossing a
boundary such as RGZPFM. APYUSRCHG assumes that you are in
control of when RGZPFM, CLRPFM or INZPFM have occurred and are
working with the proper set of journal entries to be applied.
If the file was initialized to deleted records, the recovery
steps should do the same initialization function. Normally,
these means that the file should be restored from backup
media.
Handling larger than 2000 byte records
--------------------------------------
To provide better performance, APYUSRCHG is written to handle
physical record lengths up to 2000 bytes. The following describes
the changes needed to increase the size.
** At about statement 2.00, 3.00 and 8.00 are the file
descriptions. The record size is 2125. Each journal entry
has 125 bytes of heading information. If your largest record
length is 5000 bytes, change the '2125' values to 5125.
** At about statement 35.00 is the input field description of the
JOESD field. This is the length of your largest data record.
The 'from position; should remain 126. The 'to position'
should be changed. If your largest record size is 5000 bytes,
change the '2125' value to 5125.
** At about statement 46.00 is the JOESD field described as a
data structure to avoid the RPG maximum field length
restriction. If your largest record length is 5000, change
the '2000' value to 5000.
** At about statement 110.00 is the test to ensure that the
program is not being requested to update a record greater than
the maximum record length specified in the program. If your
largest record length is 5000, change the '2000' value to
5000.
** At about statements 358.00, 360.00 and 362.00 are the output
locations for the field JOESD. If your largest record length
is 5000, change the '2000' values to 5000.
Security considerations
-----------------------
Normal security is used. The user of the APYUSRCHG command must be
authorized to make changes to each of the files to be applied to.
You may want to control who is authorized to use APYUSRCHG and
prevent public use of the command.
Prerequisites
-------------
The following TAA Tool must be on your system:
SNDCOMPMSG Send completion message
SNDESCMSG Send escape message
SNDSTSMSG Send status message
SORTDB Sort data base
Implementation
--------------
The tool is ready to use.
See the previous discussion on the use of DSPJRN to convert the
journal receiver entries so they can be processed by APYUSRCHG.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
APYUSRCHG *CMD TAAJRNG QATTCMD
TAAJRNGC *PGM CLP TAAJRNGC QATTCL
TAAJRNGR *PGM RPG TAAJRNGR QATTRPG
|
