9.1 Introduction

9.2 Dispatcher Functions

9.2.1 Registering Service Managers and Services

9.2.2 Controlling Event Queue Processing

9.2.3 Modifying Parameters

9.2.4 Queueing and Sending Service Commands

9.2.5 Managing Handles

9.2.6 Using Wait Objects

9.2.7 Logging Errors and Tracing

9.2.8 Retrieving Service Information

9.3 Service Manager Binding Functions

9.3.1 Life Cycle Binding Functions - Registration

9.3.2 Life Cycle Binding Functions - Event Handling

9.3.3 Life Cycle Binding Functions - Service Startup

9.3.4 Runtime Binding Functions - Command Processing

9.3.5 Runtime Binding Functions - Trace Handling

9.3.6 Runtime Binding Functions - Error Handling

9.3.7 Runtime Binding Functions - Event Processing

9.1 Introduction

This chapter provides an overview of the Natural Access functions by functional group:

Function Group	Description
Dispatcher	Dispatcher functions (disp prefix) are available to both services and service managers.
Service Manager Binding	Service manager binding functions (xxx prefix) provide the "glue code" that connects the service implementation to the Natural Access infrastructure.

9.2 Dispatcher Functions

The Natural Access Dispatcher provides functions for:

• Registering service managers and services

• Controlling event queue processing

• Modifying parameters

• Queuing and sending service commands

• Managing handles

• Using wait objects

• Logging errors and tracing

• Retrieving service information

9.2.1 Registering Service Managers and Services

The following functions allow you to register service managers and services with the dispatcher:

Function	Description
dispRegisterService	Registers a service with the dispatcher at initialization time.
dispRegisterServiceManager	Registers a service manager with the dispatcher at initialization time.

9.2.2 Controlling Event Queue Processing

The following functions are used to access the event queue:

Function	Description
dispGetQueueHandle	Gets the queue handle of the specified context.
dispMakeAndQueueEvent	Creates an event and sends it to the application event queue or to the dispatcher event queue.
dispQueueEvent	Queues events to other services or applications.

9.2.3 Modifying Parameters

The characteristics for many Natural Access services can be altered by modifying associated parameters. The following functions allow you to obtain or change parameter information:

Function	Description
dispCheckParmByName	Verifies the existence and returns the value of a parameter field or structure.
dispGetParmByName	Retrieves the value of parameter field or structure specified by name.
dispGetParms	Returns parameter values for a specified parameter structure.
dispSetParmByName	Permanently modifies the value of a default parameter.

9.2.4 Queueing and Sending Service Commands

The dispSendCommand function is called by service SPI functions to send commands to the service implementation.

9.2.5 Managing Handles

The following functions allow you to create, modify, and destroy service API handles:

Function	Description
dispCreateHandle	Creates a handle and associates it with a service specific value.
dispDestroyHandle	Destroys the API handle and clears its associated value.
dispGetHandleValue	Retrieves the value associated with the given API handle.
dispSetHandleValue	Associates a value with a dispatcher created handle.

9.2.6 Using Wait Objects

The following functions allow service managers or services to associate wait objects with Natural Access queues:

Function	Description
dispRegisterWaitObject	Registers wait objects and their processing functions with a Natural Access queue.
dispUnregisterWaitObject	Unregisters wait objects and their processing functions from a Natural Access queue.

9.2.7 Logging Errors and Tracing

The following functions allow you to control service error logging and tracing:

Function	Description
dispApiError	Invokes a user defined error handler, logs a trace message and returns the error code.
dispError	Logs an error to the Natural Access trace log.
dispGetTracePointer	Retrieves the address of the global trace mask at process initialization.
dispLogTrace	Logs a trace message and buffer to the Natural Access trace log.

9.2.8 Retrieving Service Information

dispGetText returns the text representation of errors, reasons, events and commands.

9.3 Service Manager Binding Functions

The binding functions in the service manager are divided into two groups:

• Life cycle binding functions

• Runtime binding functions

The life cycle binding functions are the service specific functions called by Natural Access to perform:

• Service registration

• Event handling initialization and shutdown

• Service startup and shutdown

The runtime binding functions include functions for:

• Command processing

• Trace handling

• Error handling

• Event processing

9.3.1 Life Cycle Binding Functions - Registration

The following binding functions are used to register Natural Access services and service managers:

Function	Description
xxxInitializeManager	Acts as an entry point into service. Declares binding functions and version numbers and compatibility levels for service manager.
xxxDefineService	Declares version numbers, compatibility levels, and parameters for service.

9.3.2 Life Cycle Binding Functions - Event Handling

The following binding functions are used to initialize and shut down event handling:

Function	Description
xxxAttachServiceManager	Initializes communication with managed resource, may declare wait objects and allocate queuecontext data structure.
xxxDetachServiceManager	Deallocates data structures allocated with xxxAttachServiceManager.

9.3.3 Life Cycle Binding Functions - Service Startup

The following binding functions are used during service startup and shutdown:

Function	Description
xxxOpenServiceManager	Allocates managed resource data structure which pertains to the specific context.
xxxOpenService	Initializes the managed resource.
xxxCloseServiceManager	De-allocates any data structures opened with xxxOpenServiceManager.
xxxCloseService	Shuts down the managed resource.

9.3.4 Runtime Binding Functions - Command Processing

The xxxProcessCommand binding function allows you to process service commands.

9.3.5 Runtime Binding Functions - Trace Handling

The following binding functions allow you to control tracing for specific services:

Function	Description
xxxFormatTraceBuffer	Formats a service-specific trace buffer.
xxxSetTraceLevel	Sets the tracemask for a specific service on a per context basis.

9.3.6 Runtime Binding Functions - Error Handling

The following binding functions are used to convert binary codes and trace records to ASCII:

Function	Description
xxxFormatMessage	Formats a command or event that was generated by the service.
xxxGetText	Retrieves the service specific textual representation of an error, reason, event or command code.

9.3.7 Runtime Binding Functions - Event Processing

The xxxProcessEvent binding function is used to process events from other services.