# IAppManager.LaunchDoc()

Description:

The `LaunchDoc` method launches an application based on a given document. This method automatically determines which application to launch for the specified document.

The application can be launched as chained (embedded) or stand-alone. For more information about embedded and stand-alone applications, see section Accessing and launching installed applications.

This method can be called both synchronously and asynchronously.

Syntax:

For synchronous calls:

    result = so.IAppManager.LaunchDoc(criteria);

For asynchronous calls:

    result = so.IAppManager.LaunchDoc(criteria, callback);

Arguments:

- `criteria`:

  This is an object that specifies which application to launch. For more information about the object properties and how to define them, see section Criteria for launching an application.

- `callback`:

  The `callback` argument is the name of the method that is executed when an asynchronous `LaunchDoc` call has status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the `callback` method.

  This argument is used only with an asynchronous `LaunchDoc` call.

Return value:

If synchronous, the `LaunchDoc` method returns an object that contains the name of the newly created document, if applicable, an error code, and an error message.

Table: Return value properties for a synchronous LaunchDoc
Property | Description | Value
--- | --- | ---
`[result.ReturnValue]` | This is a string that contains the name of the newly created document, if any. This property is optional. A new document is created only when both of the following are true: `criteria.MIMEType` is specified as input. The launched application creates a new document. A document name is never returned when `criteria.Document` is specified as input. |
`result.ErrorCode` | This is a number that specifies a predefined error code. | See Service API error codes.
`result.ErrorMessage` | This is a text string that describes the error. | See AppManager Service API error messages.

If asynchronous, the `LaunchDoc` method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual result information is returned by the `callback` method in the `ReturnValue` property of its result object. The returned information is described in the preceding table.

Note: If `Cancel` is called on an ongoing asynchronous request, `LaunchDoc` does not return a notification when the launched application terminates.

Table: Return value properties for an asynchronous LaunchDoc
Property | Description | Value
--- | --- | ---
`result.TransactionID` | This is a number used as an identification to match transactions started with the asynchronous `LaunchDoc` call to one or more calls it generates to `callback`. |
`result.ErrorCode` | This is a number that specifies a predefined error code. | See Service API error codes.
`result.ErrorMessage` | This is a text string that describes the error. | See AppManager Service API error messages.

Example code:

For the complete source of a sample widget that demonstrates how to use this Service API, see the full example.