Task Based Application Libraries
Applications created using the different Creo Parametric API products are interoperable. These products use Creo Parametric as the medium of interactions, eliminating the task of writing native -platform specific interactions between different programming languages.
ProArgument and Argument Management
Use the data structure ProArgument to pass application data to and from tasks in other applications. The declaration for this structure is: 
                typedef struct pro_argument
                  {
                    ProName      label;
                    ProValueData value;
                  } ProArgument;
The ProValueData structure supports the following argument types:
•  Integer
•  Double
•  String (char*)
•  String (wchar_t*)
•  Boolean
•  ProSelection
•  ProMatrix
Do not use the value type PRO_VALUE_TYPE_POINTER (provided with this structure in order to support feature element tree values) when passing arguments between applications.
Functions Introduced:
  • ProArgumentByLabelGet()
    		•
  • ProValuedataStringSet()
    		•
  • ProValuedataWstringSet()
    		•
  • ProValuedataTransformGet()
    		•
  • ProValuedataTransformSet()
    		•
  • ProArgumentProarrayFree()
    		•
    Use the function ProArgumentByLabelGet() to locate an argument within a ProArray of ProArgument structures passed between applications.
    Use the function ProValuedataStringSet() to allocate and copy memory into the ProValuedata structure for a char* argument. Using this function ensures that ProArgumentProarrayFree() releases all memory in an arguments array.
    Use the function ProValuedataWstringSet() to allocate and copy memory into the ProValuedata structure for a wchar_t* argument. Use this function to ensure that ProArgumentProarrayFree() releases all memory in an arguments array.
    Use the function ProValuedataTransformSet() to allocate and copy memory into the ProValuedata structure for a ProMatrix argument. Use this function to ensure that ProArgumentProarrayFree() releases all memory in an arguments array.
    Use the function ProValuedataTransformGet() to copy a ProMatrix value into a local variable. The matrix data is not directly accessible from the double** member of the ProValuedata structure.
    Use the function ProArgumentProarrayFree() to completely free an array of ProArgument structures.
    Creating Creo TOOLKIT DLL Task Libraries
    Functions that are intended to act as Creo TOOLKIT task library functions must have the same signature as ProTkdllFunction(): 
                    typedef ProError (*ProTkdllFunction) (
                ProArgument* inputs, ProArgument** outputs );
    Use the preprocessor macro PRO_TK_DLL_EXPORT with any function that must be accessible to external applications. This macro provides platform-specific instructions to the compiler to make the function visible to other external applications. This macro must be placed in the function prototype, if it exists, and in the function definition if the prototype does not exist.
    Some platforms require externally visible symbols to be declared on the application link line.
    Memory Management in Task Library Functions
    To avoid memory leaks or overwrites, the DLL functions must use proper memory management. The DLL function must:
    •  Ensure that the contents of the input ProArgument array are not freed. This is taken care of by the calling application and the Creo TOOLKIT communications code.
    •  Use the ProValuedata*Set() functions to assign values to the output ProArgument array. This allows the calling application to free the output array with ProArgumentProarrayFree().
    Example 1: An Exported Toolkit Task Function
    The sample code in the file UgImportfeatCreate.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_featcreat, function demonstrates how you can set up and implement a Creo TOOLKIT task function accessible from other Creo Parametric auxiliary applications. It uses the required signature and macro for task functions. It parses the input argument array to search for parameters required by the task.
    Launching Creo TOOLKIT DLL Functions
    Functions Introduced:
  • ProToolkitDllLoad()
    		•
  • ProToolkitTaskExecute()
    		•
  • ProToolkitDllUnload()
    		•
  • ProToolkitDllIdGet()
    		•
  • ProToolkitDllHandleGet()
    		•
    Use the function ProToolkitDllLoad() to register and start a Creo TOOLKIT DLL. The input parameters of this function are similar to the fields of a registry file and are as follows:
    •  app_name—The name of the application to initialize.
    •  exec_file—The DLL file to load, including its full path.
    •  text_dir—The path to the application’s message and UI text files.
    •  user_display—Set this parameter to PRO_B_TRUE if you want the interactive user to be able to see the application registered in the Creo Parametric User Interface and to see error messages if the application fails.
    The function outputs a handle to the loaded DLL in the form of a ProToolkitDllHandle. If the function fails to load the DLL, the function outputs information describing the failure and the application's user_initialize() function is called.
    Use the function ProToolkitTaskExecute() to call a properly designated function of the Creo TOOLKIT DLL library. You can pass arbitrary combinations of input arguments to the library function.
    Use the function ProToolkitDllUnload() to shutdown a Creo TOOLKIT DLL previously loaded by ProToolkitDllLoad(). The application's user_terminate() function is called.
    Use the function ProToolkitDllIdGet() to get a string representation of the DLL application. The string representation can be sent to other applications, which can use ProToolkitDllHandleGet() to obtain the Creo TOOLKIT DLL handle using this string representation. Pass NULL to the first argument of ProToolkitDllIdGet() to get the identifier for the calling application.
    Custom Creo TOOLKIT DLL Tasks for Creo Distributed Batch
    You can create a customized Creo Distributed Batch task by providing a Creo TOOLKIT DLL to be run by the Creo Distributed Batch service. The steps required to create and deploy a custom DLL task for Creo Distributed Batch are as follows:
    •  Compose the Creo TOOLKIT DLL containing a function that meets the criteria for a custom DLL task function. Refer to the Creating Creo TOOLKIT DLL Task Libraries section for the function signature. Use the standard Creo Distributed Batch arguments while coding the function. Refer to the Coding a Custom DLL Task Function section for more information on the arguments.
    •  Create a DLL registry file for Creo Distributed Batch. Refer to the Registry File for Custom DLL Tasks section for more information.
    •  Create a TTD (Task Type Definition) file specifying the Creo TOOLKIT DLL and the custom task function to be executed by the custom task. Refer to the TTD File Format for Custom DLL Tasks section for more information.
    Coding a Custom DLL Task Function
    Creo Distributed Batch provides the following input arguments to the custom DLL task function:
    Note
    All the input arguments are of the widestring data type.
    •  DBS_WORKING_DIRECTORY—Specifies the full path of the working directory for the Creo Distributed Batch service. It stores all thelog, inf, and output files generated during the execution of a custom task.
    •  DBS_CURRENT_OBJECT_NAME—Specifies the name of the object that will acted upon by the custom DLL task function.
    •  DBS_CURRENT_OBJECT_TYPE—Specifies the type of the object such as a 3D model, assembly, or drawing. The value of this argument will be a widestring containing an integer value of the type that matches with the values in the enumerated type ProMdlType.
    Creo Distributed Batch supplies any additional input arguments and their values, if they are listed in a TTD file, as <USER_DATA></USER_DATA> tags within the <TKFUNC></TKFUNC> node. Each user data tag is supplied as an independent argument.
    The custom DLL task function can influence the state of Creo Distributed Batch and the status of the task through one of the following output arguments. If an argument is not supplied, the current or default value is used.
    Note
    All the output arguments are of the widestring data type.
    •  DBS_CURRENT_OBJECT_NAME—Specifies the name of the generated object. This output informs Creo Distributed Batch that a model with this name should be used for other TTD entries that follow.
    •  DBS_CURRENT_OBJECT_TYPE—Specifies the type of the generated object such as a 3D model, assembly, or drawing. The value of this argument will be a widestring containing an integer value of the type that matches with the values in the enumerated type ProMdlType. This output informs Creo Distributed Batch that a model of this type should be used for other TTD entries that follow.
    •  DBS_IGNORE_FILE—By default, the Creo Distributed Batch service returns any file generated in the working directory, except for report type files such as log, inf and txt. The names of the files specified by this output argument will not be included in the output returned to the client. You can return more than one argument of this type.
    •  DBS_OUTPUT_FILE—Some file types such as log, inf and txt are not transferred to the Creo Distributed Batch client by default. File names specified by this output argument indicate that a particular file such as trail.txt should be passed back to the client. This file is always returned even if Creo Distributed Batch ignores it. This argument is not required for files returned by default. You can return more than one argument of this type.
    •  DBS_OUTPUT_DIRECTORY—Specifies the output directory containing all files except ones such as trail files or log files that are ignored by Creo Distributed Batch. This optional argument is required only if the contents of the output directory are different from the input working directory.
    •  DBS_MESSAGE—Specifies the user-visible message that will be printed in the log file generated by the custom DLL task function. This message is especially useful if the function returns an error.
    In case of chained TTD tasks (described in the TTD File Format for Custom DLL Tasks section), the output arguments generated by the first TTD containing the custom DLL task function are supplied as input arguments to the second TTD within the same file.
    The custom DLL task function should return one of the following types of errors:
    •  PRO_TK_NO_ERROR—Specifies that the task function executed successfully.
    •  PRO_TK_BAD_INPUTS—Specifies that the task function was called with incorrect input arguments.
    Registry File for Custom DLL Tasks
    Registering a custom Creo TOOLKIT DLL means providing information to the Creo Distributed Batch service about the files that form the DLL.
    An example of the registry file is as follows:
    name pt_userguide.dll
exec_file <creo_toolkit_loadpoint>/$<machine_type>/obj/pt_userguide.dll
text_dir <creo_toolkit_loadpoint>/protk_appls/pt_userguide/text
where:
<creo_toolkit_loadpoint> refers to the directory that forms the loadpoint of 
    Creo Parametric TOOLKIT under the Creo Parametric installation.
<machine_type> refers to the type of machine on which Creo Parametric 
    is installed. For example x86e_win64.
    The fields of the above registry file are described below:
    •  name—Specifies the name of the Creo TOOLKIT DLL to be used as the dllname attribute in the TTD file.
    •  exec_file—Specifies the full path to the DLL binary file on the service machine.
    •  text_dir—Specifies the directory containing language-specific directories that include the menu and message files used by the DLL.
    The registry file must be named dbatchs.dat The DLL registry file must be visible to the Creo Distributed Batch service on the service machine. To make it visible, place the dbatchs.dat file in the same location as the Creo Distributed Batch service executable dbatchs.exe available in the <creo_loadpoint>\<version>\Common Files\$<machine_type>\nms directory. More than one custom DLL can be listed in a given dbatchs.dat file.
    TTD File Format for Custom DLL Tasks
    TTD files serve as templates for all the common tasks that can be performed using Creo Distributed Batch. Refer to the Creo Distributed Batch Help for complete information about the nodes included in a TTD file.
    For a custom DLL task, specify the name of the Creo TOOLKIT DLL as the dllname attribute and the function ProToolkitTaskExecute() that causes Creo Parametric to execute the task function as the func attribute within the <TKFUNC></TKFUNC> node in a TTD file. Specify the name of the custom DLL task function in the <DLL_FUNCTION></DLL_FUNCTION> tag within the <TKFUNC></TKFUNC> node. You can also include the required <USER_DATA></USER_DATA> tags within the <TKFUNC></TKFUNC> node.
    Additionally, you can specify an existing Creo TOOLKIT function along with its input arguments and enumerated types within a <TKFUNC></TKFUNC> node. A TTD file containing multiple <TKFUNC></TKFUNC> nodes is called a chained TTD.
    Example 2: Chained TTD Task to convert a Creo Parametric model into a simplified representation in the VRML format
    Following is an example of a TTD file for a custom DLL task function.
    <TTD version="1.0" created_by="PTC"> 
    <DESCRIPTION>Load and call external DLL to change the
 current model to simprep</DESCRIPTION> 
    <DETAILS>Load an external Creo Parametric TOOLKIT DLL into the
 Creo Parametric session</DETAILS> 
    <SERVICE name="dbatchs"/> 
    <TKFUNC func="ProToolkitTaskExecute"
              dllname="pt_userguide.dll">
      <DLL_FUNCTION>TestSimprepActivateTask</DLL_FUNCTION>
      <USER_DATA name="SIMP_REP">NO_B</USER_DATA>
    </TKFUNC> 
    <!-- Export to VRML format -->
    <TKFUNC func="ProExportVRML">
    </TKFUNC>
</TTD>
    In the above simprep.ttd file, the function ProToolkitTaskExecute() executes the custom task function TestSimrepActivateTask defined in pt_userguide.dll. The function TestSimrepActivateTask converts a Creo Parametric model into a simplified representation. The name of the simplified representation to be created must be specified in the <USER_DATA></USER_DATA> tag.
    The activated simplified representation is converted into the VRML format by the second <TKFUNC></TKFUNC> node entry in the chained TTD task. This part of the execution is directly handled by Creo Distributed Batch.
    The C language code for the custom task function TestSimrepActivateTask used in the simprep.ttd file is present in the sample code in the file UgInterfaceExport.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_interface.
    Launching Synchronous J-Link Applications
    The functions described in this section allow Creo TOOLKIT API users to launch a synchronous J-Link application and call methods within it with user-specified arguments.
    The ability to launch and control a J-Link application by a Creo TOOLKIT API enables:
    •  Code reuse through the ability to create J-Link libraries that can be called from Creo TOOLKIT or other APIs.
    •  Creation of platform independent library routines.
    Functions Introduced:
  • ProJlinkApplicationStart()
    		•
  • ProJlinkTaskExecute()
    		•
  • ProJlinkApplicationStop()
    		•
    Use the function ProJlinkApplicationStart() to register and start a J-Link application. The input parameters of this function are similar to the fields of a registry file and are as follows:
    •  app_name—Assigns a unique name to this J-Link application.
    •  java_app_class—Specifies the fully qualified class and package name of the Java class that contains the J-Link application’s start and stop method.
    •  java_app_start—Specifies the start method of the program.
    •  java_app_stop—Specifies the stop method of the program.
    •  java_app_add_classpath—Specifies the locations of packages and classes that can be loaded when running a Java program. Can be NULL, if not needed
    •  text_dir —Specifies the application text path for menus and messages. Can be NULL if the application does not use menus or messages.
    •  user_display—Specifies whether to display the application in the Auxiliary Applications dialog box in Creo Parametric.
    The function provides the ProJlinkAppHandle handle to the J-Link application. If the start method throws an exception, the description of the exception is stored in the argument startup_exception.
    The function ProJlinkTaskExecute() calls a registered task in a J-Link application. The input parameters are:
    •  handle—Specifies the handle to the J-Link application.
    •  task_id—Specifies the task to be executed. The J-Link application should register the task using the J-Link method pfcSession.BaseSession.RegisterTask(). Refer to J-Link documentation for more information on the RegisterTask() method.
    •  input_args—Specifies the input arguments to be passed to the task.
    The output of this function is an array of arguments of type ProArgument. These arguments are returned by the J-Link task method.
    If the method throws an exception, the description of the exception is stored in the output argument exception.
    The function ProJlinkApplicationStop() stops the J-Link application specified by the ProJlinkAppHandle application handle. The function activates the application’s stop method.
    If the stop method throws an exception, the description of the exception is stored in the output argument exception.