FLAMCLE/P-API
Command Line Executor/Parser Application Programming Interface
CLE Function Pointer (call backs)

Type definitions for the callback functions used by CLE. More...

Typedefs

typedef void *() TfCleOpenPrint(FILE *pfOut, FILE *pfErr, const char *pcPat, const char *pcOwn, const char *pcPgm, const char *pcBld, int *piHdr, int *piAnc, int *piIdt, int *piPat, int *psPs1, int *piPs2, int *piPr3)
 Function 'opnHtmlDoc' of library 'libhtmldoc' called if built-in function HTMLDOC used. More...
 
typedef int() TfCleClosePrint(void *pvHdl)
 Function 'clsHtmlDoc' of library 'libhtmldoc' called if built-in function HTMLDOC used. More...
 
typedef int() TfIni(void *pvHdl, FILE *pfOut, FILE *pfTrc, void *pvGbl, const char *pcOwn, const char *pcPgm, void *pvClp)
 Type definition for initialization FLAMCLE command structure. More...
 
typedef int() TfMap(void *pvHdl, FILE *pfOut, FILE *pfTrc, void *pvGbl, int *piOid, void *pvClp, void *pvPar)
 Type definition for mapping parsed values from the FLAMCLP structure. More...
 
typedef int() TfRun(void *pvHdl, FILE *pfOut, FILE *pfTrc, void *pvGbl, const char *pcOwn, const char *pcPgm, const char *pcVsn, const char *pcAbo, const char *pcLic, const char *pcFkt, const char *pcCmd, const char *pcLst, const void *pvPar, int *piWrn, int *piScc)
 Type definition for CLE run function. More...
 
typedef int() TfFin(FILE *pfOut, FILE *pfTrc, void *pvGbl, void *pvPar)
 Type definition for the CLE fin function. More...
 
typedef const char *() TfMsg(const int siRsn)
 Type definition for the CLE message function. More...
 

Detailed Description

Type definitions for the callback functions used by CLE.

Typedef Documentation

◆ TfCleOpenPrint

typedef void*() TfCleOpenPrint(FILE *pfOut, FILE *pfErr, const char *pcPat, const char *pcOwn, const char *pcPgm, const char *pcBld, int *piHdr, int *piAnc, int *piIdt, int *piPat, int *psPs1, int *piPs2, int *piPr3)

Function 'opnHtmlDoc' of library 'libhtmldoc' called if built-in function HTMLDOC used.

The built-in function HTMLDOC use a service provider interface to create the documentation using a callback function for each page/chapter. This function is called in front of the generation process to establish a handle for the callback function.

The resulting handle is given to the callback function TfClpPrintPage defined by CLP. This callback function is called for each page/chapter written. After the documentation generation process the handle will be released with the function TfCleClosePrint.

Parameters
[in]pfOutFile pointer for normal output (NULL for no output).
[in]pfErrFile pointer for error messages (NULL for no output).
[in]pcPatPath where the documentation is written to.
[in]pcOwnString of the current Owner.
[in]pcPgmString with the current program name.
[in]pcBldOptional build/version number (could be NULL).
[in,out]piHdrBoolean to define if header information for cover page generated by CLEP.
[in,out]piAncBoolean to define if anchors generated by CLEP.
[in,out]piIdtBoolean to define if index terms generated by CLEP.
[in,out]piPatBoolean to define if path string part of the synopsis.
[in,out]piPs1Character to separate parts before command strings of the file path (use '/' for sub folders or '-' to get file names).
[in,out]piPs2Character to separate parts inside command strings of the file path (use '/' for sub folders or '-' to get file names).
[in,out]piPr3Character to replace non alpha-numerical characters in the file name.
Returns
Pointer to an handle or NULL if open failed

◆ TfCleClosePrint

typedef int() TfCleClosePrint(void *pvHdl)

Function 'clsHtmlDoc' of library 'libhtmldoc' called if built-in function HTMLDOC used.

The built-in function HTMLDOC use a service provider interface to create the documentation using a callback function for each page/chapter. A callback function is a function that is passed as a parameter to another function and is called later by this function under defined conditions with defined arguments.

This built-in function HTMLDOC is called after the generation process to free resources associated with this handle. The handle will be generated with the function TfCleOpenPrint in front of documentation generation.

Parameters
[in]pvHdlPointer the the print handle.
Returns
Return code (0 is OK else error).

◆ TfIni

typedef int() TfIni(void *pvHdl, FILE *pfOut, FILE *pfTrc, void *pvGbl, const char *pcOwn, const char *pcPgm, void *pvClp)

Type definition for initialization FLAMCLE command structure.

This FLAMCLE structure is used by the command line processor (FLAMCLP) to save the parsed values. The INI function uses this structure to pre-define values. These values are still valid, if no values are defined over the properties or command line.

The current owner and the program name are provided by the function CleExecute (see siCleExecute()), to know these values during initialization.

If additional dynamic memory is required in the CLP structure the provided handle can be used for calling function pvClpAlloc.

Parameters
[in]pvHdlPointer to the CLP handle for allocation of memory in the CLP structure.
[in]pfOutFile pointer for outputs (given over CleExecute, see siCleExecute()).
[in]pfTrcFile pointer for tracing (given over CleExecute, see siCleExecute()).
[in]pvGblPointer to a global handle as black box pass through (given over CleExecute, see siCleExecute()).
[in]pcOwnCurrent owner name (given over CleExecute, see siCleExecute()).
[in]pcPgmCurrent program name (given over CleExecute, see siCleExecute()).
[out]pvClpPointer to the corresonding FLAMCLP structure for initialisation.
Returns
Reason code (!=0) for termination or 0 for success.

◆ TfMap

typedef int() TfMap(void *pvHdl, FILE *pfOut, FILE *pfTrc, void *pvGbl, int *piOid, void *pvClp, void *pvPar)

Type definition for mapping parsed values from the FLAMCLP structure.

This function is used to map the parsed values from the FLAMCLP structure to the parameter structure of the corresponding command. This mapping can simply a memcpy or pointer assignment but it is often useful to make a real mapping for example:

The executed subprogram needs a table with some definitions. These definitions can easily managed in a file. Over the command line the user define the file name and the mapping function open this file read the definition, allocates the memory and stores the definition in the parameter structure. This means that the user defines the file name, but the executed subprogram gets the content of this file. Such things are realized over a real mapping between the parsed values and the needed arguments.

For overlay based commands the pointer to the object identifier is provided (taken from siCleExecute()). This integer can then be used to choose the correct data structure from the corresponding CLP union for mapping. (The piOid can also (mis)used to give back a integer to the caller of siCleExecute() from mapping if this pointer not NULL.)

If additional dynamic memory required in the CLP structure the provided handle can be used for pvClpAlloc.

Parameters
[in]pvClpPointer to the CLP handle for allocation of memory in the CLP structure.
[in]pfOutFile pointer for outputs (mainly error messages, given over CleExecute, see siCleExecute()).
[in]pfTrcFile pointer for tracing (mainly for complex stuff, given over CleExecute, see siCleExecute()).
[in]pvGblPointer to a global handle as black box pass through (given over CleExecute, see siCleExecute()).
[in]piOidPointer to the object identifier for overlay commands, if the pointer set at siCleExecute().
[in]pvClpPointer to the filled FLAMCLP structure (output from the command line parser).
[out]pvParPointer to the parameter structure, which will be filled based on the FLAMCLP structure with this function.
Returns
Reason code (!=0) for termination or 0 for success. If a no run reason code (!=0) defined then the run function is not executed.

◆ TfRun

typedef int() TfRun(void *pvHdl, FILE *pfOut, FILE *pfTrc, void *pvGbl, const char *pcOwn, const char *pcPgm, const char *pcVsn, const char *pcAbo, const char *pcLic, const char *pcFkt, const char *pcCmd, const char *pcLst, const void *pvPar, int *piWrn, int *piScc)

Type definition for CLE run function.

The run function is used to execute the corresponding subprogram for a command using the mapped parameter structure. For logging or other purpose all collected information are also provided at input.

The run function returns like all other functions executed by CLE a reason code. Additional to the other functions there will be another indicator to define the condition code (return code of the program). For the run function 2 possible condition codes are defined. First an error with value 8 and additional 4 in a case of a warning. The warning means that the run don't fail, but something was happen.

If additional dynamic memory required in the FLC structure (from mapping) the provided handle can be used for pvClpAlloc().

Parameters
[in]pvHdlPointer to the CLP handle for allocation of memory in the FLC structure.
[in]pfOutFile pointer for outputs (given over structure CleExecute, see siCleExecute()).
[in]pfTrcFile pointer for tracing (given over structure CleExecute, see siCleExecute()).
[in]pvGblPointer to a global handle as black box pass through (given over structure CleExecute, see siCleExecute()).
[in]pcOwnCurrent owner name (given over structure CleExecute, see siCleExecute()).
[in]pcPgmCurrent program name (given over structure CleExecute, see siCleExecute())
[in]pcVsnCurrent version information (given from structure CleExecute, see siCleExecute()).
[in]pcAboCurrent about information (given from structure CleExecute, see siCleExecute()).
[in]pcLicCurrent license text (given from structure CleExecute, see siCleExecute()).
[in]pcFktCurrent function name (key word of the command).
[in]pcCmdCurrent command (complete entered line of user).
[in]pcLstCurrent list of parsed arguments (given from FLAMCLP, could be NULL or empty).
[in]pvParPointer to the filled parameter for the run of the subprogram.
[out]piWrnPointer to an integer (the fist half word is true (0x0001), if warnings collated by directory walk, the second halfword is true (0x0001) if warnings are logged).
[out]piSccPointer to an integer containing a special condition code (if greater CLERTC_MAX(64) then used instead of CLERTC_RUN(8)).
Returns
Reason code (!=0) for termination or warning, 0 for success

◆ TfFin

typedef int() TfFin(FILE *pfOut, FILE *pfTrc, void *pvGbl, void *pvPar)

Type definition for the CLE fin function.

This function is called at the end after the run to clean up the parameter structure. For example, it could be there was a file pointer which must be closed or memory which must be freed.

Parameters
[in]pfOutFile pointer for outputs (given over CleExecute, see siCleExecute()).
[in]pfTrcFile pointer for tracing (given over CleExecute, see siCleExecute()).
[in]pvGblPointer to a global handle as black box pass through (given over CleExecute, see siCleExecute()).
[in]pvParPointer to the filled parameter structure for cleanup.
Returns
Reason code (!=0) for termination or 0 for success.

◆ TfMsg

typedef const char*() TfMsg(const int siRsn)

Type definition for the CLE message function.

This function is called to generate a appendix for the reason codes and to provide better messages in a case of an error.

In a loop starting with 1 the messages are printed to the appendix. If a NULL pointer (no message) returned the loop is finished. A empty message ("") indicates an reason code which is not printed to the appendix. Is a NULL pointer provided for this function the appendix for the reason codes and additional error messages are not generated.

Parameters
[in]siRsnReason code from INI, MAP, RUN and FIN function.
Returns
Pointer to the corresponding message.