WebSphere Message Brokers
File: ak09031_
Writer: Bill Oppenheimer

Task topic

This build: July 31, 2007 21:32:40

Creating an ESQL file

When you include a node in your message flow that requires ESQL to customize its function (the Compute, Database, and Filter nodes), you must code the ESQL statements that provide the customization in an ESQL module within an ESQL file. You can use the same ESQL file for more than one module, if you choose.

Before you start

To complete this task, you must have completed the following task:

ESQL files are stored in a file system or in a shared repository. If you are using a file system, this can be the local file system or a shared drive. If you store files in a repository, you can use any of the available repositories that are supported by Eclipse, for example CVS.

To create an ESQL file:

  1. Switch to the Broker Application Development perspective.
  2. Click File > New > Message Flow ESQL File.

    You can also press Ctrl+N. This displays a dialog box that allows you to select the wizard to create a new object. Click Message Brokers in the left view; the right view displays a list of objects that you can create for WebSphere Message Broker. Click Message Flow ESQL File in the right view, then click Next.

    The New Message Flow ESQL File wizard is displayed.
  3. Enter the name of the message flow project in which to create the ESQL file. You must enter the name of an existing message flow project. The dialog box is displayed with the current project name entered in the project name field. You can accept this value or change it to specify a different project. You can also click Browse to view a list of valid projects (projects that are defined and displayed in the Navigator view), and select the appropriate value from that list.

    If you type in the name of a project that does not exist, the error message The specified project does not exist is displayed in the dialog box and you cannot continue until you specify a valid project name.

  4. If you want the ESQL file to be defined within a specific broker schema, enter the name of the broker schema in the appropriate entry field, or click Browse to select the broker schema from the list of valid broker schema for this project. (If only the default broker schema is defined in this project, Browse is disabled.)
  5. Enter a name for the new ESQL file. If you enter a name that is already in use for an ESQL file in this project, the error message The resource <name>.esql already exists is displayed in the dialog box and you cannot continue until you specify a valid name.

    When creating ESQL files, the overall file path length must not exceed 256 characters, due to a Windows file system limitation. If you try to add a message flow to a broker archive file with ESQL or mapping files with a path length that exceeds 256 characters, the compiled message flow will not be generated and cannot be deployed. Therefore, make sure that the names of your ESQL files, mapping files, projects, and broker schema are as short as possible.

An ESQL file can also be created automatically for you. If you select Open ESQL from the menu displayed when you right-click a Compute, Database, or Filter node, and the module identified by the appropriate property does not already exist within the broker schema, a module is automatically created for you. This is created in the file <message_flow_name>.esql in the same broker schema within the same project as the <message_flow_name>.msgflow file. If that ESQL file does not already exist, that is also created for you.

The contents of a single ESQL file do not have any specific relationship with message flows and nodes. It is your decision which modules are created in which files (unless the specified module, identified by the appropriate property, is created by default in the file <message_flow_name>.esql as described above). Monitor the size and complexity of the ESQL within each file, and split the file if it becomes difficult to view or manage.

If you create reusable subroutines (at broker schema level) within an ESQL file, you might want to refer to these routines from ESQL modules in another project. To do this, specify that the project that wants to invoke the subroutines depends on the project in which the ESQL file containing them is defined. You can specify this when you create the second project, or you can update project dependencies by selecting the project, clicking Properties, and updating the dependencies in the Project Reference page of the Properties dialog box.

Related concepts
Project references
Development repository
Message flows overview
Message mappings overview
Broker schemas
ESQL modules
Related tasks
Developing message flows
Related reference
Built-in nodes
ESQL reference
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:32:40

ak09031_ This topic's URL is: