Core: Utilities
This section describes the Creo TOOLKIT utility functions.
Configuration Options
Functions Introduced:
  • ProConfigoptionGet()
    		•
  • ProConfigoptSet()
    		•
  • ProConfigoptArrayGet()
    		•
  • ProDisplistInvalidate()
    		•
    The functions ProConfigoptionGet() and ProConfigoptSet() enable you to retrieve and set the current value for the specified configuration file option. Use the function ProConfigoptionGet() instead. The function ProConfigoptionGet() returns the value of configuration option as a ProPath object.
    To use ProConfigoptSet() on a configuration option that affects the display of Creo Parametric, you must call the function ProDisplistInvalidate() before you repaint the screen. This function makes sure Creo Parametric invalidates the two- or three-dimensional display list. The calling sequence of functions is as follows: 
        ProConfigoptSet (woption, value);
    ProMdlCurrentGet (&model);
    ProDisplistInvalidate (model)
    ProWindowRepaint (-1);
    The function ProConfigoptSet(), when applied to a multi string configuration option like "search_path", adds a new path entry into the session. It does not affect existing values. When applied to a single-valued configuration option, ProConfigoptSet() modifies the value of the configuration option.
    The function ProConfigoptArrayGet() retrieves the value of a specified configuration file option. The function returns an array of values assigned to the configuration file. It returns a single value if the configuration file option is not a multi-valued option.
    Registry File Data
    Functions Introduced:
  • ProToolkitApplExecPathGet()
    		•
  • ProToolkitApplTextPathGet()
    		•
    The function ProToolkitApplExecPathGet() returns the path to the Creo TOOLKIT executable file (exec_file) from the registry file.
    The function ProToolkitApplTextPathGet() returns the path to the directory containing the "text" directory for the application.
    Trail Files
    Function Introduced:
  • ProTrailfileCommentWrite()
    		•
    To append a comment to the end of the current trail file, call the function ProTrailfileCommentWrite(). The comment should not be longer than (PRO_COMMENT_SIZE - 2) characters, and should not contain any nonprintable characters, such as “\n.”
    License Data
    Function Introduced:
  • ProOptionOrderedVerify()
    		•
    The function ProOptionOrderedVerify() reports whether a specified Creo Parametric license option (such as Pro/MESH) is currently available in the Creo Parametric session.
    Current Directory
    Functions Introduced;
  • ProDirectoryCurrentGet()
    		•
  • ProDirectoryChange()
    		•
    These two functions are concerned with the current default directory in Creo Parametric—the one in which it searches when you retrieve an object, for example. The Creo Parametric user changes this directory using the command File ▶ Manage Session ▶ Working Directory.
    The function ProDirectoryChange() enables you to do the exact equivalent of File ▶ Manage Session ▶ Working Directory in Creo Parametric. Use this function if you need to save and retrieve objects in a directory other than the one the user chose.
    The function ProDirectoryCurrentGet() returns the whole path to the directory, as a wide string.
    File Handling
    Functions Introduced:
  • ProFilesList()
    		•
  • ProFileMdlnameOpen()
    		•
  • ProFileMdlfiletypeOpen()
    		•
  • ProFileOpenRegister()
    		•
  • ProFileMdlnameSave()
    		•
  • ProFileMdlfiletypeSave()
    		•
  • ProFileSaveRegister()
    		•
  • ProDirectoryChoose()
    		•
  • ProFileMdlnameParse()
    		•
  • ProPathMdlnameCreate()
    		•
  • ProInfoWindowDisplay()
    		•
  • ProFileEdit()
    		•
  • ProTexturePathGet()
    		•
    The function ProFilesList() provides a list of the contents of a directory, given the directory path. You can filter the list to include only files of a particular type, as specified by the file extension. Use the PRO_FILE_LIST_ALL option to include all versions of a file in the list; use PRO_FILE_LIST_LATEST to include only the latest version. In addition to an array of file names, the function returns an array of subdirectory names, regardless of the filter used.
    Starting with Pro/ENGINEER Wildfire 5.0, the function ProFilesList()can also list instance objects when accessing Windchill workspaces or folders. A PDM location (for workspace or commonspace) must be passed as the directory path. The following options have been added in the ProFileListOpt enumerated type that can be passed as the listing_option argument to ProFilesList():
    •  PRO_FILE_LIST_ALL_INST—Same as the LIST_ALL option. It returns instances only for PDM locations.
    •  PRO_FILE_LIST_LATEST_INST—Same as the LIST_LATEST option. It returns instances only for PDM locations.
    •  PRO_FILE_LIST_ALL_SORTED_INST—Same as the LIST_ALL_SORTED option. It returns instances only for PDM locations.
    •  PRO_FILE_LIST_LATEST_SORTED_INST—Same as the LIST_LATEST_SORTED option. It returns instances only for PDM locations.
    •  PRO_FILE_LIST_LATEST_SORTED_INST—Same as the LIST_LATEST_SORTED option. It returns instances only for PDM locations.
    The function ProFileMdlnameOpen() opens the dialog box to browse directories and open files. The function lets you specify the title of the dialog box, a set of shortcuts to other directories, and the name of a file to be preselected. This function uses the same filtering method as ProFilesList(). You can set a filter in the dialog box to include files of a particular type. In the input argument filter_string specify all types of files extensions with wildcards separated by commas, for example, *.prt, *.asm, *.txt, *.avi, and so on.
    You can also use the function ProFileMdlfiletypeOpen() to browse directories and open files. You can set a filter in the dialog box to include files of a particular type. In the input argument file_types, you can specify an array of file types using the enumerated data type ProMdlfileType.
    Note
    The functions ProFileMdlnameOpen() and ProFileMdlfiletypeOpen() do not actually open the file, but return the file path of the selected file. For example, to open a text file, use the function ProFileEdit() or ProInfoWindowDisplay().
    The function ProFileOpenRegister() registers a new file type in the File ▶ Open dialog box in Creo Parametric. This function takes the access function ProFileOpenAccessFunction() and the action function ProFileOpenOperationAction() as its input arguments.
    The function ProFileOpenAccessFunction() is called to determine whether the new file type can be opened using the File ▶ Open dialog box. The function ProFileOpenOperationAction() is called on clicking Open for the newly registered file type.
    The function ProFileMdlnameSave() opens the save dialog box. This function has input arguments similar to ProFileMdlnameOpen().
    You can also use the function ProFileMdlfiletypeSave() to open the save dialog box. You can set a filter in the dialog box to include files of a particular type. In the input argument file_types, you can specify an array of file types using the enumerated data type ProMdlfileType.
    Note
    •  The functions ProFileMdlnameSave() and ProFileMdlfiletypeSave() do not actually save the file, but return the file path of the selected file.
    •  For multi-CAD models, in a linked session of Creo Parametric with Windchill, the functions ProFileMdlnameSave() and ProFileMdlfiletypeSave() do not support a file path location on local disk.
    The function ProFileSaveRegister() registers a new file type in the File ▶ Save a Copy dialog box in Creo Parametric. This function takes the access function ProFileSaveAccessFunction() and the action function ProFileSaveOperationAction() as its input arguments.
    The function ProFileSaveAccessFunction() is called to determine whether the new file type can be saved using the File ▶ Save a Copy dialog box. The function ProFileSaveOperationAction() is called on clicking OK for the newly registered file type.
    The function ProDirectoryChoose() prompts the user to select a directory using the Creo Parametric dialog box for browsing directories. Specify the title of the dialog box, a set of shortcuts to other directories, and the default directory path to start browsing. If the default path is specified as null, the current directory is used. The function returns the selected directory path as output.
    In general, the file utility functions refer to files using a single wide character string, which contains four, distinct pieces of information that uniquely identify the file: the directory path, file name, extension, and version. The function ProFileMdlnameParse() takes such a string as input, and returns the four segments as separate arguments.
    Note
    The function ProFileMdlnameParse() returns the file version as -1, if the input argument file_name_w_path has the path specified as the path to a Windchill model. This function does not support fetching of model version of a Windchill model.
    The function ProPathMdlnameCreate() performs the opposite operation—it builds the single wide string that identifies the file, given the path, file name, extension, and version.
    The function ProInfoWindowDisplay() creates a text information window. It reads the contents from a text file in the current directory whose name is an input to the function. The function can also override the default size, shape, and location of the window. (These do not affect the properties of the Creo Parametric Information Window.)
    The function ProFileEdit() opens an edit window on a specified text file. The editor used is the current default editor for Creo Parametric.
    The function ProTexturePathGet() looks for the full path to the specified texture, decal, or bump map files and loads them from the texture path.
    Note
    For textures embedded inside a Creo Parametric model, if the create_temp_file is set to true the ProTexturePathGet() function writes a temporary copy of the specified files.
    Wide Strings
    Functions Introduced:
  • ProStringToWstring()
    		•
  • ProWstringToString()
    		•
  • ProWcharSizeVerify()
    		•
    These three utilities are described in the section Wide Strings in the Fundamentals section.
    Freeing String Outputs
    Many Creo TOOLKIT functions provide outputs of non-fixed length strings or wide strings. These outputs must be freed using a special set of functions, because they have been allocated by a special function internally.
    Note
    These functions must be only used for strings and string arrays output from Creo TOOLKIT functions. Check the function description to determine the function to use when freeing the output.
    Functions Introduced:
  • ProStringFree()
    		•
  • ProWstringFree()
    		•
  • ProStringarrayFree()
    		•
  • ProWstringarrayFree()
    		•
  • ProStringproarrayFree()
    		•
  • ProWstringproarrayFree()
    		•
    Use the functions ProStringFree() and ProWstringFree() to free a single char* or wchar_t* output from a Creo TOOLKIT function.
    Use the functions ProStringarrayFree() and ProWstringarrayFree() to free a standard array of char* or wchar_t* output from a Creo TOOLKIT function.
    Use the functions ProStringproarrayFree() and ProWstringproarrayFree() to free a ProArray of char* or wchar_t* output from a Creo TOOLKIT function.
    Freeing Integer Outputs
    Functions Introduced:
  • ProIntarrayFree()
    		•
    Use the function ProIntarrayFree() to free a plain integer array, which has been returned from a Creo TOOLKIT function.
    Running Creo ModelCHECK
    Creo ModelCHECK is an integrated application that runs transparently within Creo Parametric. Creo ModelCHECK uses a configurable list of company design standards and best modeling practices. You can configure Creo ModelCHECK to run interactively or automatically when you regenerate or save a model.
    Functions Introduced:
  • ProModelcheckExecute()
    		•
    You can execute Creo ModelCHECK from an external application using the function ProModelcheckExecute(). The input parameters of this function are:
    •  mdl—Specifies the model on which you want to execute Creo ModelCHECK.
    •  show_ui—Specifies True to display the Creo ModelCHECK report in the Web browser.
    Note
    The configuration option SHOW_REPORT in the config_init.mc file overrides the show_ui value.
    •  mcMode—Specifies the mode in which you want to run Creo ModelCHECK. The modes are:
    ○  PRO_MODELCHECK_GRAPHICS—Interactive mode
    ○  PRO_MODELCHECK_NO_GRAPHICS—Batch mode
    •  config_dir—Specifies the location of the configuration files. If this parameter is set to NULL, the default Creo ModelCHECK configuration files are used.
    •  output_dir—Specifies a location for the reports. If this parameter is set to NULL, the default Creo ModelCHECK output directory is used.
    The output parameters of this function are:
    •  errors—Specifies the number of errors found.
    •  warnings—Specifies the number of warnings found.
    •  model_saved—True if the model is saved with updates, else false.
    Creating Custom Checks
    This section describes how to define custom checks in Creo ModelCHECK that users can run using the standard Creo ModelCHECK interface in Creo Parametric.
    To define and register a custom check:
    1. Set the CUSTMTK_CHECKS_FILE configuration option in the start configuration file to a text file that stores the check definition. For example:
    CUSTMTK_CHECKS_FILE text/custmtk_checks.txt.
    2. Set the contents of the CUSTMTK_CHECKS_FILE file to define the checks. Each check should list the following items:
    •  DEF_<checkname>—Specifies the name of the check. The format must be CHKTK_<checkname>_<mode>, where mode is PRT, ASM, or DRW.
    •  TAB_<checkname>—Specifies the tab (category) in the Creo ModelCHECK report under which the check is classified. All the custom checks are stored in the Miscellaneous category.
    •  MSG_<checkname>—Specifies the description of the check that appears in the lower part of the Creo ModelCHECK report when you select the name.
    •  DSC_<checkname>—Specifies the name of the check as it appears in the Creo ModelCHECK report table.
    •  ERM_<checkname>—If set to INFO, the check is considered an INFO check and the report table will display the text from the first item returned by the check, instead of a count of the items. Otherwise, this value must be included, but is ignored by Creo Parametric.
    See Example 1: Text File for Custom Checks for a sample custom checks text file.
    1. Add the check and its values to the Creo ModelCHECK configuration file. For an example of how this is done, see the sample code at the end of this section.
    2. Register the Creo ModelCHECK check from the Creo TOOLKIT application.
    Note
    Other than the requirements listed above, Creo TOOLKIT custom checks do not have access to the rest of the values in the Creo ModelCHECK configuration files. All the custom settings specific to the check such as start parameters, constants, and so on, must be supported by the user application and not Creo ModelCHECK. In the custom checks text file, separate options and values for options with a space, not by a tab character.
    Functions Introduced
  • ProModelcheckCheckRegister()
    		•
  • ProModelcheckCheckFunction()
    		•
  • ProModelcheckUpdateFunction()
    		•
  • ProModelcheckCleanupFunction()
    		•
    The function ProModelcheckCheckRegister() registers the callback functions for each custom check. The following arguments are available:
    •  The custom check name. This name must match the name given to the check in the Creo ModelCHECK configuration file, and must begin with "CHKTK_".
    •  The check label. Currently unused; the label is taken from the check configuration file.
    •  The check options. Currenlty unused, specify the value as NULL.
    •  The check callback functions, described in details below.
    •  Labels for the action and update buttons, or specify NULL if these buttons should not be shown.
    •  Application data to pass to the callback functions.
    The check callback functions are as follows:
    •  The check function (required)—This function, whose signature matches ProModelcheckCheckFunction(), should calculate the results of the check and provide them to Creo ModelCHECK through the function output arguments.
    •  The action and update functions (optional)—These functions are called when users choose the action or update button when viewing the Creo ModelCHECK report. These have the signature of the ProModelcheckUpdateFunction() function.
    •  The cleanup function (optional)—Gives your application a chance to free memory allocated by the check function. This has the signature of the ProModelcheckCleanupFunction() function.
    Each callback function receives the following inputs:
    •  The name of the custom check, as defined in the original call to ProModelcheckCheckRegister().
    •  The model being checked.
    •  A pointer to the application data, set during the call to ProModelcheckCheckRegister().
    The function whose prototype matches ProModelcheckCheckFunction() is used to evaluate the custom defined checks. The user application runs the check on the specified model and populates the following output arguments:
    •  results_count—Specifies an integer indicating the number of errors found by the check.
    •  results_url—Specifies the link to an application-owned page that contains information specific to the check.
    •  results_table—Specifies an array of data for each error encountered that will be shown along with the results.
    The function whose prototype matches ProModelcheckCleanupFunction() is used to release memory allocated for the check callback function.
    The functions whose prototypes matches ProModelcheckUpdateFunction() are used for the following:
    •  To execute a check-defined action on a given item.
    •  To automatically update a given item to fix errors, if any.
    The selected item’s description string is passed as an argument to the update function.
    Creo ModelCHECK checks may have one "action" function to highlight the problem, and possibly an update function, to fix it automatically. The following figure displays the Creo ModelCHECK report with an action button that invokes the action callback function.
    Example 1: Text File for Custom Checks
    The following is the text file for the custom check examples.
      UG CustomCheck: MDL PARAM NOT FOUND
  Parameter %0w is not found in the model %1w
  #
  #
  UG CustomCheck: MDL PARAM OK
  Parameter %0w is set correctly in the model %1w
  #
  #
  UG CustomCheck: MDL PARAM INV TYPE
  Parameter %0w in %1w is not a String parameter
  #
  #
  Parameter %0w value does not match model name %1w  
                   UG CustomCheck: MDL PARAM INCORRECT
  #
  #
  UG CustomCheck: MDL PARAM NAME
  Parameter %0w value matches model name
  #
  #
  UG CustomCheckUpdate: MDL PARAM NAME
  Fix Parameter
  #
  #
  %CIUG CustomCheck: MDL PARAM UPDATED
  Mdl name parameter %0w has been updated.
  #
  #
  %CEUG CustomCheck: MDL PARAM UPDATE TYPE
  Cannot modify the type of parameter %0w; this error should be fixed
  manually.
  #
  #
  UG CustomCheck: MDL ACC TYPE
  Model accuracy
  #
  #
  UG CustomCheck: MDL ACC ABS
  Absolute Accuracy
  #
  #
  UG CustomCheck: MDL ACC REL
  Relative Accuracy
  #
  #
  UG CustomCheck: DWGVIEW GENERIC
  Drawing Views using Generics
  #
  #
  UG CustomCheckAction: DWGVIEW GENERIC
  Highlight
  #
  #
    Example 2: Registering Custom Creo ModelCheck Checks
    The sample code in UgModelCheck.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_main shows how to register custom Creo ModelCHECK checks using Creo TOOLKIT. The following custom checks are registered:
    •  CHKTK_MDL_NAME_PARAM—Determines if the model has a parameter whose value is equal to the model name
    •  CHKTK_MDL_REFC_SCOPE—Info check that prints the model reference control settings
    •  CHKTK_DWVIEW_GENERIC—Drawing mode check that looks for views that use generic models
    Example 3: Implementing a Model Name Parameter Check
    The sample code in UgModelCheck.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_main shows the implementation for the model name parameter check. This check has a check function callback and an update function callback. Also included is the cleanup callback used for all of the custom checks.
    Example 4: Implementing a Reference Control Info Check
    The sample code UgModelCheck.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_main shows the implementation for an info check that will report on the reference control setting applied to the model. This check has a check function callback but no action or update function (because it is an info-only check).
    Example 5: Implementing a Check Looking for Drawing Views Using Generics
    The sample code in UgModelCheck.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_main shows the implementation for the drawing view using generics check. This check has a check function callback and an action function used to highlight the views that have this error.
    Example 6: Changes to the Creo ModelCheck Configuration Files to enable Custom Checks
    The following show the changes made to the Creo ModelCHECK configuration files to enable the custom checks. 
      Lines from the custom TK checks file (custmtk_checks.txt)
  # Custom TK Check File
  #
  # UG_MDLPARAM_NAME 
  DEF_UG_MDLPARAM_NAME CHKTK_UG_MDLPARAM_NAME_PRT
  TAB_UG_MDLPARAM_NAME PARAMETER
  MSG_UG_MDLPARAM_NAME Pro/TOOLKIT: Models with missing or invalid model
  name parameters: 
  ERM_UG_MDLPARAM_NAME  N/A
  DSC_UG_MDLPARAM_NAME Pro/TOOLKIT: Model Name Parameter
  # UG_MDL_REFC_SCOPE
  DEF_UG_MDL_REFC_SCOPE 
  CHKTK_UG_MDL_REFC_SCOPE_PRT
  TAB_UG_MDL_REFC_SCOPE INFO
  MSG_UG_MDL_REFC_SCOPE Pro/TOOLKIT: Model reference control scope: 
  ERM_UG_MDL_REFC_SCOPE INFO
  DSC_UG_MDL_REFC_SCOPE Pro/TOOLKIT: Model reference control scope:
  # UG_DWGVIEW_GENERIC 
  DEF_UG_DWGVIEW_GENERIC CHKTK_UG_DWGVIEW_GENERIC_DRW
  TAB_UG_DWGVIEW_GENERIC VIEWS
  MSG_UG_DWGVIEW_GENERIC Pro/TOOLKIT: Drawing views containing generic 
  models:
  ERM_UG_DWGVIEW_GENERIC N/A
  DSC_UG_DWGVIEW_GENERIC Pro/TOOLKIT: Drawing Views using Generics
  Lines added to the ModelCheck configuration file (default_checks.mch)
  CHKTK_UG_MDLPARAM_NAME_PRT      YNEW        E  E  E  E  Y
  CHKTK_UG_MDL_REFC_SCOPE_PRT     YNEW        Y  Y  Y  Y  Y
  CHKTK_UG_DWGVIEW_GENERIC_DRW    YNEW        E  E  E  E  Y
  Lines added to the ModelCheck start file (nostart.mcs)
  CUSTMTK_CHECKS_FILE    text/custmtk_checks.txt