The Package Source tool provides a solution for users who make
changes to source received from a vendor and then at a later point
receive a revision from the vendor. The Package Source tool attempts
to re-make the changes automatically.
To understand the Package Source tool, there are three sets of source
files that will be discussed and two commands (MRGPKGSRC and
CVTPKGSRC). The commands copy (and modify) source from one file to
another.
******* MRGPKGSRC ******* *******
* * for new vers * * CVTPKGSRC * *
* SHP * --------------> * WRK * --------------> * RUN *
* * * * * *
******* ******* *******
Ship file which Work file Run file
contains the where changes which is the
source shipped are made actual source
from the vendor being used
(a compiled object
version exists)
To best understand the Package Source tool, an example will be used
of the steps you would go thru.
Example
-------
Assume that you have received source from a vendor for an
application. The source is in a file that will be called SHP.
You begin by creating two other source files:
** WRK source file where your changes will be made.
** RUN source file where the actual source (that which represents
what is really being run) will be placed.
Since you have not made any changes at this point, you would normally
begin by using CPYSRCF to copy all of the members from the SHP file
to the RUN file. It will represent what you are actually running in
your installation.
Assume that you want to make a change to member MBRA.
When you first make a change, you begin by using CPYSRCF (or the TAA
Tool DUPSRC) to copy the source from the SHP file to the WRK file for
MBRA. The WRK file is where all your modifications will be made.
You then invoke SEU to work on the MBRA member. The first thing you
must do is to place special comments into the source. The
STROLD/ENDOLD special comments bracket the existing source where the
change is to be made.
You should always bracket a reasonable number of statements (e.g. a
minimum of 5 statements) even if you are only going to change a
single line of source. Bracketing a unique set of source is critical
to the success of the PKGSRC function. See the later discussion on
how much you should bracket. The ENDNEW special comment marks the
end of the changes.
The source would then look like:
Stmt 1
Stmt 2
/**PKG** STROLD */
Stmt 3
Stmt 4
Stmt 5
Stmt 6
Stmt 7
/**PKG** ENDOLD */
/**PKG** ENDNEW */
Stmt 8
Stmt 9
You then copy statements 3 thru 7 after the ENDOLD special comment.
Note that you do not change any of the statements between STROLD and
ENDOLD (you do not make comments out of the source either). The
statements must remain exactly as they were in the SHP source.
Assume a change is needed to Statements 3 and 4 and a new statement
must be added.
After you make the changes, the source would look like:
Stmt 1
Stmt 2
/**PKG** STROLD */
Stmt 3
Stmt 4
Stmt 5
Stmt 6
Stmt 7
/**PKG** ENDOLD */
Revised stmt 3
New statement
Revised stmt 4
Stmt 5
Stmt 6
Stmt 7
/**PKG** ENDNEW */
Stmt 8
Stmt 9
The source as it exists in the WRK file cannot be used to compile
against because it includes both the old original source and the
modifications.
You now use the CVTPKGSRC (Convert Package Source) command to copy
the source. You can use a test file or go directly to the RUN file.
The CVTPKGSRC command drops out the statements between the
STROLD/ENDOLD brackets. A CRTxxxPGM is then run against the net
source. When the source has completed testing, the final version can
then be copied to the RUN source file (if it is not already there)
with the CVTPKGSRC command.
The CVTPKGSRC command would look like:
CVTPKGSRC WRKFILE (xxxx) RUNFILE(yyyy) MBR(MBRA)
You may make several sets of changes to the same MBRA source. Each
change should be bracketed with the STROLD/ENDOLD/ENDNEW special
comments.
Now assume that the vendor has shipped you a new set of source for
MBRA. You would use the MRGPKGSRC (Merge Package Source) command to
re-make the changes to the source member.
The command would look like:
MRGPKGSRC SHPFILE (xxxx) WRKFILE(yyyy) MBR(MBRA)
The MRGPKGSRC command will attempt to find the same set of statements
that you bracketed with the STROLD/ENDOLD special comments in the new
version of the RUN source.
** If MRGPKGSRC can find a complete match, your changes will be
merged into the new source and the WRK version is rewritten.
** If MRGPKGSRC cannot find a complete match, an error will be
sent and the existing WRK source version remains unchanged.
The spooled file will describe the error condition.
After you have run MRGPKGSRC, here are the typical situations:
** If the vendor made no changes in the new version of the SHP
source, the WRK source version statements would look exactly
as they did before. The sequence numbers may change (based on
what the vendor did) and the source change dates will probably
be changed.
** If the vendor had added or changed statements outside of the
STROLD/ENDOLD brackets, your changes have been merged into the
same place in the revised source as they were originally
(assumes what you had bracketed with STROLD/ENDOLD remains
unique in the SHP source).
** If the vendor added, deleted, or changed any statements
between the STROLD/ENDOLD brackets, the MRGPKGSRC command
would fail and the WRK source version would remain unchanged.
A spooled file would document what happened and note that you
will have to make the changes again manually.
When all of the changes have been made (either automatically by
MRGPKGSRC or via a manual change), the CVTPKGSRC command can be run
to drop the statements between the STROLD/ENDOLD brackets and produce
a version in the RUN file. The new version is ready to compile and
test.
When a new version arrives from the vendor you would normally use the
MBR(*ALL) function of both MRG/CVTPKGSRC. There is also a test
function (see the RPLxxx parameters on both commands) that lets you
determine what will happen if you let the commands update the source.
Advantages
----------
** The PKGSRC tool will put discipline into how changes are
documented in vendor supplied source. A consistent technique
is required.
** There are no special requirements for the vendor to follow.
He does not place any special comments in his source, note
what statements have changed, note what members have changed,
etc.
** The tool is independent of any assigned source sequence
numbers or date changes.
** Assuming a reasonable use of the tool on your part (e.g. good
bracketing) and that the vendor has not made wholesale
changes, most of the members that you have changed should
convert automatically without any manual changes on your part.
Testing is still required.
Points of interest
------------------
** Both MRGPKGSRC and CVTPKGSRC allow you to run against a single
member, generic members, or all members in the file. See the
MBR parameter on both commands. If a generic name is
specified, the member list for the entire SHP source file is
accessed and the member names that do not match are bypassed.
** Using MRGPKGSRC for either 'all members' or 'generic members',
you do not have to have a member in the WRK file for every
member in the SHP file. The SHP file member list is used and
the MRGPKGSRC command determines if a corresponding member
exists. If not, the member is bypassed and an entry in the
spooled file occurs denoting the fact.
For CVTPKGSRC, if a member does not exist in the RUN file, it
is added.
** The spooled file output will document what members have been
successful and what errors have been found.
** MRGPKGSRC allows you to run without replacing any of the
source in the WRK file. This allows you to try out a new
version without physically changing any of the WRK file
source. The spooled file will identify what would be
successful and any error conditions. See the RPLWRK
parameter.
CVTPKGSRC has a similar concept so that you can prevent
changing anything in the RUN file. This allows you to
determine if you have properly entered the special comments.
See the RPLRUN parameter.
** MRGPKGSRC allows you to resequence the sequence numbers or
retain the original SHP sequence numbers as close as possible.
If you choose not to resequence, new sequence numbers are made
by adding .01. See the RESEQUENCE parameter on MRGPKGSRC.
CVTPKGSRC allows you to resequence the net source written to
the RUN file or to retain the original sequence numbers. See
the RESEQUENCE parameter on CVTPKGSRC.
** CVTPKGSRC allows you to retain or delete the special comments
in the RUN source output. See the OUTPKGCMT parameter on
CVTPKGSRC.
** To prevent the programmer from making a change to the WRK
source and forgetting to put in the proper brackets, both the
MRG and CVT commands provide an option which defaults to
provide checking. See the later section on Date Change
Protection.
How much should you bracket with STROLD/ENDOLD
----------------------------------------------
You do not want to bracket a single statement or only a few
statements unless you are assured of uniqueness. As a guideline, try
to bracket at least 5 statements and try to include some unique
comment from the vendors source.
The purpose of bracketing a reasonable number of statements is to
provide some uniqueness. When MRGPKGSRC runs, it is looking for a
perfect match of the statements between STROLD/ENDOLD and the new
version in the SHP file. If the statements within the brackets are
not unique, MRGPKGSRC could make a wrong assumption about where your
change belongs.
Conversely, you don't want to bracket a lot of statements because you
are increasing the probability that the vendor will make a change and
prevent MRGPKGSRC from providing an automatic solution. It is
considered an error if you try to bracket more than one hundred
statements.
When MRGPKGSRC is comparing for the same set of source between the
brackets, it only compares the data portion of the source statement.
It does not compare the sequence numbers or the change date. In
addition to the data portion of the statements, the sequence of the
statements is also used to determine a unique set.
It is considered an error if you do not bracket any statements (e.g.
STROLD immediately followed by ENDOLD).
It is valid not to have any statements between ENDOLD and ENDNEW.
This is the way you would delete a block of statements from the SHP
source.
You can have a source file with up to 240 bytes of source data (plus
the 12 bytes for sequence number and change date).
Entering the special comments
-----------------------------
The special comments must be entered correctly or the MRG/CVTPKGSRC
commands will not be able to find them and an error will occur.
** RPG and DDS source are fixed format languages and the special
comment must take a form such as:
Pos 7
.
.
**PKG** STROLD
COBOL also uses an * in position 7 for a comment, so it uses
the same form.
** All other languages (e.g. CL, command definition) are
considered free form languages and the special comment must
begin in position 1 such as:
Pos 1
.
.
/**PKG** STROLD */
There must be only one space before the type of special comment (e.g.
STROLD) begins. Any characters can appear after the type of special
comment. In fact, it is a good idea to place additional comments on
the STROLD special comment such as:
/**PKG** STROLD Changes on 3/1/94 for unique warehouse */
Placing the date into the STROLD statement is a good practice because
the default of MRGPKGSRC will change the SEU change date of the
record. Any successful STROLD statement is also shown in the spooled
output as confirmation of correct handling.
MRG/CVTPKGSRC automatically determine the type of source by
extracting the information from the member. You do not specify the
type of source on either command.
Date change protection
----------------------
A typical error that can be made using the PKGSRC tool is for the
programmer to make a change in the WRK file without using the
brackets. For example, he just changes a statement that is outside
of the brackets. If this occurs, the change would be lost the next
time the MRGPKGSRC command is run.
To protect against this type of error, the commands provide a
checking technique by default.
** When MRGPKGSRC is run, the default for the USRDATCHG parameter
is *YES. This means that any statements between ENDOLD and
ENDNEW will be output with the current date as the SEU change
date. This forces all of the user changes within the
ENDOLD/ENDNEW brackets to appear to have been made on the date
that MRGPKGSRC is run.
** When CVTPKGSRC runs using the default of *YES for the CHKDATE
parameter, it will ensure that any statement from outside of
the STROLD/ENDOLD brackets is not more current that the oldest
change date of a statement within the ENDOLD/ENDNEW brackets.
Thus if the programmer had made a change outside of the brackets, the
date of the changed source statement would be more current than the
oldest date within the ENDOLD/ENDNEW brackets and the CVTPKGSRC
command would fail with a date change error.
If you specify the MRGPKGSRC command as USRDATCHG(*NO), the source
date changes of the modifications will not be changed and you will
want to specify CVTPKGSRC as CHKDATE(*NO) to prevent an error from
occurring.
How does MRGPKGSRC work
-----------------------
The MRGPKGSRC command does the following:
** It reads the source from the WRK version of the member.
** When the STROLD special comment is found, the source from the
SHP version is read looking for the same set of statements
that were included in the STROLD/ENDOLD brackets. The SHP
statements are written to a temporary file until a matching
set of statements is found.
** If a matching set is found, the same STROLD/ENDOLD special
comments and the source within the brackets are output to the
temporary file.
** The statements from the WRK source member up to and including
the ENDNEW bracket are then output to the temporary file.
** The loop begins again of reading the WRK file for another
STROLD special comment.
** When there are no more STROLD special comments found, the
remainder of the RUN file is read and output to the temporary
file.
** If there are no errors, the temporary file is then copied back
to the WRK source member (replaces it).
If you specify MBR(*ALL), the MRG command:
** Gets a list of the members in the SHP source file.
** Determines if the same member exists in the SHP file and if so
it starts the processing for that member in the WRK file as
described previously.
** If no corresponding member exists in the WRK file, the SHP
member is ignored. An entry in the spooled listing will
occur.
** When all members have been processed, the list of members from
the WRK file is accessed and a check is made to determine if a
corresponding member exists in the SHP file. If not, an error
is posted in the spooled file. The intent is that the WRK
file should only contain modifications to the SHP source.
If a generic member name is used:
** The list of member names is accessed from the SHP file.
** Only members that match the generic name are checked to see if
a corresponding member exists and processing of that member
occurs as described previously.
** It is considered an error if no members are found with the
generic name or no corresponding members are found in the WRK
file. At least one member must be processed.
How does CVTPKGSRC work
-----------------------
The CVTPKGSRC command does the following:
** It reads the WRK member looking for a STROLD special comment.
Any statements prior to STROLD are output to a temporary file.
** If STROLD is found, all the statements up to the ENDOLD are
dropped.
** The statements between the ENDOLD/ENDNEW brackets are output
to the temporary file.
** The special comments are output to the temporary file based on
the OUTPKGCMT parameter.
** If the member does not have any errors, the temporary file is
used to replace the version in the RUN file. If no
corresponding member exists in the RUN file, a member is
added.
If MBR(*ALL) is specified, a list of members in the WRK file is
accessed and each is processed.
If a generic member name is specified, a list of members in the WRK
file is accessed and only the matching generic names are processed.
Error conditions
----------------
Several error conditions are checked for such as:
** The MRG/CVTPKGSRC commands rigorously check the source to
ensure that the special comments are paired correctly and in
the correct sequence. For any change, you must always have
the STROLD, ENDOLD, and ENDNEW special comments and in the
correct sequence.
** If the MRGPKGSRC command does not find a STROLD special
comment anywhere in the source, it is considered an error.
** You must have at least one statement between the STROLD and
ENDOLD special comments.
** If the MRGPKGSRC command does not find a complete match for
the statements between the STROLD/ENDOLD brackets, it is an
error.
** If you specify a single member for MRGPKGSRC, a member of the
same name in both the SHP and WRK source files must exist.
** When MRGPKGSRC is requested for MBR(*ALL), the member list
from the SHP file is accessed and a corresponding member is
looked for in the WRK file. If none exists, it is not
considered an error and the member is bypassed. When the SHP
member list is complete, the WRK file member list is accessed
and a check is made to see if there is corresponding member in
the SHP file. If not, it is considered an error.
** Before changing any members, the corresponding member types
are checked. If they differ, an error will occur.
** If the member to be written to cannot be allocated to an *EXCL
lock state, it is considered an error.
Compiling from test source or the RUN source
--------------------------------------------
The PKGSRC tool does not provide for any CRT steps. It only handles
the process of changing the source.
The TAA Tool EXCSRC can be used to handle the create step. Neither
EXCSRC nor PKGSRC have any dependencies on each other. They can be
used independently.
EXCSRC allows you to define one or more commands for each object you
want to create. The commands are placed in a source member and
identified with a beginning label. You can have one or more commands
for each object that needs to be created and you can use variable
values for such things as the source file, source library, and the
library to create the object in.
You can make EXCSRC a user defined option for PDM.
Thus it is possible with EXCSRC to specify that a CVTPKGSRC command
be run to place the output in a test library and that the CRTxxxPGM
command also be run using the test library as input and a test
library for the created object. This could be the default if EXCSRC
was executed from PDM. A unique version of the EXCSRC command could
be used when the source was ready for production that would output to
the RUN file and create the object in the production library.
The EXCSRC source might look like:
MBRA: CVTPKGSRC WRKFILE(xxx/QCLSRC) +
RUNFILE(&PRMSRCLIB/QCLSRC) +
MBR(MBRA)
CRTCLPGM PGM(&PRMOBJLIB/MBRA) +
SRCFILE(&PRMSRCLIB/QCLSRC)
The & names represent values that would be specified on the EXCSRC
command. When EXCSRC executes the statement, it will substitute the
command values.
For a full explanation of EXCSRC and how to create a PDM option that
will allow a simple create for the programmer, see the documentation
for the EXCSRC tool.
MRGPKGSRC Command parameters *CMD
----------------------------
SHPFILE The qualified file name of the file containing the
source shipped by the vendor. The library value
defaults to *LIBL.
WRKFILE The qualified file name of the file containing the
source as modified by you. The library value
defaults to *LIBL.
MBR The member to be converted. A specific member name,
a generic name, or the special value *ALL may be
used to process all members.
RPLWRK A *YES/*NO value that determines if the source in
the WRK file will be replaced. The default is *YES.
*NO should be used when you want to test how
successful the function will be. If any errors
occur, the source will not be written to the WRK
file for the member in error.
RESEQUENCE A *YES/*NO value that determines if the source
written to the WRK file will have the source
sequence numbers resequenced. The default is *NO.
Using the default, any inserts from the WRK file
member are written by adding .01 to the last
sequence number output. If *YES is specified, each
statement is incremented by 1.00 as it is output.
USRDATCHG A *YES/*NO value that determines if the user
modified source (the statements between ENDOLD and
ENDNEW) should be output with the current date.
*YES is the default and is used to assist in
preventing the programmer from changing a statement
outside of the brackets. See the previous section
on Date Change Protection.
CVTPKGSRC Command parameters *CMD
----------------------------
WRKFILE The qualified file name of the file containing the
source as modified including the special comments.
The library value defaults to *LIBL.
RUNFILE The qualified file name of the file containing the
net source that you want to compile against. Any
statements between STROLD/ENDOLD are removed.
MBR The member to be converted. A specific member name,
a generic name, or the special value *ALL may be
used to process all members.
RPLRUN A *YES/*NO value that determines if the source in
the RUN file will be replaced. The default is *YES.
*NO should be used when you want to test how
successful the function will be. If any errors
occur, the source will not be written to the RUN
file for the member in error.
RESEQUENCE A *YES/*NO value that determines if the source
written to the RUN file will have the source
sequence numbers resequenced. The default is *NO.
Using the default, the existing sequence numbers in
the WRK file are used when writing to the RUN file.
If *YES is specified, each statement is incremented
by 1.00 as it is output to the RUN file.
CHKDATE A *YES/*NO value that determines if the date
checking protection should be used. *YES is the
default. *NO should be used to turn off the
checking. If you have specified USRDATCHG(*NO) on
the MRGPKGSRC command, you will need to specify
CHKDATE(*NO). See the previous section on Date
Change Protection.
OUTPKGCMT A *YES/*NO value that determines if the special
comments should be included in the output source.
The default is *YES. If you specify *NO, the
special comments will be dropped.
Restrictions
------------
The PKGSRC tool uses a convention that must be followed for the tool
to be successful.
** You must properly bracket any changes.
** You must bracket a unique set of statements.
** You cannot make changes outside of the brackets.
The success of automating the re-making of your changes to a new
version is highly dependent on what the vendor does to the source and
what you bracketed.
The PKGSRC tool is not a perfect solution, but if used correctly, you
should be able to automate most of the re-making of changes.
Prerequisites
-------------
The following TAA Tools must be on your system:
ALCTMPMBR Allocate temporary member
CHKGENERC Check generic
HLRMVMSG HLL Remove message
RTVDAT Retrieve date
SNDCOMPMSG Send completion message
SNDESCMSG Send escape message
SNDSTSMSG Send status message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
MRGPKGSRC *CMD TAASRDG QATTCMD
CVTPKGSRC *CMD TAASRDG2 QATTCMD
TAASRDGC *PGM CLP TAASRDGC QATTCL
TAASRDGC2 *PGM CLP TAASRDGC2 QATTCL
TAASRDGC9 *PGM CLP TAASRDGC9 QATTCL
TAASRDGR *PGM RPG TAASRDGR QATTRPG
TAASRDGR2 *PGM RPG TAASRDGR2 QATTRPG
Structure
---------
MRGPKGSRC Cmd
TAASRDGC CL pgm
TAASRDGR RPG Pgm
TAASRDGC9 CL pgm
CVTPKGSRC Cmd
TAASRDGC2 CL pgm
TAASRDGR2 RPG Pgm
|
