CONTENTS

  Title Page

  Copyright Page

  Preface

  1      Introduction to DECmcc Management Modules

  1.1     DECmcc Management Modules

  1.2      DECmcc Access Modules
    1.2.1      Encoding and Decoding Management Requests
    1.2.2      Providing Optional Access Module Services

  1.3      DECmcc Function Modules

  1.4     DECmcc Management Module Development Stages
    1.4.1       Management Modeling
    1.4.2       The DECmcc Registry
    1.4.3       Management Specifications
    1.4.4       Internal Components of All Management Modules
      1.4.4.1      Internal Components Specific to Access Modules
    1.4.5      Dispatch Table Entries (Vector File)
    1.4.6      Management Module Help and Message Text
    1.4.7      DECmcc Management Module Development Tools

  1.5     DECmcc Sample Access Module and Example Function

  1.6      The DECmcc Development Environments

  1.7     The DECmcc Developer's Toolkit Documentation

  2      Modeling Manageable Entities

  2.1      Determining the Entities in a Network

  2.2     Management Requirements Analysis
    2.2.1      OSI Systems Management Model
    2.2.2      Devising Management Requirements Using DECmcc Directives
    2.2.3      Devising Management Requirements Using Entity Modularity
    2.2.4      Important Requirements
    2.2.5      Information Modeling Using Entity-Relationship Diagrams
    2.2.6      Analyzing Data Structures
    2.2.7      Determining Attribute Information
    2.2.8      Determining Event Information
    2.2.9      Considering Entity State
    2.2.10     Entity-Relationship Example

  2.3     Determining Entity Operations

  2.4     Naming Entity Classes and Entity Relationships

  2.5     External Factors
    2.5.1      Entity Model "Folklore"
    2.5.2      Standard Directive and Common Exception Definitions
    2.5.3      Services Offered and Required by Other Management Modules

  2.6      Iteration

  2.7      Documentation

  2.8     Registration

  2.9     Starting the Development Stage

  2.10    The DECmcc Sample AM and the Entity Design Process
    2.10.1     The Sample Access Module and the Requirements Analysis Phase
    2.10.2     The Sample Access Module and the Information Modeling Phase
    2.10.3     Sample Access Module Entity Hierarchy
    2.10.4     The Sample Access Module and the Entity Operations Phase
    2.10.5     The Sample Access Module and the Entity Naming Phase

  3      DECmcc Management Module Development Environment for VMS

  3.1      Overview of the DECmcc Management Module Development Environment

  3.2     DECmcc Dispatch Table (Vector File)

  3.3      DECmcc Event Pool

  3.4      DECmcc Data Dictionary

  3.5      Creating a DECmcc Developer's Dictionary

  3.6     DECmcc System Logical Names
    3.6.1      The MCC_component and MCC_component_LOG Logical Names

  3.7     Using a Callable DECmcc

  3.8      Creating and Maintaining Source Files
    3.8.1      DEC Code Management System (CMS)
    3.8.2      DEC/Module Management System (MMS)

  3.9      The DECmcc Management Module Development Cycle

  4      DECmcc Management Module Development Environment for ULTRIX

  4.1     Overview of the DECmcc Module Development Environment

  4.2     DECmcc Dispatch Tables

  4.3     DECmcc Event Pool

  4.4     DECmcc Data Dictionary

  4.5     Creating a DECmcc Developer's Dictionary

  4.6     DECmcc System Environment Variables
    4.6.1      The MCC_SYS_LOCATION Environment Variable
    4.6.2      The MCC_MMEXE_LOCATION Environment Variable
    4.6.3      The MCC_MSG_LOCATION Environment Variable
    4.6.4      The MCC_TIME_OUT_MODE Environment Variable
    4.6.5      The MCC_TIME_ABS_TRUNC Environment Variable
    4.6.6      The MCC_TIME_REL_TRUNC Environment Variable
    4.6.7      The MCC_<mm_component>_DEBUG Environment Variable
    4.6.8      The MCC_<mm_component>_LOG Environment Variable
    4.6.9      The MCC_DICT_NAME Environment Variable

  4.7     The DECmcc Management Module Development Cycle

  4.8      Using a Callable DEC

  5      Creating Management Specifications for a Management Module

  5.1     Overview of the Management Specification Language

  5.2     MSL and the DECmcc Registry

  5.3     MSL and Other Management Module Components

  5.4     Management Specification Language Components
    5.4.1      Management Specification Header
    5.4.2      Data Type Definitions
    5.4.3      Entity and Child Entity Definitions
    5.4.4      Attribute Partition Definition
      5.4.4.1      Attribute Definition
    5.4.5      Directive Definition

  5.5     Management Specification Language Translation

  6      Creating Dispatch Table Entries for a DECmcc Management Module

  6.1     Vector File Overview

  6.2     Vector File and Management Specifications

  6.3     Creating the Vector File

  6.4     Vector File for the Sample AM and Example FM

  6.5     Referencing the Macro Library and External Macros

  6.6     Specifying Dispatch Symbols and Structures

  6.7     Specifying a Program Section (Include for VMS Portability)

  6.8     Specifying the Transfer Vectors (Include for VMS Portability)

  6.9     Specifying the Vector File Macros
    6.9.1      Start Dispatch Table Macro
    6.9.2      Dispatch Entry Macro
    6.9.3      End Vector File Macro

  6.10    Creating a Unique Symbol Definition Code for a Dispatch Entry

  6.11    Processing A Dispatch Table on ULTRIX

  7      The Structure of a Management Module

  7.1     Overview of Access Module Design

  7.2     Overview of Function Module Design

  7.3     The Structure of a Management Module

  7.4     The DECmcc Sample Access Module

  7.5     The DECmcc Example Function Module

  7.6     Management Module Design

  7.7     Common Code:  Initialization Module and DECmcc Enrollment
    7.7.1      The Initialization Routine
    7.7.2      The Probe Routine
    7.7.3      The Log Routine

  7.8     Common Code:  The Self-Management Interface Module

  7.9     Common Code:  The Common Utilities Module

  7.10     Example FM Code:  The Service Interface Module

  7.11    Sample AM Code:  The Service Interface Module

  7.12    Sample AM Code:  Translation Module
    7.12.1      Encoding Within the Translation Module

  7.13    Sample AM Code:  Communications Services Module

  7.14    Advanced Management Module Design Considerations

  8      Creating and Enrolling Help for a DECmcc Management Module

  8.1     Overview

  8.2     DECmcc Management Module Help

  8.3     Help File Format Considerations

  8.4     Help File Examples

  8.5     Building and Verifying a Help File for VMS

  8.6     Building and Verifying a Help File for ULTRIX

  9      The MCC_CALL Interface

  9.1     The MCC_CALL Interface Hierarchy

  9.2     The MCC_CALL Interface Summary
    9.2.1      Verb
    9.2.2       In_entity
    9.2.3       Out_entity
    9.2.4      Partition
    9.2.5      Time_spec
    9.2.6       In_Q and Out_Q
    9.2.7       In_P and Out_P
    9.2.8       Time_stamp
    9.2.9      Handle
    9.2.10     Condition Values

  9.3     MCC_CALL_ACCESS Example

  10      Management Module Component Integration

  10.1    Overview

  10.2    A Simple Example of Management Module Component Integration

  10.3     MSL and the DECmcc Command Line Interface (FCL)

  10.4     MSL, ILV Encoding, and the MCC_CALL Arguments

  10.5    MSL and Response/Exception Coding
    10.5.1      Response and Exception Coding Examples
      10.5.1.1     XYZ Access Module Entry-Point Fragment
      10.5.1.2     An Exception Definition with No Arguments
      10.5.1.3     An Exception Definition with a Simple Argument
      10.5.1.4      A Response or Exception Definition with a Constructed Argument

  10.6    Devising a DECmcc Management Module Development Strategy

  11      Compiling, Linking, and Enrolling a DECmcc Management Module for VMS

  11.1     Compiling a Management Module

  11.2    Linker Requirements
    11.2.1      Creating the Options File for a DECmcc Management Module
    11.2.2      Link Option Requirements
    11.2.3      Linker Command

  11.3    Enrolling a Management Module

  11.4    Building the Sample Access Module

  11.5     Building the Example Function Module

  11.6    Packaging Your Management Module

  12      Compiling, Linking, and Enrolling a Management Module on ULTRIX

  12.1    Compiling a Management Module

  12.2    Linker Requirements

  12.3    Enrolling a Management Module

  12.4    Building the Sample Access Module

  12.5    Building the Example Function Module

  12.6    Packaging a Management Module

  13     Debugging and Testing a DECmcc Management Module on VMS

  13.1    Overview of the DECmcc VMS Debugging Environment

  13.2    Using the BREAK Command with the Test Bed Driver

  13.3    Using the Command Line Interface and LIB$SIGNAL

  13.4    Debugging a Management Module Without the Debugger

  13.5    Common DECmcc Management Module Development Problems

  14     Debugging and Testing a DECmcc Management Module for ULTRIX

  14.1    Overview of the ULTRIX Management Module Execution Model
    14.1.1      Enrollment
    14.1.2     Dispatching

  14.2    Overview of the DECmcc ULTRIX Debugging Environment

  14.3    Debugging a Management Module Without the Debugger

  14.4    Common DECmcc Management Module Development Problems

  15     DECmcc Design Framework Overview

  15.1    DECmcc Design Framework

  15.2    The DECmcc Design Framework Starter Management Module
    15.2.1      Design Framework Starter Management Module Functionality
    15.2.2      Running YOURMM

  15.3    Design Framework Internal Components
    15.3.1     The YOURMM Pseudoentity
    15.3.2     YOURMM Attribute Translation (Access Module Specific)
    15.3.3      YOURMM Directive Entry Points

  15.4    Design Framework Files
    15.4.1     Management Directive Entry Point Files
    15.4.2      Service Directive Entry Point Files
    15.4.3      Support Files
    15.4.4      Design Framework Object Library
    15.4.5      DECmcc Interface Files
    15.4.6      Design Framework Build Files

  15.5     Constructing Your Starter Management Module from the Design Framework

  15.6     Using the DECmcc Design Framework as a Starter FM

  15.7     Adding to the Starter Management Module
    15.7.1     Adding a Child Entity to the Starter Management Module

  15.8    Adding New Attributes
    15.8.1     Adding New Attributes to a pseudoEntity

  15.9    Adding New Directives

  16     The Design Framework Software Models

  16.1    The Software Models Used in the Design Framework

  16.2    Implementing Directives Using the Design Framework
    16.2.1     The .C File for a Directive
    16.2.2     The .H File for a Directive

  16.3    Maintaining a Local Context Block for a Directive

  16.4    Handle Management

  16.5    Reply Management

  16.6    The Call Arguments Interface
    16.6.1     Call Argument Validation
    16.6.2     Main Validation Table
    16.6.3     Verb Validation
    16.6.4     In_Entity Validation
    16.6.5     Attribute Validation
    16.6.6     Time Specification Validation
    16.6.7     In_Q Validation
    16.6.8     In_P Validation
    16.6.9     Handle Validation
    16.6.10    Out_Entity Validation
    16.6.11    Time_Stamp Validation
    16.6.12    Out_P Validation
    16.6.13    Out_Q Validation

  16.7    Memory Management Model

  16.8    Log Bit Model

  16.9    Attribute Translation Model

  16.10   Entity Simulation Model

  17      Management Module Portability Guidelines and Programming Considerations

  17.1     Use of Threads in the DECmcc Environment

  17.2     Use of Non-Reentrant C Runtime Routines

  17.3    Using the Common Ethernet Access Routines

  17.4    File Management in the Management Module Operating Environment

  17.5     Open File Considerations For ULTRIX

  17.6    Management Module Portability Guidelines
    17.6.1     Supporting Operating System Dependent Code in a Management Module
    17.6.2     Casting Arguments and Values Returned by Functions
    17.6.3     Using mcc_thread_create2
    17.6.4     Naming Routines
    17.6.5     Reusing #define
    17.6.6     Using Static Variables
    17.6.7     Using Constants Passed by Reference
    17.6.8     Referencing Arrays and Procedures
    17.6.9     Using Global Variables
    17.6.10    Using #module
    17.6.11    Using VMS Runtime Routines
    17.6.12    Full Pathnames for #include Directives
    17.6.13    Using Case to Distinguish Identifiers or External Names
    17.6.14    Byte Order or Alignment in Structures and Unions
    17.6.15    Processing Alert Terminate Requests

  18      Using the DECmcc Common Routines for Management Module Development

  18.1     Reasons for Using the DECmcc Common Routines

  18.2    DECmcc Data Storage in the Management Information Repository
    18.2.1     Overview of the Management Information Repository
    18.2.2     Entity Class Information
    18.2.3     Entity Instance Information
    18.2.4     Historical Information
    18.2.5     Private (Management Module) Information

  18.3    Reading Entity Class Data with the Dictionary Routines
    18.3.1     Introduction to Creating Dictionary Specifications
    18.3.2     Constructing Dictionary Specification Structures
      18.3.2.1     Example for Building a Dictionary Specification
    18.3.3     Reading Dictionary Data
      18.3.3.1     Reading Property Information from the Dictionary

  18.4    Reading and Writing Private Data with the MIR Routines
    18.4.1     What Is a Management Information Repository?
    18.4.2     Creating a Repository
      18.4.2.1     Creating Repositories and Reading Repository IDs
    18.4.3     Writing Data to a Repository
      18.4.3.1     Writing Data to a Repository
    18.4.4     Reading Data from a Repository
      18.4.4.1     Reading Data from a Repository

  18.5    Executing Multiple Tasks
    18.5.1     What Is a Thread?
    18.5.2     How to Use Threads in Your Management Module
      18.5.2.1     Child Thread Manipulation Example
    18.5.3     Special Considerations for Using Threads

  18.6     Manipulating Events
    18.6.1     The DECmcc Event Report
    18.6.2     The Get Event Directive
    18.6.3     The Event Manager and Event Pool
      18.6.3.1      The GETEVENT directive - init_handle_cancel
      18.6.3.2      The GETEVENT directive - do_directive
    18.6.4     Special Considerations

  18.7    Dumping MCC_EVENT_PUT and MCC_EVENT_GET Parameters

  A   DECmcc Design Framework Internal Utility Library Routines

  A.1      mcc_desframe_init_alloc_list

  A.2     mcc_desframe_alloc

  A.3      mcc_desframe_free_alloc_list

  A.4     mcc_desframe_create_descriptor

  A.5     mcc_desframe_set_cvr_and_reply

  A.6     mcc_desframe_append_error

  A.7     mcc_desframe_validate_callargs

  A.8     mcc_desframe_package_call_args

  B   DECmcc Design Framework Internal Utility Include Files

  B.1     dt_callargs

  B.2      dt_reply_arg_list

  B.3      dt_reply_table

  B.4      dt_comm_local_context

  B.5      dt_valid_callargs

  C   Registering an Entity in DECmcc

  C.1      Digital Distributed Name Service (DECdns)

  C.2     How DECmcc Uses DECdns
    C.2.1      Orphaned Attributes

  C.3     How DECmcc Supports the Registration FM Directives

  C.4     Supporting the Registration FM
    C.4.1      Simple Support for the Registration FM
    C.4.2      Complex Support for the Registration FM
    C.4.3      Using Registration Include Files in a Management Specification
      C.4.3.1      Including Registration Directives in the Sample MSL

  C.5     Storage Options for Orphaned Attributes
    C.5.1      Storing Orphaned Attributes in DECdns
    C.5.2      Storing Orphaned Attributes in a MIR Repository

  C.6     Example Of Supporting Advanced Registration Requirements

  D   DECmcc Debugging Worksheets

  D.1     Dispatch Errors

  D.2     Command Line Syntax Errors

  D.3      Solving Problems with the Dispatch Table

  D.4      Setting Up Vector Files (Dispatch Table) Correctly

  D.5     Changing Vector Files

  D.6     Avoiding Problems with Common Exceptions

  D.7      Avoiding Problems Running Commands Using the Command Line Interface

  D.8     VMS Dictionary Files, VMS Interdependencies

  D.9     ULTRIX Dictionary Files, ULTRIX Interdependencies

  D.10    Using MCC_BUILD_HELP.COM (VMS Only)

  D.11    Debugging Using the Forms and Command Line Presentation Module (PM)

  D.12    Setting Up MCC_SYSTEM or in ULTRIX MCC_SYS_LOCATION

  D.13    CVR Versus Exceptions

  E    DECmcc Registry

  E.1     Overview of the DECmcc Software Register

  E.2      Who Must Register Managed Objects

  E.3      What the DSR Registers

  E.4      What Managed Objects Need Not Be Registered

  E.5      Why Managed Objects Are Registered

  E.6      When to Register Managed Objects

  E.7      How the DSR Works

  E.8      Submitting a DSR Application Form

  E.9      What to Submit to the DSR for Registration

  E.10    How to Submit Your Registration Request
    E.10.1     Internet Submissions
    E.10.2     Magnetic Tape Or Floppy Disk Submissions

  E.11     What the DSR Does with Your Registration Request

  E.12     What to Do When You Receive Assigned Identifiers

  E.13    How to Register Additions to a Registered Object

  E.14    DSR Application Form

  E.15     Temporary Codes

  FIGURES

  1-1        Information Flow To and From a Managed Entity

  1-2        Encode/Decode Process

  1-3        DECmcc Function Module

  1-4        Development Flow

  1-5        Development Flow

  2-1        Entity-Relationship Diagram Example

  2-2        Containment Hierarchies

  2-3        Supported Attributes for the Sample Entity

  3-1        DECmcc Development Directories and Files for VMS

  3-2        DECmcc Development Directories and Files for VMS

  3-3        DECmcc Management Module Development Cycles

  4-1        DECmcc Development Directories and Files for ULTRIX

  4-2        DECmcc Development Directories and Files for ULTRIX (cont'd)

  4-3        DECmcc Management Module Development Cycle

  5-1        MSL Conceptual Format

  5-2        DECmcc Sample Access Module Management Specification Header

  5-3        DECmcc Sample Access Module Data Type Definition

  5-4        DECmcc Sample Access Module Global Entity Definition

  5-5        DECmcc Sample Access Module Status Attribute Partition Definition

  5-6        An Attribute Definition for the Sample Access Module

  6-1        Sample AM Vector File and Sample AM Image Entry Points

  6-2        Dispatch Template Summary

  6-3        Sample AM External Macro References

  6-4        Sample Access Module Dispatch Symbols and Structures

  6-5        Sample Access Module Program Section Dispatch Entry

  6-6        Sample Access Module Transfer Vector

  6-7        Start Vector File Macro for the Sample Access Module

  6-8        Dispatch Entry for Self-Management of the Sample Access Module

  7-1        Software Interfaces of a Management Module

  7-2        Sample Access Module Linkage to the User Interface

  7-3        Basic Access Module Design and Data Flow

  7-4        Example Function Module Linkage to the User Interface

  7-5        Basic Function Module Design and Data Flow

  7-6        FM and AM Module Design and Data Flow

  8-1        Basic Help File Format

  8-2        Sample Help File Entry

  9-1        Function Module to Access Module Relationship

  9-2        Function Module to Function Module Relationship

  9-3        Access Module to Access Module Relationship

  9-4        MCC_CALL Arguments Sent to and Received from a Management Module

  9-5        MCC_CALL Interface Arguments

  9-6        MCC_CALL Arguments and the DECmcc Routines

  9-7        MCC_CALL Interface Argument Summary for Service Caller and Service Provider

  9-8        MCC_CALL Interface Argument Summary for Service Caller and Service Provider

  9-9        MCC_CALL Interface Argument Summary for Service Caller and Service Provider

  9-10       MSL and Request/Response Information Buffers

  9-11       Encode/Decode Using In_P and Out_P

  10-1       MSL for XYZ Access Module

  10-2       Symbol File, Dispatch Entry and AM Entry-Point Code

  10-3       MSL and the DECmcc Command Line

  10-4       Contents of MCC_CALL Arguments

  10-5       ILV Dump of the OUT_P Argument Buffer

  10-6       MSL for an Exception with No Arguments

  10-7       ASCII Interpretation of Command Line OUT_P Dump for an Exception Without Arguments

  10-8       Command Line Dump of out_p for an Exception Without Arguments

  10-9       Command Line Output for an Exception Without Arguments

  10-10      MSL for an Exception with a Simple Argument

  10-11      ASCII Interpretation of OUT_P Dump for an Exception with a Simple Argument

  10-12      Dump of OUT_P for an Exception with a Simple Argument

  10-13      Message Output for an Exception with a Simple Argument

  10-14      MSL for a Response with a Constructed data type

  10-15      ASCII Interpretation of OUT_P Dump for a Response with a Constructed Argument

  10-16      Dump of OUT_P for a Response with a Constructed Argument

  10-17      Output for a Response with a Constructed Argument

  13-1       DECmcc Debugging Components

  13-2       Debugging Flow Using the Break Command and TBD

  13-3       The Debugging Flow Using the Command Line Interface

  14-1       DECmcc Execution Environment

  14-2       DECmcc Debugging Environment

  14-3       Contents of DECmcc Debugging Environment Windows

  15-1       Entity Hierarchy

  15-2       YOURMM Linkage to User Interface and DECmcc

  15-3       Basic Management Module Design and Data Flow of YOURMM

  15-4       Basic Management Module Design and Data Flow

  15-5       Basic Management Module Design and Data Flow

  15-6       Basic Management Module Design and Data Flow

  15-7       Design Framework Files

  15-8       Files to be Copied and Edited to Create a Child Entity

  15-9       Files to be Copied and Edited to Add Attributes

  15-10      Files to be Copied and Edited to Add Directives

  16-1       Pseudocode for a Directive's .C File

  16-2       Directive File Format

  16-3       Conceptual Structure of a Directive's .h File

  16-4       Context Block Data Structure

  16-5       Handle State Initialization

  16-6       Initialization of the Local Context Flags

  16-7       Directive Exit Code Actions

  16-8       Reply Table Data Type Definition

  16-9       Data Type Definition for the Reply Argument List

  16-10      Data Structure Relationships

  16-11      Reply Table Setup Example

  16-12      Call Argument Type Definition Structure

  16-13      Main Table Validation

  16-14      Call Argument Validation Data Type

  16-15      Header File Validation Definition

  16-16      Verb Validation

  16-17      Data Type Used to Define In-Entity Validation

  16-18      In_Entity Arguments Validation

  16-19      In_Entity Arguments Validation for excep_invalid_wildcard

  16-20      In_Entity Validation Example

  16-21      In_Entity Validation for a Verb with Multiple Combinations

  16-22      Attribute Validation Example

  16-23      Data Type Used to Define In_Q Argument Validation

  16-24      Valid Symbols for qual_id and qual_status

  16-25      In_Q Validation Example

  16-26      Data Type Used to Define In_P Validation

  16-27      In_P Validation Worksheet

  16-28      In_P Validation Example

  16-29      Data Type Used to Define Out_P Validation

  16-30      Log Bit Usage Example

  16-31      Log Bit Model Code for .h File

  16-32      Log Bit Model Code for .c File

  16-33      Attribute Translation Model

  16-34      Attribute Translation Data Structure

  16-35      Attribute Translation

  16-36      Set Directive

  16-37      MCC_YOURMM_PSEUDO_YOURMM.C

  16-38      MCC_YOURMM_PSEUDO_YOURMM.H

  17-1       Using #ifdef and #ifndef

  17-2       Casting Arguments and Values Returned by Functions

  17-3       The mcc_thread_create2 Routine

  17-4       Variable Initialization for VMS Only

  17-5       Variable Initialization for VMS and ULTRIX

  17-6       Constants Passed by Reference

  17-7       Declaring Global Variables

  17-8       Referencing A Global Variable

  17-9       Using #ifdef with #module

  18-1       The DECmcc Management Information Repository

  18-2       Management Information and Common Routines

  18-3       Entity Class Data

  18-4       Entity Class Data Structure

  18-5       Dictionary Specification for an Entity

  18-6       Dictionary Specification for Entity and Attribute

  18-7       Dictionary Specification for Entity, Attribute and Definition

  18-8       Entity, Directive and Exception Dictionary Specification

  18-9       Dictionary Specification Class Code Symbols

  18-10      Definition Instances - Constants

  18-11      time stamps and the MCC_MIR_WRITE_DATA Routine

  18-12      PONG Diretive Entry Point (Subroutines)

  18-13      GET EVENT

  C-1        DECmcc Use of DECdns Configuration Instance Repository

  C-2        Simple Registration Process

  C-3        Complex Registration Process

  C-4        Register Directive

  TABLES

  1 Conventions