FLAMCLE/P-API
Command Line Executor/Parser Application Programming Interface
|
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... | |
Type definitions for the callback functions used by CLE.
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.
[in] | pfOut | File pointer for normal output (NULL for no output). |
[in] | pfErr | File pointer for error messages (NULL for no output). |
[in] | pcPat | Path where the documentation is written to. |
[in] | pcOwn | String of the current Owner. |
[in] | pcPgm | String with the current program name. |
[in] | pcBld | Optional build/version number (could be NULL). |
[in,out] | piHdr | Boolean to define if header information for cover page generated by CLEP. |
[in,out] | piAnc | Boolean to define if anchors generated by CLEP. |
[in,out] | piIdt | Boolean to define if index terms generated by CLEP. |
[in,out] | piPat | Boolean to define if path string part of the synopsis. |
[in,out] | piPs1 | Character to separate parts before command strings of the file path (use '/' for sub folders or '-' to get file names). |
[in,out] | piPs2 | Character to separate parts inside command strings of the file path (use '/' for sub folders or '-' to get file names). |
[in,out] | piPr3 | Character to replace non alpha-numerical characters in the file name. |
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.
[in] | pvHdl | Pointer the the print handle. |
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.
[in] | pvHdl | Pointer to the CLP handle for allocation of memory in the CLP structure. |
[in] | pfOut | File pointer for outputs (given over CleExecute, see siCleExecute()). |
[in] | pfTrc | File pointer for tracing (given over CleExecute, see siCleExecute()). |
[in] | pvGbl | Pointer to a global handle as black box pass through (given over CleExecute, see siCleExecute()). |
[in] | pcOwn | Current owner name (given over CleExecute, see siCleExecute()). |
[in] | pcPgm | Current program name (given over CleExecute, see siCleExecute()). |
[out] | pvClp | Pointer to the corresonding FLAMCLP structure for initialisation. |
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.
[in] | pvClp | Pointer to the CLP handle for allocation of memory in the CLP structure. |
[in] | pfOut | File pointer for outputs (mainly error messages, given over CleExecute, see siCleExecute()). |
[in] | pfTrc | File pointer for tracing (mainly for complex stuff, given over CleExecute, see siCleExecute()). |
[in] | pvGbl | Pointer to a global handle as black box pass through (given over CleExecute, see siCleExecute()). |
[in] | piOid | Pointer to the object identifier for overlay commands, if the pointer set at siCleExecute(). |
[in] | pvClp | Pointer to the filled FLAMCLP structure (output from the command line parser). |
[out] | pvPar | Pointer to the parameter structure, which will be filled based on the FLAMCLP structure with this function. |
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().
[in] | pvHdl | Pointer to the CLP handle for allocation of memory in the FLC structure. |
[in] | pfOut | File pointer for outputs (given over structure CleExecute, see siCleExecute()). |
[in] | pfTrc | File pointer for tracing (given over structure CleExecute, see siCleExecute()). |
[in] | pvGbl | Pointer to a global handle as black box pass through (given over structure CleExecute, see siCleExecute()). |
[in] | pcOwn | Current owner name (given over structure CleExecute, see siCleExecute()). |
[in] | pcPgm | Current program name (given over structure CleExecute, see siCleExecute()) |
[in] | pcVsn | Current version information (given from structure CleExecute, see siCleExecute()). |
[in] | pcAbo | Current about information (given from structure CleExecute, see siCleExecute()). |
[in] | pcLic | Current license text (given from structure CleExecute, see siCleExecute()). |
[in] | pcFkt | Current function name (key word of the command). |
[in] | pcCmd | Current command (complete entered line of user). |
[in] | pcLst | Current list of parsed arguments (given from FLAMCLP, could be NULL or empty). |
[in] | pvPar | Pointer to the filled parameter for the run of the subprogram. |
[out] | piWrn | Pointer 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] | piScc | Pointer to an integer containing a special condition code (if greater CLERTC_MAX(64) then used instead of CLERTC_RUN(8)). |
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.
[in] | pfOut | File pointer for outputs (given over CleExecute, see siCleExecute()). |
[in] | pfTrc | File pointer for tracing (given over CleExecute, see siCleExecute()). |
[in] | pvGbl | Pointer to a global handle as black box pass through (given over CleExecute, see siCleExecute()). |
[in] | pvPar | Pointer to the filled parameter structure for cleanup. |
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.
[in] | siRsn | Reason code from INI, MAP, RUN and FIN function. |