home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxb97305.zip / REXBUILD.INF (.txt) < prev   
OS/2 Help File  |  1997-11-01  |  12KB  |  392 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction & Command Line Syntax ΓòÉΓòÉΓòÉ
  3.  
  4. DESCRIPTION 
  5.  
  6. This is a rexx preprocessor which provides many of the same advantages as the 
  7. 'C' preprocessor.  It  provides "#include" & "#define" facilities amoungst 
  8. others. 
  9.  
  10. Depending on the options chosen the generated rexx procedure will take up much 
  11. less disk space and may be stipped of comments altogether (making it much 
  12. harder for someone to work out your code). 
  13.  
  14. SYNTAX 
  15.  
  16.           REXBUILD[.EXE]  SourceFile  TargetFile  [Options]
  17.  
  18.  The "SourceFile" parameter of course specifies the input file while the 
  19.  "TargetFile" specifies the name of the generated rexx procedure.  The 
  20.  extensions must be specified as there are no defaults. 
  21.  
  22.  Valid "Options" are as follows: 
  23.  
  24.        1. $LeaveComments 
  25.           Unless this option is specified then comments which don't span 
  26.           multiple lines are removed from the generated output. 
  27.  
  28.        2. $LeaveIndents 
  29.           Ulness this option is specified, all leading whitespace is removed 
  30.           from every line in the target file. 
  31.  
  32.        3. $LeaveBlankLines 
  33.           Normally blank lines (all whitespace) are removed, use this option to 
  34.           keep them in. 
  35.  
  36.        4. $WarningOnSussText 
  37.           If your used to writing 'C' code you will tend to use '  and '!=' in 
  38.           rexx code.  By default this will cause this program to fail with a 
  39.           non zero return code.  This option will cause a warning to be 
  40.           generated and prevent the premature termination of processing. keep 
  41.           them in. 
  42.  
  43.  
  44. ΓòÉΓòÉΓòÉ 2. Source Structure ΓòÉΓòÉΓòÉ
  45.  
  46. Any line that starts with the character ";" is considered to be a comment and 
  47. is dropped altogether. This program optionally removes rexx comments from your 
  48. source (on by default) so that if the "/*" and "*/" strings are found on the 
  49. same line they will be removed.  If you need to create strings containing these 
  50. characters then I suggest something along the lines of ""/" || "*"". 
  51.  
  52. The source may contain commands such as "#include" or strings (such as 
  53. "{__FILE__}") to be replaced during the build process. 
  54.  
  55.  
  56. ΓòÉΓòÉΓòÉ 3. Commands ΓòÉΓòÉΓòÉ
  57.  
  58. The commands that are available are a subset of the 'C' preprocessor commands 
  59. and they all have a similar syntax to their 'C' counterparts so as not to 
  60. confuse you. 
  61.  
  62. Available commands are as follows: 
  63.  
  64.        1. #define 
  65.        2. #include 
  66.  
  67.  
  68. ΓòÉΓòÉΓòÉ 3.1. #define ΓòÉΓòÉΓòÉ
  69.  
  70. DESCRIPTION 
  71.  
  72. This command is used to create or remove definitions which define text to be 
  73. substituted. 
  74.  
  75. You should be very careful when naming these items as test is replaced anyplace 
  76. within a line, not just tokens. 
  77.  
  78. You could use this command within a header file (included with #include) to 
  79. create headers of standard definitions. 
  80.  
  81. SYNTAX 
  82.  
  83. #define  ["|'"]DefineName["|'"]  Contents
  84.  
  85. The "DefineName" parameter specifies what you wish replaced in code that 
  86. follows, it may have been used before in which case the new definition replaces 
  87. the old.  Most characters can be used in a definitions name. 
  88.  
  89. The Contents parameter specifies the value that will replace the "DefineName" 
  90. string whenever its found in subsequent source lines.  The value is the rest of 
  91. the line after the "DefineName" stripped of leading & trailing whitespace. 
  92.  
  93. The "Contents" value may contain other standard definitions (such as 
  94. {__FILE__}) however (in this version) should not include your own definitions. 
  95.  
  96. You can remove (#undef) a variable by leaving off the "Contents" parameter. 
  97.  
  98.  
  99. ΓòÉΓòÉΓòÉ 3.2. #include ΓòÉΓòÉΓòÉ
  100.  
  101. DESCRIPTION 
  102.  
  103. This command will imbed the code into the generated file much exactly like the 
  104. command under 'C'. 
  105.  
  106. The included filename can either a full filename or one that can be found in 
  107. the paths specified in one of the following environment variables: 
  108.  
  109.        1. REXBUILD 
  110.        2. INCLUDE 
  111.  
  112.  The #include command will allow you to set up libraries of small routines 
  113.  which you can use much like the 'C' runtime library routines.  You would just 
  114.  include the ones you reference in your code. 
  115.  
  116.  Of course you can also set up header files which don't include code but create 
  117.  'standard' definitions through the use of the #define command. 
  118.  
  119.  SYNTAX 
  120.  
  121.   #include  ["|'"]filename["|'"]
  122.  
  123.  
  124. ΓòÉΓòÉΓòÉ 4. Variable Replacement ΓòÉΓòÉΓòÉ
  125.  
  126. There are a number of standard variables which are defined in the system, a 
  127. list of these follows: 
  128.  
  129.        1. {BuiltAt} 
  130.  
  131.        2. ??? 
  132.  
  133.  Note that these variables are case sensitive, you must get the case right! 
  134.  
  135.  
  136. ΓòÉΓòÉΓòÉ 4.1. {BuiltAt} ΓòÉΓòÉΓòÉ
  137.  
  138. This value is replaced with the date & time that the build took place.  Note 
  139. that there are other variables which may be of use such as "{Time}". 
  140.  
  141. The output will be a string similar to "Sun Nov 13 1994 05:18:35PM". 
  142.  
  143.  
  144. ΓòÉΓòÉΓòÉ 4.2. {DateDDMMYY} ΓòÉΓòÉΓòÉ
  145.  
  146. This value is replaced with the date that the build is taking place.  The time 
  147. can be obtained with "{Time}" 
  148.  
  149. The output will be a string similar to "13/11/94". 
  150.  
  151.  
  152. ΓòÉΓòÉΓòÉ 4.3. {RexBuildVersion} ΓòÉΓòÉΓòÉ
  153.  
  154. This value is replaced with the version number of the RexBuild.exe program 
  155. which is being used. 
  156.  
  157. The output will be a string similar to "94.307". 
  158.  
  159.  
  160. ΓòÉΓòÉΓòÉ 4.4. {Time} ΓòÉΓòÉΓòÉ
  161.  
  162. This value is replaced with the time that the build is taking place.  The date 
  163. can be obtained with "{DateDDMMYY}" 
  164.  
  165. The output will be a string similar to "09:33a". 
  166.  
  167.  
  168. ΓòÉΓòÉΓòÉ 4.5. {TimeVersion} ΓòÉΓòÉΓòÉ
  169.  
  170. This value is replaced with a short string which can be used as a 
  171. timestamp/version string. 
  172.  
  173. The output will be a string similar to "131194.0933". 
  174.  
  175.  
  176. ΓòÉΓòÉΓòÉ 4.6. {__FILE__} ΓòÉΓòÉΓòÉ
  177.  
  178. This value is replaced by the full name of the current file being processed. 
  179. This may be the file specified on the compilers command line or the name of any 
  180. header being included. 
  181.  
  182. The {__file__}  variable will give you the same filename without the path & the 
  183. {__LINE__} variable will give you the current line number in the same file. 
  184.  
  185.  
  186. ΓòÉΓòÉΓòÉ 4.7. {__file__} ΓòÉΓòÉΓòÉ
  187.  
  188. This value is replaced by the name of the current file being processed without 
  189. its path.  This may be the file specified on the compilers command line or the 
  190. name of any header being included. 
  191.  
  192. The {__FILE__} variable will give you the same filename with the path & 
  193. {__LINE__} variable will give you the current line number in the same file. 
  194.  
  195.  
  196. ΓòÉΓòÉΓòÉ 4.8. {__LINE__} ΓòÉΓòÉΓòÉ
  197.  
  198. This value is replaced by the current line number within the current file being 
  199. processed.  This may be the file specified on the compilers command line or the 
  200. name of any header being included. 
  201.  
  202. The {__file__} or {__FILE__} variables will give you the name of the file this 
  203. line number is contained in. 
  204.  
  205.  
  206. ΓòÉΓòÉΓòÉ 4.9. {__OFILE__} ΓòÉΓòÉΓòÉ
  207.  
  208. This value is replaced by the name of the output file being generated.  The 
  209. filename includes any path specified on the build command line, so that it may 
  210. or may not have a path attached. 
  211.  
  212. The {__ofile__}  variable will give you the same filename without the path & 
  213. {__OLINE__} variable will give you the current line number in the same file. 
  214.  
  215.  
  216. ΓòÉΓòÉΓòÉ 4.10. {__ofile__} ΓòÉΓòÉΓòÉ
  217.  
  218. Not yet implemented... ??? 
  219.  
  220.  
  221. ΓòÉΓòÉΓòÉ 4.11. {__OLINE__} ΓòÉΓòÉΓòÉ
  222.  
  223. This value is replaced by the current line number within the file being 
  224. generated. 
  225.  
  226. The {__ofile__} or {__OFILE__} variables will give you the name of the file 
  227. this line number is contained in. 
  228.  
  229.  
  230. ΓòÉΓòÉΓòÉ 4.12. {__IFILE__} ΓòÉΓòÉΓòÉ
  231.  
  232. This value is replaced with the full filename of the input file specified on 
  233. the build command line.  This is the 'controlling' file which may include many 
  234. other header files. 
  235.  
  236.  
  237. ΓòÉΓòÉΓòÉ 4.13. {__ILINE__} ΓòÉΓòÉΓòÉ
  238.  
  239. Not yet implemented... ??? 
  240.  
  241.  
  242. ΓòÉΓòÉΓòÉ 5. Example ΓòÉΓòÉΓòÉ
  243.  
  244. SOURCE #1 - EXAMPLE.X 
  245.  
  246. ;---------------------------------------------------------------------------
  247. ;
  248. ;     MODULE NAME:   EXAMPLE.X
  249. ;
  250. ;         $Author:   Dennis Bareis  $
  251. ;       $Revision:   1.0  $
  252. ;           $Date:   01 Dec 1993 13:30:24  $
  253. ;        $Logfile:   V:/SUEPVCS/SUPPORT/TEMPLATE.DEV  $
  254. ;
  255. ;     DESCRIPTION:   These comments will disappear during compile as the
  256. ;                    1st significant character in each line is a semi colon.
  257. ;
  258. ;                    The only purpose of this file is as an small example, of
  259. ;                    what can be done.
  260. ;
  261. ;                    Note that I use ".X" for 'rexx' code and '.XH' for
  262. ;                    header files.
  263. ;---------------------------------------------------------------------------
  264.  
  265.  
  266.  
  267. /*
  268.  * This comment will remain whether or not you are stripping out rexx
  269.  * comments as it spans multiple lines.
  270.  *
  271.  * $Header:   V:/PVCS_PF/MSS/INSTALL/JUSTINI.X_V   1.0   14 Sep 1994 08:12:14   Dennis_Bareis  $
  272.  */
  273.  
  274.  
  275. /*--- Display a few variables -----------------------------------------------*/
  276. say 'About to display some standard 'defines' and their values.'
  277. #include "example.xh"
  278.  
  279. /*--- Create a definition which will describe where an error is detected ----*/
  280. #define $ERRORLOC  "Line #{__OLINE__} - #{__LINE__} in {__file__}"
  281.  
  282.  
  283. /*--- Expect one argument ---------------------------------------------------*/
  284. if arg(1) = "" then
  285.    call ERROR_EXIT $ERRORLOC, "Not enough parameters, expected 1"
  286.  
  287. /*--- Now exit --------------------------------------------------------------*/
  288. say 'Thats All Folks!'
  289. exit;
  290.  
  291.  
  292.  
  293. ;############################################################################
  294. ERROR_EXIT:
  295. ;############################################################################
  296.    say 'ERROR: ' || ARG(2);
  297.    say '   AT: ' || ARG(1);
  298.    exit 255;
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306. SOURCE #2 - EXAMPLE.XH 
  307.  
  308. ;---------------------------------------------------------------------------
  309. ;
  310. ;     MODULE NAME:   EXAMPLE.XH
  311. ;
  312. ;         $Author:   Dennis Bareis  $
  313. ;       $Revision:   1.0  $
  314. ;           $Date:   01 Dec 1993 13:30:24  $
  315. ;        $Logfile:   V:/SUEPVCS/SUPPORT/TEMPLATE.DEV  $
  316. ;
  317. ;     DESCRIPTION:   Header file for inclusion in the example rexx program
  318. ;                    "EXAMPLE.X".
  319. ;---------------------------------------------------------------------------
  320.  
  321.  
  322. say '{' || '__FILE__}        = "{__FILE__}"';
  323. say '{' || '__file__}        = "{__file__}"';
  324. say '{' || '__LINE__}        = "{__LINE__}"';
  325.  
  326. say '{' || '__IFILE__}       = "{__IFILE__}"';
  327. say '{' || '__ILINE__}       = "{__ILINE__}"';
  328.  
  329. say '{' || '__OFILE__}       = "{__OFILE__}"';
  330. say '{' || '__OLINE__}       = "{__OLINE__}"';
  331.  
  332. say '{' || 'TimeVersion}     = "{TimeVersion}"';
  333. say '{' || 'Time}            = "{Time}"';
  334. say '{' || 'DateDDMMYY}      = "{DateDDMMYY}"';
  335. say '{' || 'BuiltAt}         = "{BuiltAt}"';
  336. say '{' || 'RexBuildVersion} = "{RexBuildVersion}"';
  337. say '';
  338. say '';
  339. say '';
  340.  
  341. Compile Command 
  342.  
  343. REXBUILD.EXE  EXAMPLE.X  OUT\EXAMPLE.CMD  $LeaveIndents
  344.  
  345. OUTPUT - EXAMPLE.CMD 
  346.  
  347. /*
  348.  * REXBUILD VERSION: 94.317
  349.  * BUILT AT        : Sat Nov 01 1997 03:15:57PM
  350.  * SOURCE          : E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X
  351.  * DESTINATION     : OUT\EXAMPLE.CMD
  352.  */
  353.  
  354. /* @ START FILE: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X (Sat Nov 01 1997 03:15:12PM) */
  355. /*
  356.  * This comment will remain whether or not you are stripping out rexx
  357.  * comments as it spans multiple lines.
  358.  *
  359.  * $Header:   V:/PVCS_PF/MSS/INSTALL/JUSTINI.X_V   1.0   14 Sep 1994 08:12:14   Dennis_Bareis  $
  360.  */
  361. /* @ EXAMPLE.X(30) */
  362. say 'About to display some standard 'defines' and their values.'
  363. /* @ FILE>: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X, LINE: 32 */
  364. /* @ START FILE: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.XH (Sat Nov 01 1997 03:15:12PM) */
  365. say '{' || '__FILE__}        = "E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.XH"';
  366. say '{' || '__file__}        = "EXAMPLE.XH"';
  367. say '{' || '__LINE__}        = "17"';
  368. say '{' || '__IFILE__}       = "E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X"';
  369. say '{' || '__ILINE__}       = "{__ILINE__}"';
  370. say '{' || '__OFILE__}       = "OUT\EXAMPLE.CMD"';
  371. say '{' || '__OLINE__}       = "25"';
  372. say '{' || 'TimeVersion}     = "011197.1515"';
  373. say '{' || 'Time}            = "03:15p"';
  374. say '{' || 'DateDDMMYY}      = "01/11/97"';
  375. say '{' || 'BuiltAt}         = "Sat Nov 01 1997 03:15:57PM"';
  376. say '{' || 'RexBuildVersion} = "94.317"';
  377. /* @ EXAMPLE.XH(30) */
  378. say '';
  379. say '';
  380. say '';
  381. /* @ END   FILE: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.XH (processed 33 lines) */
  382. /* @ FILE<: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X, LINE: 32 */
  383. if arg(1) = "" then
  384.    call ERROR_EXIT "Line #38 - #40 in EXAMPLE.X", "Not enough parameters, expected 1"
  385. say 'Thats All Folks!'
  386. exit;
  387. ERROR_EXIT:
  388.    say 'ERROR: ' || ARG(2);
  389.    say '   AT: ' || ARG(1);
  390.    exit 255;
  391. /* @ END   FILE: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X (processed 60 lines) */
  392.