Dispatcher service function summary

This topic presents a summary of the dispatcher service functions:

Service manager and service registration
Event queue processing control
Parameter modification
Service command queuing and sending
Handle management
Wait object
Error and tracing log
Service information retrieval
Buffer management
Runtime control
Application initialization information
Server command

Service manager and service registration

The following functions enable you to register service managers and services with the dispatcher. Both of these functions are synchronous:

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

Event queue processing control

The following functions are used to access the event queue. All of these functions are synchronous:

Function	Description
dispGetQueueHandle	Retrieves 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.

Parameter modification

By modifying associated parameters, you can alter the characteristics of many Natural Access services. The following functions enable you to obtain or change parameter information. All of these functions are synchronous:

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.

Service command queuing and sending

Service SPI functions call dispSendCommand to send commands to the service implementation. This function is synchronous.

Handle management

The following functions enable you to create, modify, and destroy service API handles. All of these functions are synchronous:

Function	Description
dispAttachHandle	Associates a handle with a Natural Access context or object descriptor.
dispCreateHandle	Creates a client-side API handle and associates it with a server-side object handle.
dispDestroyHandle	Destroys the API handle and clears its associated value.
dispFindHandle	Returns the client-side handle associated with a server-side handle.
dispFindHandleByName	Returns the client-side handle associated with the name of a service object.
dispGetHandleValue	Retrieves information associated with a client-side API handle: context handle, server-side service object handle, and service identifier.
dispGetHandleValueEx	Retrieves all information associated with a client-side API handle: context handle, server-side service object handle, service object name, and service identifier.
dispSetHandleValue	Associates a server-side object handle with a client-side API handle.
dispSetHandleValueEx	Associates a service object name with a client-side API handle.
dispQueueCommand	Adds a command message to the context's dispatcher queue.

Wait object

The following functions enable service managers or services to associate wait objects with Natural Access queues. All of these functions are synchronous:

Function	Description
dispFindWaitObject	Returns an internal wait object representing the operating system-specific wait object.
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.

Error and tracing log

The following functions enable you to control service error logging and tracing. All of these functions are synchronous:

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.

Service information retrieval

dispGetText returns the text representation of errors, reasons, events and commands. This function is synchronous.

Buffer management

The following functions aid service developers in the use of data buffers within the Natural Access client-server development environment. All of these functions are synchronous:

Function	Description
dispAllocBuffer	Allocates buffer of memory managed by the Natural Access dispatcher.
dispFreeBuffer	Releases a buffer of memory managed by the Natural Access dispatcher.
dispSetAsyncIn	Designates a command buffer as being used for asynchronous input.
dispSetAsyncOut	Designates a command buffer as being used for asynchronous output.

Runtime control

The following functions enable service managers to use the dispatcher runtime control mechanisms. All of these functions are synchronous:

Function	Description
dispAddRTC	Requests that a service action be invoked when a runtime control condition occurs.
dispGetActiveRTC	Returns the runtime control conditions and actions that are registered on the Natural Access context.
dispGetNumRTC	Returns the number of runtime control conditions that are registered on the Natural Access context.
dispGetNumRTCAliases	Returns the number of runtime control aliases added to the RTC database by services on the context.
dispGetRTCAliases	Returns the runtime control aliases added to the RTC database by services on the context.
dispRegisterRTCAlias	Registers an alias with the dispatcher to be associated with a service specific event.
dispRemoveRTC	Requests that the dispatcher's notification about a runtime control condition be removed.
dispUnregisterRTCAlias	Unregisters an event alias previously registered with the dispatcher.

Application initialization information

dispGetAppCtl returns information about default Natural Access usage by the application. This function is synchronous:

Server command

dispShutdown shutdowns or restarts either the Natural Access server (ctdaemon) or the system hosting the server. This function is synchronous.