Start of README v1.0

Free Form Definition Specifications


Free Form Definition Specifications has now been added to ADP.
ADP was developed by McKay Software Services Ltd www.mckaysoftware.ie
It is also the preprocessor for /COPYBOOK statements

This describes the purpose and components of Free Form Definition Specifications and how to download, install, use and execute this facility.

Examples of free form D specs are.

  • FIELD zfrmto char 1-50
  • field zalpha CHAR(100)
  • Field zintg INT(5,0)
  • field zbnry BIN(5,2)
  • field zpckd PACKED(6,3)
  • array zctary perrcd(1) dim(4) char(10)
  •    ctdata
  •       {  here
  •         there
  •         anywhere   }

    CONTENTS

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

  1. PURPOSE
  2. Free Form Definition Specifications release the developer from the fixed format of the D specification lines.
    The objective is to improeve readibility and to give a more holistic means of definition.
    For example, compile-time data (CTDATA) can be written immediately after the array or table definition.
    While it is developed at V5R3, it is intended to be generic in that it can be used on V5R3 or later. Fields, tables, arrays, indicators, structures, prototypes, interfaces, constants, objects and data areas can all be defined in a free format style.

    ===>CONTENTS



  3. METHOD
  4. The basic layout of the free form specification is ...
       Identifier Name Type Size
    Keywords are listed as a group as follows ...
          Having {
             Inz('abc') }
    or
          Having {  Inz('abc') }


    Please note that the Having construct is not an exact equivalent for keywords.
    There are two differences.
    First, array / table definitions (Perrcd, Dim or CTData) can be specified after the Identifier string or in the Having list.
    If Perrcd, Dim or CTData are used in the definition of the table or array, these are copied into the keywords section. Otherwise, they should be defined in the Having list.
          *  array zctary perrcd(1) dim(4) char(10)
          *    ctdata                              
          *      { here                            
          *        there                           
          *        anywhere   }                    
    

    Secondly, the strings for Object types can be specified along with the Identifier line.
          *  object zobj                        
          *           {  'java.lang.object'   }                   
    

    The Identifiers are as follows ...
    Array name type Having {   } CTData {   }
    Constant name   Having {   }  
    Data-Area name type Having {   } {   }
    Data-Structure name type Having {   } {   }
    Field</TD> name type Having {   }  
    Indicator name   Having {   }  
    Interface name type Having {   } {   }
    Object name {   } Having {   }  
    Program-Status name type Having {   } {   }
    Prototype name type Having {   } {   }
    Table name type Having {   } CTData {   }


    The identifier, name and type are converted to uppercase prior to processing.
    The contents of the Having and the CTData lists are not converted to uppercase.
    Name should follow the standard RPG naming rules. There is no validation on this.
    Starting position is 8. This allows for the comment * in position 7 of the line. The maximum length is 93.
    The Interface statement will create the Begin-Procedure statement and associated definition statements.

    External elements are identified with the word External.

    At least one space is required between each element.
    Each statement can be on more than one line.
    The Data-Structure phrase is optional in Program-Status and Data-Area lines.

    CTData can be replaced by **.
    The CTData records are written following the array/table definition in this free-form syntax.
    They are saved and written out after all the input records have been read.
    If any of the CTData records contain leading blanks, then START=n should be used.

    The length of the CTData record is calculated form size * elements per record.
    If the PerRcd( ) is in the Having clause, not in the array/table definition itself, the length = size.

    The following types are recognised and converted into the equivalent fixed-format definition.
    CHAR(n)
    FLOAT(n,0)
    INT(n,0)
    UNSIGNED(n,n)
    BIN(n,n)
    PACKED(n,n)
    ZONED(n,n)
    DATE
    TIME
    TIMESTAMP
    POINTER

    For example Char(5) or packed(5,2)
    Either length (number of characters/digits) or from-to entries can be used, for example char(25) or char 1-25,
    or packed 1-25,2.
    Figurative definitions (e.g. *STATUS) can be used where appropriate.
    Subfields for a data structure are written within {   }.
    External is used before the name to specify an external description for a data-structure or subfield.

    The message file ADPMSGF contains the messages written to the expanded source at the start and end of each preprocessed 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


    If the program cannot find the message file ADPMSGF, it continues without issuing a message.
    If a message is not found in the message file, the program continues without issuing a message.
    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

  5. ADP Preprocessor Command

  6. 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


  7. SAVEFILE
  8. 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


  9. SHIPPING LIST
  10. 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




  11. Change Log


===>CONTENTS



21 Aug 2011
©2011 McKay Software Services Ltd
www.mckaysoftware.ie
www.rpglanguage.com
End of README v1.0