NMS Logo

Natural Access Service Writer's Manual

P/N 6405-14
Version

Table of Contents NMS Glossary Previous Page Next Page Version

Table of Contents

1 Introduction

1.1 Introduction
1.2 What is Natural Access?
1.2.1 Types of Services
1.3 Natural Access Operation
1.3.1 Context
1.3.2 Event Queue
1.4 Natural Access Application Setup and Initialization
1.4.1 Initializing Natural Access
1.4.2 Creating Queues
1.4.3 Creating Contexts
1.4.4 Opening Services

2 Natural Access Architecture

2.1 Introduction
2.2 Review of Distributed Computing Concepts
2.2.1 Remote Procedure Call
2.3 Natural Access Architectural Model
2.3.1 Managed Resource
2.3.2 Service Implementation
2.3.3 Service API
2.3.4 Service SPI
2.3.5 Service Manager
2.3.6 Dispatcher
2.4 Dispatcher Functionality
2.4.1 Communications
2.4.2 Built-In Dispatcher Services
Service Setup
Command Processing
Event Handling
Error Handling
Parameter Management
Tracing
2.5 Summary

3 Writing a Natural Access Service - Overview

3.1 Introduction
3.2 Service Components
3.3 Service Name
3.4 Service ID
3.5 Software Structure
3.5.1 Binary Files
Source Files
3.6 Natural Access Coding Conventions
3.6.1 Function Names
3.6.2 Function Arguments
3.6.3 Return Values
3.6.4 Event and Reason Names
3.6.5 Error, Reason, Event, Command, and Trace Tag Codes
3.6.6 Manifest Constants and Enums
3.6.7 Structures
3.6.8 Parameter Structure Naming Convention
3.7 Writing a Service
3.7.1 Defining a Service
3.7.2 Implementing a Service
3.8 Sample Natural Access Service
3.8.1 Template Source Files

4 Defining a Service

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

5 Implementing the API

5.1 Introduction
5.2 Creating the Header Files
5.2.1 Defining the API Function Prototypes
5.2.2 Defining the API Function Command Codes
5.2.3 Defining Error Codes
5.2.4 Defining Event and Reason Codes
5.2.5 Defining the Trace Tags
5.3 Writing the API Function Code
5.3.1 Calling the SPI Function
5.3.2 Error Handling Macros
5.3.3 Example API Function
5.4 Declaring Parameters
5.4.1 Creating the Parameter Definition File
5.4.2 Generating the Parameter Files

6 Implementing the SPI

6.1 Introduction
6.2 Declaring SPI Function Prototypes
6.3 Implementing the SPI Functions
6.3.1 DISP_COMMAND Structure
6.3.2 Marshalling
6.3.3 Example SPI Function

7 Implementing the Service Manager

7.1 Introduction
7.2 Binding Function Overview
7.3 Life Cycle Binding Functions
7.4 Service Registration
7.4.1 xxxInitializeManager
Registering Binding Functions
Version and Compatibility Information
Specifying Version and Compatibility Levels
Initializing Global and Local Tracemasks
xxxInitializeManager Example
7.4.2 xxxDefineService
7.5 Initializing Managed Resource Event Handling
7.6 Service Startup
7.6.1 xxxOpenServiceManager
7.6.2 xxxOpenService
7.7 Event Handling Shutdown
7.8 Service Shutdown
7.8.1 xxxCloseService
7.8.2 xxxCloseServiceManager
7.9 Runtime Binding Functions
7.9.1 Command Processing
7.9.2 Error Handling
xxxGetText
xxxFormatMessage
7.9.3 Trace Handling
Setting Local TraceMask
Converting Trace Records to ASCII
7.9.4 Event Processing
7.10 Additional Binding Functions

8 Service Implementation

8.1 Introduction
8.2 Implementing Service Functions
8.2.1 Arguments to Service Implementation Functions
8.2.2 Handling Service Parameters as Function Arguments
8.3 Processing Events from the Managed Resource
8.4 Generating Trace Records

9 Function Summary

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

10 Alphabetical Function Reference

10.1 Introduction
10.2 Dispatcher Services
dispApiError
dispCheckParmByName
dispCreateHandle
dispDestroyHandle
dispError
dispGetHandleValue
dispGetParmByName
dispGetParms
dispGetQueueHandle
dispGetText
dispGetTracePointer
dispLogTrace
dispMakeAndQueueEvent
dispQueueEvent
dispRegisterService
dispRegisterServiceManager
dispRegisterWaitObject
dispSendCommand
dispSetHandleValue
dispSetParmByName
dispUnregisterWaitObject
10.3 Service Manager Binding Functions
xxxAttachServiceManager
xxxCloseService
xxxCloseServiceManager
xxxDefineService
xxxDetachServiceManager
xxxFormatMessage
xxxFormatTraceBuffer
xxxGetText
xxxInitializeManager
xxxOpenService
xxxOpenServiceManager
xxxProcessCommand
xxxProcessEvent
xxxSetTraceLevel

11 Demonstration Program and Utility

11.1 Introduction
11.2 TIK Service Test Program - tiktst
11.3 Parameter File Generation Utility - pf2src

Appendix A Errors and Events

Introduction
Alphabetical Error Summary
Numerical Error Summary
Events

Table of Contents NMS Glossary Previous Page Next Page Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com
Copyright © 2001, Natural MicroSystems, Inc. All rights reserved.