home *** CD-ROM | disk | FTP | other *** search
/ Hall of Fame / HallofFameCDROM.cdr / 3x400 / rpgfree.lzh / RFREE.DOC < prev    next >
Text File  |  1990-04-18  |  36KB  |  1,041 lines
  1. RFREE.DOC -- RPG/free (tm) and RPG/pretty (tm) documentation
  2.  
  3. Version 1.0 April 1990
  4. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5.  
  6. by Paul Conte (Copyright 1990)
  7.  
  8. Please note:    This document can be reproduced for any purpose, as long as the
  9.         following notice is included on the first page:
  10.  
  11. ***************************************************************************
  12. ***    RPG/free and RPG/pretty are trademarks of Paul Conte.        ***
  13. ***                                    ***
  14. ***    RPG/free and RPG/pretty programs are Software copyright 1990    ***
  15. ***    by Paul Conte.                             ***
  16. ***************************************************************************
  17.  
  18.  
  19. INTRODUCTION.
  20.  
  21. RPG/free is a free format version of RPG.  The RPG/free precompiler translates
  22. RPG/free input into standard RPG, which can be compiled by one of the RPG
  23. compilers.  The RPG/pretty translator translates standard RPG input into
  24. "pretty" RPG/free code.  Both RPG/free and RPG/pretty run under MS-DOS or the
  25. DOS compatability box of OS/2.
  26.  
  27. The executable versions of RPG/free and RPG/pretty covered by this 
  28. documentation can be freely copied and distributed.  They are commercial 
  29. quality programs intended for production use; however, because they are free, 
  30. no warranty or support is offerred.  Please use normal care in backing up files
  31. as you use these programs.
  32.  
  33. If you find errors or have suggestions for improvements, please share your
  34. knowledge.  By filling out the form in file FREENEWS, you can receive a
  35. free RPG/free newsletter that contains tips-and-techniques and error reports.
  36. The newsletter also contains the latest information on new releases
  37. of RPG/free and RPG/pretty.  The latest releases of the programs are available
  38. on the NEWSLINK bulletin board of NEWS 3X/400 magazine.  (Other bulletin boards
  39. are free to copy the latest releases from NEWSLINK to their own system for
  40. distribution.  My only request is that you also provide the latest version
  41. of this RFREE.DOC file along with the programs.)
  42.  
  43.  
  44. INSTALLATION.
  45.  
  46. To install, just copy RF.EXE (for RPG/free) and RP.EXE (for RPG/pretty) to
  47. your PC hard disk.  (After you copy the two progams to your hard disk, you
  48. may want to rename the programs to avoid accidentally typing "RP" instead of 
  49. "RF" when you execute them. For example, you might rename RF.EXE to RFREE.EXE.)
  50.  
  51. You can test the programs by executing:
  52.  
  53.     rf /listopt tstin1.rpf  tstin2.rpf  out.rpg
  54.     
  55.     rp tstin.rpg out.rpf
  56.  
  57. Then compare the generated file OUT.RPG with the supplied file TSTOUT.RPG,
  58. and compare the generated file  OUT.RPF with the supplied file TSTOUT.RPF.
  59. These aren't comprehensive tests, but they will at least let you know you have
  60. functioning versions of the programs.
  61.  
  62.  
  63. EXECUTION.
  64.  
  65. For RPG/free, enter:
  66.  
  67.     rf  [options]  input-file1  input-file2 ... input-filen  output-file
  68.  
  69.  
  70. For RPG/pretty, enter:
  71.  
  72.     rp  [options]  input-file  output-file
  73.  
  74.  
  75. For both programs:
  76.  
  77.     [options] is a list of options, each beginning with /  (e.g., /noform)
  78.  
  79.     At least one input file and one output file are required, the last
  80.     file listed is the output file.  RPG/pretty can have up to 20 input
  81.     files (or your current DOS maximum open file limit).
  82.  
  83.     *** Be sure to include your output file when you use more than one 
  84.     *** RPG/free input file.  The command:  rf  inp1.rpf  inp2.rpf
  85.     *** treats inp2.rpf as the output file and replaces its contents.
  86.  
  87.     Use standard DOS file specifications for the input and output files.
  88.  
  89.     Recommended file extensions are .RPG for standard RPG files and .RPF for
  90.     RPG/free files.  For included macro files (discussed below), the
  91.     standard extension is .RPM.  You must include the extension when you 
  92.     specify a file.
  93.  
  94.  
  95. RPG/free options:
  96.  
  97. /help        List option switches.
  98.  
  99. /listopt    List the option settings for current execution.
  100.  
  101. /nocmt        Do not output RPG/free comment lines.
  102.         Default is to output all comment lines.
  103.  
  104. /nocvttab    Do not convert tabs in input to spaces.
  105.         Default is to convert tabs using tab stops [9, 17, 25, 33, ...]
  106.  
  107. /numbers    Output RPG source line numbers in positions 1-5.
  108.         Default is to output blanks in 1-5.
  109.  
  110. /asna        Output source is Amalgamated Software of North America 400 RPG.
  111. /bps        Output is BPS Information Services RPG II 1/2.
  112. /cspi        Output is California Software Products Inc. RPG II.
  113. /cspi400    Output is California Software Products Inc. RPG 400.
  114. /lattice    Output is Lattice, Inc. RPG II.
  115. /native        Output is Native Software RPG 400.
  116. /rpgii        Output is IBM RPG II  (or 100% compatible).
  117. /rpgiii        Output is IBM RPG III (or 100% compatible).
  118. /rpg400        Output is IBM RPG/400 (or 100% compatible).
  119. /softwest    Output is Software West RPG II.
  120. /trident    Output is Trident Software, Inc. RPG III.
  121.         Default is RPG III.
  122.  
  123.  
  124. RPG/pretty options:
  125.  
  126. /idcap        Output identifiers with initial letter in upper case and other
  127.         letters in lower case.
  128. /idupper    Output identifiers in upper case.
  129.         Default is lower case.
  130.  
  131. /indentNb    Use N blanks for each indent.
  132. /indentNt    Use N tabs for each indent.
  133.         Default is 1 tab.
  134.  
  135. /isn        Don't output warning for truncation of non-blank data in 
  136.         positions 1-5.
  137.         Default is to output warning.
  138.  
  139. /kwdlower    Output keywords in lower case.
  140.         Default is upper case.
  141.  
  142. /maxindentN    Maximum indent is N levels.
  143.         Default is 5.
  144.  
  145. /noform        Begin H, F, E, I, T, L, and O spec output in position 7.
  146.         Default is position 6 (form type character).
  147.  
  148. /sepNb        Use N blanks between operands.
  149. /sepNt        Use N tabs between operands.
  150.         Default is 1 tab.
  151.  
  152. /symind        Output indicators in symbolic form (*INxx).
  153.         Default is nonsymbolic form (xx).
  154.  
  155. /bps        Output is BPS Information Services RPG II 1/2.
  156. /lattice    Output is Lattice, Inc. RPG II.
  157. /rpgii        Output is IBM RPG II  (or 100% compatible).
  158. /rpgiii        Output is IBM RPG III (or 100% compatible).
  159. /rpg400        Output is IBM RPG/400 (or 100% compatible).
  160.         Default is RPG III.
  161.  
  162.         (Note: All vendors' versions of RPG are supported.  
  163.          Use /rpgii  for RPG II  from CSPI and Software West;
  164.          use /rpgiii for RPG III from Trident Software;
  165.          use /rpg400 for RPG/400 from ASNA, CSPI, and Native Software.)  
  166.  
  167.  
  168. RPG II NOTES:
  169.  
  170. Most RPG II opcodes are handled fine with the default /rpgiii compiler type.
  171. The following opcodes may require /rpgii or one of the third-party RPG II 
  172. compiler options (depending on which operands you use for Factor1, Factor2,
  173. and Result):
  174.  
  175.     DEBUG
  176.     DEFN
  177.     POST
  178.  
  179.  
  180. VENDOR OPCODE EXTENSIONS:
  181.  
  182. ASNA 400 RPG:
  183.  
  184. Vendor    RPG/free                Indicator Keywords
  185. Opcode    Synonym        Factor1    Factor2    Result    54-55 56-57 58-59
  186. ------    -----------    -------    -------    ------    ----- ----- -----
  187. CKDT            Blank    Rqd    Rqd
  188. CVDT            Rqd    Rqd    Rqd
  189. EDIT            Rqd    Rqd    Rqd
  190. WAIT            Blank    Rqd    Blank
  191.  
  192.  
  193. Lattice RPG II:
  194.  
  195. Vendor    RPG/free                Indicator Keywords
  196. Opcode    Synonym        Factor1    Factor2    Result    54-55 56-57 58-59
  197. ------    -----------    -------    -------    ------    ----- ----- -----
  198. blank    ENDSS or    Blank    Rqd    Rqd
  199.     ENDSUBSTR
  200. CATST    CATSTR        Rqd    Rqd    Rqd
  201. SUBST    SUBSTR        Rqd    Rqd    Blank
  202.  
  203.  
  204. Native Software RPG 400:
  205.  
  206. Vendor    RPG/free                Indicator Keywords
  207. Opcode    Synonym        Factor1    Factor2    Result    54-55 56-57 58-59
  208. ------    -----------    -------    -------    ------    ----- ----- -----
  209. MODE            Blank    Rqd    Blank                RI3
  210. RDCOM            Blank    Blank    Rqd    RI1   RI2   RI3
  211. WRCOM            Blank    Rqd    Blank          RI2   RI3
  212.  
  213.  
  214. Other vendor extensions:
  215.  
  216. If you encounter a vendor extension that is not properly handled by RPG/free's
  217. translation, the ultimate "work-around" is to use a /FIX directive, followed by 
  218. the exact format of the standard RPG statement, followed by a /FREE directive.
  219.  
  220.  
  221. RPG/free notes:
  222.  
  223. The only effect of the compiler options are:
  224.  
  225.     /lattice    Required to translate X'FFFF....' into X'FFFF....
  226.  
  227.             Required to translate ENDSS to blank opcode.
  228.  
  229.     /rpgii        Required to properly handle some DEFN, DEBUG, and POST
  230.             opcodes.
  231.  
  232.  
  233.  
  234. RPG/free does not translate non-C-spec input to uppercase.  You should use
  235. uppercase wherever standard RPG requires it in non-C-specs.
  236.  
  237. Tabs are converted to blanks on input using DOS default tabstops (9, 17, ...).
  238. The /nocvttab option eliminates conversion.  The only place where you
  239. might encounter problems are in non-C-specs or quoted literals, if you are
  240. using different tab stops than the defaults.  Just replace any problem
  241. tabs with appropriate spaces.
  242.  
  243. RPG/free writes error messages to the STDERR output stream.  Unfortunately.
  244. DOS will not redirect STDERR to a file.  (This may be changed in future
  245. versions.)
  246.  
  247. Most syntax error messages are prefixed by a number.  This number appears
  248. in the generated standard RPG code for reference purposes.
  249.  
  250. Some error messages list the current token as seen by the parser.  You may see 
  251. the following "strange" symbols:
  252.  
  253.     EOS    End of string (the end of the input statement)
  254.     U+    Unary plus  (as in X = + Y)
  255.     U-    Unary minus (as in X = - Y)
  256.  
  257. In some cases, the translator pushes the current token back on the input stream
  258. and re-parses it.  This may cause you to see two or more error messages for
  259. the same token (for example when there is an unclosed string in the input).
  260.  
  261. The following tables shows how RPG/free treats operation arguments:
  262.  
  263.                                                  Logical
  264.     Operation      Factor1   Factor2   Result    Operator    Notes
  265.     ---------      --------  --------  --------  --------    --------------
  266.     ACQ            Required  Required                    
  267.     ADD            Optional  Required  Required          
  268.     AND            Required  Optional            Optional    Extended op
  269.     ANDxx          Required  Required                    
  270.     BEGSR          Required                              
  271.     BITOF                    Required  Required          
  272.     BITON                    Required  Required          
  273.     CABxx          Required  Required  Optional          
  274.     CALL                     Required  Optional          
  275.     CAS            Optional  Optional  Required          
  276.     CASE           Optional  Optional  Required  Optional    Extended op
  277.     CASxx          Optional  Optional  Required          
  278.     CATST          Required  Required  Required        Lattice          
  279.     CHAIN          Required  Required  Optional          
  280.     CKDT                     Required  Required         ASNA         
  281.     CLOSE                    Required                    
  282.     COMIT          Optional                              
  283.     COMP           Required  Required                    
  284.     CVDT           Required  Required  Required         ASNA         
  285.     DCL                      Optional  Required         Extended op         
  286.     DEBUG          Optional  Optional  Optional        RPG III/400          
  287.     DEBUG          Optional  Required  Optional        RPG II          
  288.     DEFN           Required  Optional  Required        RPG III/400           
  289.     DEFN           Required  Required  Required        RPG II             
  290.     DELET          Optional  Required                    
  291.     DIV            Optional  Required  Required          
  292.     DO             Optional  Optional  Optional          
  293.     DOUxx          Required  Required                    
  294.     DOWxx          Required  Required                    
  295.     DSPLY          Optional  Optional  Optional          
  296.     DUMP           Optional                              
  297.     EDIT           Required  Required  Required        ASNA          
  298.     ELSE                                                 
  299.     END                      Optional                    
  300.     ENDSR          Optional  Optional                    
  301.     ENDSS                    Required  Required        Lattice          
  302.     EXCPT                    Optional                    
  303.     EXFMT                    Required                    
  304.     EXIT                     Required            RPG II                    
  305.     EXSR                     Required                    
  306.     FEOD                     Required                    
  307.     FOR            Required  Required  Required  Required    Extended op
  308.     FORCE                    Required                    
  309.     FREE                     Required                    
  310.     GOTO                     Required                    
  311.     IF             Required  Optional            Optional    Extended op
  312.     IFxx           Required  Required                    
  313.     IN             Optional  Required                    
  314.     KEYxx          Optional            Optional        RPG II          
  315.     KFLD                               Required          
  316.     KLIST          Required                              
  317.     LOKUP          Required  Required  Optional          
  318.     MHHZO                    Required  Required          
  319.     MHLZO                    Required  Required          
  320.     MLHZO                    Required  Required          
  321.     MLLZO                    Required  Required          
  322.     MODE                     Required                 Native Software           
  323.     MOVEx                    Required  Required          
  324.     MULT           Optional  Required  Required          
  325.     MVR                                Required          
  326.     NEXT           Required  Required                    
  327.     OCUR           Optional  Required  Optional          
  328.     OPEN                     Required                    
  329.     OR             Required  Optional            Optional    Extended op
  330.     ORxx           Required  Required                    
  331.     OUT            Optional  Required                    
  332.     PARM           Optional  Optional  Required
  333.     PLIST          Required                              
  334.     POST           Optional  Optional  Optional        RPG III/400          
  335.     POST           Required            Required        RPG II          
  336.     RDCOM                              Required             Native Software
  337.     READ                     Required  Optional          
  338.     READC                    Required                    
  339.     READE          Required  Required  Optional          
  340.     READP                    Required  Optional          
  341.     REDPE          Required  Required  Optional          
  342.     REL            Required  Required                    
  343.     RETRN                                                
  344.     RLABL                              Required        RPG II          
  345.     ROLBK                                                
  346.     SETGT          Required  Required                    
  347.     SETLL          Required  Required                    
  348.     SETOF                                                
  349.     SETON                                                
  350.     SETxx          Optional  Optional  Optional        RPG II          
  351.     SHTDN                                                
  352.     SORTA                    Required                    
  353.     SQRT                     Required  Required          
  354.     SUB            Optional  Required  Required          
  355.     SUBST          Required  Required            Lattice                    
  356.     TAG            Required                              
  357.     TESTB                    Required  Required          
  358.     TESTN                              Required          
  359.     TESTZ                              Required          
  360.     TIME                               Required          
  361.     UNLCK                    Required                    
  362.     UNTIL          Required  Optional            Optional    Extended op
  363.     UPDAT                    Required  Optional          
  364.     WAIT                     Required             ASNA                   
  365.     WHILE          Required  Optional            Optional    Extended op
  366.     WRCOM                    Required                Native Software                   
  367.     WRITE                    Required  Optional          
  368.     XFOOT                    Required  Required          
  369.     Z-ADD                    Required  Required          
  370.     Z-SUB                    Required  Required          
  371.  
  372.  
  373. RPG/pretty notes:
  374.  
  375. The only effect of the compiler options are:
  376.  
  377.     /bps        Required to recognize *? in positions 1-2 as
  378.             beginning of data 
  379.  
  380.     /lattice    Required to translate X'FFFF.... into X'FFFF....'
  381.  
  382.             Required to translate blank opcode following SUBST
  383.             to ENDSUBSTR.
  384.  
  385.     /rpgii        Required to recognize ** in positions 1-2 with
  386.             non-blank in 3 as beginning of data.  (Default /rpgiii
  387.             requires position 3 to be blank.)
  388.         
  389.  
  390.             Required to recognize /* in positions 1-2 as 
  391.             end-of-file
  392.  
  393.  
  394. RPG/pretty determines where position 1 of the standard RPG specification is
  395. in the DOS file by examining the first input record to see if there are S/38 or 
  396. AS/400 SEU-style source numbers or dates (not the RPG statement numbers in RPG 
  397. positions 1-5). These source numbers and dates are normally stripped when you 
  398. use PC Support on the S/38 or AS/400 to download a source file member.  But if 
  399. they are included, RPG/pretty can normally figure out how to skip them.  
  400.  
  401. The rules RPG/pretty uses are:
  402.  
  403.     IF    characters 1-8  contain xxxxx.nn AND
  404.         characters 9-15 contain xxxxxxn
  405.  
  406.         The RPG statement starts in 16
  407.  
  408.     ELSE IF    characters 1-7  contain xxxxxxn  AND
  409.         characters 8-15 contain xxxxx.nn
  410.  
  411.         The RPG statement starts in 16
  412.  
  413.     ELSE IF    characters 1-8  contain xxxxx.nn
  414.  
  415.         The RPG statement starts in 9
  416.  
  417.     ELSE IF    characters 1-7  contain xxxxxxn
  418.  
  419.         The RPG statement starts in 8
  420.  
  421.     ELSE    The RPG statement starts in 1
  422.  
  423.     (Where each  n  is a digit and each  x  is a digit or blank.)
  424.  
  425. If you have problems, just strip off any non-RPG line numbers.  (Do NOT
  426. strip off RPG statement numbers in positions 1-5; use the /isn option
  427. to ignore them.)
  428.  
  429. RPG/pretty does not convert tabs to blanks on input.
  430.  
  431. Some invalid specifications do not cause a warning; for example, an indicator
  432. like UX is considered valid.  RPG/free will catch many of these.
  433.  
  434. All opcode lookups are done in UPPERCASE (as standard RPG requires).
  435.  
  436. Comment lines that are not C-specs are output as the formtype followed by an 
  437. asterisk (with /noform, just an asterisk).  For example,
  438.  
  439.     F* comment...
  440.  
  441. You may want to use a PC editor to search and replace this pattern (e.g., F*)
  442. with  --  which is the standard RPG/free comment.  The current RPG/pretty
  443. approach maintains better alignment for commented non-C-specs in existing code.
  444.  
  445.  
  446. IMPLEMENTATION NOTES:
  447.  
  448. RPG/pretty was implemented using POLYTRON PolyAWK Plus 1.0 compiler.
  449.  
  450. RPG/free was implemented using Microsoft C version 5.01 under IBM PC-DOS 4.01.
  451.  
  452. RPG/free has the following maxima:
  453.  
  454.     Input files                  20
  455.     File name length              90
  456.     Number of command line arguments      20
  457.     Command argument length              90
  458.     Number of continuation lines          19
  459.     Input line length             250
  460.     Statement length            1000
  461.     Keyword length                  20
  462.     Token length                  80
  463.     Macro replacement text length         100
  464.     Number of macros             100
  465.  
  466.  
  467.  
  468. THE RPG/free LANGUAGE:
  469.  
  470. A full description of RPG/free is published in the article "RPG/free -- The
  471. Golden Age of RPG Programming", Paul Conte, NEWS 3X/400, April 1990.  Copies
  472. of this article are available as a back issue order from NEWS 3X/400,
  473. P.O. Box 3438, Loveland, CO 80539-9916 (800) 373-3853.
  474.  
  475.  
  476. PROGRAM STRUCTURE
  477.  
  478. RPG/free programs have the same structure as standard RPG programs.  You 
  479. specify the form type with a directive.  A complete program might contain:
  480.  
  481. /CONTROL or /HEADER (optional)
  482.  Control specifications
  483. /FILE
  484.  File specifications
  485. /EXTENSION or /EXT
  486.  Extension specifications
  487. /LINE
  488.  Line counter specifications
  489. /TELCOM
  490.  Telecommunications specifications
  491. /INPUT
  492.  Input specifications
  493. /CALC
  494.  Calculation specifications
  495. /OUTPUT
  496.  Output specifications
  497. /DATA
  498. **
  499.  File translation records
  500. **
  501.  Alternate collating sequence records
  502. **
  503.  Compile-time array and table data
  504.  
  505.  
  506. The precompiler starts with form type as H, so a beginning /CONTROL is
  507. optional.  You do not have to include directives for unused form types.
  508. The form types must be in the standard RPG order, the precompiler does not
  509. sort them.
  510.  
  511.  
  512.  
  513. NON-C-SPECS
  514.  
  515. H, F, E, L, T, I, and O specifications are output without translation, except 
  516. for proper column alignment based on the /FIRSTCOL directive setting.
  517.  
  518. With the standard /FIRSTCOL setting (6), you begin each statement with the form 
  519. character in position 1.  (This is redundant, but aids readability.)
  520.  
  521. To eliminate form characters, use the /FIRSTCOL 7 directive.
  522.  
  523. To add characters in positions 1-5, use /FIRSTCOL n where n is 1 to 5 and
  524. specifies where position 1 of the input will be placed in the output.
  525. You can use multiple /FIRSTCOL directives, so you can bracket a statement
  526. that you want to mark and leave the others as the default:
  527.  
  528.     FAFILE1  ....
  529.     /FIRSTCOL 4
  530.     >>FAFILE2  ...
  531.     /FIRSTCOL 6
  532.     FAFILE3 ...
  533.  
  534.  
  535. C-SPECIFICATION STATEMENTS
  536.  
  537. C-specs are free format, you can use blanks and tabs freely for alignment.
  538. You can also use upper or lower case for all keywords, identifiers, and
  539. special values.  Lower case is converted to upper case except within string
  540. constants (e.g., 'Name' is unchanged) and figurative constants (e.g., 
  541. *all'x' becomes *ALL'x').
  542.  
  543. A complete C-spec has the following parts:
  544.  
  545.     Control (or level) indicator
  546.     Conditioning indicators
  547.     Operation
  548.     Declaration
  549.     Half-adjust
  550.     Resulting indicators
  551.  
  552. Rules for combining these parts are the same as in standard RPG.
  553.  
  554. CONTROL INDICATOR
  555.  
  556. You can specify any one of the following control indicator keywords:
  557.  
  558.     L0()    L1()    L2()    L3()    L4()
  559.     L5()    L6()    L7()    L8()    L9()    LR()
  560.  
  561. You must use the parentheses.  The left parenthesis must immediately follow
  562. the keyword.  You can use blanks or tabs anywhere within the parentheses.
  563.  
  564. CONDITIONING INDICATORS
  565.  
  566. You can specify up to three conditioning indicators for each statement as:
  567.  
  568.     (01 02 03)     or    First or only conditioning indicators
  569.     COND(01 02 03)        for statement
  570.  
  571.     AND(01 02 03)        AND'd indicators
  572.  
  573.     OR(01 02 03)        OR'd indicators
  574.  
  575. You can specify negated indicators as (n01 n02 n03).
  576.  
  577. You can use symbolic indicators as (*in01 *in02 *in03) or 
  578. (*inn01 *inn02 *inn03).
  579.  
  580.  
  581. OPERATION
  582.  
  583. Allowable operands are:
  584.  
  585.     Operand type            Example        Fact1    Fact2    Result
  586.     ------------------------------    -------        -----    -----    ------
  587.     Identifier            custid          Y      Y      Y
  588.     Subscripted identifier        ary,2          Y      Y      Y
  589.     Non-negated symbolic indicator    *IN01          Y      Y      Y
  590.     Subscripted indicator array    *IN,i          Y      Y      Y
  591.     Null placeholder        *N          Y      Y      Y
  592.     Special value            *zero          Y      Y      Y
  593.     Numeric constant        -1.2          Y      Y      N
  594.     String constant            'Name'          Y      Y      N
  595.     Figurative constant        *all'X'          Y      Y      N
  596.     Hexadecimal constant        x'f0'          Y      Y      N
  597.  
  598.  
  599. Within operations, array references have the same form as in standard RPG;
  600. for example:  X,3
  601.  
  602. There are two forms of operation: arithmetic assignment and keyword operations.
  603.  
  604. Arithmetic assignments have the form:    a = b    or   a = b + c
  605. You can use +, *, -, or /.  You can't use parentheses or compound expressions
  606. such as a = (b + c) * d.
  607.  
  608. Standard keyword operations have an operation-operand form:
  609.  
  610.     operation  factor1  factor2  result
  611.  
  612. If an operation has blank or optional Factor1 or Factor2, you usually do not
  613. have to specify it.  RPG/free looks up the operation and places operands
  614. where they belong.  You can use the placeholder *n or *N to explicitly
  615. place blanks in an operand field.  For example,
  616.  
  617.     DELETE cusrcd               generates           DELETCUSRCD
  618.     DELETE *n cusrcd            generates           DELETCUSRCD
  619.     DELETE custid  cusrcd       generates  CUSTID   DELETCUSRCD
  620.     UPDATE cusfil               generates           UPDATCUSFIL
  621.     UPDATE cusfil  cusds        generates           UPDATCUSFIL   CUSDS
  622.  
  623. Note that RPG II and RPG III have different rules for the following opcodes:
  624. CHAIN, DEBUG, DEFN, POST, READ, READE, and READP.  RPG/free default placement
  625. will correctly handle all versions of CHAIN, READ, READE, and READP.  You can 
  626. use either the /rpgii option or explicit *n placeholders for the RPG II
  627. versions of DEBUG, DEFN, and POST.
  628.  
  629. You can use the following correctly spelled synonyms instead of standard RPG
  630. opcodes:
  631.  
  632.     RPG/free synonym    Standard RPG opcode
  633.     ----------------    -------------------
  634.     CASE            CAS
  635.     COMMIT            COMIT
  636.     DELETE            DELET
  637.     DISPLAY            DSPLY
  638.     ENDCASE            END
  639.     ENDDO            END
  640.     ENDFOR            END
  641.     ENDIF            END
  642.     ENDUNTIL        END
  643.     ENDWHILE        END
  644.     LOOKUP            LOKUP
  645.     OCCUR            OCUR
  646.     READPE            REDPE
  647.     RETURN            RETRN
  648.     ROLLBACK        ROLBK
  649.     SETOFF            SETOF
  650.     UNLOCK            UNLCK
  651.     UPDATE            UPDAT
  652.  
  653. If you think of C-spec operands as Factor1, Factor2, Result instead of
  654. first, second, and third operands, you can use RPG/free keywords as in the
  655. examples (operands can be in any order when you use keywords):
  656.  
  657.     UPDATE F2(cusfil) R(cusds)
  658.     
  659.     add f1(x) f2(y) r(z)
  660.  
  661.     add r(z)  f2(y) f1(x)
  662.  
  663. You can mix the keyword and positional forms, but be careful because the
  664. default placement of operands does not work the same as in S/38 and OS/400 CL.
  665. RPG/free first places operands specified with keywords, then fills in vacant
  666. operands using its default rules.
  667.  
  668.  
  669. RPG/free has a set of extended operations for control structures:
  670.  
  671.     RPG/free        Standard RPG
  672.     ---------------------    ---------------------------------------
  673.     AND    f1 =  f2        F1    ANDEQF2
  674.     AND    f1        F1    ANDEQ'1'
  675.     CASE   f1 <  f2 r    F1    CASLTF2        R
  676.     CASE   f1  r        F1    CASEQ'1'    R
  677.     CASE   r            CAS        R
  678.     FOR    r = f1 f2    F1    DO   F2        R
  679.     ENDFOR f2            END  F2
  680.     IF     f1 <=  f2    F1    IFLE F2
  681.     IF     f1        F1    IFEQ '1'
  682.     OR     f1 >  f2        F1    ORGT F2
  683.     OR     f1        F1    OREQ '1'
  684.     UNTIL  f1 <> f2        F1    DOUNEF2
  685.     UNTIL  f1        F1    DOUEQ'1'
  686.     WHILE  f1 >= f2        F1    DOWGEF2
  687.     WHILE  f1        F1    DOWEQ'1'
  688.  
  689.  
  690. The logical operators are:
  691.  
  692.     Operator    Meaning
  693.     --------    --------------
  694.        <        Less than
  695.        <=        Less than or equal
  696.        =        Equal
  697.        <>        Not equal
  698.        >=        Greater than or equal
  699.        >        Greater than
  700.  
  701.  
  702. You can also use keywords with extended operations (although it isn't very
  703. readable):
  704.  
  705.     IF f1(x) op(<=) f2(y)
  706.  
  707.     FOR r(idx) op(=) f1(bgn) f2(end)
  708.  
  709.  
  710. DECLARATIONS
  711.  
  712. After an operation and its operands, you can declare the result field:
  713.  
  714.     ADD x y z LEN(7 0)        Declares numeric field Z
  715.     
  716.     a = b * c LEN(7 2)        Declares numeric field A
  717.  
  718.     MOVE 'Name' outfld LEN(8)    Declares character field OUTFLD
  719.  
  720. You can use relative sizes on the DEFN operation
  721.  
  722.     DEFN *LIKE x z LEN(+2)        Declares numeric field Z as 2
  723.                     positions larger than X.
  724.  
  725.  
  726. The RPG/free DCL extended operation allows independent field declarations.
  727.  
  728.     RPG/free operation    Standard RPG
  729.     ------------------    ---------------------------
  730.     DCL r LEN(5)        MOVELR        R      5
  731.  
  732.     DCL r LEN(5 0)        Z-ADDR        R      50
  733.  
  734.     DCL f2 r LEN(5)        MOVE *BLANK    R      5
  735.                 MOVELF2        R
  736.  
  737.     DCL f2 r LEN(5 0)    Z-ADDF2        r      50
  738.  
  739. Note that the DCL does generate executable statements.  You may want to
  740. put these in an initialization subroutine that is executed only once; or
  741. put under a conditional statement:
  742.  
  743.     IF pgminz = false
  744.  
  745.        DCL inpcid LEN(5 0)
  746.        ...
  747.        MOVE true pgminz
  748.     ENDIF
  749.  
  750.  
  751. HALF-ADJUST
  752.  
  753. On arithmetic operations, you can code H() to specify half-adjust.
  754.  
  755.  
  756. RESULTING INDICATORS
  757.  
  758. You can specify up to three resulting indicators in two ways: as a list
  759. enclosed within RESULT(...) or with resulting indicator keywords.
  760.  
  761. The three relative positions within a RESULT(...) list correspond to positions
  762. 54-55, 56-57, and 58-59.  For example:
  763.  
  764.                             555555
  765.     RPG/free                    456789
  766.     ----------------                ------
  767.     RESULT(01 *n 02)          generates    01  02
  768.  
  769. You can use symbolic indicators as in RESULT(*in01 *in02).  You cannot use
  770. negated indicators (e.g., N01).
  771.  
  772. Instead of a RESULT(...) list, you can use the following keywords:
  773.  
  774.     54-55        56-57        58-59        Notes
  775.     ----------    ----------    ----------    -----------
  776.     RI1        RI2        RI3        e.g., SETON
  777.     POS        NEG        ZER        e.g., ADD
  778.                     ZERO
  779.                     ZERBLK        e.g., MOVE
  780.                     BLANK
  781.                     BLK
  782.     HI        LO        EQ        e.g., LOKUP
  783.     NR        ER        EOF        e.g., CHAIN, READ
  784.             ERR        BOF        e.g., READP
  785.     OFF        MIX        ON        TESTB
  786.     ALLNUM        LEADBLK        ALLBLK        TESTN
  787.     ZONEA        ZONEJ        ZONEX        TESTZ
  788.     SHTDN                        SHTDN
  789.  
  790. You don't have to use the matching keywords for each operation.  For example,
  791. you can use:
  792.  
  793.     MOVE x  y  HI(01) LO(02) EQ(03)
  794.  
  795. You can place keywords in any order, but you cannot specify the same standard
  796. RPG positions more than once.  You can use symbolic indicators, but not
  797. negated indicators.  You cannot use *n with resulting indicator keywords.
  798.  
  799.  
  800. COMMENTS
  801.  
  802. You can add a trailing comment to any RPG/free statement, except the /DEFINE
  803. and /TITLE directives.  Comments can be added to other directives and 
  804. non-C-specs as well as C-specs.  You cannot add comments to lines that follow 
  805. the /DATA directive, lines between /FIX and /FREE directives, or lines in a file
  806. included with the /INCLUDEF directive.  (You can place comments on lines in a 
  807. file included with the /INCLUDE directive.)
  808.  
  809. Use -- to begin a comment.  For example:
  810.  
  811.     add a b -- This is a comment
  812.  
  813. The comment ends at the end of the input line or at the last character before
  814. a plus sign (+) indicates a continued statement.  The first unquoted -- in a
  815. line marks the beginning of the comment.  Although you can generally leave
  816. blanks out of assignment operations (e.g., a=b-c), don't code "b minus -3" 
  817. as  b--3 because the --3 will be treated as a comment.
  818.  
  819. To code a comment line, just begin with -- anywhere in the line.
  820.  
  821.  
  822. CONTINUATIONS
  823.  
  824. You can continue an RPG/free statement across multiple lines by coding a +
  825. as the last nonblank, nontab character on a line: 
  826.  
  827.     MOVE     'Name' +
  828.          outfld
  829.  
  830. When the RPG/free precompiler reads an input line, the precompiler first checks 
  831. for, and removes, a trailing + specifying a continued statement.  The 
  832. precompiler than scans the line for an unquoted -- marking the beginning of a 
  833. comment.  Any comment is removed from the input line and output as
  834.  
  835.     C*-- Comment
  836.  
  837. The precompiler reads the next line and removes all leading blanks before the
  838. line is concatenated to the end of the continued line.  The precompiler
  839. repeats this process until the end of a statement (i.e., no continuation or
  840. end-of-input).  The precompiler then parses the input statement according to
  841. RPG/free syntax rules.
  842.  
  843.  
  844. DIRECTIVES
  845.  
  846. RPG/free supports the following standard RPG compiler directives:
  847.  
  848.     /COPY    host-file-member-spec
  849.  
  850.     /EJECT
  851.  
  852.     /EXEC SQL   sql-statement
  853.       sql-statement
  854.       ...
  855.     /END-EXEC
  856.  
  857.     /SKIP   n
  858.  
  859.     /SPACE  n
  860.  
  861.     /TITLE   title
  862.  
  863. You can use blanks and tabs between a directive keyword and its argument,
  864. the precompiler realigns the argument to meet standard RPG requirements.
  865. SQL statements between the /EXEC SQL and /END-EXEC directives must not have the 
  866. leading + used in standard RPG/400; the + is added by the precompiler.
  867.  
  868.  
  869. RPG/free includes the following precompiler directives:
  870.  
  871.     /DEFINE   identifier  replacement-text        Define a macro
  872.  
  873.     /UNDEFINE identifier                Remove macro definition
  874.  
  875.     /FIRSTCOL  n                    Set output position
  876.                             for non-C-specs
  877.  
  878.     /FIX                        Begin fixed input
  879.  
  880.     /FREE                        Resume free format input
  881.  
  882.     /INCLUDE  pc-file-spec                Include free format 
  883.                             file
  884.  
  885.     /INCLUDEF pc-file-spec                Include fixed format 
  886.                             file
  887.  
  888.  
  889. SETTING FIRST COLUMN (/FIRSTCOL)
  890.  
  891. The /FIRSTCOL directive has an argument from 1 to 7 that specifies the
  892. position in the standard RPG output where the first position in a non-C-spec
  893. input line will be placed.  The default is 6 which requires you to begin
  894. non-C-specs with the proper form type character.
  895.  
  896. /FIRSTCOL does not effect lines between /FIX and /FREE directives, within
  897. an /INCLUDEF file, or following the /DATA directive.
  898.  
  899.  
  900. SOURCE MACROS (/DEFINE and /UNDEFINE)
  901.  
  902. An RPG/free source macro is an identifier for a string of replacement text.
  903. Although RPG/free macros are fairly simple, they provide great flexibility in
  904. creating highly readable programs.  To define a macro, code /DEFINE followed by
  905. one or more blanks and tabs and the macro name.  Follow the macro name with
  906. one or more blanks or tabs and then code the replacement text.  The replacement
  907. text begins with the first nonblank, nontab after the macro name and ends with
  908. the last nonblank, nontab character on the same line.
  909.  
  910. The macro name must begin with a letter or national character ($, #, @) and can
  911. include letters, national characters, numbers, and the _ (underscore)
  912. readability character.  Upper and lower case letters are considered identical
  913. in matching macro names.  A macro name can be up to 80 characters long.
  914.  
  915. The replacement text can include any characters, except leading or trailing
  916. blanks and tabs, which are always trimmed.  Remember not to code comments or
  917. continuations on a macro because they are not processed and become part of 
  918. the replacement text. 
  919.  
  920. As the precompiler encounters tokens during its parse of an RPG/free C-spec,
  921. it replaces every occurrence of a macro identifier with the corresponding
  922. replacement text.  The precompiler then restarts its parse at the beginning
  923. of the replacement text, thus allowing nested macros.  For example:
  924.  
  925.     /DEFINE    customer_id    csid
  926.     /DEFINE exit_key    *in03
  927.     /DEFINE true        '1'
  928.     /DEFINE IFNOT        IF true <>
  929.  
  930.     IFNOT    exit_key        becomes           IF '1' <> *in03
  931.  
  932. The precompiler does not replace a macro in any input line until it encounters 
  933. the macro's definition on a /DEFINE.  When another /DEFINE for the same macro
  934. is encountered, the replacement text is changed for subsequent input lines.
  935. As some examples:
  936.  
  937.     /DEFINE    customer_id csid
  938.  
  939.     MOVE customer_id  outfld    becomes    MOVE csid outfld
  940.  
  941.     /DEFINE customer_id custid
  942.  
  943.     MOVE customer_id  outfld    becomes    MOVE custid outfld
  944.  
  945. If you code a /DEFINE with a macro name and replacement text that is nothing
  946. but blanks and tabs, the precompiler replaces the macro name with the null
  947. string (i.e., deletes it) when the macro is encountered in subsequent input
  948. lines.  You can use this to add readability words to your statements:
  949.  
  950.     /DEFINE  TO
  951.     /DEFINE     FROM
  952.  
  953.     ADD x TO y            becomes        ADD x y
  954.  
  955.     SUB x FROM y            becomes        SUB x y
  956.  
  957. Be careful not to code recursive macros, which will cause a syntax error:
  958.  
  959.     /DEFINE x y
  960.     /DEFINE y x
  961.  
  962.     a = x  causes syntax error
  963.  
  964. To remove a macro definition, use /UNDEFINE with the macro name:
  965.  
  966.     /DEFINE x csid
  967.  
  968.     a = x                becomes        a = csid
  969.  
  970.     /UNDEFINE x
  971.  
  972.     a = x                remains        a = x
  973.  
  974.  
  975. FIXED FORMAT INPUT (/FIX and /FREE)
  976.  
  977. You can included standard, fixed-format RPG in an RPG/free source file by
  978. placing it after a /FIX directive.  All records following a /FIX directive
  979. are moved without any modification to the output.  Fixed format lines end
  980. when a /FREE directive or end-of-file is encountered.  You cannot span
  981. multiple input files with a /FIX; you must code a /FIX at the beginning of each
  982. one.  (This approach prevents "runaway" /FIX directives.)
  983.  
  984.  
  985. INCLUDING SOURCE FILES (/INCLUDE and /INCLUDEF)
  986.  
  987. You can include RPG/free source at any point in the input by coding an /INCLUDE
  988. directive with a PC file specification:
  989.  
  990.     /INCLUDE  include1.rpf
  991.  
  992. You can nest /INCLUDEs up to 20 deep (or the current DOS limit on open files),
  993. but you cannot use recursive /INCLUDEs.
  994.  
  995. With /INCLUDE, all input is treated as RPG/free code (unless the included file
  996. contains a /FIX or /DATA directive).
  997.  
  998. To include standard, fixed-format RPG, use /INCLUDEF.  All input lines from a 
  999. file specified on an /INCLUDEF are treated the same as if they followed a /FIX
  1000. directive.  The RPG/free precompiler does not recognize any directives
  1001. within a file included using /INCLUDEF.
  1002.  
  1003.  
  1004. COMBINING MACROS AND INCLUDE FILES
  1005.  
  1006. A powerful technique is to use /INCLUDEs to "reuse" standard macros.  
  1007. Consider the following file as SYSMAC.RPM:
  1008.  
  1009.     /DEFINE    true    '1'
  1010.     /DEFINE false    '0'
  1011.     /DEFINE IFNOT    IF true <>
  1012.     ...
  1013.  
  1014. Then in any RPG/free program, you can simply code:
  1015.  
  1016.     /INCLUDE sysmac.rpm
  1017.  
  1018. to get the standard definitions.  You can create /INCLUDE files for indicator
  1019. definitions, standard variable declarations, etc.  
  1020.  
  1021. Another technique is to define standard long names for database file fields.
  1022. Consider the following file as CUSFLD.RPM:
  1023.  
  1024.     -- Customer file (CUSMST)
  1025.  
  1026.     /DEFINE    Cust_ID        csid
  1027.     /DEFINE    Cust_name    csnam
  1028.     /DEFINE    Cust_discount    csdsc
  1029.     ...
  1030.  
  1031. In any program that references the CUSMST file, you can simply code:
  1032.  
  1033.     /INCLUDE cusfld.rpm
  1034.  
  1035. to make available the standard long names.  On the S/38 and AS/400, you can
  1036. automatically generate files like CUSFLD.RPM by using the DSPFFD (Display
  1037. File Field Description) command.  An article describing this technique and
  1038. the necessary CL and RPG/400 code is scheduled for publication in NEWS 3X/400
  1039. in the summer of 1990.
  1040.  
  1041. -- End of RFREE.DOC --