SOMTEMPL: The SOM Template Application Builder The somtempl program is a programming utility that generates SOM source files and programs from predefined templates. It is a useful tool to simplify repetitive SOM programming tasks. In general, it can generate any sort of text file from a predefined template; however, it's options are primarily focused at SOM programming. It can also be used similarly to C++ templates to define parameterized SOM classes. For beginners, somtempl is also useful because it includes a template for a complete SOM/DSOM program - including make files for AIX, OS/2 and Windows. Running somtempl To run somtempl, simply enter at the command line: somtempl When run without arguments, somtempl displays help on its options and also shows a list of the available templates that can be generated. To generate one of the templates, use the -a option. For example, to generate a generic IDL file from a template named gidl, enter: somtempl -a gidl With this command, the file defined in the gidl template will be generated into the current directory. The gidl template generates the following IDL file named xxxx.idl by default: #ifndef xxxx_idl #define xxxx_idl #include #include interface defaultClass : SOMObject { // Attributes filled in here: // Operations filled in here: #ifdef __SOMIDL__ implementation { releaseorder:; // Class Modifiers: align = 4; dllname = "xxxx.dll"; metaclass = "SOMClass"; // Attribute Modifiers: // Overrides: somDefaultInit: override, init; // Default object initializer somDestruct: override; // Default object uninitializer }; #endif /* __SOMIDL__ */ }; #endif /* xxxx_idl */ When a template is generated, the names of files and classes have predefined values by default. These values can, however, be changed with options given on the somtempl command line. These options are described below. Option -n classname The template will be generated with the given class name. If no class name is given with this option, the class name defaults to defaultClass. -s filestem This option allows you to uniquely name the files that are generated by somtempl. The default file stem is xxxx. On systems that limit file names to 8 characters, the filestem given with this option should be limited to 4 characters. -p class=filestem This option allows you to select a parent class for the main class generated in the template. If no parent is specified, the default parent is SOMObject. This is equivalent to -p SOMObject=somobj. More than one parent class can be specified by including more than one -p option on the command line. The directories specified in the SMINCLUDE environment variable are searched to locate the specified file named filestem.idl. If the file is not found, a new parent class file named filestem.idl is generated from the included generic IDL file template. -m class=filestem This option allows you to select a metaclass for the main class generated in the template. If no metaclass is specified, the default metaclass is SOMClass. This is equivalent to -m SOMClass=somcls. Only one metaclass option can be specified. The directories specified in the SMINCLUDE environment variable are searched to locate the specified file named filestem.idl. If the file is not found, a new metaclass file named filestem.idl is generated from the included generic IDL file template. -e This option inhibits the searching of the directories named in the SMINCLUDE environment variable. This affects the operation of the -m and -p options. The following example uses the above options to generate the generic IDL template with a class named "Animal", a parent class named "SOMPPersistentObject", a metaclass named "AnimalFactory" and file names beginning with "ani". somtempl -a gidl -n Animal -s ani -p SOMPPersistentObject=po -m AnimalFactory=animeta The main IDL file produced by this command, named "ani.idl", is shown below. Note the differences between this and the earlier generic IDL file. The parent class file "po.idl" already exists in the SOM include directory; therefore, it is not created in the current directory. The "AnimalFactory" metaclass in "animeta.idl" did not previously exist; thus the "animeta.idl" file is generated into the current directory. #ifndef ani_idl #define ani_idl #include #include interface Animal : SOMPPersistentObject { // Attributes filled in here: // Operations filled in here: #ifdef __SOMIDL__ implementation { releaseorder:; // Class Modifiers: align = 4; dllname = "ani.dll"; metaclass = "AnimalFactory"; // Attribute Modifiers: // Overrides: somDefaultInit: override, init; // Default object initializer somDestruct: override; // Default object uninitializer }; #endif /* __SOMIDL__ */ }; #endif /* ani_idl */ Templates may include more than just an IDL file. Supplied with somtempl is a DSOM template (option -a dsom). This template includes the IDL files, as well as the C source files and make files to create a complete DSOM application. Template files The somtempl program uses two files (located via the SMINCLUDE environment variable) to determine the files to be generated and the available templates: The first file is called the configuration file. The configuration file contains the names of the templates that can be generated and the names of the files that make up the template. The configuration file also contains user-defined symbols for substitution when files are generated. The contents of the files defined by the configuration file are contained in the second file, the template file. The supplied templates The default configuration file used by somtempl is named somtempl.cfg. The default template file is named somtempl.app. These files are supplied in SOM's include directory. To change the names of the configuration and template files used by somtempl, you can use the following options when you run the program: Option -f configfile configfile is the name of the somtempl configuration file. Default is somtempl.cfg. -t templatefile templatefile is the name of the somtempl template file. Default is somtempl.app. Contained in the default configuration and template files, you will find the following templates: Template gidl A template of a generic IDL file. Generate this template and then add your own methods, attributes and data. idl_dll A template of the same generic IDL file as in the gidl template plus make files, module definition files and class library initialization source for AIX, OS/2 and Windows. The generated template can be built immediately with the make utility. dsom This template generates a complete Distributed SOM program for a basic SOM class. Also generated are the make files, module definition files, class library initialization source and source to simplify local/remote object transparency. The generated application creates either local or remote objects and includes command scripts to set up the server location. dsomsvr The template generates a DSOM server program. The program generated can be used in place of the somdsvr program supplied with the SOMobjects Toolkit. Only the -s option is useful when generating this template. The -s option allows you to change the server program name from xxxxsvr to svr. Other somtempl options -o This option indicates you will allow somtempl to overwrite existing files. By default, a file in the current directory with the same name as a generated file will not be overwritten. -i file When this option is used, somtempl will read options from the named file, rather than from the command line. -u name=value This option specifies that a user-defined symbol name should be replaced by the given value when files are generated. This allows you to define parameterized SOM class templates. You may specify multiple -u options on the same command line. If the name specified is the same as a user-defined symbol name already defined in the somtempl configuration file, the substitution value on the command line takes precedence. -S This option inhibits substitution of template symbols. The files generated by somtempl will contain the content of the template file without substitution. This may be useful for creating your own additions to the template file. Modifying and adding templates to somtempl You may add templates or modify existing templates by making changes to somtempl's configuration and template files, somtempl.cfg and somtempl.app. This section describes the contents of these files in more detail and explains how to modify these files. Configuration file The somtempl.cfg file defines the templates that can be generated by somtempl. There are two sections in this file that can be modified by users. The first section is for user-defined symbols. (Comments in the somtempl.cfg file indicate where the user-defined symbols should be placed.) A user-defined symbol is defined with the syntax: symbolname=value An example of such a symbol, shown below, can be found in the somtempl.cfg file. USERDEFINEDTYPE=long The string "USERDEFINEDTYPE" within a template file (somtempl.app) will be replaced by the string value "long" when the file containing the symbol is generated. The value associated with a user-defined symbol can be modified when somtempl is run, by using the -u option. For example, the above definition could be changed by adding the option: -u USERDEFINEDTYPE=string The second section that can be modified in a configuration file is the portion that defines the files to be generated for a template. The syntax of this portion of the configuration file is shown below: :||templatefile== [template_section_name] ... [>[?]] template_name The template name is a single string that uniquely identifies the template. template_title The title can be multiple strings. The title, along with the template's name, is shown when the somtempl help is displayed. filename This is the name of the template file that contains the aggregate contents of the files named by template_filename. It can be any text file, although it is typically somtempl.app. template_filename This is the name of a file that will be generated by somtempl. You include one template_filename entry for each file you want somtempl to generate. The specified file name may contain the string __SOM_STEM__. __SOM_STEM__ will be replaced by the file stem specified with the -s command line option. When the -s option is not used, __SOM_STEM__ is replaced by xxxx. The generated contents of template_filename are located via a label of the form :_ within the templatefile. If a template_section_name is given along with a template_filename, the generated contents of template_filename are located via a label of the form: : The template_section_name option allows you to define a single label that can be used by multiple templates. > This character, placed in the first column, directs the strings that follow on that line to standard error output - usually the display - after the files named by template_filename have been generated. You can tailor your message by system by including an optional system name following the > character. Specifically, >?AIX outputs only on AIX systems, >?OS2 outputs only on OS/2 systems and >?W16 outputs only on Windows systems. # This character, placed in the first column, indicates the line is a comment. A complete example for the template named "idl_dll", contained in the supplied somtempl.cfg, is shown below: # Template: idl_dll # Title: Basic SOM Class Library # Contents of files in: somtempl.app :idl_dll|Basic SOM Class Library|templatefile==somtempl.app # Generate the following 8 files. # Note: the __SOM_STEM__.idl file is just the # generic IDL file. Makefile makefile.32 makefile.w16 __SOM_STEM__.def __SOM_STEM__.exp __SOM_STEM__.idl gidl __SOM_STEM__init.c __SOM_STEM__w16.def # Output the following after the files are generated. > Application __SOM_CLASS_NAME__ generation completed. >?AIX Please type: >?AIX make >?AIX to build your __SOM_STEM__.dll. >?OS2 Please type: >?OS2 nmake -f makefile.32 >?OS2 to build your __SOM_STEM__.dll. >?W16 Please type: >?W16 nmake -f makefile.w16 >?W16 to build your __SOM_STEM__.dll. Template file A template file contains the aggregate contents of the files that have been defined within the somtempl configuration file. A template file contains the contents of multiple files to be generated. Each file generated is located located within a template file via a label. As described in the previous section, the label name may be either: :_ or : The lines defining the generated file contents follow the label, up to but not including the line containing the next label. Template file symbols Within a template file, there are several symbols that can be used to allow a template to be generated based on the command line options used when somtempl is run. The value for each symbol is determined when somtempl is run; that is, each value is substituted in place of the corresponding symbol when files are generated. These symbols are in addition to the user-defined symbols that can be defined in the somtempl configuration file. The available symbols are described below: (Review the contents of the default template file somtempl.app to see in more detail how these symbols are used.) Symbol __SOM_CLASS_NAME__ This symbol is replaced by the name of the class specified with the -n option or with the default defaultClass. __SOM_META_NAMES__ This symbol is used within IDL files and is replaced by the IDL file to be included for the metaclass named with the -m option. This defaults to #include . __SOM_PARENT_NAMES__ This symbol is replaced by the names of the parent classes specified with the -p option. This defaults to SOMObject. When more than one parent class is specified, the parent class names of the value of this symbol will be separated by commas. __SOM_STEM__ This symbol can be used in file names or wherever a unique name is needed. It corresponds to the stem specified with the -s command line option. It defaults to xxxx. __SOM_OBJS__ This symbol is used in make files. It names the object files that the generated application will need to build. Typically, the value of this symbol is xxxx.o. When parent class source is also generated, this object file name is also included in the value of this symbol. For example: parent.o xxxx.o. A metaclass object file name may also be added if generated. __SOM_OBJS_RESPONSE__ This symbol is used in linker response files and is similar to __SOM_OBJS__ except that file names are separated with a "+" character. __SOM_OBJS_C_DEPS__ This symbol is used in make files. It includes a line for each dependency to build an object file from a C source file. For example: xxxx.o: xxxx.ih xxxx.c. The dependencies for parent and metaclasses are also included in the symbol if they are generated. __SOM_OBJS_CPP_DEPS__ This symbol is used in make files. It includes a line for each dependency to build an object file from a C++ source file. For example: xxxx.o: xxxx.xih xxxx.cpp. The dependencies for parent and metaclasses are also included in the symbol if they are generated. __SOM_INIT_BODY__ This symbol is used in the body of a SOMInitModule procedure. It contains calls to the NewClass procedure of the classes generated. For example: parentNewClass(parent_MajorVersion, parent_MinorVersion); defaultClassNewClass(defaultClass_MajorVersion, defaultClass_MinorVersion); __SOM_C_HEADER_FILES__ This symbol is used in C source code to include the generated class header files. For example: #include "pppp.h" #include "xxxx.h" __SOM_C_HEADER_DELETE_FILES__ This symbol is used in make files. It names the C header files to be deleted when the directory is cleaned of unnecessary files. For example: -$(DELETE) pppp.h -$(DELETE) xxxx.h __SOM_CPP_HEADER_FILES__ This symbol is used in C++ source code to include the generated class header files. For example: #include "pppp.xh" #include "xxxx.xh" __SOM_CPP_HEADER_DELETE_FILES__ This symbol is used in make files. It names the C++ header files to be deleted when the directory is cleaned of unnecessary files. For example: -$(DELETE) pppp.xh -$(DELETE) xxxx.xh __SOM_EXPORT_C_NAMES__ This symbol is used in module definition files to name external entry points for the generated classes. For example: _parentCClassData _parentClassData _parentNewClass _defaultClassCClassData _defaultClassClassData _defaultClassNewClass __SOM_EXPORT_PASCAL_NAMES__ This symbol is used in module definition files to name external entry points for the generated classes. For example: parentCClassData parentClassData parentNewClass defaultClassCClassData defaultClassClassData defaultClassNewClass __SOM_META_CLASS_NAME__ This symbol is replaced by the class name of the metaclass specified with the -m option. __SOM_PARENT_CLASS_NAME__ This symbol is replaced by the class name of the parent specified with the -p option. When more than one -p option is specified, this symbol represents the first parent named. __SOM_DLLSTEM__ This symbol is used to name overall output file names, such as a DLL or library produced by a make file. It defaults to xxxx and can be set via the -s option. The value of this symbol is constant, even when parent and metaclass files are generated (that is, where __SOM_STEM__ is determined by the -p and -m options.) Adding templates You can add new templates to the somtempl.cfg and somtempl.app files with any text editor. You may find that this is the most convenient approach. There is, however, an alternate way to add templates to these files that may simplify your task - you can use the -g option. The following are the recommend steps to use the -g option: 1. Make backup copies of the current somtempl.cfg and somtempl.app files. 2. Generate an existing template with the -S option. This option generates a template's files without doing any symbol substitution. For example, first generate the idl_dll template: somtempl -a idl_dll -S This will give you a set of files that is ready to be placed back into the template file somtempl.app as a new template. 3. Next, modify the set of generated template files to include the changes you want in your new template. 4. Use the -g and -T options with the names of the generated template files to add a new template to the configuration and template files. For example: somtempl -T "This is my modified template" -g newone Makefile makefile.32 makefile.w16 xxxx.def xxxx.exp xxxx.idl xxxxinit.c xxxxw16.def This will add a section in the somtempl.cfg file for the template named "newone" with a title of "This is my modified template". The named files (Makefile, makefile.32, ...) will be added to somtempl.app. 5. Finally, edit the somtempl.cfg and somtempl.app files to make any finishing touches to your new template. For example, add text to the configuration file that should be displayed when the template is generated: >?AIX Please type: >?AIX make >?AIX to build your __SOM_STEM__.dll. >?OS2 Please type: >?OS2 nmake -f makefile.32 >?OS2 to build your __SOM_STEM__.dll. >?W16 Please type: >?W16 nmake -f makefile.w16 >?W16 to build your __SOM_STEM__.dll. Note: When you use the -g option, the only reverse symbol substitution that is done is for the stem name (-s) and class name (-n). That is, the names of the files in the example above are stored in the configuration and template files using __SOM_STEM__ instead of xxxx. Likewise, defaultClass is replaced with __SOM_CLASS_NAME__.