Core: Asynchronous Mode
This section explains using Creo TOOLKIT in Asynchronous Mode.
Overview
Asynchronous mode is a multiprocess mode in which the Creo TOOLKIT 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 TOOLKIT 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 that an asynchronous application will not appear in the Auxiliary Applications dialog box.
The section How Creo Toolkit Works in Fundamentals describes two modes—DLL and multiprocess (or “spawned”). These modes are synchronous modes in the sense that the Creo TOOLKIT 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. You can also run Creo Parametric in batch mode using Creo TOOLKIT applications; for more information on batch mode operation, refer to the section Using Creo Toolkit to Make a Batch Creo Parametric Session.
Setting up an Asynchronous Creo 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.exe , that is, <creo_loadpoint>\<version>\Common Files\<machine>\obj\pro_comm_msg.exe
Set PRO_COMM_MSG_EXE in the Environment Variables section of the System window (which can be accessed from the Control Panel).
Depending on how your asynchronous application handles messages from Creo Parametric, your application can be classified as either “simple” or “full”. The following sections describe simple and full asynchronous mode.
The environment variable RPC_TIMEOUT sets the maximum time limit in which the remote procedure calls must be executed. The variable sets the time in seconds. The default value is set to 2000 seconds. The functions return the error PRO_TK_COMM_ERROR, when the application times out without complete execution. If your application requires more time for execution, you must set this variable to a higher value.
Note
For asynchronous mode applications, you are not required to supply user_initialize() and user_terminate(), Creo TOOLKIT will supply a default implementation for these functions. If you do wish to include a custom version of either function, both the functions user_initialize() and user_terminate() must be supplied in the application. A custom user_initialize() will make it possible to access the user_initialize() input arguments and to reuse code from a synchronous application without making modifications.
Simple Asynchronous Mode
A simple asynchronous application does not implement a way to handle requests from Creo Parametric. Therefore, Creo Parametric cannot call functions in the Creo TOOLKIT application. Consequently, Creo Parametric cannot invoke the callback functions that must be supplied when you add, for example, menu buttons or notifications to Creo Parametric.
Despite this limitation, Creo Parametric running with graphics is still an interactive process available to the user.
When you design a Creo TOOLKIT application to run in simple asynchronous mode, keep the following in mind:
•  The Creo Parametric process and the application perform operations concurrently.
•  None of the application’s functions are invoked by Creo Parametric.
•  Simple asynchronous mode supports Creo TOOLKIT visit functions (ProSolidFeatVisit(), for example), but does not support notification callbacks.
These considerations imply that the Creo TOOLKIT application does not know the state (the current mode, for example) of the Creo Parametric process at any moment.
Starting and Stopping Creo Parametric
Functions introduced:
  • ProEngineerStart()
    		•
  • ProEngineerConnectionStart()
    		•
  • ProEngineerEnd()
    		•
    A simple asynchronous application can spawn and connect to a Creo Parametric process via the function ProEngineerStart(). During this startup, Creo Parametric calls user_initialize() if it is present in the application. The Creo Parametric process “listens” for requests from the application and acts on the requests at suitable breakpoints—normally between commands.
    The function ProEngineerConnectionStart() performs the same task as ProEngineerStart(), except that ProEngineerConnectionStart() outputs a ProProcessHandle which can be used for later connect and disconnect operations. Using this function requires building with a C++ compiler — see the description of ProEngineerConnect() for more information.
    To connect to an existing Creo Parametric process from an asynchronous application, see the section Connecting to a Creo Parametric Process.
    Unlike applications running in synchronous mode, asynchronous applications are not terminated when Creo Parametric terminates. This functionality is useful when the application needs to perform Creo Parametric operations only intermittently, and therefore start and stop Creo Parametric more than once during a session. To end a Creo Parametric process, call the function ProEngineerEnd().
    Connecting to a Creo Parametric Process
    Functions introduced:
  • ProEngineerConnectIdGet()
    		•
  • ProEngineerConnect()
    		•
  • ProEngineerDisconnect()
    		•
  • ProEngineerConnectIdExtract()
    		•
    The function ProEngineerConnectIdGet() returns the asynchronous connection id of the Creo Parametric session that the application is running with. This function can be called from any synchronous (DLL or spawn mode) or asynchronous application. It allows the application to send the connection id to any other asynchronous application that needs to connect to this specific Creo Parametric session.
    A simple asynchronous application can also connect to a Creo Parametric process that is already running on that machine. The function ProEngineerConnect() performs this function. It allows you to specify the name of the user who owns the Creo Parametric process to which you want to connect, and the name of the machine used for the display. If multiple Creo Parametric sessions meet this specification, ProEngineerConnect() can optionally choose one process at random or return an error status.
    To disconnect from a Creo Parametric process, call ProEngineerDisconnect().
    The connection to a Creo Parametric process uses information that is 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 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.
    The function ProEngineerConnectIdExtract() returns a string connection identifier for the Creo Parametric process. This identifier can be used later to connect to the same process using a call to ProEngineerConnect(). Pass the connection id as the first argument to the connection function.
    To use the functions in this section, and also the function ProEngineerConnectionStart(), you must link your application with the library pt_asynchronous.lib, which is in the following location: 
    <creo_toolkit_loadpoint>/<Machine>/obj
    Because this is a C++ library, you must use a C++ compiler to build your application. For sample makefiles containing C++ settings, see the makefiles under the directory <creo_toolkit_loadpoint>/<Machine>/obj
    Note
    You do not have to link with pt_asynchronous.lib (or use a C++ compiler) if you do not use the functions just described or ProEngineerConnectionStart().
    Status of a Process
    Function introduced:
  • ProEngineerStatusGet()
    		•
    It might be useful for your application to know whether a Creo Parametric process is running. The function ProEngineerStatusGet() returns this information.
    Full Asynchronous Mode
    Functions introduced:
  • ProEventProcess()
    		•
  • ProAsynchronousEventLoop()
    		•
  • ProAsynchronousEventLoopInterrupt()
    		•
  • ProTermFuncSet()
    		•
  • ProTerminationAction()
    		•
    Full asynchronous mode is identical to simple asynchronous mode except in the way the Creo TOOLKIT application handles requests from Creo Parametric. In simple asynchronous mode, it is not possible to process such requests. In full asynchronous mode, the application must implement a control loop that “listens” for messages that arrive from Creo Parametric. As a result, Creo Parametric can call functions in the application, including callback functions for menu buttons and notifications.
    The control loop of an application running in full asynchronous mode must contain a call to the function ProEventProcess(), which takes no arguments. This function responds to Creo Parametric messages in a manner similar to synchronous mode. For example, if the user selects a menu button that is added by your application, ProEventProcess() processes the call to your callback function and returns when the call completes. (For more information on callback functions and adding menu buttons, see the User Interface: Menus, Commands, and Popupmenus section.)
    The function ProAsynchronousEventLoop() 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 will take place while the application is waiting. The loop will continue until ProAsynchronousEventLoopInterrupt() is called from a Creo TOOLKIT callback action, or until the application detects that Creo Parametric has terminated.
    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. The function ProTermFuncSet() binds a termination action to be executed when Creo Parametric is terminated. The termination action is a function that you supply and identify in the input of ProTermFuncSet() by a function pointer of type ProTerminationAction. The input to the termination action is the termination type, which is one of the following:
    •  PROTERM_EXIT—Normal exit (the user picks Exit from the menu).
    •  PROTERM_ABNORMAL—Exit with error status.
    •  PROTERM_SIGNAL—Fatal signal raised.
    Your application can interpret the termination type and take appropriate action.
    Setting Up a Non-Interactive Session
    You can spawn a Creo Parametric session that is both noninteractive and nongraphical. In asynchronous mode, include the following arguments in the call to ProEngineerStart():
    •  -g:no_graphics—Turn off the graphics display.
    •  -i:rpc_input—Cause Creo Parametric to expect input from your asynchronous application only.
    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: 
    ProEngineerStart ("parametric -g:no_graphics -i:rpc_input", <text_dir>);
    In the syntax, parametric is the command to start Creo Parametric.