Running J-Link Applications in Asynchronous Mode
This section explains how to use J-Link in Asynchronous Mode.
Note
Creo Object TOOLKIT Java is not supported in Asynchronous Mode.
Overview
Asynchronous mode is a multiprocess mode in which the J-Link application and Creo Parametric can perform concurrent operations. Unlike the synchronous modes, asynchronous mode uses JNI (Java Native Interface) and RPC (remote procedure calls) 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 J-Link application. In synchronous mode, the application is started by Creo Parametric, based on information contained in the registry file. In asynchronous mode, the application (containing its own main() method) is started independently of Creo Parametric and subsequently either starts or connects to a Creo Parametric process.
Note
An asynchronous application that starts Creo Parametric will not appear in the Auxiliary Applications dialog box.
The use of RPC causes asynchronous mode to perform more slowly than synchronous mode. For this reason, apply asynchronous mode only when it is needed.
An asynchronous mode is not the only mode in which your application has explicit control over Creo Parametric. Because Creo Parametric calls a Java start method when an application starts, your synchronous application can take control by initiating all operations in Java start method (thus interrupting any user interaction). This technique is important when you want to run Creo Parametric in batch mode.
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.
Setting up an Asynchronous J-Link 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.
To support the asynchronous mode, use the jar file pfcasync.jar in your CLASSPATH. This file is available at <creo_loadpoint>\<version>\Common Files\text\java. This file contains all required classes for running with asynchronous J-Link.
Note
Asynchronous applications are incompatible with the classes in the synchronous .jar files. You must build and run your application classes specifically to run in asynchronous mode.
You must add the asynchronous library, pfcasyncmt, to your environment that launches the J-Link application. This library is stored in <creo_loadpoint>\<version>\Common Files\<machine type>\<lib>.
Note
The library has prefix and extension specifiers for a dynamically loaded library for the platform being used.
System
Library
Path
i486_nt, x86e_win64
pfcasyncmt.dll
set PATH=<creo_loadpoint>
\<version>\Common Files\<machine Type>\lib;%PATH%
Asynchronous J-Link applications must load the library prior to calls made to the asynchronous methods. This can be accomplished by adding the following line to your application.
System.loadLibrary (“pfcasyncmt”)
Simple Asynchronous Mode
A simple asynchronous application does not implement a way to handle requests from Creo Parametric. Therefore, J-Link 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 J-Link 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 J-Link methods but does not support ActionListeners. These considerations imply that the J-Link 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 J-Link applications.
Methods Introduced:
  • pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_Start
  • pfcAsyncConnection.AsyncConnection.End
    		•
    A simple asynchronous application can spawn and connect to a Creo Parametric process with the method pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_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 J-Link 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.AsyncConnection.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.pfcAsyncConnection.AsyncConnection_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.pfcAsyncConnection.AsyncConnection_Start
("pro -g:no_graphics -i:rpc_input",<text_dir>);
    where pro is the command to start Creo Parametric.
    Example Code
    The sample code in the file pfcAsyncStartExample.java located at <creo_jlink_loadpoint>/jlink_appls/jlinkasyncexamples demonstrates how to use J-Link in asynchronous mode. The method starts Creo Parametric asynchronously, retrieves a Session, and opens a model in Creo Parametric.
    Connecting to a Creo Parametric Process
    Methods Introduced:
  • pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_Connect
  • pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_GetActiveConnection
    		•
  • pfcAsyncConnection.AsyncConnection.Disconnect
    		•
    A simple asynchronous application can also connect to a Creo Parametric process that is already running on a local computer. The method pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_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.pfcAsyncConnection.AsyncConnection
    _GetActiveConnection     returns the current connection to a Creo Parametric session.
    To disconnect from a Creo Parametric process, call the method pfcAsyncConnection.AsyncConnection.Disconnect. This method can be called only if you used the method pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_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.AsyncConnection.GetConnectionId
    		•
  • pfcAsyncConnection.ConnectionId.GetExternalRep
    		•
  • pfcSession.BaseSession.GetConnectionId
    		•
  • pfcAsyncConnection.pfcAsyncConnection.ConnectionId_Create
    		•
  • pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_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.AsyncConnection.GetConnectionId returns a data structure containing the connection ID.
    If the connection id must be passed to some other application the method pfcAsyncConnection.ConnectionId.GetExternalRep provides the string external representation for the connection ID.
    The method pfcSession.BaseSession.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 pfcAsyncConnection.pfcAsyncConnection.ConnectionId_Create takes a string representation and creates a ConnectionId data object. The method pfcAsyncConnection.pfcAsyncConnection.
    AsyncConnection_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.AsyncConnection.IsRunning
    		•
    To find out whether a Creo Parametric process is running, use the method pfcAsyncConnectionAsyncConnection.IsRunning.
    Getting the Session Object
    Method Introduced:
  • pfcAsyncConnection.AsyncConnection.GetSession
    		•
    The method pfcAsyncConnection.AsyncConnection.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 J-Link 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.AsyncConnection.EventProcess
    		•
  • pfcAsyncConnection.AsyncConnection.WaitForEvents
    		•
  • pfcAsyncConnection.AsyncConnection.InterruptEventProcessing
    		•
  • pfcAsyncConnection.AsyncActionListener.OnTerminate
    		•
    The control loop of an application running in full asynchronous mode must contain a call to the method pfcAsyncConnection.AsyncConnection.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.AsyncConnection.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.AsyncConnection.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.AsyncConnection.InterruptEventProcessing is called from a J-Link 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 pfcAsyncConnection.AsyncActionListener.OnTerminate handles the termination that you must override. It sends a member of the class pfcAsyncConnection.TerminationStatus, which is one of the following:
    •  TERM_EXIT—Normal exit (the user clicks Exit on the menu).
    •  TERM_ABNORMAL—Quit with error status.
    •  TERM_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.
    Example Code
    The sample code in the file pfcAsyncFullExample.java located at <creo_jlink_loadpoint>/jlink_appls/jlinkasyncexamples is a fully asynchronous application. It follows the procedure for a full asynchronous application:
    1. The application establishes listeners for Creo Parametric events, in this case, the menu button and the termination listener.
    2. The application goes into a control loop calling EventProcess which allows the application to respond to the Creo Parametric events.
    Message and Menu File
    J-Link
J-Link
#
#
AsyncApp
Hit me!
#
#
AsyncAppHelp
Launch async application callback
#
#
    Troubleshooting Asynchronous J-Link
    General Problems
    UnsatisfiedLinkError in System.loadLibrary ("pfcasyncmt")
    Add $PRO_DIRECTORY/$PRO_MACHINE_TYPE/lib to your library path:
    Windows and Windows XP 64bit:$PATH (separated with semicolon)
    Java gives this exception when it has any trouble loading the library, not just when the library is not in the library path. If you are working in a non-standard configuration make sure that all of these libraries are in your library path (subject to your OS naming, for example cipstdmtz.dll on Windows):
    •  pfcasyncmt
    •  jnicipjavamtz
    •  jniadaptsmtz
    •  cipstdmtz
    •  ctoolsmtz
    •  baselibmtz
    •  i18nmtz
    Look at what is printed on stdout/stderr. There can be unresolved symbols. Windows usually reports unresolved symbols in a pop-up dialog so you will see it immediately. If that does not help, then enable the debug output from the operating system's dynamic loader, start with reading the main page.
    UnsatisfiedLinkError on first call to a JLink method
    Ensure that you executed the System.loadLibrary ("pfcasyncmt"). Put a debug printout right after it to ensure it gets loaded.
    In most cases the J-Link jar files (pfcasync.jar) are loaded using a non-system class loader. Java lets you load native libraries from classes loaded with either the system class loader (pfcasync.jarmust be in the default CLASSPATH), or a signed class loader. Java will not throw an exception on System.loadLibrary. For this reason everything will appear to be fine until the first call to a native method. At this point you will get an UnsatisfiedLinkError. Add J-Link jar files to the default CLASSPATH, usually to the CLASSPATH environment or an appropriate place in your servlet engine's configuration.
    NullPointerException from a JLink method early in program execution
    Make sure that you have jar files from only one version of J-Link in your CLASSPATH. If you have both async and sync jar files, the VM will pick up incorrect classes.
    •  Sync J-Link jars:
    •  Async J-Link jars:
    pfcExceptions.XToolkitNotFound exception on the first call to pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_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.
    pfcExceptions.XToolkitGeneralError or pfcExceptions.CommError on the first call to pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_Start or pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_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.pfcAsyncConnection.AsyncConnection_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.
    Problems Specific to Servlets and JSP
    pfcExceptions.XToolkitGeneralError or pfcExceptions.CommError on the first call to pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_Start or pfcAsyncConnection.pfcAsyncConnection.AsyncConnection_Connect
    •  Make sure you have PRO_COMM_MSG_EXE and PRO_DIRECTORY set correctly.
    •  On Windows, servlet engine deployments typically belong to the SYSTEM account and not a local user account. So, you must set PRO_COMM_MSG_EXE and PRO_DIRECTORY in your system environment and restart Windows to cause this change to take effect.