Asynchronous Mode
This section explains how to use Creo Object TOOLKIT C++ in Asynchronous Mode.
Overview
Asynchronous mode is a multiprocess mode in which the Creo Object TOOLKIT C++ application and Creo Parametric can perform concurrent operations. Unlike synchronous mode, the asynchronous mode uses remote procedure calls (rpc) as the means of communication between the application and Creo Parametric.
Another important difference between synchronous and asynchronous modes is in the startup of the Creo Object TOOLKIT C++ application. In synchronous mode, the application is started by Creo Parametric, based on information contained in the registry file. In asynchronous mode, the application is started independently of Creo Parametric and subsequently either starts or connects to a Creo Parametric process. The application can contain its own main() or wmain() function. Use wmain() if the application needs to receive command-line arguments as wchar_t, for example if the input contains non-usascii characters.
Note
An asynchronous application that starts Creo Parametric will not appear in the Auxiliary Applications dialog box.
The section How Creo Object TOOLKIT C++ Works in Overview of Creo Object TOOLKIT C++ describes two modes—DLL and multiprocess (or “spawned”). These modes are synchronous modes in the sense that the Creo Object TOOLKIT C++ application and Creo Parametric do not perform operations concurrently. In spawn mode, each process can send a message to the other to ask for some operation, but each waits for a returning message that reports that the operation is complete. Control alternates between the two processes, one of which is always in a wait state.
Asynchronous mode applications operate with the same method of communication as spawn mode (multiprocess). The use of rpc in spawn mode causes this mode to perform significantly slower than DLL communications. For this reason, you should be careful not to apply asynchronous mode when it is not needed. Note that asynchronous mode is not the only mode in which your application can have explicit control over Creo Parametric.
An asynchronous application can also use the user_initialize() function, which will be called back by Creo Parametric when the application starts the connection. Note that in the asynchronous mode the callback to user_initialize() happens twice.
Setting up an Asynchronous Creo Object TOOLKIT Application
For your asynchronous application to communicate with Creo Parametric, you must set the environment variable PRO_COMM_MSG_EXE to the full path of the executable pro_comm_msg.
On Windows systems, set PRO_COMM_MSG_EXE in the Environment section of the System window that you access from the Control Panel.
Simple Asynchronous Mode
A simple asynchronous application does not implement a way to handle requests from Creo Parametric. Therefore, Creo Object TOOLKIT C++ cannot plant listeners to be notified when events happen in Creo Parametric. Consequently, Creo Parametric cannot invoke the methods that must be supplied when you add, for example, menu buttons to Creo Parametric.
Despite this limitation, a simple asynchronous mode application can be used to automate processes in Creo Parametric. The application may either start or connect to an existing Creo Parametric session, and may access Creo Parametric in interactive or in a non graphical, non interactive mode. When Creo Parametric is running with graphics, it is an interactive process available to the user.
When you design a Creo Object TOOLKIT C++ application to run in simple asynchronous mode, keep the following points in mind:
•  The Creo Parametric process and the application perform operations concurrently.
•  None of the application’s listener methods can be invoked by Creo Parametric.
Simple asynchronous mode supports normal Creo Object TOOLKIT C++ methods but does not support callbacks. These considerations imply that the Creo Object TOOLKIT C++ application does not know the state (the current mode, for example) of the Creo Parametric process at any moment.
Starting and Stopping Creo Parametric
The following methods are used to start and stop Creo Parametric when using Creo Object TOOLKIT C++ applications.
Methods Introduced:
  • pfcAsyncConnection::Start
  • pfcAsyncConnection::End
    		•
    A simple asynchronous application can spawn and connect to a Creo Parametric process with the method pfcAsyncConnection::Start. The Creo Parametric process listens for requests from the application and acts on the requests at suitable breakpoints, usually between commands.
    Unlike applications running in synchronous mode, asynchronous applications are not terminated when Creo Parametric terminates. This is useful when the application needs to perform Creo Parametric operations intermittently, and therefore, must start and stop Creo Parametric more than once during a session.
    The application can connect to or start only one Creo Parametric session at any time. If the Creo Object TOOLKIT C++ application spawns a second session, connection to the first session is lost.
    To end any Creo Parametric process that the application is connected to, call the method pfcAsyncConnection::End.
    Setting Up a Noninteractive Session
    You can spawn a Creo Parametric session that is both noninteractive and nongraphical. In asynchronous mode, include the following strings in the Creo Parametric start or connect call to pfcAsyncConnection::Start:
    •  -g:no_graphics—Turn off the graphics display.
    •  -i:rpc_input—Causes Creo Parametric to expect input from your asynchronous application only.
    Note
    Both of these arguments are required, but the order is not important.
    The syntax of the call for a noninteractive, nongraphical session is as follows: 
    pfcAsyncConnection::Start
("pro -g:no_graphics -i:rpc_input",<text_dir>);
    where pro is the command to start Creo Parametric.
    Connecting to a Creo Parametric Process
    Methods Introduced:
  • pfcAsyncConnection::Connect
  • pfcAsyncConnection::GetActiveConnection
    		•
  • pfcAsyncConnection::Disconnect
    		•
    A simple asynchronous application can also connect to a Creo Parametric process that is already running on a local computer. The method pfcAsyncConnection::Connect performs this connection. This method fails to connect if multiple Creo Parametric sessions are running. If several versions of Creo Parametric are running on the same computer, try to connect by specifying user and display parameters. However, if several versions of Creo Parametric are running in the same user and display parameters, the connection may not be possible.
    pfcAsyncConnection::GetActiveConnection returns the current connection to a Creo Parametric session.
    To disconnect from a Creo Parametric process, call the method pfcAsyncConnection::Disconnect. This method can be called only if you used the method pfcAsyncConnection::Connect to get the connection.
    The connection to a Creo Parametric process uses information provided by the name service daemon. The name service daemon accepts and supplies information about the processes running on the specified hosts. The application manager, for example, uses the name service when it starts up Creo Parametric and other processes. The name service daemon is set up as part of the Creo Parametric installation.
    Connecting Via Connection ID
    Methods Introduced:
  • pfcAsyncConnection::GetConnectionId
    		•
  • pfcConnectionId::GetExternalRep
    		•
  • pfcBaseSession::GetConnectionId
    		•
  • pfcConnectionId::Create
    		•
  • pfcAsyncConnection::ConnectById
    		•
    Each Creo Parametric process maintains a unique identity for communications purposes. Use this ID to reconnect to a Creo Parametric process.
    The method pfcAsyncConnection::GetConnectionId returns a data structure containing the connection ID.
    If the connection id must be passed to some other application the method pfcConnectionId::GetExternalRep provides the string external representation for the connection ID.
    The method pfcBaseSession::GetConnectionId provides access to the asynchronous connection ID for the current Creo Parametric session. This ID can be passed to any asynchronous mode application that needs to connect to the current session of Creo Parametric.
    The method pfcConnectionId::Create takes a string representation and creates a ConnectionId data object. The method pfcAsyncConnection::ConnectById connects to Creo Parametric at the specified connection ID.
    Note
    Connection IDs are unique for each Creo Parametric process and are not maintained after you quit Creo Parametric.
    Status of a Creo Parametric Process
    Method Introduced:
  • pfcAsyncConnection::IsRunning
    		•
    To find out whether a Creo Parametric process is running, use the method pfcAsyncConnection::IsRunning.
    Getting the Session Object
    Method Introduced:
  • pfcAsyncConnection::GetSession
    		•
    The method pfcAsyncConnection::GetSession returns the session object representing the Creo Parametric session. Use this object to access the contents of the Creo Parametric session. See the Session Objects section for additional information.
    Full Asynchronous Mode
    Full asynchronous mode is identical to the simple asynchronous mode except in the way the Creo Object TOOLKIT C++ application handles requests from Creo Parametric. In simple asynchronous mode, it is not possible to process these requests. In full asynchronous mode, the application implements a control loop that ‘listens’ for messages from Creo Parametric. As a result, Creo Parametric can call functions in the application, including callback functions for menu buttons and notifications.
    Note
    Using full asynchronous mode requires starting or connecting to Creo Parametric using the methods described in the previous sections. The difference is that the application must provide an event loop to process calls from menu buttons and listeners.
    Methods Introduced:
  • pfcAsyncConnection::EventProcess
    		•
  • pfcAsyncConnection::WaitForEvents
    		•
  • pfcAsyncConnection::InterruptEventProcessing
    		•
  • pfcAsyncActionListener::OnTerminate
    		•
    The control loop of an application running in full asynchronous mode must contain a call to the method pfcAsyncConnection::EventProcess, which takes no arguments. This method allows the application to respond to messages sent from Creo Parametric. For example, if the user selects a menu button that is added by your application, pfcAsyncConnection::EventProcess processes the call to your listener and returns when the call completes. For more information on listeners and adding menu buttons, see the Session Objects section.
    The method pfcAsyncConnection::WaitForEvents provides an alternative to the development of an event processing loop in a full asynchronous mode application. Call this function to have the application wait in a loop for events to be passed from Creo Parametric. No other processing takes place while the application is waiting. The loop continues until pfcAsyncConnection::InterruptEventProcessing is called from a Creo Object TOOLKIT C++ callback action, or until the application detects the termination of Creo Parametric.
    It is often necessary for your full asynchronous application to be notified of the termination of the Creo Parametric process. In particular, your control loop need not continue to listen for Creo Parametric messages if Creo Parametric is no longer running.
    An AsyncConnection object can be assigned an Action Listener to bind a termination action that is executed upon the termination of Creo Parametric. The method pfcAsyncActionListener::OnTerminate handles the termination that you must override. It sends a member of the class pfcAsyncConnection::TerminationStatus, which is one of the following:
    •  pfcTERM_EXIT—Normal exit (the user clicks Exit on the menu).
    •  pfcTERM_ABNORMAL—Quit with error status.
    •  pfcTERM_SIGNAL—Fatal signal raised.
    Your application can interpret the termination type and take appropriate action. For more information on Action Listeners, see the Action Listeners section.
    Troubleshooting Asynchronous Creo Object TOOLKIT
    General Problems
    pfcXToolkitNotFound exception on the first call to pfcAsyncConnection::Start on Windows.
    Make sure your Creo Parametric command is correct. If it's not a full path to a script/executable, make sure $PATH is set correctly. Try full path in the command: if it works, then your $PATHis incorrect.
    pfcXToolkitGeneralError or pfcXToolkitCommError on the first call to pfcAsyncConnection::Start or pfcAsyncConnection::Connect
    •  Make sure the environment variable PRO_COMM_MSG_EXE is set to full path to pro_comm_msg, including file name, including .exe on Windows.
    •  Make sure the environment variable PRO_DIRECTORY is set to Creo Parametric installation directory.
    •  Make sure name service () is running.
    pfcAsyncConnection::Start hangs, even though Creo Parametric already started.
    Make sure name service () is also started with Creo Parametric. Open Task Manager and look for nmsd.exe in the process listing.