TAA Tools

 CPYCMD          COPY CMD                               TAASREB

 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

Added to TAA Productivity Tools May 1, 1999


Home Page

Last modified on November 19, 2014 © 1995, 2014 - TAA Tools, Inc.