home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / somtempl.zip / SOMTEMPL.TXT < prev   
Text File  |  1996-02-14  |  23KB  |  551 lines
  1.  
  2. SOMTEMPL: The SOM Template Application Builder
  3.  
  4. The somtempl program is a programming utility that generates SOM source files
  5. and programs from predefined templates.  It is a useful tool to simplify
  6. repetitive SOM programming tasks.  In general, it can generate any sort of
  7. text file from a predefined template; however, it's options are primarily
  8. focused at SOM programming.  It can also be used similarly to C++ templates
  9. to define parameterized SOM classes.  For beginners, somtempl is also useful
  10. because it includes a template for a complete SOM/DSOM program - including
  11. make files for AIX, OS/2 and Windows.
  12.  
  13. Running somtempl
  14.  
  15. To run somtempl, simply enter at the command line:
  16.  
  17.         somtempl
  18.  
  19. When run without arguments, somtempl displays help on its options and also
  20. shows a list of the available templates that can be generated.  To generate
  21. one of the templates, use the -a option.  For example, to generate a generic
  22. IDL file from a template named gidl, enter:
  23.  
  24.         somtempl -a gidl
  25.  
  26. With this command, the file defined in the gidl template will be generated
  27. into the current directory.  The gidl template generates the following IDL
  28. file named xxxx.idl by default:
  29.  
  30.         #ifndef xxxx_idl
  31.         #define xxxx_idl
  32.         #include <somobj.idl>
  33.         #include <somcls.idl>
  34.         interface defaultClass : SOMObject
  35.         {
  36.           // Attributes filled in here:
  37.           // Operations filled in here:
  38.         #ifdef __SOMIDL__
  39.           implementation {
  40.             releaseorder:;
  41.             // Class Modifiers:
  42.             align     = 4;
  43.             dllname   = "xxxx.dll";
  44.             metaclass = "SOMClass";
  45.             // Attribute Modifiers:
  46.             // Overrides:
  47.             somDefaultInit: override, init; // Default object initializer
  48.             somDestruct: override;          // Default object uninitializer
  49.           };
  50.         #endif /* __SOMIDL__ */
  51.         };
  52.         #endif  /* xxxx_idl */
  53.  
  54. When a template is generated, the names of files and classes have predefined
  55. values by default.  These values can, however, be changed with options given
  56. on the somtempl command line.  These options are described below.
  57.  
  58. Option
  59.  
  60. -n classname
  61.         The template will be generated with the given class name.  If no
  62.         class name is given with this option, the class name defaults to
  63.         defaultClass.
  64.  
  65. -s filestem
  66.         This option allows you to uniquely name the files that are generated
  67.         by somtempl.  The default file stem is xxxx.  On systems that limit
  68.         file names to 8 characters, the filestem given with this option
  69.         should be limited to 4 characters.
  70.  
  71. -p class=filestem
  72.         This option allows you to select a parent class for the main class
  73.         generated in the template.  If no parent is specified, the default
  74.         parent is SOMObject.  This is equivalent to -p SOMObject=somobj.
  75.         More than one parent class can be specified by including more than
  76.         one -p option on the command line.  The directories specified in the
  77.         SMINCLUDE environment variable are searched to locate the specified
  78.         file named filestem.idl.  If the file is not found, a new parent
  79.         class file named filestem.idl is generated from the included generic
  80.         IDL file template.
  81.  
  82. -m class=filestem
  83.         This option allows you to select a metaclass for the main class
  84.         generated in the template.  If no metaclass is specified, the default
  85.         metaclass is SOMClass.  This is equivalent to -m SOMClass=somcls.
  86.         Only one metaclass option can be specified.  The directories
  87.         specified in the SMINCLUDE environment variable are searched to
  88.         locate the specified file named filestem.idl.  If the file is not
  89.         found, a new metaclass file named filestem.idl is generated from the
  90.         included generic IDL file template.
  91.  
  92. -e
  93.         This option inhibits the searching of the directories named in the
  94.         SMINCLUDE environment variable.  This affects the operation of the -m
  95.         and -p options.
  96.  
  97. The following example uses the above options to generate the generic IDL
  98. template with a class named "Animal", a parent class named
  99. "SOMPPersistentObject", a metaclass named "AnimalFactory" and file names
  100. beginning with "ani".
  101.  
  102.         somtempl -a gidl -n Animal -s ani -p SOMPPersistentObject=po
  103.         -m AnimalFactory=animeta
  104.  
  105. The main IDL file produced by this command, named "ani.idl", is shown below.
  106. Note the differences between this and the earlier generic IDL file.  The
  107. parent class file "po.idl" already exists in the SOM include directory;
  108. therefore, it is not created in the current directory.  The "AnimalFactory"
  109. metaclass in "animeta.idl" did not previously exist; thus the "animeta.idl"
  110. file is generated into the current directory.
  111.  
  112.         #ifndef ani_idl
  113.         #define ani_idl
  114.         #include <po.idl>
  115.         #include <animeta.idl>
  116.         interface Animal : SOMPPersistentObject
  117.         {
  118.           // Attributes filled in here:
  119.           // Operations filled in here:
  120.         #ifdef __SOMIDL__
  121.           implementation {
  122.             releaseorder:;
  123.             // Class Modifiers:
  124.             align     = 4;
  125.             dllname   = "ani.dll";
  126.             metaclass = "AnimalFactory";
  127.  
  128.             // Attribute Modifiers:
  129.             // Overrides:
  130.             somDefaultInit: override, init; // Default object initializer
  131.             somDestruct: override;          // Default object uninitializer
  132.           };
  133.         #endif /* __SOMIDL__ */
  134.         };
  135.         #endif  /* ani_idl */
  136.  
  137. Templates may include more than just an IDL file.  Supplied with somtempl is
  138. a DSOM template (option -a dsom).  This template includes the IDL files, as
  139. well as the C source files and make files to create a complete DSOM
  140. application.
  141.  
  142. Template files
  143.  
  144. The somtempl program uses two files (located via the SMINCLUDE environment
  145. variable) to determine the files to be generated and the available templates:
  146.  
  147. The first file is called the configuration file.  The configuration file
  148. contains the names of the templates that can be generated and the names of
  149. the files that make up the template.  The configuration file also contains
  150. user-defined symbols for substitution when files are generated.
  151.  
  152. The contents of the files defined by the configuration file are contained in
  153. the second file, the template file.
  154.  
  155. The supplied templates
  156.  
  157. The default configuration file used by somtempl is named somtempl.cfg.  The
  158. default template file is named somtempl.app.  These files are supplied in
  159. SOM's include directory.  To change the names of the configuration and
  160. template files used by somtempl, you can use the following options when you
  161. run the program:
  162.  
  163. Option
  164.  
  165. -f configfile
  166.         configfile is the name of the somtempl configuration file.  Default
  167.         is somtempl.cfg.
  168.  
  169. -t templatefile
  170.         templatefile is the name of the somtempl template file.  Default is
  171.         somtempl.app.
  172.  
  173. Contained in the default configuration and template files, you will find the
  174. following templates:
  175.  
  176. Template
  177.  
  178. gidl
  179.         A template of a generic IDL file.  Generate this template and then
  180.         add your own methods, attributes and data.
  181.  
  182. idl_dll
  183.         A template of the same generic IDL file as in the gidl template plus
  184.         make files, module definition files and class library initialization
  185.         source for AIX, OS/2 and Windows.  The generated template can be
  186.         built immediately with the make utility.
  187.  
  188. dsom
  189.         This template generates a complete Distributed SOM program for a
  190.         basic SOM class.  Also generated are the make files, module
  191.         definition files, class library initialization source and source to
  192.         simplify local/remote object transparency.  The generated application
  193.         creates either local or remote objects and includes command scripts
  194.         to set up the server location.
  195.  
  196. dsomsvr
  197.         The template generates a DSOM server program.  The program generated
  198.         can be used in place of the somdsvr program supplied with the
  199.         SOMobjects Toolkit.  Only the -s option is useful when generating
  200.         this template.  The -s <stem> option allows you to change the server
  201.         program name from xxxxsvr to <stem>svr.
  202.  
  203. Other somtempl options
  204.  
  205. -o
  206.         This option indicates you will allow somtempl to overwrite existing
  207.         files.  By default, a file in the current directory with the same
  208.         name as a generated file will not be overwritten.
  209.  
  210. -i file
  211.         When this option is used, somtempl will read options from the named
  212.         file, rather than from the command line.
  213.  
  214. -u name=value
  215.         This option specifies that a user-defined symbol name should be
  216.         replaced by the given value when files are generated.  This allows
  217.         you to define parameterized SOM class templates.  You may specify
  218.         multiple -u options on the same command line.  If the name specified
  219.         is the same as a user-defined symbol name already defined in the
  220.         somtempl configuration file, the substitution value on the command
  221.         line takes precedence.
  222.  
  223. -S
  224.         This option inhibits substitution of template symbols.  The files
  225.         generated by somtempl will contain the content of the template file
  226.         without substitution.  This may be useful for creating your own
  227.         additions to the template file.
  228.  
  229.  
  230. Modifying and adding templates to somtempl
  231.  
  232. You may add templates or modify existing templates by making changes to
  233. somtempl's configuration and template files, somtempl.cfg and somtempl.app.
  234. This section describes the contents of these files in more detail and
  235. explains how to modify these files.
  236.  
  237. Configuration file
  238.  
  239. The somtempl.cfg file defines the templates that can be generated by
  240. somtempl.  There are two sections in this file that can be modified by users.
  241. The first section is for user-defined symbols.  (Comments in the somtempl.cfg
  242. file indicate where the user-defined symbols should be placed.) A
  243. user-defined symbol is defined with the syntax:
  244.  
  245.         symbolname=value
  246.  
  247. An example of such a symbol, shown below, can be found in the somtempl.cfg
  248. file.
  249.  
  250.         USERDEFINEDTYPE=long
  251.  
  252. The string "USERDEFINEDTYPE" within a template file (somtempl.app) will be
  253. replaced by the string value "long" when the file containing the symbol is
  254. generated.  The value associated with a user-defined symbol can be modified
  255. when somtempl is run, by using the -u option.  For example, the above
  256. definition could be changed by adding the option:
  257.  
  258.         -u USERDEFINEDTYPE=string
  259.  
  260. The second section that can be modified in a configuration file is the
  261. portion that defines the files to be generated for a template.  The syntax of
  262. this portion of the configuration file is shown below:
  263.  
  264.         :<template_name>|<template_title>|templatefile==<filename>
  265.            <template_filename> [template_section_name]
  266.            ...
  267.         [>[?<AIX|OS2|W16>]]
  268.  
  269. template_name
  270.         The template name is a single string that uniquely identifies the
  271.         template.
  272.  
  273. template_title
  274.         The title can be multiple strings.  The title, along with the
  275.         template's name, is shown when the somtempl help is displayed.
  276.  
  277. filename
  278.         This is the name of the template file that contains the aggregate
  279.         contents of the files named by template_filename.  It can be any text
  280.         file, although it is typically somtempl.app.
  281.  
  282. template_filename
  283.         This is the name of a file that will be generated by somtempl.  You
  284.         include one template_filename entry for each file you want somtempl
  285.         to generate.  The specified file name may contain the string
  286.         __SOM_STEM__.  __SOM_STEM__ will be replaced by the file stem
  287.         specified with the -s command line option.  When the -s option is not
  288.         used, __SOM_STEM__ is replaced by xxxx.  The generated contents of
  289.         template_filename are located via a label of the form
  290.  
  291.                 :<template_name>_<template_filename>
  292.  
  293.         within the templatefile.  If a template_section_name is given along
  294.         with a template_filename, the generated contents of template_filename
  295.         are located via a label of the form:
  296.  
  297.                 :<template_section_name>
  298.  
  299.         The template_section_name option allows you to define a single label
  300.         that can be used by multiple templates.
  301.  
  302. >
  303.         This character, placed in the first column, directs the strings that
  304.         follow on that line to standard error output - usually the display -
  305.         after the files named by template_filename have been generated.  You
  306.         can tailor your message by system by including an optional system
  307.         name following the > character.  Specifically, >?AIX outputs only on
  308.         AIX systems, >?OS2 outputs only on OS/2 systems and >?W16 outputs
  309.         only on Windows systems.
  310.  
  311. #
  312.         This character, placed in the first column, indicates the line is a
  313.         comment.
  314.  
  315. A complete example for the template named "idl_dll", contained in the
  316. supplied somtempl.cfg, is shown below:
  317.  
  318.         # Template: idl_dll
  319.         # Title: Basic SOM Class Library
  320.         # Contents of files in: somtempl.app
  321.         :idl_dll|Basic SOM Class Library|templatefile==somtempl.app
  322.         # Generate the following 8 files.
  323.         # Note: the __SOM_STEM__.idl file is just the
  324.         #       generic IDL file.
  325.             Makefile
  326.             makefile.32
  327.             makefile.w16
  328.             __SOM_STEM__.def
  329.             __SOM_STEM__.exp
  330.             __SOM_STEM__.idl gidl
  331.             __SOM_STEM__init.c
  332.             __SOM_STEM__w16.def
  333.         # Output the following after the files are generated.
  334.         >    Application __SOM_CLASS_NAME__ generation completed.
  335.         >?AIX    Please type:
  336.         >?AIX        make
  337.         >?AIX    to build your __SOM_STEM__.dll.
  338.         >?OS2    Please type:
  339.         >?OS2        nmake -f makefile.32
  340.         >?OS2    to build your __SOM_STEM__.dll.
  341.         >?W16    Please type:
  342.         >?W16        nmake -f makefile.w16
  343.         >?W16    to build your __SOM_STEM__.dll.
  344.  
  345.  
  346. Template file
  347.  
  348. A template file contains the aggregate contents of the files that have been
  349. defined within the somtempl configuration file.  A template file contains the
  350. contents of multiple files to be generated.  Each file generated is located
  351. located within a template file via a label.  As described in the previous
  352. section, the label name may be either:
  353.  
  354.         :<template_name>_<template_filename>
  355.  
  356. or
  357.  
  358.         :<template_section_name>
  359.  
  360. The lines defining the generated file contents follow the label, up to but
  361. not including the line containing the next label.
  362.  
  363. Template file symbols
  364.  
  365. Within a template file, there are several symbols that can be used to allow a
  366. template to be generated based on the command line options used when somtempl
  367. is run.  The value for each symbol is determined when somtempl is run; that
  368. is, each value is substituted in place of the corresponding symbol when files
  369. are generated.  These symbols are in addition to the user-defined symbols
  370. that can be defined in the somtempl configuration file.  The available
  371. symbols are described below: (Review the contents of the default template
  372. file somtempl.app to see in more detail how these symbols are used.)
  373.  
  374. Symbol
  375.  
  376. __SOM_CLASS_NAME__
  377.         This symbol is replaced by the name of the class specified with the
  378.         -n option or with the default defaultClass.
  379.  
  380. __SOM_META_NAMES__
  381.         This symbol is used within IDL files and is replaced by the IDL file
  382.         to be included for the metaclass named with the -m option.  This
  383.         defaults to #include <somcls.idl>.
  384.  
  385. __SOM_PARENT_NAMES__
  386.         This symbol is replaced by the names of the parent classes specified
  387.         with the -p option.  This defaults to SOMObject.  When more than one
  388.         parent class is specified, the parent class names of the value of
  389.         this symbol will be separated by commas.
  390.  
  391. __SOM_STEM__
  392.         This symbol can be used in file names or wherever a unique name is
  393.         needed.  It corresponds to the stem specified with the -s command
  394.         line option.  It defaults to xxxx.
  395.  
  396. __SOM_OBJS__
  397.         This symbol is used in make files.  It names the object files that
  398.         the generated application will need to build.  Typically, the value
  399.         of this symbol is xxxx.o. When parent class source is also generated,
  400.         this object file name is also included in the value of this symbol.
  401.         For example: parent.o xxxx.o. A metaclass object file name may also
  402.         be added if generated.
  403.  
  404. __SOM_OBJS_RESPONSE__
  405.         This symbol is used in linker response files and is similar to
  406.         __SOM_OBJS__ except that file names are separated with a "+"
  407.         character.
  408.  
  409. __SOM_OBJS_C_DEPS__
  410.         This symbol is used in make files.  It includes a line for each
  411.         dependency to build an object file from a C source file.  For
  412.         example: xxxx.o: xxxx.ih xxxx.c. The dependencies for parent and
  413.         metaclasses are also included in the symbol if they are generated.
  414.  
  415. __SOM_OBJS_CPP_DEPS__
  416.         This symbol is used in make files.  It includes a line for each
  417.         dependency to build an object file from a C++ source file.  For
  418.         example: xxxx.o: xxxx.xih xxxx.cpp.  The dependencies for parent and
  419.         metaclasses are also included in the symbol if they are generated.
  420.  
  421. __SOM_INIT_BODY__
  422.         This symbol is used in the body of a SOMInitModule procedure.  It
  423.         contains calls to the NewClass procedure of the classes generated.
  424.         For example:
  425.  
  426.                 parentNewClass(parent_MajorVersion, parent_MinorVersion);
  427.                 defaultClassNewClass(defaultClass_MajorVersion,
  428.                                      defaultClass_MinorVersion);
  429.  
  430. __SOM_C_HEADER_FILES__
  431.         This symbol is used in C source code to include the generated class
  432.         header files.  For example:
  433.  
  434.                 #include "pppp.h"
  435.                 #include "xxxx.h"
  436.  
  437. __SOM_C_HEADER_DELETE_FILES__
  438.         This symbol is used in make files.  It names the C header files to be
  439.         deleted when the directory is cleaned of unnecessary files.  For
  440.         example:
  441.  
  442.                 -$(DELETE) pppp.h
  443.                 -$(DELETE) xxxx.h
  444.  
  445. __SOM_CPP_HEADER_FILES__
  446.         This symbol is used in C++ source code to include the generated class
  447.         header files.  For example:
  448.  
  449.                 #include "pppp.xh"
  450.                 #include "xxxx.xh"
  451.  
  452. __SOM_CPP_HEADER_DELETE_FILES__
  453.         This symbol is used in make files.  It names the C++ header files to
  454.         be deleted when the directory is cleaned of unnecessary files.  For
  455.         example:
  456.  
  457.                 -$(DELETE) pppp.xh
  458.                 -$(DELETE) xxxx.xh
  459.  
  460. __SOM_EXPORT_C_NAMES__
  461.         This symbol is used in module definition files to name external entry
  462.         points for the generated classes.  For example:
  463.  
  464.                 _parentCClassData
  465.                 _parentClassData
  466.                 _parentNewClass
  467.                 _defaultClassCClassData
  468.                 _defaultClassClassData
  469.                 _defaultClassNewClass
  470.  
  471. __SOM_EXPORT_PASCAL_NAMES__
  472.         This symbol is used in module definition files to name external entry
  473.         points for the generated classes.  For example:
  474.  
  475.                 parentCClassData
  476.                 parentClassData
  477.                 parentNewClass
  478.                 defaultClassCClassData
  479.                 defaultClassClassData
  480.                 defaultClassNewClass
  481.  
  482. __SOM_META_CLASS_NAME__
  483.         This symbol is replaced by the class name of the metaclass specified
  484.         with the -m option.
  485.  
  486. __SOM_PARENT_CLASS_NAME__
  487.         This symbol is replaced by the class name of the parent specified
  488.         with the -p option.  When more than one -p option is specified, this
  489.         symbol represents the first parent named.
  490.  
  491. __SOM_DLLSTEM__
  492.         This symbol is used to name overall output file names, such as a DLL
  493.         or library produced by a make file.  It defaults to xxxx and can be
  494.         set via the -s option.  The value of this symbol is constant, even
  495.         when parent and metaclass files are generated (that is, where
  496.         __SOM_STEM__ is determined by the -p and -m options.)
  497.  
  498. Adding templates
  499.  
  500. You can add new templates to the somtempl.cfg and somtempl.app files with any
  501. text editor.  You may find that this is the most convenient approach.  There
  502. is, however, an alternate way to add templates to these files that may
  503. simplify your task - you can use the -g option.  The following are the
  504. recommend steps to use the -g option:
  505.  
  506. 1.  Make backup copies of the current somtempl.cfg and somtempl.app files.
  507.  
  508. 2.  Generate an existing template with the -S option.  This option generates
  509. a template's files without doing any symbol substitution.  For example, first
  510. generate the idl_dll template:
  511.  
  512.         somtempl -a idl_dll -S
  513.  
  514. This will give you a set of files that is ready to be placed back into the
  515. template file somtempl.app as a new template.
  516.  
  517. 3.  Next, modify the set of generated template files to include the changes
  518. you want in your new template.
  519.  
  520. 4.  Use the -g and -T options with the names of the generated template files
  521. to add a new template to the configuration and template files.  For example:
  522.  
  523.         somtempl -T "This is my modified template" -g newone Makefile
  524.            makefile.32 makefile.w16 xxxx.def xxxx.exp xxxx.idl xxxxinit.c
  525.            xxxxw16.def
  526.  
  527. This will add a section in the somtempl.cfg file for the template named
  528. "newone" with a title of "This is my modified template".  The named files
  529. (Makefile, makefile.32, ...) will be added to somtempl.app.
  530.  
  531. 5.  Finally, edit the somtempl.cfg and somtempl.app files to make any
  532. finishing touches to your new template.  For example, add text to the
  533. configuration file that should be displayed when the template is generated:
  534.  
  535.         >?AIX    Please type:
  536.         >?AIX        make
  537.         >?AIX    to build your __SOM_STEM__.dll.
  538.         >?OS2    Please type:
  539.         >?OS2        nmake -f makefile.32
  540.         >?OS2    to build your __SOM_STEM__.dll.
  541.         >?W16    Please type:
  542.         >?W16        nmake -f makefile.w16
  543.         >?W16    to build your __SOM_STEM__.dll.
  544.  
  545. Note: When you use the -g option, the only reverse symbol substitution that
  546. is done is for the stem name (-s) and class name (-n).  That is, the names of
  547. the files in the example above are stored in the configuration and template
  548. files using __SOM_STEM__ instead of xxxx.  Likewise, defaultClass is replaced
  549. with __SOM_CLASS_NAME__.
  550.  
  551.