═══ 1. Introduction & Command Line Syntax ═══ DESCRIPTION This is a rexx preprocessor which provides many of the same advantages as the 'C' preprocessor. It provides "#include" & "#define" facilities amoungst others. Depending on the options chosen the generated rexx procedure will take up much less disk space and may be stipped of comments altogether (making it much harder for someone to work out your code). SYNTAX REXBUILD[.EXE] SourceFile TargetFile [Options] The "SourceFile" parameter of course specifies the input file while the "TargetFile" specifies the name of the generated rexx procedure. The extensions must be specified as there are no defaults. Valid "Options" are as follows: 1. $LeaveComments Unless this option is specified then comments which don't span multiple lines are removed from the generated output. 2. $LeaveIndents Ulness this option is specified, all leading whitespace is removed from every line in the target file. 3. $LeaveBlankLines Normally blank lines (all whitespace) are removed, use this option to keep them in. 4. $WarningOnSussText If your used to writing 'C' code you will tend to use ' and '!=' in rexx code. By default this will cause this program to fail with a non zero return code. This option will cause a warning to be generated and prevent the premature termination of processing. keep them in. ═══ 2. Source Structure ═══ Any line that starts with the character ";" is considered to be a comment and is dropped altogether. This program optionally removes rexx comments from your source (on by default) so that if the "/*" and "*/" strings are found on the same line they will be removed. If you need to create strings containing these characters then I suggest something along the lines of ""/" || "*"". The source may contain commands such as "#include" or strings (such as "{__FILE__}") to be replaced during the build process. ═══ 3. Commands ═══ The commands that are available are a subset of the 'C' preprocessor commands and they all have a similar syntax to their 'C' counterparts so as not to confuse you. Available commands are as follows: 1. #define 2. #include ═══ 3.1. #define ═══ DESCRIPTION This command is used to create or remove definitions which define text to be substituted. You should be very careful when naming these items as test is replaced anyplace within a line, not just tokens. You could use this command within a header file (included with #include) to create headers of standard definitions. SYNTAX #define ["|'"]DefineName["|'"] Contents The "DefineName" parameter specifies what you wish replaced in code that follows, it may have been used before in which case the new definition replaces the old. Most characters can be used in a definitions name. The Contents parameter specifies the value that will replace the "DefineName" string whenever its found in subsequent source lines. The value is the rest of the line after the "DefineName" stripped of leading & trailing whitespace. The "Contents" value may contain other standard definitions (such as {__FILE__}) however (in this version) should not include your own definitions. You can remove (#undef) a variable by leaving off the "Contents" parameter. ═══ 3.2. #include ═══ DESCRIPTION This command will imbed the code into the generated file much exactly like the command under 'C'. The included filename can either a full filename or one that can be found in the paths specified in one of the following environment variables: 1. REXBUILD 2. INCLUDE The #include command will allow you to set up libraries of small routines which you can use much like the 'C' runtime library routines. You would just include the ones you reference in your code. Of course you can also set up header files which don't include code but create 'standard' definitions through the use of the #define command. SYNTAX #include ["|'"]filename["|'"] ═══ 4. Variable Replacement ═══ There are a number of standard variables which are defined in the system, a list of these follows: 1. {BuiltAt} 2. ??? Note that these variables are case sensitive, you must get the case right! ═══ 4.1. {BuiltAt} ═══ This value is replaced with the date & time that the build took place. Note that there are other variables which may be of use such as "{Time}". The output will be a string similar to "Sun Nov 13 1994 05:18:35PM". ═══ 4.2. {DateDDMMYY} ═══ This value is replaced with the date that the build is taking place. The time can be obtained with "{Time}" The output will be a string similar to "13/11/94". ═══ 4.3. {RexBuildVersion} ═══ This value is replaced with the version number of the RexBuild.exe program which is being used. The output will be a string similar to "94.307". ═══ 4.4. {Time} ═══ This value is replaced with the time that the build is taking place. The date can be obtained with "{DateDDMMYY}" The output will be a string similar to "09:33a". ═══ 4.5. {TimeVersion} ═══ This value is replaced with a short string which can be used as a timestamp/version string. The output will be a string similar to "131194.0933". ═══ 4.6. {__FILE__} ═══ This value is replaced by the full name of the current file being processed. This may be the file specified on the compilers command line or the name of any header being included. The {__file__} variable will give you the same filename without the path & the {__LINE__} variable will give you the current line number in the same file. ═══ 4.7. {__file__} ═══ This value is replaced by the name of the current file being processed without its path. This may be the file specified on the compilers command line or the name of any header being included. The {__FILE__} variable will give you the same filename with the path & {__LINE__} variable will give you the current line number in the same file. ═══ 4.8. {__LINE__} ═══ This value is replaced by the current line number within the current file being processed. This may be the file specified on the compilers command line or the name of any header being included. The {__file__} or {__FILE__} variables will give you the name of the file this line number is contained in. ═══ 4.9. {__OFILE__} ═══ This value is replaced by the name of the output file being generated. The filename includes any path specified on the build command line, so that it may or may not have a path attached. The {__ofile__} variable will give you the same filename without the path & {__OLINE__} variable will give you the current line number in the same file. ═══ 4.10. {__ofile__} ═══ Not yet implemented... ??? ═══ 4.11. {__OLINE__} ═══ This value is replaced by the current line number within the file being generated. The {__ofile__} or {__OFILE__} variables will give you the name of the file this line number is contained in. ═══ 4.12. {__IFILE__} ═══ This value is replaced with the full filename of the input file specified on the build command line. This is the 'controlling' file which may include many other header files. ═══ 4.13. {__ILINE__} ═══ Not yet implemented... ??? ═══ 5. Example ═══ SOURCE #1 - EXAMPLE.X ;--------------------------------------------------------------------------- ; ; MODULE NAME: EXAMPLE.X ; ; $Author: Dennis Bareis $ ; $Revision: 1.0 $ ; $Date: 01 Dec 1993 13:30:24 $ ; $Logfile: V:/SUEPVCS/SUPPORT/TEMPLATE.DEV $ ; ; DESCRIPTION: These comments will disappear during compile as the ; 1st significant character in each line is a semi colon. ; ; The only purpose of this file is as an small example, of ; what can be done. ; ; Note that I use ".X" for 'rexx' code and '.XH' for ; header files. ;--------------------------------------------------------------------------- /* * This comment will remain whether or not you are stripping out rexx * comments as it spans multiple lines. * * $Header: V:/PVCS_PF/MSS/INSTALL/JUSTINI.X_V 1.0 14 Sep 1994 08:12:14 Dennis_Bareis $ */ /*--- Display a few variables -----------------------------------------------*/ say 'About to display some standard 'defines' and their values.' #include "example.xh" /*--- Create a definition which will describe where an error is detected ----*/ #define $ERRORLOC "Line #{__OLINE__} - #{__LINE__} in {__file__}" /*--- Expect one argument ---------------------------------------------------*/ if arg(1) = "" then call ERROR_EXIT $ERRORLOC, "Not enough parameters, expected 1" /*--- Now exit --------------------------------------------------------------*/ say 'Thats All Folks!' exit; ;############################################################################ ERROR_EXIT: ;############################################################################ say 'ERROR: ' || ARG(2); say ' AT: ' || ARG(1); exit 255; SOURCE #2 - EXAMPLE.XH ;--------------------------------------------------------------------------- ; ; MODULE NAME: EXAMPLE.XH ; ; $Author: Dennis Bareis $ ; $Revision: 1.0 $ ; $Date: 01 Dec 1993 13:30:24 $ ; $Logfile: V:/SUEPVCS/SUPPORT/TEMPLATE.DEV $ ; ; DESCRIPTION: Header file for inclusion in the example rexx program ; "EXAMPLE.X". ;--------------------------------------------------------------------------- say '{' || '__FILE__} = "{__FILE__}"'; say '{' || '__file__} = "{__file__}"'; say '{' || '__LINE__} = "{__LINE__}"'; say '{' || '__IFILE__} = "{__IFILE__}"'; say '{' || '__ILINE__} = "{__ILINE__}"'; say '{' || '__OFILE__} = "{__OFILE__}"'; say '{' || '__OLINE__} = "{__OLINE__}"'; say '{' || 'TimeVersion} = "{TimeVersion}"'; say '{' || 'Time} = "{Time}"'; say '{' || 'DateDDMMYY} = "{DateDDMMYY}"'; say '{' || 'BuiltAt} = "{BuiltAt}"'; say '{' || 'RexBuildVersion} = "{RexBuildVersion}"'; say ''; say ''; say ''; Compile Command REXBUILD.EXE EXAMPLE.X OUT\EXAMPLE.CMD $LeaveIndents OUTPUT - EXAMPLE.CMD /* * REXBUILD VERSION: 94.317 * BUILT AT : Sat Nov 01 1997 03:15:57PM * SOURCE : E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X * DESTINATION : OUT\EXAMPLE.CMD */ /* @ START FILE: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X (Sat Nov 01 1997 03:15:12PM) */ /* * This comment will remain whether or not you are stripping out rexx * comments as it spans multiple lines. * * $Header: V:/PVCS_PF/MSS/INSTALL/JUSTINI.X_V 1.0 14 Sep 1994 08:12:14 Dennis_Bareis $ */ /* @ EXAMPLE.X(30) */ say 'About to display some standard 'defines' and their values.' /* @ FILE>: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X, LINE: 32 */ /* @ START FILE: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.XH (Sat Nov 01 1997 03:15:12PM) */ say '{' || '__FILE__} = "E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.XH"'; say '{' || '__file__} = "EXAMPLE.XH"'; say '{' || '__LINE__} = "17"'; say '{' || '__IFILE__} = "E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X"'; say '{' || '__ILINE__} = "{__ILINE__}"'; say '{' || '__OFILE__} = "OUT\EXAMPLE.CMD"'; say '{' || '__OLINE__} = "25"'; say '{' || 'TimeVersion} = "011197.1515"'; say '{' || 'Time} = "03:15p"'; say '{' || 'DateDDMMYY} = "01/11/97"'; say '{' || 'BuiltAt} = "Sat Nov 01 1997 03:15:57PM"'; say '{' || 'RexBuildVersion} = "94.317"'; /* @ EXAMPLE.XH(30) */ say ''; say ''; say ''; /* @ END FILE: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.XH (processed 33 lines) */ /* @ FILE<: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X, LINE: 32 */ if arg(1) = "" then call ERROR_EXIT "Line #38 - #40 in EXAMPLE.X", "Not enough parameters, expected 1" say 'Thats All Folks!' exit; ERROR_EXIT: say 'ERROR: ' || ARG(2); say ' AT: ' || ARG(1); exit 255; /* @ END FILE: E:\DB\PROJECTS\OS2\REXBUILD\EXAMPLE.X (processed 60 lines) */