# Dispatcher functionality

The dispatcher is responsible for providing functionality for:

- Communications

- Built-in services

## Communications

The dispatcher provides and maintains a communications path between the SPI and the service manager, even between different computers. By using dispatcher functions, details of network programming are hidden from the service developer.

Dispatcher communications

The Natural Access dispatcher corresponds to portions of the RPC runtime library having to do with low level IPC and network communications.

## Built-in dispatcher services

The dispatcher built-in services include:

- Service setup

- Command processing

- Event handling

- Parameter management

- Tracing

- Service object handles

- Buffers

The following illustration shows the dispatcher built-in services:

Dispatcher built-in services

The built-in dispatcher services are implemented across the client/server separation. They are not exclusively owned by either side.

### Service setup

When setting up a Natural Access application, services and service managers are registered and initialized by calling dispatcher functions. These dispatcher functions declare the version numbers, compatibility levels, and binding function addresses for the service.

### Command processing

When an application calls a service API function, a command buffer is passed to the dispatcher. The dispatcher invokes the appropriate service manager binding function which, in turn, performs an upcall to the corresponding service implementation function.

### Event handling

Conceptually, an event service is a mechanism that allows:

- Event producers to publish their events in a well-known location.

- Event consumers to register their interest in certain events and, when those events are published, to retrieve them.

An event service does not impose a restriction on the types of event information that can be published nor does it inform the consumer as to the contents of an event. The content of an event is completely determined and documented by the producer of the event.

However, an event service defines the transport structure to encapsulate the raw event published by the producer and retrieved by the consumer. By doing so, the mechanics of sending an event from the producer to the consumer are greatly simplified since the event service is trafficking in only one common data structure.

The dispatcher includes a built-in service to provide streamlined event service functionality. The built-in dispatcher event service:

- Defines a generic event structure for transport of events between Natural Access services and Natural Access applications. This generic event structure encapsulates raw event data produced by a service.

- Provides the ability for a Natural Access service to define and publish events to a specific consumer (either another Natural Access service or a Natural Access application).

- Provides the ability for a Natural Access service to process an incoming event.

- Provides the ability for a managed resource to publish raw (unencapsulated) event data to a specific Natural Access service.

- Provides the ability for a Natural Access service to process an incoming raw event from a managed resource using a specific callback function.

- Provides the ability for independently operating Natural Access services to be notified when particular service events are generated. This feature is called runtime control.

### Error handling

Natural Access handles errors in API calls by calling an error handler. The default error handler returns the error as the function return value. An application can override error handling by registering its own error handler with Natural Access. Internal errors in services or service managers are sent to the trace log if tracing is enabled.

### Parameter management

Each service has a defined set of parameters that allow dynamic modification of service behavior. These parameters are specified by each service, but are managed by the dispatcher. Each context maintains the parameter values for each service opened on the context. There are also Natural Access server defaults for service parameters that may be either shared between processes or held locally in process memory. Parameter default values are copied from the Natural Access server defaults to a context when it is created. Natural Access parameter functions can be used by an application to modify either the parameter values in a specific context or the Natural Access server default parameter values.

Service APIs support the passing of structures for parameter values. Parameters passed in API calls modify the behavior of the function but do not modify the default parameter values stored in the context.

Each service has a set of standard parameters that all conforming service implementations must expose. Natural Access also provides the capability for services to define extension parameters. Currently, Natural Access services do not define any extension parameters.

### Tracing

To facilitate debugging of both services and applications, Natural Access provides a built-in dispatcher service to log warning, error, and informational messages to a central location. These messages are referred to as trace records. The trace records can then be viewed using the Natural Access Server (ctdaemon). Refer to the Natural Access Developer's Reference Manual for more information on viewing trace records this way.

There are a variety of trace record categories that are supported by the dispatcher built-in tracing service. For some of these categories, the Natural Access dispatcher automatically generates the trace records. The remaining trace record categories are service-specific. For service-specific trace records, each Natural Access service must associate corresponding trace records and explicitly generate them.

The dispatcher also provides a mechanism (a tracemask) to identify which trace record categories are active. If the trace record category is active, the associated trace records are generated and logged.

### Service object handles

The service object is a functional unit within a service that represents a managed resource and is associated with a Natural Access context. Service object handles are used as the reference to real service objects that are managed by the service implementation. Two kinds of object handles are supported in Natural Access:

- A server-side object handle provides service implementation access to resources and resides on the server.

- A client-side object handle provides the client of the service access to objects on the server.

Mapping information between the client side and server side object handles must be maintained by all services interfaces. The Natural Access dispatcher includes general functions to handle mapping table logic.

### Buffers

The Natural Access dispatcher includes a set of specialized functions for handling of data buffers. Due to the client/server architecture, there are some issues you must understand and account for when passing data buffers, either through an API function call or through a service generated event.