Community articleFunction Call Evaluate Template
Added by IBM contributorIBM on May 2, 2012
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

This function performs the necessary work for your custom-built function. You will have to insert the details of your custom functions within this function and pass a pointer for this function to IFSObject_SetObjectProc.

Function Template

PRE_FUNCTION_ DECL r_short POST_FUNCTION_DECL FCISimpleFunction(
   FunctionCall *theFunctionCall,
   r_charP thePackageName,  
   r_charP theFunctionName, 
   r_u_long theFunctionID, 
   r_data theFunctionInstance, 
   r_short theCommand, 
   formNodeP theForm, 
   formNodeP theComputeNode, 
   IFSUserData **theFunctionDataPtr, 
   IFSUserData **theFunctionInstanceDataPtr, 
   formNodeP *theArgList, 
   r_long *theArgListSizePtr,
   formNodeP theResult);


Parameters

Table 1. evaluate parameters
ExpressionTypeDescription
theFunctionCallFunctionCall*The FunctionCall structure.
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.
theFunctionInstance r_dataA unique number that differentiates one instance of the function from another instance. See Notes for more information.
theCommandr_shortThe name of the command for this function to perform. See Notes for more information. Other commands can be found within the manual.
theForm formNodePThe root node of the form that contains the function.
theComputeNodeformNodePThe node within the form that the function belongs to. See Notes for more information.
theFunctionDataPtrIFSUserData**Reserved. Although this expression is not used, it must be present.
theFunctionInstance DataPtrIFSUserData**Reserved. Although this expression is not used, it must be present.
theArgListformNodeP*The list of arguments. See Notes for more information.
theArgListSizePtrr_long*A pointer to the number of arguments.
theResultformNodePThe formNodeP structure in which you can store the result. Simply use UFLSetLiteralEx on this 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.
  • theCommand — the value of theCommand represents the command that your implementation of FunctionCallEvaluate will perform.
    • The value of theCommand depends on the value of the parameter called theFlags in the function called FCMRegisterFunctionCall.
    • Usually the value of theCommand will be set to FCICOMMAND_RUN which indicates that a function must be evaluated.
    • Other possible values for theCommand include:
    • FCICOMMAND_INSTANCEDEREGISTER — This constant indicates that FunctionCallEvaluate should execute a procedure when an instance of the function has been de-registered.
    • FCICOMMAND_DEREGISTER — This constant indicates that FunctionCallEvaluate should execute a procedure when the function has been de-registered.
    • FCICOMMAND_REGISTER — This constant indicates that FunctionCallEvaluate should execute a procedure when the function is registered.
    • FCICOMMAND_INSTANCEREGISTER — This constant indicates that FunctionCallEvaluate should execute a procedure when an instance of the function is registered.
  • theFunctionInstance — is a unique number that differentiates one instance of the function with another instance. For example if a form contains two calls to the function test_Pkg.multiply then two unique values for theFunctionInstance variable will exist.
  • theComputeNode — is the node within the form that the function belongs to. For example, if you have an item like:
  •       <label sid="label1">
             <value compute="test_Pkg.multiply(f1.value, f2.value)"></value>
          </label>

    theComputeNode will point to the node that represents the value option.
  • theFunctionInstanceData — is data specific to an instance of a function. It will always be returned when the instance of the function is called. This data is only provided when the FCI_WANTS_INSTANCE_DATA flag is set during the call to FCMRegisterFunctionCall.
  • theArgList — Each argument's value is stored as a literal within a formNodeP structure. For example to get the value of the first argument, type the following:
  • UFLGetLiteral(theArgList [0], NULL, &returnValue)

Example

PRE_FUNCTION_DECL r_short POST_FUNCTION_DECL FCISimpleFunctions(FunctionCall 
   *theObject, 
r_charP thePackageName, r_charP theFunctionName, r_u_long theFunctionID, r_data 
   theFunctionInstance, 
r_short theCommand, formNodeP theForm, formNodeP theComputeNode, IFSUserData 
**theFunctionDataPtr, IFSUserData **theFunctionInstanceDataPtr, formNodeP 
     *theArgList, r_long 
theArgListSize, formNodeP theResult)
{
r_charP theFirstParam;
double firstNum;
r_charP theSecondParam;
double secondNum;
double theMultiplyResult;
char theLiteralBuffer [50]; 
/*    Verify the input parameters */
      if ((thePackageName == NULL) || (theFunctionName == NULL))
      {
         MessageBox(NULL, "Invalid parameters", "Error", MB_OK);
         return(NOTOK);
      }
/* Make sure that the package is the one we are expecting. */
      if (cp_strcmp(thePackageName, PACKAGE_NAME) != OK)
      {
         MessageBox(NULL,"Function called with the wrong package",
            "Error", MB_OK);
         return(NOTOK);
      }
/* The first switch in this function is based on theCommand.  The only
      case that we are interested in handling is FCICOMMAND_RUN that
      indicates that we should evaluate a function. */
      switch (theCommand)
      {
         case FCICOMMAND_RUN:
/* The second switch is based on theFunctionID that you set for each of
      your custom functions. This makes it easy for a single Function Call
      object to support multiple functions. */
            switch (theFunctionID)
            {
               case FCI_MULTIPLY_ID:
                  /* Insert Implementation Details Here */ 
      
                  break;
            
               default:
                  break;
            }
            break;
            case FCICOMMAND_INSTANCEREGISTER:
               break;
      
            case FCICOMMAND_INSTANCEDEREGISTER:
               break;
            case FCICOMMAND_REGISTER:
               break;
            case FCICOMMAND_DEREGISTER:
               break;
         default:
            break;
      }
      return(OK);
}