PATH clause

The PATH clause specifies a list of additional schemas to be searched when matching function and procedure calls to their implementations. The schema in which the call lies is implicitly included in the PATH.

The PATH feature is used to resolve unqualified function and procedure names in the tools according to the following algorithm.

There must be a single function or procedure that matches the unqualified name, or the tools report an error. You can correct the error by qualifying the function or procedure name with a schemaId:
  1. The current MODULE (if any) is searched for a matching function or procedure. MODULE-scope functions and procedures are visible only within their containing MODULE. MODULE-scope functions and procedures hide schema-scope functions and procedures.
  2. The <node schema> (but none of its contained MODULEs) and the <SQL-broker schema> or schemas identified by the PATH statement are searched for a matching function procedure
Note: The schemaId must be a fully qualified schema name.

The <node schema> is the schema containing the node's message flow. The name of this schema is given by the last segment of the message processing node uuid in the broker XML message.

When a routine is invoked, the name used can be qualified by the schema name. The behavior depends on the circumstances as follows:
  • If the schema is specified, the named schema routine is invoked. The scalar built-in functions, excluding CAST, EXTRACT and the special registers, are considered to be defined within an implicitly declared schema called SQL. They can be invoked in this way, for example, SQL.SUBSTRING(... ).

    Whatever happens next depends on whether the caller is in a module routine or is a schema routine.

    For a module routine:
    • If the schema is not specified, the calling statement is in a module routine, and a routine of the given name exists in the local module, that local routine is invoked.
    • If the schema is not specified, the calling statement is in a module routine, and a routine of the given name does not exist in the local module, all schemas in the schema path are searched for a routine of the same name.
      If a matching function exists in one schema, it is used. If a matching function exists in more than one schema a compile time error occurs. If there is no matching function, the schema SQL is searched.
      Note: This rule and the preceding rule imply that a local module routine takes priority over a built-in routine of the same name.
    For a schema routine:
    • If the schema is not specified, the caller is a schema routine, and a routine of the given name exists in the local schema, that local routine is invoked.
    • If the schema is not specified, the calling statement is in a schema routine, and a routine of the given name does not exist in the local schema, all schemas in the schema path are searched for a routine of the same name
      If a matching function exists in one schema, it is used. If a matching function exists in more than one schema a compile time error occurs. If there is no matching function, the schema SQL is searched.
      Note: This rule and the preceding rule imply that a local schema routine takes priority over a built-in routine of the same name.

The <node schema> is defined as the schema containing the node's message flow. The name of this schema is given by the last segment of the message processing node uuid in the broker XML message.

The <node schema> is specified in this manner to provide backward compatibility with previous versions of WebSphere Message Broker

When the <node schema> is the only schema referenced, the broker XML message does not include the extra features contained in WebSphere Message Broker V5.0.

Brokers in previous versions of WebSphere Message Broker do not support multiple schemas, for example, subroutine libraries for reuse. To deploy to a broker in a previous version of the product, put all ESQL subroutines in the same schema as the message flow and node that is invoking them.

Eclipse tooling uses WebSphere Message Broker V5.0 ESQL syntax in content assist and source code validation. When generating broker ESQL code, the Eclipse tooling can generate V2.1 style code for backward compatibility.

The broker schema of the message flow must contain, at the schema level, any of the following in its ESQL files:
  • A schema level function
  • A schema level procedure
  • A schema level constant
  • A module level constant
  • A module level variable

Without the presence of any of the preceding items, the Eclipse tooling generates broker ESQL without MODULE and FUNCTION Main wrappers. This style is accepted by both V2.1 and V5.0 brokers. However, if you use a V2.1 broker, you cannot use any V5.0 syntax in the code, for example, namespace

Functions and procedure names must be unique within their SCHEMA or MODULE.

Examples

The following example adds a path to a schema called CommonUtils:
BROKER SCHEMA CommonUtils
PATH SpecialUtils;

MODULE ....
The next example adds a path to the default schema:
PATH CommonUtils, SpecialUtils;

MODULE ....
Related concepts
ESQL overview
Related tasks
Developing ESQL
Related reference
Syntax diagrams: available types
ESQL statements
BROKER SCHEMA statement
CREATE MODULE statement