Creating a custom function

To create your own functions, a C or C++ development tool is required, or the Java Native Interface (JNI) if you are working in a Java environment.

Procedure

  1. From a component rule in the Type Designer or from a map rule in the Map Designer, right-click and select the Insert Function option.
    (Additionally in the Map Designer, if you are not in a map rule, you can create a new function by selecting Rules > New Function.)
  2. From the Insert Function window, select Design.
    The Custom Function Modules window is displayed.
  3. In the Path field, enter the path of where to create the external library.
    This should always be in the install_dir/function_libs directory.
  4. In the Name field, enter a name for the library.
  5. Click Add to add a function to the library.
    The Function Specifics window is displayed.
  6. In the Name field, enter a name for the function.
  7. For Return Type, select the function return type from the drop-down list.
    You can select up to four function parameters from the respective drop-down list. Choices include Boolean, date, number, text, time, and byte stream.
  8. In the space provided, enter a description for your function.
    This information will be displayed in the Insert Function window of both Designers.
  9. Click OK to validate the selected parameters and close the Function Specifics window.
  10. Click Generate.
    The Designer generates a collection of operating system specific makefiles and definition files that provide the framework for the function you are creating.
  11. Go to the install_dir/function_libs directory to view the results.
    As a result of the generation process, framework files are created for each operating system that HCL® OneTest™ Data supports. You can find the operating system-specific makefiles and definition files in the install_dir/function_libs/your_new_lib directory.
  12. Now you must modify the framework that was generated by the Designer.
    The following functions with the parameter information that you selected were exported to the .c file:
    • GetFunctionCount
    • GetFunctionName
    • GetInputParameter
    • GetReturnType
    • GetParameterCount
    • GetFunctionDesc

    To complete the new function, open the .c file and add your programming code for the applicable function or functions provided.

    Use the .c file to build your dynamic link library (DLL) and then place the DLL in the install_dir/function_libs/your_new_lib directory. (All custom designed libraries and functions must be placed in the install_dir/function_libs directory.)

    The new library name is listed under Category in the Insert Function window, and the new function that you created is placed in the list of functions and will remain available for future use from both the Type Designer and Map Designer applications.

Example

The following example displays how to implement a custom function called SIN. 
void ConvertToBytes(double  returnValue, LPEXITPARAM lpep)
{
  double value = 0.0;  
  int decimal = 2,   sign = 0, j = 0, k = 0;
  char byString[100];
  char* lpbyData = _fcvt(returnValue, 7, &decimal, &sign );
  memset(byString, 0, sizeof(byString));

  if (sign)  
       byString[j++] = '-';

  if (decimal  <= 0)   
  {
   byString[j++] = '0';
   byString[j++] = '.';
    while (decimal != 0)
    {
     byString[j++] = '0';	decimal++;
    }
  }
  else if (decimal > 0)
  {
    while (decimal != 0)
    {
     byString[j++] = lpbyData[k++]; decimal--;
    }
     byString[j++] = '.';
  }
  while (lpbyData[k])  byString[j++] = lpbyData[k++];

  byString[j] = '\0';

  if (NULL == (lpep->lpDataFromApp = GlobalAllocPtr
     (GHND, j + 1)))   
  {
  lpep->nReturn = -1;
  lstrcpy(lpep->szErrMsg, "Memory allocation failed in Alternate");
  return;  
  }

  memcpy(lpep->lpDataFromApp, byString, j);   
  lpep->dwFromLen =  j;
  lpep->lpDataFromApp[j++] = '\0';
}


void CALLBACK EXPORT SIN(LPEXITPARAM lpep) 
{
  double value = 0.0;
  double returnValue = 0.0;  
  LPEXITPARAMEXTENDED lpExtended = NULL;

  if (lpep->dwSize != sizeof(EXITPARAM))
  {
   return;
  }

  lpExtended = (LPEXITPARAMEXTENDED)lpep->lpv;
value = atof(lpExtended->lpFirstInputParameter);

returnValue = sin(value);
ConvertToBytes(returnValue, lpep);
  lpep->wCleanupAction = GetReturnType("SIN");
lstrcpy(lpep->szErrMsg, "SIN function was successful");

return;
}

What to do next

At run time, all custom designed libraries and functions that your maps use must be in the install_dir/function_libs directory. When you deploy a map that uses a custom function to a remote host, the library is not transferred. Therefore you must manually copy the custom function library to the install_dir/function_libs directory on the remote host.