gtpc2m89C/C++ Language Support User's Guide

tpf_help-Issue Help Messages

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);

input_message_pointer
Specifies the address of the input message for which a help message must be issued. HELP or ? at the beginning of the message is skipped and the remainder of the message is parsed with the IPRSE_parse function.

help_syntax_pointer
Specifies the address of the syntax that is used in the IPRSE_parse function to split the input message into its parameters.

main_help_structure_pointer
Specifies the address of the help structure array that you must create. The last entry in the structure must be NULL terminated.

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.

prefix_pointer
Prefixes the help message, which has a severity code of I and a number of 0.

Normal Return

Void.

Error Return

Not applicable.

Programming Considerations

The TPF_HELP data structure has several fields that you must initialize, as follows:

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