Command Line Reference
To generate code with CodeGen a developer goes to the operating system command prompt in an appropriately configured environment and issues codegen commands.
As a minimum the developer must use the -t option to specify the name of at least one template file to be used, and in almost all situations the -s option is also used to specify one or more repository structures to be processed.
There are several other command line options documented below. Some of the main ones are the -r option which causes any existing output files to be replaced, and the -v option which produces various information messages to be displayed as CodeGen generates code.
For example, a developer might use a command like this:
C:> codegen -t data_class -s customer -r -v
This command would cause CodeGen to create an output file based on the code defined in the template file named data_class.tpl and using information from the repository structure named CUSTOMER. If the output file already exists then it will be overwritten, and verbose messages will be displayed.
codegen <options>
Commonly Used Command Line Options
These options are used almost every time CodeGen is used:
-s structure[.group] [...] | *
Structure(s) to process. You must specify the name of at least one structure and may optionally specify multiple structure names separated by spaces. Alternatively you can specify the * wild-card to indicate that all structures are to be processed. It is also possible to generate a "pseudo structure" based on the fields within an implicit group within a structure.
If you need to process a large number of structures you can use the -s option to specify a single structure input file that defines structure names, and also optionally structure alias names and file override names.
In-process API equivalent: CodeGenTask.Structures property (List<String>).
Template(s) to process. You must specify at least one template name, and may optionally specify multiple template names separated by spaces. Alternatively you can use the wild-card character * to specify that multiple templates should be processed (e.g. database*) or use the * wild-card alone to indicate that all templates should be processed.
In-process API equivalent: CodeGenTask.Templates property (List<String>).
Replace existing files. By default existing files are not replaced.
In-process API equivalent: CodeGenTask.ReplaceFiles property (Boolean)
Other Command Line Options
These options can be used to modify how CodeGen works:
Structure aliases. A structure alias is an alternate name to be used to represent a structure. If -a is used then you must specify at least one alias name, and may optionally specify multiple alias names separated by spaces, up to but not exceeding the number of structure names that have been specified via the -s option. If you wish to omit an alias for a structure in the middle of the list then specify an empty string by passing two double quote characters.
If you are using a structure list input file then aliases must be specified via that file.
In-process API equivalent: CodeGenTask.Aliases property (List<String>).
Alternate field names. When this option is used most field loop tokens that refer to the name of a field will return the ALTERNATE name if defined. If not define the actual name will continue to be returned.
EXPERIMENTAL: Enabling this option impacts a lot if things internally and it is possible that we may not have currently covered all use cases appropriately. Please report any 'strange behavior' you experience when using this option.
In-process API equivalent: CodeGenTask.UseAlternateFieldNames property (Boolean).
Alternate structure names. Enabling this option is similar to using structure aliasing, except that the structure names are derived from the alternate name (ODBC table name) associated with the first structure assignment of the first FILE definition that the current structure is associated with. If the structure is not assigned to a file, or the file does not have any assigned structures, or the first assigned structure does not have an associated ODBC table name, then the structures original name is retained.
WARNING: This option can only be used successfully when structures are only assigned to a single file definition. If used with a structure that is assigned to multiple file definitions the FIRST file definition will always be used.
In-process API equivalent: CodeGenTask.UseAlternateStructureNames property (Boolean).
Override default button loop processing rules.
-ba Always use the default buttons defined in DefaultButtons.xml.
-bd Never use the default buttons defined in DefaultButtons.xml.
-bn Never load any buttons (DefaultButtons.xml or window script).
In-process API equivalents:
-ba CodeGenTask.AlwaysLoadDefaultButtons property (Boolean)
-bd CodeGenTask.NeverLoadDefaultButtons property (Boolean)
-bn CodeGenTask.NeverLoadAnyButtons property (Boolean)
Continue processing after errors. If multiple templates, files or tasks are being processed then this option allows code generation to continue even though one template/structure combination has generated an error.
In-process API equivalent: CodeGenTaskSet.ContinueAfterError property (Boolean)
Specifies that custom data mappings are loaded from an XML file. Refer to Customizing Data Type Mappings in the docs for more info.
In-process API equivalent: CodeGenTaskSet.DataMappingsFile property (String)
Overrides the default number of pixels per row to be used when calculating pixel coordinates using tokens like <FIELD_PIXEL_ROW>.
In-process API equivalent: CodeGenTask.CharacterHeight property (int)
Checks whether there is a later version of CodeGen available for download. This option requires Internet connectivity. If you do not specify an interval value then CodeGen will perform an immediate check for available updates and will report the result. If you specify an interval of 1 or more (days) then CodeGen will automatically check for available updates after that many days has expired since the previous update check; the update check will take place the next time you use CodeGen and you will see messages as the update check takes place. To cancel a previously scheduled automatic update checks specify an interval of 0.
Overrides the default number of pixels per character to be used when calculating pixel coordinates using tokens like <FIELD_PIXEL_WIDTH>.
In-process API equivalent: CodeGenTask.CharacterWidth property (int)
Debug mode. Displays additional information during processing; more than verbose mode.
In-process API equivalent: CodeGenTaskSet.LoggingLevel property (use LoggingLevel.Debug)
-database SQLServer | MySQL | PostgreSQL
Database type. Specifies the relational database that code is being generated for by altering the SQL data types emitted by the <FIELD_SQLTYPE> token. The default database type is SQLServer, unless altered by the CODEGEN_DATABASE_TYPE environment variable.
In-process API equivalent: CodeGenTaskSet.DatabaseType property
-define <identifier> [<identifier>...]
Defines one or more identifiers, the presence of which can be tested in template files to implement conditional processing.
In-process API equivalent: CodeGenTaskSet.Defines property (List<string>)
Displays the CodeGen documentation, either the Windows help file if the documentation is installed locally, or the on-line documentation if not. Bear in mind that the on-line documentation will always be for the latest version of CodeGen, which may be later than the version that you are currently running.
In-process API equivalent: None
Debug tree. Creates log files containing the internal results of the code tokenization and parsing phases.
In-process API equivalent: CodeGenTaskSet.LogTokenizerResults property (Boolean)
Echo the command line used to start CodeGen. This can be useful when starting CodeGen from a batch file in which echo has been disabled but where you want to see a representation of the commands that are being executed.
In-process API equivalent: CodeGenTaskSet.EchoCommands property (Boolean)
Restores the original CodeGen behavior failing if certain types of loop are encountered with no supporting data. For example, if a key loop is encountered when processing a structure with no keys.
In-process API equivalent: CodeGenTaskSet.EmptyLoopFail property (Boolean)
Override default field loop processing rules.
-f o Include overlay fields.
-f l DO NOT exclude fields which are "Excluded by Language".
-f t Exclude fields which are "Excluded by Toolkit".
-f r Exclude fields which are "Excluded by ReportWriter".
-f w Exclude fields which are "Excluded by Web".
In-process API equivalents:
-f o CodeGenTask.IncludeOverlayFields property (Boolean)
-f l CodeGenTask.IgnoreExcludeLanguage property (Boolean)
-f t CodeGenTask.HonorExcludeToolkit property (Boolean)
-f r CodeGenTask.HonorExcludeReportWriter property (Boolean)
-f w CodeGenTask.HonorExcludeWeb property (Boolean)
-fields [str.]field [[str.]field] ...
Creates a field subset based on the list of fields listed on the command line. When processing multiple structures concurrently (via the -ms or -file options) field names may be prefixed with the appropriate structure names.
In-process API equivalent: CodeGenTask.SubsetFields property (List<Tuple<String, String>>)
Repository file name to process. This option causes all structures that are assigned to the file definition to be available for use when processing templates. The end result is similar to specifying multiple structures with -s and using the -ms option.
In-process API equivalent: CodeGenTask.RepositoryFile property (String).
File Overrides. Allows you to specify which repository file definition is used for each structure being processing. This option is useful if the structure that you are using is assigned to multiple files because by default CodeGen will use the first assigned file. When the -fo option is used you must specify at least one repository file definition name, and have the option of specifying file overrides for multiple structures, up to but not exceeding the number of structures specified via the -s option. If you wish to omit a file override for a structure in the middle of the list then specify an empty string by passing two double quote characters.
If you are using a structure list input file then file overrides must be specified via that file.
In-process API equivalent: CodeGenTask.FileOverrides property (List<String>).
Override default group field name prefix rules
-g e Don't expand explicit groups to individual fields. Explicit groups are group fields with locally defined members.
-g f Don't prefix group fields with group name.
-g i Don't expand implicit groups to individual fields. Implicit groups are group fields where the members are defined by another structure.
-g r Don't use repository group field prefix.
In-process API equivalents:
-g e CodeGenTask.ExplicitGroupNoExpand property (Boolean)
-g f CodeGenTask.GroupFieldNoGroupPrefix property (Boolean)
-g i CodeGenTask.ImplicitGroupNoExpand property (Boolean)
-g r CodeGenTask.GroupFieldNoRpsPrefix property (Boolean)
Enables very special and top secret processing rules for the exclusive use of GI Computer Solutions, Ltd.
WARNING: Use with care, results may be disturbing to others!
Display command-line help information.
In-process API equivalent: None
Input file directory containing templates. Defaults to the current directory, or the directory specified with the CODEGEN_TPLDIR environment variable. You can specify a full or relative path, or a logical name followed by a colon (e.g. TPL:).
In-process API equivalent: CodeGenTaskSet.TemplateFolder property (String) or CodeGenTask.TemplateFolder property (String)
Load code generation instructions from a previously saved code generation instructions file. Refer to -save for information about saving an instructions file.
In-process API equivalent: CodeGenTaskSet.LoadFromFile(file,taskset) method.
List Files. Lists the names of any files generated when not running in verbose or debug logging modes.
In-process API equivalent: CodeGenTaskSet.ListGeneratedFiles property (Boolean)
Multiple Structures. Specifies that the structures that follow the -s command line option should all be available to templates being processed, at the same time.
In-process API equivalent: CodeGenTask.MultipleStructures property (Boolean).
Multi-write a file if the same file is generated more than once.
In-process API equivalent: CodeGenTask.MultiWriteFiles property (Boolean)
The namespace to use when replacing the <NAMESPACE> token. Codegen will determine the default namespace using the environment variable SYNDEFNS, and this can be overridden with the -n option.
In-process API equivalent: CodeGenTask.Namespace property (String)
No custom pluralization. Using this option suppresses the features of the <STRUCTURE_PLURAL> and <STRUCTURE_NOPLURAL> tokens, making them behave the same as <STRUCTURE_NAME>.
In-process API equivalent: CodeGenTask.NoCustomPluralization property (Boolean)
Don't append sub-folder to namespace. If a template file uses the <CODEGEN_FOLDER> token to specify that files created from the template should be created in a sub-folder below the main output folder, then by default, if a namespace is also being used, the name of the sub-folder is appended to the namespace. This option overrides that behavior.
In-process API equivalent: CodeGenTask.DontAppendFolderToNamespace property (Boolean)
Output directory. Defaults to the current directory, or the directory specified with the CODEGEN_OUTDIR environment variable. You can use a full or relative path, or a logical followed by a colon (e.g. SRC:).
In-process API equivalent: CodeGenTaskSet.OutputFolder property (String) or CodeGenTask.OutputFolder property (String)
Overrides the key that is used when a primary key block (<PRIMARY_KEY>) is used. By default the first key defined by the structure is used.
In-process API equivalent: CodeGenTask.PrimaryKeyNumber property (int)
Preserve arrays; do not expand arrays into individual fields.
WARNING: This is an experimental feature and may currently cause unexpected side effects with some expression tokens.
In-process API equivalent: CodeGenTask.PreserveArrays property (Boolean)
When using the <FIELD_NAME> token, prefix field names with <name>. Useful with repository .include with the optional prefix= qualifier.
In-process API equivalent: CodeGenTask.FieldPrefix property (String)
Allows the repository main and text files to be used to be specified on the command line, overriding other mechanisms for repository selection such as RPSDAT, RPSMFIL and RPSTFIL environment variables.
In-process API equivalent: CodeGenTask.RepositoryMainFile and CodeGenTask.RepositoryTextFile properties (String)
Specifies the name of a repository override file.
In-process API equivalent: CodeGenTask.RepositoryOverrideFile property (String)
Save the code generation instructions used during the current invocation to a code generation instructions file. The file can then be used later with the -input option. If the code generation invocation was launched via -input then you should not specify a file name after -save because the file name specified with -input will be used. If you are not processing an existing instructions file then you must specify the file to create. The file name may be an absolute or relative path, or may have the location specified via a logical name.
In-process API equivalent: CodeGenTaskSet.SaveToFile(file) method.
Specifies a prefix that should be added to the structure name for struct field data type definitions.
In-process API equivalent: CodeGenTaskSet.StructFieldPrefix property (String).
Subset of fields to use. Specify subsets in field user text strings with @SUB=name; syntax. This option is only valid when processing a single repository structure.
In-process API equivalent: CodeGenTask.Subset property (String).
Allow template defined folders. From CodeGen V5.0.2 it has been possible for template files to define the name of a sub folder (below the main output folder) where files generated from the template should be created. This is done by using the file header token <CODEGEN_FOLDER>. This option enables this functionality.
In-process API equivalent: CodeGenTask.AllowTemplateFolder property (Boolean)
Activate a specific named tweak to the way the CodeGen works. Tweaks implement minor variations in processing.
User defined token file. Specify a full or relative file spec of the file that contains user defined token definitions. The file spec can include Synergy logical names.
In-process API equivalent: CodeGenTask.UserTokenFile property (String)
User defined tokens specified via the command line. You must specify at least one name=value, and may optionally specify multiple name=value pairs separated by spaces. If spaces exist in the name or value then you should enclose the entire name=value pair in quotation marks.
In-process API equivalent: CodeGenTask.UserTokens property (List<UserToken>)
Treat user-defined tokens as preprocessor tokens, expanding them out to their constituent parts during the initial tokenization phase. This enables other tokens to be embedded in the values of user-defined tokens.
Verbose mode. Displays additional information during processing; not as much as debug (-d) mode.
In-process API equivalent: CodeGenTaskSet.LoggingLevel property (use LoggingLevel.Verbose)
Display the version of CodeGen that you are running.
Process input from a UI Toolkit Window script file. By default the fields and buttons collection will be based on the first input window found in the script file, but this can be overridden using the #n qualifier, which specifies either a 1-based input window number or the name of the input window to process.
In-process API equivalent: CodeGenTask.WindowScript property (String)
When processing input from a UI Toolkit Window script file this option prevents script file input window field attributes from being used to override repository field attributes. This allows you to generate code based on only the fields listed in an input window, but using only the repository field definitions.
In-process API equivalent: CodeGenTask.IgnoreScriptFieldAttributes property (Boolean)
Window script selection list processing. When this option is used CodeGen will examine any fields which have selection windows specified and will attempt to populate the field selections property based on the selection items defined in the named selection window.
In-process API equivalent: CodeGenTask.SelectionWindowScript property (String)
Processing a Synergy Method Catalog
These options are used to perform code generation based on metadata contained in a Synergy Method Catalog XML export file.
Synergy method catalog XML file to use. When using this option you may not use the -s option to specify specific structures to process. If you also specify the -interface option then only that interface will be processed, and you may not use interface loops in your template files. If you do not specify the -interface option then you MUST use an interface loop in your template file.
In-process API equivalent: CodeGenTask.MethodCatalogFile (string)
Synergy method catalog extensions file to use.
In-process API equivalent: CodeGenTask.MethodCatalogExtensionsFile (string)
This option causes the list of structures to be processed to be limited to the structured referenced in a Synergy Method Catalog XML export file. By default all structures listed in the XML file will be processed regardless of which interface(s) they are referenced by. The only information drawn from the XML file is the list of structure names; all structure attributes are taken from the repository. This option is used with regular REPOSITORY-BASED code generation and DOES NOT enable the processing of interface loops, method loops or parameter loops. This option may not be used in conjunction with the -s or -smc options.
In-process API equivalent: CodeGenTask.MethodCatalogFile (string) and set CodeGenTask.MethodCatalogStructureMode (boolean) to true.
The name of the interface in the Synergy Method Catalog XML file that you wish to generate code for. This option is only valid in conjunction with the -smc and -smcstrs options, and cannot be used with the -iloop option.
In-process API equivalent: CodeGenTask.MethodCatalogInterface (string).
-iloop <interfaceName> [<interfaceName> ...]
The name of one or more interfaces in the Synergy Method Catalog XML file that you wish to be processed by any interface loops. This option is only valid in conjunction with the -smc option, and cannot be used with the -interface option.
In-process API equivalent: CodeGenTask.MethodCatalogInterfaces (@ObservableCollection<string>).
-mexclude <methodName> [<methodName> ...]
The name of one or more methods in the Synergy Method Catalog that you wish to exclude from processing. This option can only be used with the -smc and -interface options.
In-process API equivalent: CodeGenTask.MethodCatalogExcludeMethods (@ObservableCollection<string>)
-minclude <methodName> [<methodName> ...]
The name of one or more methods in the Synergy Method Catalog that you wish to include in processing; all other methods will be excluded. This option can only be used with the -smc or -smcstrs options, and the -interface option.
In-process API equivalent: CodeGenTask.MethodCatalogIncludeMethods (@ObservableCollection<string>)
Identifies then name of a JSON file containing an array of strings that are the names of parameters that you wish to exclude when processing parameter loops. This option can only be used with the with the -smc option. Parameter names are NOT case sensitive when processed by this feature. An example of a JSON file that can be used with this feature is:
[ "param1", "spare", "roomToGrow" ]
In-process API equivalent: CodeGenTask.MethodCatalogExcludeParameters (@ObservableCollection<string>)
Identifies then name of a JSON file containing an array of strings that are the names of parameters that you wish to include when processing parameter loops. All other parameters will be excluded. This option can only be used with the with the -smc option. Parameter names are NOT case sensitive when processed by this feature. An example of a JSON file that can be used with this feature is:
[ "param1", "spare", "roomToGrow" ]
In-process API equivalent: CodeGenTask.MethodCatalogIncludeParameters (@ObservableCollection<string>)
Advanced Debugging Options
These options are intended for use by CodeGen developers and are not particularly useful when using CodeGen to generate code.
Intended for use by CodeGen developers, this option causes CodeGen to wait for a key press at the very beginning of processing. This makes it possible to attach an external debugger to the process before processing begins.
In-process API equivalent: None
Developer debug mode (displays extensive debugging information).
In-process API equivalent: CodeGenTaskSet.LoggingLevel property (use LoggingLevel.DeveloperDebug)
Causes CodeGen to wait for a key press at the very end of processing. This makes it possible to perform final tasks before a debugging environment terminates.
In-process API equivalent: None
Causes CodeGen to re-throw some caught exceptions to assist with debugging scenarios.
In-process API equivalent: None
Displays the elapsed time taken to process the command.
In-process API equivalent: None
Copyright © 2021 Synergex International, Inc.