gtpc2m89 | C/C++ Language Support User's Guide |
This function provides an easy way to send you help messages for particular parameters. You do not need to write any C code for this function; it only requires that you provide data structures to issue the correct help message.
Format
#include <c$help.h> void tpf_help(const char *input_message_pointer, const char *help_syntax_pointer, TPF_HELP *main_help_structure_pointer, const char *prefix_pointer);
The first entry in the structure is used for a simple help display; for example, this message is displayed whenever an entry is called with the help request without any additional parameters. This message is also displayed when the parser returns with an error.
Normal Return
Void.
Error Return
Not applicable.
Programming Considerations
The TPF_HELP data structure has several fields that you must initialize, as follows:
This field contains the address of the action code as specified in the syntax string; for example, ACTivate would be valid. Set this field to NULL to mark the end of the help structure.
This pointer specifies the address of a string. The string can contain \n to continue on a new line. The maximum length of a line is restricted to 255 characters; the string itself is not limited in any way.
When the action code specified previously has additional subparameters, this field can contain the address of another TPF_HELP array.
Because many definitions are required for this function, call this function in a subfunction that is called from the main function. To best handle the help requests, store the definitions in their own source file.
Examples
The following example shows how the tpf_help function is used.
#include <tpfapi.h> #include <tpfparse.h> #include <c$help.h> #include <stdlib.h> void my_help(char *input_ptr) { const char oth_message[] = "This is the last help text which is available to show\n" "the nice and easy use of the tpf_help function. Please come\n" "again."; TPF_HELP me_sub_help[] = { { "OTHERS",oth_message,NULL}, { NULL,NULL,NULL} }; const char all_message[] = "Again a short help message"; const char me_message[] = "This parameter has a subparameter and you can have\n" "some additional help when you specify the following:" " OTHERS"; const char non_message[] = "None, but still a display"; TPF_HELP dis_sub_help[] = { { "ALL",all_message,NULL}, { "ME",me_message,me_sub_help}, { "NONe",non_message,NULL}, { NULL,NULL,NULL} }; const char main_help_message[] = "Welcome to the wonders of the tpf_help function\n" "This string has a carriage return in it and will\n" "write four lines with just one single wtopc call," "which is more efficient than doing it for each line." "Please notice that only strings with a ',' at the end\n" "will have a pointer and do not need to have a\n" "carriage return at the end. But now, I will show you\n" "some more help if you select one of the following:" " ADD\n ACTivate\n DEActivate\n DELete\n DISplay"; const char add_message[] = "This is an explanation of the ADD Parameter since you\n" "requested additional help on this." "There are no subparameters for the ADD function and\n" "the function makes no sense anyway"; const char act_message[] = "Very short help message"; const char dea_message[] = "Another short help message"; const char del_message[] = "The last short help message"; const char dis_message[] = "Now this is a bigger help display, because we can select\n" "additional help for three subparameters. " "Request help for one of the following parameters :\n" " ALL\n ME\n NONe"; TPF_HELP help[] = { { "HELP",main_help_message,NULL}, /* <- This is default */ { "ADD",add_message,NULL}, { "ACTivate",act_message,NULL}, { "DEActivate",dea_message,NULL}, { "DELete",del_message,NULL}, { "DISplay,dis_message,dis_sub_help}, { NULL,NULL,NULL} }; const char *syntax = " { " " ADD " " | " " ACTivate " " | " " DEActivate " " | " " DELete " " | " " DISplay " " [ " " { " " ALL " " | " " ME [ OTHERS ]" " | " " NONe " " } " " ] " " } "; tpf_help(input_ptr,syntax,help,"TEST"); } int main() { const char *syntax = " { " " ADD " " | " " ACTivate " " | " " DEActivate " " | " " DELete " " | " " DISplay " " { " " ALL " " | " " ME [ OTHERS ] " " | " " NONe " " } " " } "; struct mi0mi *block_ptr; char *input_ptr; struct IPRSE_output parsed_struc; struct IPRSE_output *next_ptr; long result; block_ptr=(struct mi0mi *)ecbptr()->ce1cr0; input_ptr=block_ptr->mi0acc; input_ptr=input_ptr+5; result=IPRSE_parse(input_ptr,syntax,&parsed_struc, IPRSE_EOM+IPRSE_PRINT+IPRSE_ALLOC, "TEST"); /******************************************************************** * Any error? IPRSE_BAD Message already send * ********************************************************************/ if (result!=IPRSE_BAD) { /****************************************************************** * help request ? * ******************************************************************/ if (result==IPRSE_HELP) { my_help(input_ptr); } else { . . . . . } } exit(0); }
Related Information