Community articleFunction Call Help Template
Added by IBM contributorIBM on August 16, 2011
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

No abstract provided.



Description

Provides help information about each of your custom functions. This help can be accesses from a form development environment. For example, the Designer can display this help information.

Function Template

PRE_FUNCTION_DECL r_short POST_FUNCTION_DECL FCISimpleHelp(
   FunctionCall *theFunctionCall,
   r_charP thePackageName, 
   r_charP theFunctionName,
   r_u_long theFunctionID, 
   IFSUserData **theFunctionDataPtr, 
   r_charP *theQuickDescPtr, 
   r_charP *theFunctionDescPtr, 
   r_charP *theSampleCodePtr, 
   r_charP **theArgsNameListPtr, 
   r_long *theArgsNameListSizePtr, 
   r_charP *theArgsDescListPtr, 
   r_long *theArgsDescListSizePtr, 
   r_short **theArgsFlagListPtr, 
   r_long *theArgsFlagsListSizePtr, 
   r_charP *theRetValDescPtr, 
   r_short *theRetValFlagPtr);


Parameters

Table 1. help parameters
ExpressionTypeDescription
theFunctionCallFunctionCall*The FunctionCall structure for your application.
thePackageNamer_charPThe name of the package that contains the function.
theFunctionNamer_charPThe name of the function.
theFunctionIDr_u_longA unique number that can be used to identify the function.
theFunctionDataPtrIFSUserData**Reserved. Although this expression is not used, it must be present.
theQuickDescPtr r_charP*The function will set a quick one-line description of what the function does.
theFunctionDescPtr r_charP*The function will set a longer more detailed description of the function.
theSampleCodePtrr_charP*The function will set an example of the XFDL code used to call your function, including an example of the function parameters.
theArgsNameListPtr r_charP**The function will set a list of arguments that your function takes. See Notes for more information.
theArgsNameListSizePtrr_long*The pointer to the size of theArgsNameList.
theArgsDescListPtr r_charP*The function will set a description of each of the arguments in the theArgsNameList. See Notes for more information.
theArgsDescListSizePtr r_long*The pointer to the size of theArgsDescList.
theArgsFlagListPtrr_short*The function will set a list of bit flags representing the type of each argument that the function takes. See Notes for more information.
theArgsFlagsListSizePtrr_long*A pointer to the size of theArgsFlagList
theRetValDescr_charP*The function will set a description of function custom function's return value.
theRetValFlagr_charP*The function will set a bit flag representing the type of the return value. See Notes for more information. Simply use UFLSetLiteralEx on this object to store the result.


Returns

OK on success or an error code on failure.

Notes

  • PRE_FUNCTION_DECL and POST_FUNCTION_DECL are used to import and export the functions you implement in your .c source file to other code modules used by the Forms System.
  • Refer to the table of FunctionCall Constants API 4 CCreate New Article for possible values for:
    • theArgsFlagList
    • theRetValFlag
  • For both theArgsDescListPtr and theArgsNameListPtr, if you have no arguments you must dereference the pointer and set it to NULL. For example:
  • *theArgsNameListPtr = NULL;

Example

PRE_FUNCTION_DECL r_short POST_FUNCTION_DECL FCISimpleHelp(FunctionCall *theObject, 
r_charP thePackageName, r_charP theFunctionName, r_u_long theFunctionID, IFSUserData 
**theFunctionDataPtr, r_charP *theQuickDescPtr, r_charP *theFunctionDescPtr, r_charP 
*theSampleCodePtr, r_charP **theArgsNameListPtr, r_long *theArgsNameListSizePtr, 
   r_charP 
**theArgsDescListPtr, r_long *theArgsDescListSizePtr, r_short **theArgsFlagListPtr, 
   r_long 
*theArgsFlagListSizePtr, r_charP *theRetValDescPtr, r_short *theRetValFlagPtr)
{
/* Switch on theFunctionID. This makes it easy for a single FunctionCall
      structure to support multiple functions. */
      
      switch(theFunctionID)
      {
/* Remember that you must define an ID number for each custom function
      that you create. In the example below the constant FCI_MULTIPLY_ID
      represents the identification number for the multiply function. */
         case FCI_MULTIPLY_ID:
            *theQuickDescPtr =
               cp_strdup("Multiplies two numbers together");
         
            *theFunctionDescPtr =cp_strdup( 
               "Function multiplies two numbers.\n"
               "It takes the values of two fields\n"
               "and finds their product with precision\n"
               "of up to seven decimal places.");
            *theSampleCodePtr = cp_strdup(
               "\t<field sid=\"PRODUCT_FIELD\">\n"
               "\t\t<value compute=\"test_Pkg.multiply"
               "(field1.value, field2.value)\"></value>\n"
               "\t\t<size>\n"
               "\t\t\t<ae>10</ae>\n"
               "\t\t\t<ae>1</ae>\n"
               "\t\t</size>\n"
               "\t</field>\n");
            *theRetValDescPtr = cp_strdup(
               "The product of the two parameters given");
            break;
         default:
            break;
      }
      return(OK);
}