Numerous built-in functions are available to obtain extensive help about syntax, errors, commands and functions of a program with help messages, manual pages and documentation.
Other built-in functions can be used for owner, property, environment and trace management. All built-in functions have the purpose to simplify handling of powerful and sometimes complex commands.
HELP: Provides the syntax for each command TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 SYNTAX [command[.path] [DEPTH1 | ... | DEPTH9 | ALL]]
The syntax function shows how the arguments can be set on the command line. Depending on depth the syntax is printed in one line or in structured form. A structured print out means that you have a question or exclamation mark before the argument.
The path is a dotted keyword list in accordance with the syntax of the corresponding command.
command.para1.para2.para3
:> FLAM4 SYNTAX :> FLAM4 SYNTAX command :> FLAM4 SYNTAX command ALL :> FLAM4 SYNTAX command.para :> FLAM4 SYNTAX command.para ALL
HELP: Provides quick help for arguments TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 HELP [command[.path] [DEPTH1 | ... | DEPTH9 | ALL]] [MAN]
The help function can provide extensive information about each parameter which is adjustable on the command line. With the help functionality you get a structured list of arguments:
The keyword can be abbreviated, but it must be unique for this list. The required letters are upper case if case sensitive mode is used. With the case sensitive mode an additional line is required to mark the appropriate letter.
The path is a dotted keyword list in accordance with the syntax of the corresponding command.
command.para1.para2.para3
Help can also be used to show the corresponding detailed description of the manual pages with keyword MAN.
:> FLAM4 HELP :> FLAM4 HELP MAN :> FLAM4 HELP command :> FLAM4 HELP command MAN :> FLAM4 HELP command ALL :> FLAM4 HELP command.para :> FLAM4 HELP command.para MAN :> FLAM4 HELP command.para ALL
HELP: Provides manual pages (detailed help) TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 MANPAGE [function | command[.path][=filename]] | [filename]
Shows the manpages of the program, all commands and built-in functions and if available for each argument up to selections/constant definitions.
This function prints the corresponding section from the user manual on the screen (doctype: book). If a filename is given then the doctype manpage of ASCIIDOC is written to the file.
Do not use space characters between the key, assignment character (=) and filename.
The files in ASCIIDOC format can be used to generate manpages with the tool ASCIIDOC.
:> FLAM4 MANPAGE :> FLAM4 MANPAGE filename :> FLAM4 MANPAGE command :> FLAM4 MANPAGE command=filename :> FLAM4 MANPAGE function :> FLAM4 MANPAGE function=filename :> FLAM4 MANPAGE command.para :> FLAM4 MANPAGE command.para=filename
HELP: Generates auxiliary documentation (ASCIIDOC text format) TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 GENDOCU [command[.path]=]filename [NONBR] [SHORT]
The complete user manual is generated when only the filename is given. If a command, or command path, is specified the corresponding section of the user manual is written to a file. The generated files are in ASCIIDOC format, to be readable as normal text document on all platforms and easily convertible into HTML, PDF or other formats with ASCIIDOC. The example below generates the complete manual and convert it in a second step to a HTML5 document.
:> flam4 gendocu book.txt :> asciidoc -b html5 -f asciidoc-html5.conf -a toc2 -a toclevels=4 -o book.html book.txt
The numbering will vary in places where the complete manual uses a bullet list for arguments and constants, when no detailed description is available and some of these arguments are required for the path.
The numbering can be disabled by setting the optional keyword NONBR. This is useful if numbering is generated by a post processing utility (for example 'pdflatex').
To create a short manual without the CLP parameter description the optional keyword SHORT can be used. This is useful for example, if you deliver a text file and no dictionary can be used.
In opposite to the built-in function HTMLDOC at text file generation the corresponding path string is written to the synopsis but index chapter and index terms are not generated anymore.
Do not use space characters between the key, assignment character (=) and filename.
:> FLAM4 GENDOCU flam4.manual.txt NONBR :> FLAM4 GENDOCU flam4.manual.txt SHORT :> FLAM4 GENDOCU command=command.manual.txt :> FLAM4 GENDOCU command.argument=argument.manual.txt
HELP: Generates the complete HTML documentation into a folder TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 HTMLDOC [path] [NUMBERS] [TYPES] [SHORT]
This built-in function generates the complete user manual in HTML format into a folder. The folder can be defined as optional parameter. If no path given, then the current directory is used as default.
With the optional keyword NUMBERS the numbering of headlines can be
activated. The keyword TYPE add the type information to each generated
headline. The keyword SHORT will result in a short version of the
document, not containing the parameter of the commands and other CLP
strings.
In opposite to the built-in function GENDOCU at HTML generation no path is written to the synopsis but index terms are generated by default.
The built-in function can only be used if a call back function for HTML documentation provided. If not a error will be issued if HTMLDOC is executed. The callback function is called for each prepared page and the unique pointer to the original manual string can be used to determine if this page already created and if so then only a link to this existing page is required. This interface allows to generated more flexible (with dictionary, index, search) and redundancy free HTML documentation.
To understand the service provider interface (open, close and callback function) for HTML generation see the DOXYGEN documentation of FLAMCLE/CLP.h
:> FLAM4 HTMLDOC :> FLAM4 HTMLDOC . SHORT :> FLAM4 HTMLDOC /user/home/docu/flclbook :> FLAM4 HTMLDOC NUMBERS SHORT :> FLAM4 HTMLDOC /user/home/docu/flclbook SHORT
HELP: Generates a property file TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 GENPROP [command=]filename
A property file is generated for all commands if only a filename is provided. If a command is specified, a property file for this specific command is created. Property files can be used to define default settings for commands. For each parameter, a property entry is written to a text file. The text file contains comments to help in editing the properties. A property file can be activated with the built-in function SETPROP.
Property files will be activated by their owner. A property file overrides hard coded properties and properties defined over environment variables. A specific property file overrides the general property file. At time of generation all current default settings are written to the property file.
We recommend to work only with command specific property files, because the built-in function CHGPROP can be used to generate, update and activate a property file for a certain command.
Do not use space characters between the key, assignment character (=) and filename.
To optimize the program performance, one can remove all unnecessary properties.
See Appendix Properties for the current property file content.
:> FLAM4 GENPROP owner.general.properties :> FLAM4 GENPROP command=owner.command.properties
HELP: Activate a property file TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 SETPROP [command=]filename
The filename is set as current global property file when no command is specified. The file name is set as current local property file when a command is given. The property file can be generated with GENPROP and will be activated for the current owner.
After generation you can activate the property file, but there will be no effect until you change the settings inside the property file, because the current default settings are written.
The filename can contain replacement/mapping rules (<HOME>/<USER>).
Do not use space characters between the key, assignment character (=) and filename.
We recommend to work only with command specific property files, because the built-in function CHGPROP can be used to generate, update and activate a property file for a certain command.
See Appendix Properties for the current property file content.
:> FLAM4 SETPROP general.properties :> FLAM4 SETPROP command=command.properties
HELP: Change a property value in the currently active property file TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 CHGPROP command [path[=value]]*
The built-in function updates property values in the currently active (see SETPROP) property file for a dedicated command. If no property file is activated, a property file is generated (see GENPROP), updated with the provided property list and activated (see SETPROP).
The first argument of CHGPROP is the command name. All other arguments are key-value pairs of properties that should be updated. The key is internally prefixed with the root (owner.program.command.). The values are enclosed in double quotation marks. Multiple properties of a command can be updated at once by separating them with a space character (please do not use spaces between key, assignment character (=) and the value). This set of properties is parsed by the CLP. If no property is provided, the property file for the command is either parsed or generated (if it does not exist) and then activated without updating properties. This behavior can be used to generate and activate command specific property files for the different commands.
The built-in function reads and parses the currently active property file. Then it parses the provided property list and writes the updated property file back to disk. The currently active property file could be a global, not command specific property file. In such a case, a new command specific property file is generated and activated. Properties from the global property file are copied into the newly generated one.
If no property file is defined (see SETPROP) that corresponds to the owner, program and command, a property file is generated. The filename formats below are used to read or write property files from/to the home directory:
On non-mainframe systems (WINDOWS, UNIX, MAC):
".owner.program.command.properties"
On mainframe systems (ZOS, VSE, BS200, ...):
"<SYSUID>.OWNER.PROGRAM.COMMAND.PROPS"
If the default filenames and/or path are not sufficient, you can change the filename of each property file by setting environment variables using the following naming convention:
OWNER_PROGRAM_COMMAND_PROPERTY_FILENAME
If no home directory is defined, then the current working directory is used as default directory to save the property files. On mainframes SYSUID is used for the first level qualifier, to represent the "home directory".
Property files are managed per owner: This means that updates are only done for the current owner.
To delete a property you can simply specify the path without the root and with out a sign.
See Appendix Properties for the current property file content.
:> FLAM4 CHGPROP command overlay.object.argument=value :> FLAM4 CHGPROP command overlay.object.argument :> FLAM4 CHGPROP command object.argument=value1 argument=value2
HELP: Remove a property file from configuration TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 DELPROP [command]
Without a command the current global property file is deleted from the configuration data. A command specific property file can be deleted from the configuration data when the command name is given.
Property files are managed per owner, this means that delete is only done for the current owner.
We recommend to work only with command specific property files.
See Appendix Properties for the current property file content.
:> FLAM4 DELPROP :> FLAM4 DELPROP command
HELP: Show current properties TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 GETPROP [command[.path] [DEPTH1 | ... | DEPTH9 | DEPALL | DEFALL]]
All or certain properties can be shown for a dedicated path. The path is a dotted keyword list according to the syntax of the corresponding command.
command.para1.para2.para3
A help message for a certain parameter will also show the assigned property value.
See Appendix Properties for the current property file content.
DEPTH1 / DEPTH2 / ... / DEPTH9
DEPALL
DEFALL
:> FLAM4 GETPROP :> FLAM4 GETPROP command :> FLAM4 GETPROP command DEFALL :> FLAM4 GETPROP command.para :> FLAM4 GETPROP command.para DEPALL
HELP: Defines the current owner TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 SETOWNER name
The current owner id (prefix or separation) can be changed. The owner concept is very powerful to separate different property settings. You can run the same command with different properties simply by switching the owner. The owner is a general solution to separate all settings and can be used for environment, client and other purposes.
If not already defined, the owner is written to the environment table under the key word OWNERID. This environment variable can for example used as replacement in file names (~/<OWNERID>.dat) or to refer a signature key.
:> FLAM4 SETOWNER com.company
HELP: Show current owner setting TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 GETOWNER
The current owner id (prefix for separation) will be shown. The owner concept allows to manage different configurations as a logical separation of what is done with this id.
:> FLAM4 GETOWNER
HELP: Set an environment variable (defined in the config file) TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 SETENV variable=value
This function allows to set environment variables within the configuration file for a certain owner. All defined environment variables are placed in the current environment table of the process before a command is executed.
Do not use space characters between the key, assignment character (=) and value.
Attention: The environment variables will be temporary overwritten:> FLAM4 SETENV LANG=DE_DE.IBM-1141 :> FLAM4 SETENV LANG=DE_DE.UTF-8 :> FLAM4 SETENV ENVID=T :> FLAM4 SETENV ENVID=P
HELP: Show the environment variables (defined in the config file) TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 GETENV
This function lists all environment variables which are set within the configuration file for a certain owner. All shown environment variables are placed in the environment table of the process.
Attention: The environment variables will be temporary overwritten:> FLAM4 GETENV
HELP: Delete an environment variable (defined in the config file) TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 DELENV variable
This function will delete environment variables from the configuration file for a certain owner.
:> FLAM4 DELENV LANG
HELP: List status of all possible usable environment variables TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 LSTENV
This function will list the status of all possible useable environment variables.
:> FLAM4 LSTENV
HELP: List help message for all possible usable environment variables TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 HLPENV
This function will print the help message for all possible usable environment variables.
:> FLAM4 LSTENV
HELP: Manage trace capabilities TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 TRACE ON | OFF | FILE=filename
Tracing for command line parser and commands can be enabled or disabled. A trace is only required to diagnose errors. In such a case a trace file must be defined first, then the trace can be activated, the erroneous command executed and the trace file sent to the support team.
If no trace file is defined, stdout/stderr is used as default. To prevent tracing on the screen, please define a trace file first before tracing is switched on.
Do not use space characters between the key, assignment character (=) and filename.
:> FLAM4 TRACE FILE=filename :> FLAM4 TRACE ON :> FLAM4 TRACE OFF
HELP: Shows or clear all the current configuration settings TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 CONFIG [CLEAR]
The actual configuration list with owner id, property file names trace setting, environment variables and more is shown. With the option CLEAR the configuration data including the corresponding file will be deleted.
The configuration file name can be defined by the environment variable:
FLAM4_CONFIG_FILE=config.file.name
This can be used to work with a global configuration file. If this location is not defined, the configuration file is stored in the home directory with the name:
.flam4.config
If no home directory is defined for the current user (this case is very improbable), the working directory is used.
To read the configuration file when the environment variable above is not defined, CLE first looks in the working and then in the home directory. This makes it possible to prefer a property file, by copying it to the current working directory.
On mainframes the data set name 'SYSUID.FLAM4.CONFIG' is used as default. SYSUID as high level qualifier is a kind of replacement for the current home directory in other operating systems in this way.
:> FLAM4 CONFIG :> FLAM4 CONFIG CLEAR
HELP: Shows the grammar for commands and properties TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 GRAMMAR
The grammar used for interpreting the command line and property files is shown. This is helpful for understanding how the commands and property files are interpreted by the command line processor.
See Appendix Grammar for an explanation and the output of this command.
:> FLAM4 GRAMMAR
HELP: Shows the regular expressions accepted in a command TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 LEXEMES
The regular expression used for the tokens of the command syntax will be shown. This could be helpful in understanding how the commands and property files are interpreted by the command line processor. Moreover it will be shown how to define a number, a string, a keyword and other values inside a command.
See Appendix Lexemes for an explanation and the output of this command.
:> FLAM4 LEXEMES
HELP: List license information for the program TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 LICENSE
The license string of the software product is shown. This string is provided to the command line executer (CLE) by the calling program and should reflect the current license text for this program.
:> FLAM4 LICENSE
HELP: List version information for the program TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 VERSION
The version of the software product is shown. This string is provided to the command line executer (CLE) by the calling program and should reflect the current version information for this program.
See Appendix Version for the output of this command.
:> FLAM4 VERSION
HELP: Show information about the program TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 ABOUT
Shows information about the software product like version, copyright, external libraries, license and other attributes. This string is provided to the command line executer (CLE) by the calling program and should reflect the current about information for this program (flam4).
See Appendix About for the output of this command.
:> FLAM4 ABOUT
HELP: Show information about return and reason codes of the program TYPE: BUILT-IN FUNCTION SYNTAX: > flam4 ERRORS
This built-in function prints explanations for the return/condition/exit codes of the executable and, if available, the reason codes of executed commands.
The command line executer (CLE) initialized the CLP structure. Calls the command line processor (CLP). Calls the mapping function, which converts the CLP structure in a corresponding command structure. Then it runs the command and as last step it calls the finish function with the command structure, to close all files and free all the allocated memory. If one of these steps fails, then a corresponding return (condition/exit) code is given back from the executable. Only the command execution can result in a error (return code 8) or in a warning (return code 4). The command it self must return a reason code for such a warning or error. This means that the return (condition/exit) code can be used to control the batch processing. The reason code gives more information about the error or warning.
See sections return codes and reason codes for an explanation and the output of this command.
:> FLAM4 ERRORS