Start of README v2.1

/COPYBOOK preprocessor


/COPYBOOK was developed by McKay Software Services Ltd www.mckaysoftware.ie

This describes the purpose and components of /COPYBOOK and how to download, install, use and execute the /COPYBOOK preprocessor command.

/COPYBOOK offers the following features which are not available in the standard /copy.

  • Copy from line number, to line number
  • Copy from label, to label
  • end-free, free not required
  • Copy DDS sources, ie ...
  • ... screen files
  • ... printer files
  • ... physical files
  • ... logical files

    CONTENTS

  1. PURPOSE
  2. METHOD
  3. ADP Preprocessor Command
  4. SAVEFILE
  5. SHIPPING LIST
  6. Change Log

  1. PURPOSE
    2. /COPYBOOK allows developers on AS400 to work on RPG and DDS sources with greater flexibility and make more efficient use of existing source members.
    A subset of a source member to be copied into another at compile time, rather than copying a complete member.
    This is done by specifying from and to lines, or from and to labels.  It is no longer necessary to isolate the copy source in a separate member.
    Furthermore, DDS sources can now be copied into other DDS sources.  For example, the subfile control statements from one screen file can be copied into another screen file at compile time.  Likewise, screen banners need only be defined in one screen file and copied as required into other screens.   Similarly, banners and overflow statements can be copied from one printer file to another printer file.
    This release requires V5R3M0 or later.
    ===>CONTENTS

  2. METHOD
    3. There are two steps.
    Step 1 is the inclusion of the preprocessor /COPYBOOK in the target source member.
    If using from and to labels, insert /ADP-LABEL= in the member being copied at the from and to locations with the appropriate labels.
    Step 2 is to execute the ADP command, which processes the /COPYBOOK command to expand the source and then to (optionally) compile the expanded source.
    When using /COPYBOOK in an RPG fixed-format source line or a DDS line, a * is expected in position 7.  This forces SEU to regard the line as a comment.  /COPYBOOK must be in positions 8 - 16.  Alternatively, when using /COPYBOOK on free-fromat RPG line, a // is expected in positions 8 - 9.  /COPYBOOK is then expected in positions 10 - 18.
    The format of the /COPYBOOK statement is

    /COPYBOOK

    LIBRARY/FILE,MEMBER:fromlabel-tolabel
    or

    /COPYBOOK

    LIBRARY/FILE,MEMBER:fromline-toline
    or

    /COPYBOOK

    FILE,MEMBER:fromlabel-tolabel
    or

    /COPYBOOK

    FILE,MEMBER:fromline-toline
    or

    /COPYBOOK

    MEMBER:fromlabel-tolabel
    or

    /COPYBOOK

    MEMBER:fromline-toline
    or

    /COPYBOOK

    MEMBER:fromline
    or

    /COPYBOOK

    MEMBER


    One space is required between /COPYBOOK and the next character.

    LIBRARY and FILE are optional.
    If LIBRARY is omitted, the name of the library in which the source file containing the member with the /COPYBOOK statement is inserted.
    If FILE is omitted, the name of the source file containing the member with the /COPYBOOK statement is inserted.

    All alphabetic entries may be keyed in either UPPER or lower case or a combination.
    All alphabetic entries are converted to UPPERCASE.

    A label must start with an alphabetic character, i.e. between a and z or A and Z.
    Note that all lowercase characters are converted to UPPERCASE before use.
    Any characters after the first character can be alphabetic or numeric.
    In addition, some other characters are valid, but not space : / = - ' "
    The maximum length for a label is ten characters; minimum length is one.
    When using a from and to label on the /COPYBOOK, a corresponding from and to label must exist in the source member being copied.
    The corresponding label is expected on the keyword /ADP-LABEL=
    This keyword is the same for both from and to labels and is keyed immediately after the comment identifier (* or //).
    There is no validation on the label on this keyword - validation takes place only on the /COPYBOOK.

    If using labels, the from and to label must be specified together.
    It is not valid to use a label and a line number on the one /COPYBOOK statement.

    If no line number range nor label range is given, all of the member is copied.

    If a number is given on its own, ONLY that line in the copy member is copied..

    Up to 99 /COPYBOOK statements may be nested.

    A member may not call itself or one higher in the nested hierarchy.

    The message file ADPMSGF contains the messages written to the merged source at the start and end of each copied segment as well as error messages. These messages are ...
    ADP0001   0   ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP
    ADP0002   0   Start of copybook &1 here
    ADP0003   0   Start of level &1
    ADP0004   0   End of level &1
    ADP0005   0   End of copybook &1
    ADP0006   0   Number of records copied &1
    ADP0007   0   Duplicate name &1 - no action taken
    ADP0008   0   ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP
    ADP0009   0   The From Flag cannot be same as the To Flag
    ADP0010   0   No From Flag given
    ADP0011   0   No To Flag given
    ADP0012   0   From Line with To Flag is not valid
    ADP0013   0   From Flag with To Line is not valid


    The program will fail if it cannot find the message file ADPMSGF in the library list.
    You can change the text of the messages. If you do not want a message to appear, simply remove it from the message file. You can also remove the parameter.



    Example 1 ... /COPYBOOK with line numbers
    ... Source member with /COPYBOOK:

    0064.00   A*
    0065.00   A                                          21   8'BUSINESS CATEGORY'
    0066.00   A     S1BUS             R     B  21  26REFFLD(CUBUS)
    0067.00   A                                                    EDTCDE(Z)
    0068.00   A                                                    COLOR(WHT)
    0069.00   A     S1BUSDESC   15A   O  21 30COLOR(BLU)
    0070.00   A*
    0071.00   A*/COPYBOOK AFM800FM:1-999


    ... Copy source member:
    0001.00   A*
    0002.00   A                                             24   5'F3 Exit'
    0003.00   A                                             24  18'F4 Prompt'


    ... Merged source member:
    0064.00   A*
    0065.00   A                                          21   8'BUSINESS CATEGORY'
    0066.00   A     S1BUS             R     B  21  26REFFLD(CUBUS)
    0067.00   A                                                    EDTCDE(Z)
    0068.00   A                                                    COLOR(WHT)
    0069.00   A     S1BUSDESC   15A   O  21 30COLOR(BLU)
    0070.00   A*
    0071.00   A*/COPYBOOK AFM800FM:1-999
    0072.00      *ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP
    0073.00      *Start of copybook JMCKAY1/QDDSSRC,AFM800FM:1-999 here
    0074.00      *Start of level 1
    0075.00   A*
    0076.00   A                                             24   5'F3 Exit'
    0077.00   A                                             24  18'F4 Prompt'
    0078.00      *End of level 1
    0079.00      *End of copybook JMCKAY1/QDDSSRC,AFM800FM:1-999
    0080.00      *Number of records copied 3
    0081.00      *ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP


    Example 2 ... /COPYBOOK with labels
    ... Source member with /COPYBOOK:
    0064.00   D*/copybook atestcopy3:dfrom-dto


    ... Copy source member:
    0001.00 */adp-label=dfrom
    0002.00 D p_number      pr
    . . .
    0031.00 D zmantissa  s      5    5
    0032.00 */adp-label=dto


    ... Merged source member:
    001900 D*/COPYBOOK ATESTCOPY3:DFROM-DTO
    002000 *ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP
    002100 *Start of copybook JMCKAY1/QRPGLESRC,ATESTCOPY3:DFROM-DTO here
    002200 *Start of level 1
    002300 */ADP-LABEL=DFROM
    002400 D p_number      pr
    . . .
    005300 D zmantissa  s      5    5
    005400 */ADP-LABEL=DTO
    005500 *End of level 1
    005600 *End of copybook JMCKAY1/QRPGLESRC:DFROM-DTO
    005700 *Number of records copied 31
    005800 *ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP ADP


    ===>CONTENTS

  3. ADP Preprocessor Command

    4. INTEGRATED PREPROCESSOR (ADP)

    Type choices, press Enter.
    Input Member Name . . . . . . .          __________           Name
    Input Source File . . . . . . .                __________           Name
         Library . . . . . . . . . . . .                    *LIBL_____       Name, *LIBL
    Member Type . . . . . . . . . .              __________           Name
    Compile Command . . . . . . . .          __________           Name
    Output Member Name . . . . . . .       *IMEMBER           Name, *IMEMBER
    Output Source File . . . . . . .            ADPOUTPUT         Name
         Library . . . . . . . . . . .                    QTEMP_____     Name
    Output Object . . . . . . . . .                __________          Name
         Library . . . . . . . . . . .                     __________       Name



    Bottom
    F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
    F24=More keys


    Input Member NameThe name of the source member which is to be expanded.Required
    Input Source FileThe source file which contains the input member.Required
    Member TypeThe member type, e.g. RPGLE, DSPF.  This is used when adding the member to the output file.Optional
    Compile CommandThe compile command to be executed on the merged source.  A number of standard compile commands - e.g. CRTBNDRPG, CRTPRFTF - are included in the command prcessing program AD6.  You may customize this to suit your own development environment.Optional
    Output Member NameThe output member to be created.  The default is to use the input member name.   Any specified compile command executes on this member.Optional
    Output Source FileThe name of the output source file.  The default is QTEMP/ADPOUTPUT.   If the output file does not exist, it is created during the run.  Any specified compile command executes on this file.  Optional
    Output ObjectThe object to be created.  The default is to use the input member name.Optional



    You may change the ADP command, and the related cl ADP6 to suit your own compile environment - as long as you keep the parameters to ADP5 in the same sequence and with the same lengths and types.
    ADP6 is the command processing program.  It calls ADP5 which reads the lines in the input source member, expands the /COPYBOOK statements as appropriate and, by default, writes the expanded source out to file ADPOUTPUT in library QTEMP.
    The member name and the input file name are required.
    If you wish to compile the expanded source immediately, you key in the relevant compiler command.
    Similarly, if you wish to retain the expanded output, or write it to another location, you change the output parameters as required.
    The command ADP looks for the preprocessor program ADP6 in the *LIBL. You can of course change this location to suit your own environment.
    ===>CONTENTS


  4. SAVEFILE
    5. The objects are provided in a savef MCKADPSAVF.  To restore the savef, first create a savef on the AS400.  Use FTP with binary to upload the file to the savf you created.
    You may then move the contents to a library or libraries of your choice.
    ===>CONTENTS


  5. SHIPPING LIST
    6. The following objects are shipped in the savefile MCKADPSAVF ...
    ADPCMDThis is the preprocessor command which merges the sources and optionally executes the compiler
    ADP6CL programThe command processing program
    ADP5CLLE programThis is the merge program and is called by the previous program
    ADPSRCSRC PFSource file containing the sources for ADP and ADP6
    ADPMSGFMSG FILEThe messages written at the start and end of each copied segment are here

    ===>CONTENTS




  6. Change Log V2.0

    7. Messages in external message file.
    Expanded documentation.
    ADP command expects ADP6 in *LIBL.
    Objects shipped as savefile objects, not as savlib.
    Change Log V2.1
    Copy from label, to label.

===>CONTENTS



28 Sep 2009
©2009 McKay Software Services Ltd
www.mckaysoftware.ie
www.rpglanguage.com
End of README v2.1