The CPYCMD command is designed for Command definition source and
allows you to copy in source from another member. CPYCMD acts
somewhat as an 'include' or the RPG /COPY statement. It provides a
solution for having standard source that will change and must appear
in several source members.
The normal solution when you have some standard source that you want
to copy into Command definition source is to use the SEU copy
function (F15). The disadvantage to this is that when the standard
source changes, you have a lot of work to find all of the places
where you have done the copy, change the source of many members, and
do the re-creates.
The advantage of CPYCMD is that you can significantly reduce your
effort when the standard source must be changed.
CPYCMD Function
---------------
The CPYCMD function is not the same as an 'include' like the RPG
/COPY statement. In some ways it is actually better.
The major difference is that the CPYCMD command is not part of the
CRTCMD function. Therefore, you must remember to use CPYCMD before
creating the command.
Once you have used CPYCMD, the standard source exists in your normal
source member. The standard source acts as normal source so if you
create the command, you get the desired results.
If the standard source is changed, there is a special companion
command (CRTCPYCMD) which is described later that will do the work
for you of finding the places where you have used the standard
source, refreshing the source member, and re-creating the commands.
If you use a function like the RPG /COPY and your standard source
changes, you must determine all of the places you have used the
function and re-create the commands one at a time. CRTCPYCMD
provides a better solution than this.
Special comment statements are used to describe what must be copied.
Assume you are entering source into MBR1 and want to copy the
contents of STDSRC1. In MBR1, you would enter the special STRCPYCMD
comment at the location you wanted STDSRC1 copied.
Pos
1
PARM KWD(xxx)
/*STRCPYCMD STDSRC1 */
PARM KWD(yyy)
After you end SEU, use CPYCMD against the same member.
CPYCMD SRCMBR(MBR1) FROMSRCF(xxxx)
CPYCMD reads the MBR1 source and looks for the special statement.
When it is found, the source is extracted from STDSRC1 and copied
into the MBR1 source in a temporary member. The STRCPYCMD comment is
changed slightly and an ENDCPYCMD comment is added.
See the later section about whether comments in your standard source
are copied.
When all statements have been copied and there are no errors, the
temporary member is written back to your source member. The source
statements are always renumbered 1.00, 2.00 etc. See the later
discussion on writing to a different member.
The results in MBR1 would look like this:
Pos
1
PARM KWD(xxx)
/*STRCPYCMD - FOLLOWS - STDSRC1 */
.
. The source from STDSRC1
.
/*ENDCPYCMD */
PARM KWD(yyy)
The purpose of changing the STRCPYCMD comment and adding the
ENDCPYCMD comment allows you to see what was copied as standard
source and to provide a boundary for refreshing the standard source.
For copying a partial statement (for example, not all of the keywords
for a PARM statement), see the section on Partial Statements.
You can have as many STRCPYCMD comments in one source member as
needed. Each time you use CPYCMD, it will refresh the source from
the members you name on the STRCPYCMD comments.
The STRCPYCMD comment may not exist in the source being copied (No
nesting is allowed).
Note that your source is not rearranged. The only changes are the
insertion of the copied in source and the STR/ENDCPYCMD comment
statements.
To assist you in specifying the STRCPYCMD comment correctly, there is
a very rigid syntax of the STRCPYCMD comment.
- It must begin in position 1
- The exact characters /*STRCPYCMD must be used
- There must be one (and only one) blank before the member name
- There must be at least one blank after the member name
- There must be at least one blank after the optional file name
- Because STRCPYCMD is a comment, it must end with a */
By default, CPYCMD will look for your member name in the same source
file as the member named on CPYCMD. You can optionally add a file
name or a qualified file name.
The three valid choices would look like:
Pos
1
/*STRCPYCMD MBR1 */
/*STRCPYCMD MBR1 QCMDSRC */
/*STRCPYCMD MBR1 LIB1/QCMDSRC */
There must be at least one blank after the member name and after the
file name. There can be no other characters in the line other than
the ending */.
Invalid syntax:
Pos
1
1. /*STRCPYCMD MBR1 */
2. /*STRCPYCMD MBR1 */
3. /*STRCPYCMD MBR1 QCMDSRC*/
4. /*STRCPYCMD MBR1 QCMDSRC
5. /*STRCPYCMD MBR1 LIB1/ */
6. /*STRCPYCMD MBR1 LIB1/QCMDSRC XXX */
Invalid reasons:
1. The /*STRCPYCMD does not start in pos 1.
2. There is more than one space before MBR1.
3. There is no blank after the file name.
4. There is no ending */.
5. There is no file name.
6. There are other characters after the file name.
When CPYCMD has copied the source into your member it adds the text
'- FOLLOWS -' right after the STRCPYCMD text and retains your member
name (also library/file if specified). You should not make any
changes to the STRCPYCMD or ENDCPYCMD comments. They must exist 'as
is' in order for CPYCMD to be used again on the same source.
If you want to delete all of the copied in source (and the ENDCPYCMD
comment), you should change the STRCPYCMD comment to look like the
version before CPYCMD is used. For normal use, there is no reason to
do this. If the standard source changes, you just use CPYCMD again
and it will refresh the source.
If you want to prevent the use of CPYCMD, just remove the STRCPYCMD
and ENDCPYCMD comments. The copied in source is now part of your
source member.
CPYCMD will ensure that if a FOLLOWS comment exists, that there must
be a matching ENDCPYCMD statement.
You can have any value in your standard source as long as the final
source makes sense to the CRTCMD command.
Partial Statements
------------------
Assume that you want to copy in a list of values to add onto a
partial PARM statement such as:
PARM KWD(OBJTYPE) TYPE(*CHAR) LEN(7) DFT(*ALL) +
EXPR(*YES) RSTD(*YES) VALUES(*ALL +
If you enter a normal STRCPYCMD comment statement such as:
/*STRCPYCMD STDSRC1 */
an error will occur when creating the command because the comment
does not have a continuation symbol (+ or -).
CPYCMD uses a convention for this case.
** If you are copying the middle of a PARM statement, end the
comment with a + symbol such as:
PARM KWD(OBJTYPE) TYPE(*CHAR) LEN(7) DFT(*ALL) +
EXPR(*YES) RSTD(*YES) VALUES(*ALL +
/*STRCPYCMD STDSRC1 */ +
) PROMPT('Object type')
** If you are copying the remainder of the PARM statement (such
as more values and the PROMPT keyword), end the comment with a
- symbol such as:
PARM KWD(OBJTYPE) TYPE(*CHAR) LEN(7) DFT(*ALL) +
EXPR(*YES) RSTD(*YES) VALUES(*ALL +
/*STRCPYCMD STDSRC1 */ -
The + symbol tells CPYCMD to place a + at the end of both the STR and
END special comments.
The - symbol tells CPYCMD to place a - at the end of the STR comment
and no continuation value at the end of the END special comment.
If the STR special comment ends without either a + or -, CPYCMD
assumes you are copying an entire statement (not a partial
statement).
When using a partial statement, you may have a syntax error in either
the normal source or your standard source or both when the source is
initially entered. After running CPYCMD, the normal source should be
in the correct syntax to create the command.
Handling of comments in the standard source
-------------------------------------------
CPYCMD uses a convention as follows:
If the /* value begins in Column 1 of the source, the comment
will not be copied.
Thus you could set up your source as follows:
Pos
1
/* A comment that is not copied */
/* A second comment that is not copied */
/* A comment that is copied */
Using a different To file
-------------------------
By default, CPYCMD will write back to the same member in the same
file. You can name a different TOSRCF and write to a totally
different source file (the same member name is always used).
CPYCMD Escape messages you can monitor for
------------------------------------------
TAA9891 From file does not exist
TAA9892 To file does not exist
TAA9893 *OBJMGT required for source file
TAA9894 *CHANGE authority required for To file
TAA9895 Member does not exist
TAA9896 Member is not a command type
TAA9897 No STRCPYCMD found
CRTCPYCMD Function
------------------
The CRTCPYCMD command is the companion command to CPYCMD. It is
intended to be used when you have changed the standard source. At
that point you want to find all of the commands that use the standard
source and get them re-created with the new standard source.
You can use CRTCPYCMD for a single command, but the real power is to
use it against all commands in a library.
Assume the following:
** CPYCMD was used to copy in some standard source for several
members.
** All of the commands are part of an application set that
resides in LIBX.
** The name of the standard source members are STDSRC1, STDSRC2,
and STDSRC3.
** A change needs to be made to the STDSRC1 source member. You
make the change.
** All of the commands in LIBX that use STDSRC1 should be
re-created.
The CRTCPYCMD command makes it easy. All you say is:
CRTCPYCMD CMD(LIBX/*ALL) STRCPYCMD(STDSRC1)
CRTCPYCMD does the following:
** Builds an outfile of all the command objects in the library.
** Reads the file and uses the outfile information to determine
the source member that was used to create each command.
** Ensures that the source member exists and that you have
authorization to replace both the source and the command.
** Searches the source looking for STRCPYCMD comment and the
member you named (STDSRC1).
** If it finds a member with a match, it uses CPYCMD to refresh
the source. This causes the new source for STDSRC1 to be
inserted in your member. If you have other STRCPYCMD
statements in the same member (such as for STDSRC2), that
source will also be refreshed. CPYCMD always refreshes
everything.
If the standard source name you specified does not exist
within the source, CPYCMD is not used. You can specify that
*ANY standard source be refreshed in which case if any
STRCPYCMD comments exist, CPYCMD will be used.
** The TAA Tool RPLCMD is used to replace the command. It
captures the attributes of the command (such as CPP and MODE)
and uses them on the CRTCMD command. REPLACE(*YES) is
specified so the old version of the command is moved to
QRPLOBJ. Any security information remains the same.
** If DLTSPLF(*YES) is specified (it is the default), the CRTCMD
spooled files for successfully created commands are deleted.
** A printed listing occurs which includes both the commands that
did not use the STDSRC1 member and those that did. Totals are
generated and any errors are listed.
The source for your commands must exist in the same library as was
used to initially create each command.
If you used CRTDUPOBJ, the original source information is retained in
the new object. It is accessed and the duplicate command would be
re-created from the original source.
STRCPYCMD does not adopt any authority. If you are not authorized to
*OBJEXIST for any command, an error will occur.
OBJTYP Tool
-----------
The Object Type tool provides the command definition source as
standard source for two types of a typical OBJTYPE parameter. The
source is intended to be used with CPYCMD. See the OBJTYP tool for
details.
CRTCPYCMD Escape messages you can monitor for
---------------------------------------------
TAA9893 Command does not exist
TAA9894 Object existence for the command is required
TAA9895 Source does not exist for the command
CPYCMD Command parameters *CMD
-------------------------
CPYCMD must be used before you use CRTCMD. It will copy the source
from the members you have described with the special STRCPYCMD
comment.
SRCMBR The name of your source member that contains the
STRCPYCMD comment. One or more STRCPYCMD comments
may exist.
FROMSRCF The qualified name of your From source file. The
file defaults to QCMDSRC and the library defaults to
*LIBL. *CURLIB may also be used as the library
name.
TOSRCF The qualified name of the To source file. The
default is *SAME meaning that the same name as the
FROMSRCF parameter is used. If the library name is
blank, the same library as the FROMSRCF parameter is
used.
The TOSRCF parameter does not appear on the command
prompt unless you use F9 or F10.
CRTCPYCMD Command parameters *CMD
----------------------------
CMD The qualified command name to be recreated. The
command must exist. The special value *ALL may be
entered. *ALL may not be used if the library value
is *LIBL. The library defaults to *LIBL. *CURLIB
may also be used.
STRCPYCMD The name of the standard source member to be
searched for. The special value *ANY may be
specified. This means that if any CMD source member
contains a STRCPYCMD comment, CPYCMD will be invoked
and the command will be re-created. If a match
occurs on the STRCPYCMD member name, all STRCPYCMD
functions within the same member are refreshed.
DLTSPLF A *YES/*NO value for whether the spooled files for
successfully created Commands should be deleted.
The default is *YES. This cleans up the output
queue so that only those commands which have failed
to create will have spooled files. *NO causes all
spooled files to be retained.
Restrictions
------------
** The CPYCMD command must be used before you create the command.
Unless you change the standard source, you never need to
consider CPYCMD again for the same source member.
** If you change the standard source, you need to run CPYCMD
again. The simplest solution is to use CRTCPYCMD.
** The standard source being copied may not contain a STRCPYCMD
comment (no nesting).
** CRTCPYCMD requires that the source exist in the same file and
member that was used to originally create the command.
** See the prior discussion of copying a partial statement.
** See the prior discussion of copying comments within the
standard source.
Prerequisites
-------------
The following TAA Tools must be on your system:
EDTVAR Edit variable
HLRMVMSG HLL Remove message
RPLCMD Replace command
RTVDAT Retrieve date
RTVSYSVAL3 Retrieve system value 3
SNDCOMPMSG Send completion message
SNDDIAGMSG Send diagnostic 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
------ ---- --------- ---------- ----------
CPYCMD *CMD TAASREB QATTCMD
CRTCPYCMD *CMD TAASREB2 QATTCMD
TAASREBC *PGM CLP TAASREBC QATTCL
TAASREBC2 *PGM CLP TAASREBC2 QATTCL
TAASREBR *PGM RPG TAASREBR QATTRPG
TAASREBR2 *PGM RPG TAASREBR2 QATTRPG
Structure
---------
CPYCMD Cmd
TAASREBC CL
TAASREBR RPG
CRTCPYCMD Cmd
TAASREBC2 CL
TAASREBR2 RPG
|
