4.1 Introduction

4.2 Understanding the Managed Resource

4.3 Getting a Service ID

4.4 Defining the API

4.5 Defining Events and Reasons

4.6 Defining Errors

4.7 Defining Parameters

4.8 Defining Tracing

4.8.1 Service-Specific Trace Record Categories

4.8.2 Defining Trace Tags

4.1 Introduction

In the definition phase of a Natural Access service, the following tasks must be accomplished:

• Understand the managed resource

• Get a service ID and service name

• Define the API functions

• Define any events and reasons

• Define the errors

• Define the parameters

• Defining non-generic items to be traced (for debugging purposes)

4.2 Understanding the Managed Resource

Before designing a Natural Access service, you must understand exactly what the managed resource is and how it operates. For example, if the managed resource is a telephony board, then you must first understand the low-level details of interoperating with the telephony board such as:

• How to initialize the board.

• How to send commands to the board.

• How to process messages from the board.

You can then define a simple, intuitive Natural Access API to the managed resource. Suggested action items include:

1. API Analysis
   Create a list of managed resource interface calls and then determine if any of those calls can be combined into a smaller set of simpler, more abstract functions.

2. Event Analysis

3. Itemize the list of all incoming messages (raw events) from the managed resource and determine which of these messages should be processed and forwarded to a client. By definition, the remaining messages (if any) are processed and consumed.

4. Determine whether the managed resource is multiplexed (i.e., whether you can use one wait object for events from the managed resource or the managed resource requires multiple wait objects). If the messages sent to and from the managed resource contain addressing information describing the identity of the caller, the managed resource is multiplexed (i.e., requires only one wait object).

5. Data Abstraction Analysis
   Create, when appropriate, data structures to model the managed resource in software as follows:

6. A data structure that contains information concerning the managed resource itself.

7. A data structure that contains information pertaining to a client of the managed resource.

8. Zero or more data structures containing information pertaining to entities that can be manipulated by a client on the managed resource.

There are at least two types of information that are useful during this phase:

• A documented interface to the managed resource. This can be used as a baseline for defining the corresponding simpler, more abstract Natural Access service API. Without documentation, the interface must be discerned from the implementation of the managed resource.

• Documented internal behavior of the managed resource, such as state diagrams or interaction diagrams.

  tik service

  The managed resource for the TIK Service is a software timer known as the TICK server. The TICK server operates as a software timer - it waits for a certain interval to expire then generates and sends a text message over a well defined IPC channel to a client until a maximum number of messages has been generated. The timer interval and maximum number of messages are specified by the client; the text message is configured at server initialization time and is not dynamically configurable. The TICK server can support, at most, 10 separate channels per client. Commands can be sent from a client to the TICK server that: · Request a connection with the TICK server. · Allocate a logical channel. · Start timer on a logical channel based upon number of ticks to generate and duration between ticks. · Stop timer on a logical channel before all tick strings have been received. · Request a channel tear down. When all tick messages have been generated by the TICK server, the logical channel is left active so that another start tick request can be serviced. If a client sends a "stop" request string to the server, the server will abort generation of remaining ticks. The logical channel remains active for further start tick requests.

  Using the description of the TICK server, the following information summarizes the results of the suggested action items: 1. Analysis of interaction with TICK server · Based on the list of messages to be generated by a client of the TICK Server, the abstracted set of API calls are: - A function to start a ticker - A function to stop a ticker - A function to request information concerning the status of the logical connection 2. Event identification and processing · List of incoming messages received from the TICK server are: - An "Open Channel Response" message indicating whether a communications channel has been established with the server. - A "Stop Ticking" message indicating that a request to abnormally terminate generation of tick strings has been honored. - A "Tick" message containing the periodic tick string. · The TICK server is multiplexed in that all messages to and from the server contain a field denoting the id of the client. 3. Abstract data structures: · Managed Resource Data Structure should contain: - Communications endpoint for TICK server - Status fields for communications with TICK server including when a read is pending and how many reads have been performed. - Storage for the latest message received from the TICK server - Array of logical channels that are active · Client specific data structure for the managed resource should contain the: - Associated CTA context handle (i.e., the client id) - Actual logical channel id being used - State of the logical channel - Tracemask for per-CTA context tracing · The only entity to be manipulated by a client of the TICK server is the software timer. Similarly, a client can only manipulate one of them at a time. Therefore, it is not necessary to define explicit entity data structures.

4.3 Getting a Service ID

A numeric service ID is used to internally guarantee uniqueness of services.

To register a new service with Natural MicroSystems, contact Technical Services and provide them with the service's three letter acronym and a description of the service. Technical Services will verify that the acronym is unique and assign a service ID.

During service development and testing, assign any three letter acronym and service ID to the service. When the service is ready to be published, register the service with NMS.

The service IDs for services supplied by NMS range from 0 to 0x40 (this includes services such as ADI, VCE, SWI, etc.). IDs for services not supplied by NMS typically range from 0x41 to 0xFFF.

tik service

The TIK service is registered as: Service name = TIK Service ID = 0x40

4.4 Defining the API

The API for a Natural Access service consists of:

• A set of one or more function prototypes (i.e., function name, function return, and function arguments).

• A description of each API function.

• A determination of whether the function operates synchronously or asynchronously.

Each API function typically includes a context handle to identify the unique processing context for the function invocation.

tik service

Based upon the event analysis (Section 4.2, Understanding the Managed Resource), the following API functions are defined: DWORD tikStartTimer ( CTAHD ctahd, TIK_START_PARMS *start ) Starts the timer function on TICK server, asynchronously returns timer ticks. Passes a parameter structure defining the number of ticks to generate and the frequency. DWORD tikStopTimer ( CTAHD ctahd ) Stops the timer function on TICK server, asynchronously returns acknowledgment. DWORD tikGetChannelInfo ( CTAHD ctahd, TIK_CONTEXT_INFO* info, unsigned size) Asynchronously, gets the operational information from the TIK service. Passes a parameter structure to hold the channel data.

4.5 Defining Events and Reasons

For each asynchronous function defined in the API, a set of one or more events must be defined for subsequent return to the client application. These events typically denote the results of asynchronous API functions invoked by the client application, but they can also represent unsolicited events that were generated by the managed resource.

Each event structure has a value field which can contain additional information or classification for the event. By convention, the value field of a DONE event contains either a reason for completion or an error code. See Section 3.6.4, Event and Reason Names for details.

Set up your service so that it uses existing Natural Access event and reason codes whenever possible. Natural Access events are defined in ctadef.h. Natural Access errors and reason codes are defined in ctaerr.h and are listed in Appendix A.

tik service	Based upon the event analysis (Section 4.2, Understanding the Managed Resource), the following event codes and associated reasons are defined: TIKEVN_TIMER_TICK Event generated by the TIK service and sent back to the client for all tick strings.
	TIKEVN_TIMER_DONE Event generated by the TIK service and sent back to the client to indicate that all tick strings were sent to the client. May have the following reason codes:
		CTA_REASON_FINISHED - Indicates that the TIK service has successfully generated all requested tick strings at the requested frequency.
		TIK_REASON_UNKNOWN_SERVER_REASON - indicates an unexpected error has occurred at the TIK service.
		TIK_REASON_TIMER_STOPPED - Indicates tikStopTimer was successful.
	TIK_REASON_INVALID_CHANNEL Reason code for CTAEVN_DISP_OPEN_SERVICE_DONE. Indicates a failure in initializing communication with the TIK service.
	TIK_REASON_CHANNEL_ACTIVE Reason code for CTAEVN_DISP_OPEN_SERVICE_DONE. Indicates that the requested channel is occupied.

4.6 Defining Errors

Each API function must specify a function return. The return codes can be whatever makes sense for the function. Use existing Natural Access error codes as much as possible. For example, generic error codes include: CTAERR_OUT_OF_MEMORY, CTAERR_OUT_OF_RESOURCES, CTAERR_BOARD_ERROR, etc.

Generic error codes are provided in ctaerr.h.

tik service	TIKERR_COMM_FAILURE Error communicating with server.
	TIKERR_CHANNEL_NOT_OPENED Server connection has not been established.
	TIKERR_OWNER_CONFLICT Owner conflict for CTA context.
	TIKERR_UNKNOWN_SERVER_RESPONSE Unknown server response.
	TIKERR_CAN_NOT_CONNECT Cannot establish connection to server.

4.7 Defining Parameters

Natural Access parameters are a mechanism to allow the operating characteristics of a service to be dynamically modified. If the service being developed needs this type of extensibility, then a set of one or more parameters must be defined. Parameters are named entities with the following syntax:

xxx.category.fieldname

A parameter category is like a directory in a modern file system. It allows multiple, logically-related fieldnames to be nested. For example, the ADI service contains multiple categories, each of which contain multiple fieldnames:

          ADI.CALLPROG.busycount
          ADI.CALLPROG.leakagetime
          ADI.CALLPROG.maxbusy

          ADI.COLLECT.firsttimeout
          ADI.COLLECT.intertimeout

Associated with each parameter is a data type and a default value. Supported data types are:

Data Type	Description
WORD	16 bit unsigned integer
DWORD	32 bit unsigned integer
INT16	16 bit signed integer
INT32	32 bit signed integer
STRING	Arbitrary length string which may contain spaces
BYTE_ARRAY	Array of bytes

tik service

For the TIK service, there is one category comprised of two field names: Number of tick strings to be received = tik.start.NumTicks data type = DWORD, default = 2 Frequency of tick strings to be received = tik.start.Frequency data type = DWORD, default = 2

4.8 Defining Tracing

Natural Access provides a mechanism to log warning, error, and information messages (trace records) to a central location. These trace records are grouped into trace record categories.

A tracemask is used to determine which trace record categories are active (i.e., messages should be logged). Tracemasks are set by the application using ctaSetTraceLevel and by ctdaemon. See the Natural Access Developer's Reference Manual for more information on setting tracemasks.

The Natural Access dispatcher automatically generates trace records for the following trace record categories:

• Service API calls invoked via an application.

• Service SPI calls invoked via another service.

• Events generated by a Natural Access service and destined for the calling application.

• Events generated by a Natural Access service and destined for the calling service.

4.8.1 Service-Specific Trace Record Categories

For service-specific trace record categories, the service must explicitly generate the trace records. There are three service-specific trace record categories explicitly defined by Natural Access. They are:

• Commands issued by the service to a low level driver (or another process).

• Events received from the low level driver (or another process).

• Internal service errors.

There are four other service-specific categories (called "debug" categories) that can be used for any remaining trace records that are deemed appropriate for your service and do not fit into the explicitly defined categories.

To support service-specific trace categories, a service must:

• Define trace tags to represent the trace records.

• Check if appropriate tracemasks are set and call the trace logging function (dispLogTrace).

• Create binding functions to set local tracemasks (xxxSetTraceLevel) and generate trace records (xxxFormatTraceBuffer).

As shown in Figure 21, the application determines which trace record categories will be logged. Standard trace record categories (e.g., logging service API function calls) are handled by the dispatcher. Service-specific trace record categories (e.g., logging driver calls) must be checked and generated by the service.

Figure 21. Tracing Overview

4.8.2 Defining Trace Tags

For each service, decide which service-specific trace record categories to implement. For each category, define a set of one or more trace tags. The trace tag is used by the service to uniquely identify the trace record.

You are not required to define and implement service-specific trace records. However, it is strongly recommended to do so. Similarly, it is not required to implement trace records for each of the explicitly defined service-specific trace categories.

tik service	The TIK service supports service-specific trace processing. For the TIK service, there are no trace records for the internal service error category. Also, there is only one trace record per category. The specific tracing to be done is:
	Category	Associated Trace Mask	TIK Specific Trace Tags
	driver commands	CTA_TRACEMASK_DRIVER_COMMANDS	TIK_TRACETAG_CMD - Log messages sent from TIK service to TICK server.
	driver events	CTA_TRACEMASK_DRIVER_EVENTS	TIK_TRACETAG_RSP - Log events received from TICK server.
	service errors	CTA_TRACEMASK_SVC_ERRORS	none needed
	debug 1	CTA_TRACEMASK_DEBUG_BIT0	TIK_TRACETAG_BIT0 - Log internal state transitions.
	debug 2	CTA_TRACEMASK_DEBUG_BIT1	None needed.
	debug 3	CTA_TRACEMASK_DEBUG_BIT2	None needed.
	debug 4	CTA_TRACEMASK_DEBUG_BIT3	None needed.