startApplicationWithParameter

startApplicationWithParameter(schemaName:          String;
                              appName:             String;
                              initializeParameter: Object input): Process;

The startApplicationWithParameter method of the Application class enables your logic to initiate another application on the same node as the initiating application. This method enables you to share transient objects between JADE applications.

If you use this method to share transient objects between applications (that is, by passing transients to the initialize method), ensure that the transients are created as shared transient objects. (For details, see "create Instruction", in Chapter 1 of the JADE Developer’s Reference.)

If you use this method from within a serverExecution method, the initializeParameter object must be persistent.

The parameters for the startApplicationWithParameter method are listed in the following table.

Parameter Description
schemaName Specifies the name of the schema in which the application is located
appName Specifies the name of the application to start
initializeParameter Passed to the initialize method of the application

The object specified in the initializeParameter parameter is passed to the initialize method of the application, specified by using the JADE development environment Define Application dialog Initialize Method combo box. The parameter must be a persistent object or a shared transient object (except in serverExecution methods). If the parameter is a non-shared transient object or a shared transient object and the startApplicationWithParameter method is used in a server execution method to start a server application, an exception (1000 - Invalid parameter type) exception is raised.

The initialize method must have a signature that contains only the initializeParameter parameter; that is:

method-name(initializeParameter: Object);

The following example shows the use of the startApplicationWithParameter method.

addWorker() updating;
vars
    worker : Worker;
begin
    // create a WORKER shared transient object and
    // start it up as a separate application
    beginTransientTransaction;
        create worker sharedTransient;
        worker.central:= self;
        worker.name:= "Worker " & workers.size.String;
    commitTransientTransaction;
    app.startApplicationWithParameter("Threads", "Threads", worker);
end;

This method starts only applications of type ApplicationType_Non_GUI_Web, ApplicationType_Non_GUI_Rest, or ApplicationType_Non_GUI if this method is invoked from a server method or server application. (An exception is raised if this method is invoked from a server method or a server application to start an application of a type other than a non-GUI application.)

On a client node, this method starts all types of application. For details about running non-GUI applications in standard (or fat client) mode, see the Application class applicationType property.

When multiple applications are initiated, they run independently of each other. The JADE application program switches the context between applications, based on the form or control that is causing an event. If one application is terminated (when all forms of that application are closed), the database remains open, as each application uses the same open instance of that database.

You can use the MaxWaitAppStart parameter in the [JadeClient] or [JadeServer] section of the JADE initialization file to increase the time that JADE waits for a GUI or GUI, No Forms application to initiate on another thread before raising an exception, when your system has a large number of applications to start and the default value of 45 seconds may not be sufficient for the loading on the machine during startup. For details, see the JADE Initialization File Reference.

This method returns the process of the application that was started. The application that calls the method continues executing after JADE has successfully created a new process. If the application is not initiated (for example, because of EnableAppRestrictions security restrictions) an exception is raised in the application requesting the initiation.

The types of application that you can start by using the startApplicationWithParameter method on client nodes or server nodes are listed in the following table, which also lists their termination behavior.

Start-up Location GUI Non_GUI and Non_GUI_Web GUI_No_Forms
Client nodes Stays while application has forms Always stays running Always stays running
  Executes finalize method Executes finalize method Executes finalize method
Server nodes Not available Always stays running Not available
    Executes finalize method  

In this table: