## Built-in Functions

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.

### SYNTAX

#### Synopsis

    HELP:   Provides the syntax for each command
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl SYNTAX [command[.path] [DEPTH1 | ... | DEPTH9 | ALL]]

#### Description

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.

- question mark - optional parameter
- exclamation mark - required parameter

The path is a dotted keyword list in accordance with the syntax of the corresponding command.

       command.para1.para2.para3

#### Options

- DEPTH1 / DEPTH2 / ... / DEPTH9
  - Specifies the depth of the output. Default is DEPTH1. If the depth is greater than 1 the structured print out is used.
- ALL
  - Shows complete syntax for the specified path, not just DEPTH1. Structured print out is used.

#### Examples

       :> FLCL SYNTAX
       :> FLCL SYNTAX command
       :> FLCL SYNTAX command ALL
       :> FLCL SYNTAX command.para
       :> FLCL SYNTAX command.para ALL

### HELP

#### Synopsis

    HELP:   Provides quick help for arguments
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl HELP [command[.path] [DEPTH1 | ... | DEPTH9 | ALL]] [MAN]

#### Description

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:

- keyword - the keyword for the argument
- (TYPE: ...) - the type of this argument
- help message - the short help text
- (PROPERTY: [...]) - the current hard coded property value (optional)

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.

#### Options

- DEPTH1 / DEPTH2 / ... / DEPTH9
  - Specifies the depth of the output. Default is DEPTH1.
- ALL
  - Shows complete help below specified path, not just DEPTH1 and includes all aliases defined for a certain argument.
- MAN
  - Shows additionally the detailed description for this program, command or parameter and the next level of arguments including the aliases.

#### Examples

       :> FLCL HELP
       :> FLCL HELP MAN
       :> FLCL HELP command
       :> FLCL HELP command MAN
       :> FLCL HELP command ALL
       :> FLCL HELP command.para
       :> FLCL HELP command.para MAN
       :> FLCL HELP command.para ALL

### MANPAGE

#### Synopsis

    HELP:   Provides manual pages (detailed help)
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl MANPAGE [function | command[.path][=filename]] | [filename]

#### Description

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.

#### Examples

       :> FLCL MANPAGE
       :> FLCL MANPAGE filename
       :> FLCL MANPAGE command
       :> FLCL MANPAGE command=filename
       :> FLCL MANPAGE function
       :> FLCL MANPAGE function=filename
       :> FLCL MANPAGE command.para
       :> FLCL MANPAGE command.para=filename

### GENDOCU

#### Synopsis

    HELP:   Generates auxiliary documentation (ASCIIDOC text format)
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl GENDOCU [command[.path]=]filename [NONBR] [SHORT]

#### Description

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.

       :> flcl 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.

#### Examples

       :> FLCL GENDOCU flcl.manual.txt NONBR
       :> FLCL GENDOCU flcl.manual.txt SHORT
       :> FLCL GENDOCU command=command.manual.txt
       :> FLCL GENDOCU command.argument=argument.manual.txt

### HTMLDOC

#### Synopsis

    HELP:   Generates the complete HTML documentation into a folder
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl HTMLDOC [path] [NUMBERS] [TYPES] [SHORT]

#### Description

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

#### Examples

       :> FLCL HTMLDOC
       :> FLCL HTMLDOC . SHORT
       :> FLCL HTMLDOC /user/home/docu/flclbook
       :> FLCL HTMLDOC NUMBERS SHORT
       :> FLCL HTMLDOC /user/home/docu/flclbook SHORT

### GENPROP

#### Synopsis

    HELP:   Generates a property file
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl GENPROP [command=]filename

#### Description

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.

#### Examples

       :> FLCL GENPROP owner.general.properties
       :> FLCL GENPROP command=owner.command.properties

### SETPROP

#### Synopsis

    HELP:   Activate a property file
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl SETPROP [command=]filename

#### Description

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.

#### Examples

       :> FLCL SETPROP general.properties
       :> FLCL SETPROP command=command.properties

### CHGPROP

#### Synopsis

    HELP:   Change a property value in the currently active property file
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl CHGPROP command [path[=value]]*

#### Description

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.

#### Examples

       :> FLCL CHGPROP command overlay.object.argument=value
       :> FLCL CHGPROP command overlay.object.argument
       :> FLCL CHGPROP command object.argument=value1 argument=value2

### DELPROP

#### Synopsis

    HELP:   Remove a property file from configuration
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl DELPROP [command]

#### Description

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.

#### Examples

       :> FLCL DELPROP
       :> FLCL DELPROP command

### GETPROP

#### Synopsis

    HELP:   Show current properties
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl GETPROP [command[.path] [DEPTH1 | ... | DEPTH9 | DEPALL | DEFALL]]

#### Description

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.

#### Options

- `DEPTH1 / DEPTH2 / ... / DEPTH9`
  - Specifies the depth of the output. Default is DEPTH1.
- `DEPALL`
  - Shows all properties to the specified path, not just DEPTH1.
- `DEFALL`
  - Shows all defined properties to the specified path.

#### Examples

       :> FLCL GETPROP
       :> FLCL GETPROP command
       :> FLCL GETPROP command DEFALL
       :> FLCL GETPROP command.para
       :> FLCL GETPROP command.para DEPALL

### SETOWNER

#### Synopsis

    HELP:   Defines the current owner
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl SETOWNER name

#### Description

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.

#### Examples

       :> FLCL SETOWNER com.company

### GETOWNER

#### Synopsis

    HELP:   Show current owner setting
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl GETOWNER

#### Description

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.

#### Examples

       :> FLCL GETOWNER

### SETENV

#### Synopsis

    HELP:   Set an environment variable (defined in the config file)
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl SETENV variable=value

#### Description

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

#### Examples

       :> FLCL SETENV LANG=DE_DE.IBM-1141
       :> FLCL SETENV LANG=DE_DE.UTF-8
       :> FLCL SETENV ENVID=T
       :> FLCL SETENV ENVID=P

### GETENV

#### Synopsis

    HELP:   Show the environment variables (defined in the config file)
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl GETENV

#### Description

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

#### Examples

       :> FLCL GETENV

### DELENV

#### Synopsis

    HELP:   Delete an environment variable (defined in the config file)
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl DELENV variable

#### Description

This function will delete environment variables from the configuration file for a certain owner.

#### Examples

       :> FLCL DELENV LANG

### LSTENV

#### Synopsis

    HELP:   List status of all possible usable environment variables
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl LSTENV

#### Description

This function will list the status of all possible useable environment variables.

#### Examples

       :> FLCL LSTENV

### HLPENV

#### Synopsis

    HELP:   List help message for all possible usable environment variables
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl HLPENV

#### Description

This function will print the help message for all possible usable environment variables.

#### Examples

       :> FLCL LSTENV

### TRACE

#### Synopsis

    HELP:   Manage trace capabilities
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl TRACE ON | OFF | FILE=filename

#### Description

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.

#### Examples

       :> FLCL TRACE FILE=filename
       :> FLCL TRACE ON
       :> FLCL TRACE OFF

### CONFIG

#### Synopsis

    HELP:   Shows or clear all the current configuration settings
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl CONFIG [CLEAR]

#### Description

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:

       FLCL_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:

       .flcl.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.FLCL.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.

#### Examples

       :> FLCL CONFIG
       :> FLCL CONFIG CLEAR

### GRAMMAR

#### Synopsis

    HELP:   Shows the grammar for commands and properties
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl GRAMMAR

#### Description

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.

#### Examples

       :> FLCL GRAMMAR

### LEXEMES

#### Synopsis

    HELP:   Shows the regular expressions accepted in a command
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl LEXEMES

#### Description

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.

#### Examples

       :> FLCL LEXEMES

### LICENSE

#### Synopsis

    HELP:   List license information for the program
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl LICENSE

#### Description

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.

#### Examples

       :> FLCL LICENSE

### VERSION

#### Synopsis

    HELP:   List version information for the program
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl VERSION

#### Description

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.

#### Examples

       :> FLCL VERSION

### ABOUT

#### Synopsis

    HELP:   Show information about the program
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl ABOUT

#### Description

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 (flcl).

See Appendix About for the output of this command.

#### Examples

       :> FLCL ABOUT

### ERRORS

#### Synopsis

    HELP:   Show information about return and reason codes of the program
    TYPE:   BUILT-IN FUNCTION
    SYNTAX: > flcl ERRORS

#### Description

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.

#### Examples

       :> FLCL ERRORS