Session Objects
This section describes how to program on the session level using Web.Link.
Overview of Session Objects
The Creo Parametric Session object (contained in the class pfcSession) is the highest level object in Web.Link . Any program that accesses data from Creo Parametric must first get a handle to the pfcSession object before accessing more specific data.
The pfcSession object contains methods to perform the following operations:
•  Accessing models and windows (described in the Models and Windows chapters).
•  Working with the Creo Parametric user interface.
•  Allowing interactive selection of items within the session.
•  Accessing global settings such as line styles, colors, and configuration options.
The following sections describe these operations in detail.
Getting the Session Object
Method Introduced:
  • MpfcSession.GetCurrentSession
    		•
  • MpfcSession.GetCurrentSessionWithCompatibility
    		•
    For every application, Creo assigns a unique session. The session contains license information, the compatibility information as a pfcCreoCompatibility object, and other additional data of the application. When a session is assigned to an application, Creo sets the compatibility to CompatibilityUndefined in the associated pfcAppInfo object. You must set the compatibility of the application before working with sessions. To set the compatibility, call the method MpfcSession.GetCurrentSessionWithCompatibility(). Use the values defined in the enumerated data type pfcCreoCompatibility to set the compatibility of the application. See Compatibility of Deprecated Methods for more information on compatibility and AppInfo object. Use the method MpfcSession.GetCurrentSession() to get the current pfcSession object in synchronous mode. If the compatibility is not set, the method throws the exception pfcXCompatibilityNotSet.
    The method MpfcCOMGlobal.GetProESession() is deprecated. Use the method MpfcSession.GetCurrentSession instead. MpfcSession.GetCurrentSession also gets the pfcSession object. If you call this method without setting the compatibility, the method sets the compatibility to C3Compatible. This setting ensures forward compatibility of the Creo applications. If you set a specific compatibility using the method MpfcSession.GetCurrentSessionWithCompatibility(), and call the method MpfcSession.GetCurrentSession then all calls to MpfcSession.GetCurrentSession return the session with the set compatibility.
    Note
    You can make multiple calls to this method, but each call gives you a handle to the same object.
    Getting Session Information
    Methods Introduced:
  • MpfcCOMGlobal.GetProEArguments()
    		•
  • MpfcCOMGlobal.GetProEVersion()
    		•
  • MpfcCOMGlobal.GetProEBuildCode()
    		•
    The method MpfcCOMGlobal.GetProEArguments() returns an array containing the command line arguments passed to Creo Parametric if these arguments follow one of two formats:
    •  Any argument starting with a plus sign (+) followed by a letter character.
    •  Any argument starting with a minus (-) followed by a capitalized letter.
    The first argument passed in the array is the full path to the Creo Parametric executable.
    The method MpfcCOMGlobal.GetProEVersion() returns a string that represent the Creo Parametric version, for example “Wildfire”.
    The method MpfcCOMGlobal.GetProEBuildCode() returns a string that represents the build code of the Creo Parametric session.
    Note
    The preceding methods can only access information in synchronous mode.
    Example: Accessing the Creo Parametric Command Line Arguments
    The sample code in the file pfcProEArgumentsExample.js located at <creo_weblink_loadpoint>/weblinkexamples/jscript describes the use of the GetProEArguments method to access the Creo Parametric command line arguments. The first argument is always the full path to the Creo Parametric executable. For this application the next two arguments can be either ("+runtime" or "+development") or ("-Unix" or "-NT"). Based on these values 2 boolean variables are set and passed on to another method which makes use of this information.
    Compatibility of Deprecated Methods
    In a release cycle, some methods are deprecated, and new methods are added. The deprecated methods are supported in the current release, and then obsoleted in a future release. You can either choose to let the deprecated methods work in the current release, or allow only new methods to work. Use the methods explained in this section along with the compatibility value to work with either deprecated or new methods for the current release.
    Methods Introduced:
  • pfcAppInfo.GetCompatibility()
    		•
  • pfcAppInfo.SetCompatibility()
    		•
  • pfcAppInfo.Create()
    		•
  • pfcSession.GetAppInfo()
    		•
  • pfcSession.SetAppInfo()
    		•
    The methods pfcAppInfo.GetCompatibility() and pfcAppInfo.SetCompatibility() get and set the compatibility value for the specified application using the enumerated data type pfcCreoCompatibility. The valid values are:
    •  CompatibilityUndefined—Specifies that compatibility value is not set. The default compatibility value is used.
    •  C3Compatible—Specifies that the methods deprecated in Web.Link 4.0 are compatible and continue working in Web.Link 4.0. By default the compatibility is set to C3Compatible.
    •  C4Compatible—Specifies that the methods deprecated in Web.Link 4.0 will not work in Web.Link 4.0. If your application uses the deprecated methods, you must replace these methods with new methods and rebuild you applications.
    Note
    If you rebuild or run Web.Link applications from previous releases in the current release, the compatibility is set C3Compatible to current release. For example, if you rebuild a Web.Link 3.0 application in release 4.0, the compatibility is set to C3Compatible. To set the compatibility to the current release, use the method pfcAppInfo.SetCompatibility().
    The method pfcAppInfo.Create() creates a new instance of the pfcAppInfo object.
    The methods pfcSession.GetAppInfo() and pfcSession.SetAppInfo() get and set the information for an application in terms of their compatibility value as a pfcSession.SetAppInfo() object.
    Directories
    Methods Introduced:
  • pfcBaseSession.GetCurrentDirectory()
    		•
  • pfcBaseSession.ChangeDirectory()
    		•
    The method pfcBaseSession.GetCurrentDirectory() returns the absolute path name for the current working directory of Creo Parametric.
    The method pfcBaseSession.ChangeDirectory() changes Creo Parametric to another working directory.
    File Handling
    Methods Introduced:
  • pfcBaseSession.ListFiles()
    		•
  • pfcBaseSession.ListSubdirectories()
    		•
    The method pfcBaseSession.ListFiles() returns a list of files in 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.
    Starting with Pro/ENGINEER Wildfire 5.0 M040, the method pfcBaseSession.ListFiles() 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 pfcFileListOpt enumerated type:
    •  FILE_LIST_ALL—Lists all the files. It may also include multiple versions of the same file.
    •  FILE_LIST_LATEST—Lists only the latest version of each file.
    •  FILE_LIST_ALL_INST—Same as the FILE_LIST_ALL option. It returns instances only for PDM locations.
    •  FILE_LIST_LATEST_INST—Same as the FILE_LIST_LATEST option. It returns instances only for PDM locations.
    The method pfcBaseSession.ListSubdirectories() returns the subdirectories in a given directory location.
    Configuration Options
    Methods Introduced:
  • pfcBaseSession.GetConfigOptionValues()
    		•
  • pfcBaseSession.SetConfigOption()
    		•
  • pfcBaseSession.LoadConfigFile()
    		•
    You can access configuration options programmatically using the methods described in this section.
    Use the method pfcBaseSession.GetConfigOptionValues() to retrieve the value of a specified configuration file option. Pass the Name of the configuration file option as the input to this method. The method returns an array of values that the configuration file option is set to. It returns a single value if the configuration file option is not a multi-valued option. The method returns a null if the specified configuration file option does not exist.
    The method pfcBaseSession.SetConfigOption() is used to set the value of a specified configuration file option. If the option is a multi-value option, it adds a new value to the array of values that already exist.
    The method pfcBaseSession.LoadConfigFile() loads an entire configuration file into Creo Parametric.
    Macros
    Method Introduced:
  • pfcBaseSession.RunMacro()
    		•
    The method pfcBaseSession.RunMacro() runs a macro string. A Web.Link macro string is equivalent to a Creo Parametric mapkey minus the key sequence and the mapkey name. To generate a macro string, create a mapkey in Creo Parametric. Refer to the Creo Parametric online help for more information about creating a mapkey.
    Copy the Value of the generated mapkey Option from the Tools ▶ Options dialog box. An example Value is as follows: 
    $F2 @MAPKEY_LABELtest;
~ Activate `main_dlg_cur` `ProCmdModelNew.file`;
~ Activate `new` `OK`;
    The key sequence is $F2. The mapkey name is @MAPKEY_LABELtest. The remainder of the string following the first semicolon is the macro string that should be passed to the method pfcBaseSession.RunMacro().
    In this case, it is as follows:
    ~ Activate `main_dlg_cur` `ProCmdModelNew.file`;
~ Activate `new` `OK`;
    Note
    Creating or editing the macro string manually is not supported as the mapkeys are not a supported scripting language. The syntax is not defined for users and is not guaranteed to remain constant across different versions of Creo Parametric.
    Macros are executed from synchronous mode only when control returns to Creo Parametric from the program. Macros are stored in reverse order (last in, first out).
    Colors and Line Styles
    Methods Introduced:
  • pfcBaseSession.SetStdColorFromRGB()
    		•
  • pfcBaseSession.GetRGBFromStdColor()
    		•
  • pfcBaseSession.SetTextColor()
    		•
  • pfcBaseSession.SetLineStyle()
    		•
    These methods control the general display of a Creo Parametric session.
    Use the method pfcBaseSession.SetStdColorFromRGB() to customize any of the Creo Parametric standard colors.
    To change the color of any text in the window, use the method pfcBaseSession.SetTextColor().
    To change the appearance of nonsolid lines (for example, datums) use the method pfcBaseSession.SetLineStyle().
    Accessing the Creo Parametric Interface
    The pfcSession object has methods that work with the Creo Parametric interface. These methods provide access to the message window.
    The Text Message File
    A text message file is where you define strings that are displayed in the Creo Parametric user interface. This includes the strings on the command buttons that you add to the Creo Parametric number, the help string that displays when the user’s cursor is positioned over such a command button, and text strings that you display in the Message Window. You have the option of including a translation for each string in the text message file.
    Note
    Remember that Web.Link applications, as unregistered web pages, do not currently support setting of the Creo Parametric text directory. All the resource files for messages must be located under $PRO_DIRECTORY/text folder. You can force Creo Parametric to load a message file by registering a Creo TOOLKIT or J-Link application via the web page, and calling a function or method that requires the message file. Once the file has been loaded by Creo Parametric, Web.Link applications may use any of its keystrings for displaying messages in the message window.
    Restrictions on the Text Message File
    You must observe the following restrictions when you name your message file:
    •  The name of the file must be 30 characters or less, including the extension.
    •  The name of the file must contain lower case characters only.
    •  The file extension must be three characters.
    •  The version number must be in the range 1 to 9999.
    •  All message file names must be unique, and all message key strings must be unique across all applications that run with Creo Parametric. Duplicate message file names or message key strings can cause Creo Parametric to exhibit unexpected behavior. To avoid conflicts with the names of Creo Parametric or foreign application message files or message key strings, PTC recommends that you choose a prefix unique to your application, and prepend that prefix to each message file name and each message key string corresponding to that application
    Note
    Message files are loaded into Creo Parametric only once during a session. If you make a change to the message file while Creo Parametric is running you must exit and restart Creo Parametric before the change will take effect.
    Contents of the Message File
    The message file consists of groups of four lines, one group for each message you want to write. The four lines are as follows:
    1. A string that acts as the identifier for the message. This keyword must be unique for all Creo Parametric messages.
    2. The string that will be substituted for the identifier.
    This string can include placeholders for run-time information stored in a stringseq object (shown in Writing Messages to the Message Window).
    3. The translation of the message into another language (can be blank).
    4. An intentionally blank line reserved for future extensions.
    Writing a Message Using a Message Pop-up Dialog Box
    Method Introduced:
  • pfcSession.UIShowMessageDialog()
    		•
    The method pfcSession.UIShowMessageDialog() displays the UI message dialog. The input arguments to the method are:
    •  Message—The message text to be displayed in the dialog.
    •  Options—An instance of the pfcMessageDialogOptions containing other options for the resulting displayed message. If this is not supplied, the dialog will show a default message dialog with an Info classification and an OK button. If this is not to be null, create an instance of this options type with pfcMessageDialogOptions.Create(). You can set the following options:
    ○  Buttons—Specifies an array of buttons to include in the dialog. If not supplied, the dialog will include only the OK button. Use the method pfcMessageDialogOptions.Buttons to set this option.
    ○  DefaultButton—Specifies the identifier of the default button for the dialog box. This must match one of the available buttons. Use the method pfcMessageDialogOptions.DefaultButton to set this option.
    ○  DialogLabel—The text to display as the title of the dialog box. If not supplied, the label will be the english string Info. Use the method pfcMessageDialogOptions.DialogLabel to set this option.
    ○  MessageDialogType—The type of icon to be displayed with the dialog box (Info, Prompt, Warning, or Error). If not supplied, an Info icon is used. Use the method pfcMessageDialogOptions.MessageDialogType to set this option.
    Accessing the Message Window
    The following sections describe how to access the message window using Web.Link. The topics are as follows:
    •  Writing Messages to the Message Window
    •  Writing Messages to an Internal Buffer
    Writing Messages to the Message Window
    Methods Introduced:
  • pfcSession.UIDisplayMessage()
    		•
  • pfcSession.UIDisplayLocalizedMessage()
    		•
  • pfcSession.UIClearMessage()
    		•
    These methods enable you to display program information on the screen.
    The input arguments to the methods pfcSession.UIDisplayMessage() and pfcSession.UIDisplayLocalizedMessage() include the names of the message file, a message identifier, and (optionally) a stringseq object that contains upto 10 pieces of run-time information. For pfcSession.UIDisplayMessage(), the strings in the stringseq are identified as %0s, %1s, ... %9s based on their location in the sequence. For pfcSession.UIDisplayLocalizedMessage(), the strings in the stringseq are identified as %0w, %1w, ... %9w based on their location in the sequence. To include other types of run-time data (such as integers or reals) you must first convert the data to strings and store it in the string sequence.
    Writing Messages to an Internal Buffer
    Methods Introduced:
  • pfcBaseSession.GetMessageContents()
    		•
  • pfcBaseSession.GetLocalizedMessageContents
    		•
    The methods pfcBaseSession.GetMessageContents() and pfcBaseSession.GetLocalizedMessageContents enable you to write a message to an internal buffer instead of the Creo Parametric message area.
    These methods take the same input arguments and perform exactly the same argument substitution and translation as the pfcSession.UIDisplayMessage() and pfcBaseSession.GetLocalizedMessageContents methods described in the previous section.
    Message Classification
    Messages displayed in Web.Link include a symbol that identifies the message type. Every message type is identified by a classification that begins with the characters %C. A message classification requires that the message key line (line one in the message file) must be preceded by the classification code.
    Note
    Any message key string used in the code should not contain the classification.
    Web.Link applications can now display any or all of the following message symbols:
    •  Prompt—This Web.Link message is preceded by a green arrow. The user must respond to this message type. Responding includes, specifying input information, accepting the default value offered, or canceling the application. If no action is taken, the progress of the application is halted. A response may either be textual or a selection. The classification for Prompt messages is %CP
    •  Info—This Web.Link message is preceded by a blue dot. Info message types contain information such as user requests or feedback from Web.Link or Creo Parametric. The classification for Info messages is %CI
    Note
    Do not classify messages that display information regarding problems with an operation or process as Info. These types of messages must be classified as Warnings.
    •  Warning—This Web.Link message is preceded by a triangle containing an exclamation point. Warning message types contain information to alert users to situations that could potentially lead to an error during a later stage of the process. Examples of warnings could be a process restriction or a suspected data problem. A Warning will not prevent or interrupt a process. Also, a Warning should not be used to indicate a failed operation. Warnings must only caution a user that the completed operation may not have been performed in a completely desirable way. The classification for Warning messages is %CW
    •  Error—This Web.Link message is preceded by a a broken square. An Error message informs the user that a required task was not completed successfully. Depending on the application, a failed task may or may not require intervention or correction before work can continue. Whenever possible redress this situation by providing a path. The classification for Error messages is %CE
    •  Critical—This Web.Link message is preceded by a red X. A Critical message type informs the user of an extremely serious situation that is usually preceeded by loss of user data. Options redressing this situation, if available, should be provided within the message. The classification for a Critical messages is %CC
    Example Code: Writing a Message
    The sample code in the file located at demonstrates how to write a message to the message window. The program uses the message file mymessages.txt.
    Reading Data from the Message Window
    Methods Introduced:
  • pfcSession.UIReadIntMessage()
    		•
  • pfcSession.UIReadRealMessage()
    		•
  • pfcSession.UIReadStringMessage()
    		•
    These methods enable a program to get data from the user. The methods obtain keyboard input from a text box in the Creo Parametric user interface.
    Note
    When the user presses Esc or clicks Cancel in the Creo Parametric user interface, these methods throw the exception PFCXToolkitMsgUserQuit.
    The pfcSession.UIReadIntMessage() and pfcSession.UIReadRealMessage() methods contain optional arguments that can be used to limit the value of the data to a certain range.
    The method pfcSession.UIReadStringMessage() includes an optional Boolean argument that specifies whether to echo characters entered onto the screen. You would use this argument when prompting a user to enter a password.
    Note
    A default value is displayed in the text box as input. When user presses the Enter key as input in the user interface, the default value is not passed to the Web.Link method; instead, the method returns a constant string use_default_string. When this string is returned, the application must interpret that the user wants to use the default value.
    Displaying Feature Parameters
    Method Introduced:
  • pfcSession.UIDisplayFeatureParams
    		•
    The method pfcSession.UIDisplayFeatureParams() forces Creo Parametric to show dimensions or other parameters stored on a specific feature. The displayed dimensions may then be interactively selected by the user.
    File Dialogs
    Methods Introduced:
  • pfcSession.UIOpenFile()
    		•
  • pfcFileOpenOptions.Create()
    		•
  • pfcFileOpenOptions.FilterString
    		•
  • pfcFileOpenOptions.PreselectedItem
    		•
  • pfcFileUIOptions.DefaultPath
    		•
  • pfcFileUIOptions.DialogLabel
    		•
  • pfcFileUIOptions.Shortcuts
    		•
  • pfcFileOpenShortcut.Create()
    		•
  • pfcFileOpenShortcut.ShortcutName
    		•
  • pfcFileOpenShortcut.ShortcutPath
    		•
  • pfcSession.UISaveFile()
    		•
  • pfcFileSaveOptions.Create()
    		•
  • pfcSession.UISelectDirectory()
    		•
  • pfcDirectorySelectionOptions.Create()
    		•
    The method pfcSession.UIOpenFile() opens the relevant dialog box for browsing directories and opening files. The method lets you specify several options through the input arguments pfcFileOpenOptions and pfcFileUIOptions.
    Use the method pfcFileOpenOptions.Create() to create a new instance of the pfcFileOpenOptions object. This object contains the following options:
    •  FilterString—Specifies the filter string for the type of file accepted by the dialog box. Multiple file types should be listed with wildcards and separated by commas, for example, *.prt, *.asm, *.txt, *.avi, and so on. Use the property pfcFileOpenOptions.FilterString to set this option.
    •  PreselectedItem—Specifies the name of an item to preselect in the dialog box. Use the property pfcFileOpenOptions.PreselectedItem to set this option.
    The pfcFileUIOptions object contains the following options:
    •  DefaultPath—Specifies the name of the path to be opened by default in the dialog box. Use the property pfcFileUIOptions.DefaultPath to set this option.
    •  DialogLabel—Specifies the title of the dialog box. Use the property pfcFileUIOptions.DialogLabel to set this option.
    •  Shortcuts—Specifies an array of file shortcuts of the type pfcFileOpenShortcut. Create this object using the method pfcFileOpenShortcut.Create(). This object contains the following attributes:
    ○  ShortcutName—Specifies the name of shortcut path to be made available in the dialog box.
    ○  ShortcutPath—Specifies the string for the shortcut path.
    Use the property pfcFileUIOptions.Shortcuts to set the array of file shortcuts.
    The method pfcSession.UIOpenFile() returns the file selected by you. The application must use other methods or techniques to perform the desired action on the file.
    The method pfcSession.UISaveFile() opens the relevant dialog box for saving a file. The method accepts options similar to pfcSession.UIOpenFile() through the PFCFileSaveOptions and pfcFileUIOptions objects. Use the method pfcFileSaveOptions.Create() to create a new instance of the pfcFileSaveOptions object. When using the Save dialog box, you can set the name to a non-existent file. The method pfcSession.UISaveFile() returns the name of the file selected by you; the application must use other methods or techniques to perform the desired action on the file.
    The method pfcSession.UISelectDirectory() prompts the user to select a directory using the Creo Parametric dialog box for browsing directories. The method accepts options through the pfcDirectorySelectionOptions object which is similar to the pfcFileUIOptions object (described for the method pfcSession.UIOpenFile()). Specify the default directory path, the title of the dialog box, and a set of shortcuts to other directories to start browsing. If the default path is specified as NULL, the current directory is used. Use the method pfcFileOpenOptions.Create() to create a new instance of the pfcDirectorySelectionOptions object. The method pfcSession.UISelectDirectory() returns the selected directory path; the application must use other methods or techniques to perform other relevant tasks with this selected path.
    Customizing the Creo Parametric Navigation Area
    The Creo Parametric navigation area includes the Model and Layer Tree pane, Folder browser pane, and Favorites pane. The methods described in this section enable Web.Link applications to add custom panes that contain Web pages to the Creo Parametric navigation area.
    Adding Custom Web Pages
    To add custom Web pages to the navigation area, the Web.Link application must:
    1. Add a new pane to the navigation area.
    2. Set an icon for this pane.
    3. Set the URL of the location that will be displayed in the pane.
    Methods Introduced:
  • pfcSession.NavigatorPaneBrowserAdd()
    		•
  • pfcSession.NavigatorPaneBrowserIconSet()
    		•
  • pfcSession.NavigatorPaneBrowserURLSet()
    		•
    The method pfcSession.NavigatorPaneBrowserAdd() adds a new pane that can display a Web page to the navigation area. The input parameters are:
    •  PaneName—Specify a unique name for the pane. Use this name in subsequent calls to pfcSession.NavigatorPaneBrowserIconSet() and pfcSession.NavigatorPaneBrowserURLSet().
    •  IconFileName—Specify the name of the icon file, including the extension. A valid format for the icon file is the PTC-proprietary format used by Creo Parametric .BIF, .GIF, .JPG, or .PNG. The new pane is displayed with the icon image. If you specify the value as NULL, the default Creo Parametric icon is used.
    The default search paths for finding the icons are:
    ○  <creo_loadpoint>\<version>\Common Files\text\resource
    ○  <Application text dir>\resource
    ○  <Application text dir>\<language>\resource
    The location of the application text directory is specified in the registry file.
    •  URL—Specify the URL of the location to be accessed from the pane.
    Use the method pfcSession.NavigatorPaneBrowserIconSet() to set or change the icon of a specified browser pane in the navigation area.
    Use the method pfcSession.NavigatorPaneBrowserURLSet() to change the URL of the page displayed in the browser pane in the navigation area.