This document describes a proposed public interface through which an application, such as a network management console, interacts with an Asynchronous Management Protocol (AMP) Manager via a database supporting the Structured Query Language (SQL). The use of SQL as an interfacing layer provides a natural way to describe interactions with an AMP Manager independent of a particular implementation of either the Manager or the application. Specifically, this document presents a database schema capturing how to send controls to a Manager and how to accept reports received by a Manager from one or more AMP Agents.

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

1. Introduction

This document presents a public interface through which an application, such as a network management console, interacts with an Asynchronous Management Protocol ([AMP]) Manager via a database supporting the Structured Query Language (SQL). Such an interface is useful as an implementation independent way of specifying how an application may interact with an AMP Manager to issue commands (such as through a custom graphical user interface) and to receive reports (as they are received by one or more AMP Agents).

1.1. Purpose

This document describes a database layout comprised of a series of names tables and the columns the comprise those tables. Where appropriate, primary and foreign key constraints are also discussed. This set of tables presents a data model through which all AMP Manager roles and responsibilities, as defined in the Asynchronous Management Architecture ([AMA]), can be accomplished.

Application developers can use this specification to describe how to populate a database with AMP-related information such that an AMP Manager implementation can read and use this data to effect AMP behavior. By reading and writing the tables in accordance with this specification, applications can claim conformance with the AMP Manager regardless of which AMP Manager implementation is used, so long as such a Manager is also in conformance with this specification.

AMP Manager developers use this specification to describe how AMP users input actions to the Manager and how to send received reports back to those users.

1.2. Scope

This document covers table names and the names, data types, default values, and comments associated with each column of each names table. These types should be appropriate for any database implementing a SQL interface and SHOULD NOT use any language or function specific to a particular SQL database vendor.

This document does not specify the setup, configuration, administration, or other function associated with a particular SQL database vendor. Further, this document does not specify how either the application or the AMP Manager log on to the database, or how database communications are verified and secured. Finally, this document does not discuss the architecture associated with incorporating a database between an application and an AMP Manager, as such architectures are likely tightly coupled to a network deployment.

1.3. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].

2. Conventions

2.1. Table Naming

This specification uses a naming convention to delineate between two types of database tables: those containing mutable data and those containing immutable data. Tables containing mutable data are named with the prefix "dbt" where tables containing immutable data are named with the prefix "lvt", as defined below.

3. Database Overview

This specification assumes that all tables exist in a database called "amp_core", capturing the information necessary to capture core operations associated with the AMP Manager.

The schema contains tables capturing information about various areas of the AMP Manager interface. The following table types are defined.

+-------------------------+------------------------+
| Table Name              | Table Type             |
+-------------------------+------------------------+
| lvtDataTypes            | Constants              |
| lvtIncomingState        | Constants              |
| lvtMIDCategory          | Constants              |
| lvtMIDOIDType           | Constants              |
| lvtMIDType              | Constants              |
| lvtOutgoingState        | Constants              |                             
| dbtADMNicknames         | ADM Support            |
| dbtADMs                 | ADM Support            |
| dbtProtoMIDParameter    | ADM Support            |
| dbtProtoMIDParameters   | ADM Support            |
| dbtProtoMIDs            | ADM Support            |
| dbtRegisteredAgents     | Agent Support          |                                             
| dbtDataCollection       | MID Information        |
| dbtDataCollections      | MID Information        |
| dbtMIDCollection        | MID Information        |
| dbtMIDCollections       | MID Information        |
| dbtMIDs                 | MID Information        |
| dbtOIDs                 | MID Information        |
| dbtOutgoingMessageGroup | Outgoing Support       |
| dbtOutgoingMessages     | Outgoing Support       |                     
| dbtIncomingMessageGroup | Incoming Support       |
| dbtIncomingMessages     | Incoming Support       |
+-------------------------+------------------------+

Figure 1: amp_core tables

The specification comprises 16 dbt tables and 7 lvt tables, as in Figure 1.

4. Constants

4.1. Data Types - lvtDataTypes

Data types, as defined in the AMP, enumerate the types of information associated with collections of data, such as defined in MID parameters, computed values, and report definitions.

+-------------+------------------+------+-----+---------+-------+
| Field       | Type             | Null | Key | Default | Extra |
+-------------+------------------+------+-----+---------+-------+
| ID          | int(10) unsigned | NO   | PRI | NULL    |       |
| Name        | varchar(50)      | NO   | UNI |         |       |
| Description | varchar(255)     | NO   |     |         |       |
+-------------+------------------+------+-----+---------+-------+

lvtDataTypes

The format of the table is as follows.

ID: The primary key for this table, and the enumerated value of the data type from the AMP specification.
Name: The name associated with this data type.
Description: The description associated with this data type.

+----+--------+-------------------------------------+
| ID | Name   | Description                         |
+----+--------+-------------------------------------+
|  0 | BYTE   | 8-bits; Standard Byte               |
|  1 | INT    | Signed 32-bit Integer               |
|  2 | UINT   | Unsigned 32-bit Integer             |
|  3 | VAST   | Signed 64-bit Integer               |
|  4 | UVAST  | Unsigned 64-bit Integer             |
|  5 | REAL32 | Single-Precision Floating Point     |
|  6 | REAL64 | Double-Precision Floating Point     |
|  7 | STR    | Character String                    |
|  8 | BLOB   | Binary Large Object (Length + Data) |
|  9 | SDNV   | Self-Delineating Numerical Value    |
| 10 | TS     | Timestamp                           |
| 11 | DC     | Data Collection                     |
| 12 | MID    | Managed Identifier                  |
| 13 | MC     | Managed Identifier Collection       |
| 14 | EXPR   | Expression                          |
| 15 | DEF    | Definition                          |
| 16 | TRL    | Time-Based Rule                     |
| 17 | SRL    | State-Based Rule                    |
| 18 | TDC    | Typed Data Collection               |
| 19 | RPT    | Report                              |
| 20 | MACRO  | Macro                               |
| 21 | UNK    | Unknown Type                        |
+----+--------+-------------------------------------+

lvtDataTypes Example

An example of such a table is illustrated below.

4.2. Incoming State - lvtIncomingState

When reports are being received by a Manager from an Agent, they will be written into various Incoming Support table types. However, the application reviewing these incoming reports should not start to read them until the Manager has finished receiving and persisting them into the database.

+-------------+---------------------+------+-----+---------+-------+
| Field       | Type                | Null | Key | Default | Extra |
+-------------+---------------------+------+-----+---------+-------+
| ID          | tinyint(3) unsigned | NO   | PRI | NULL    |       |
| Name        | varchar(50)         | NO   |     |         |       |
| Description | varchar(255)        | NO   |     |         |       |
+-------------+---------------------+------+-----+---------+-------+

lvtIncomingState

The lvtIncomingState table identifies three different wait states associated with receiving reports from Agents. The format of the table is defined as follows.

ID

The primary key for this table, and the enumerated value of the incoming state. Three states are defined in this specification, as follows.

0 - Initializing: This state signifies that a Manager is receiving a set of information and rows associated with this state should not be read by an application.
1 - Ready: This state signifies that a Manager has completed receiving reports and that rows associated with this state may be processed by an application.
2 - Processed: This state signifies that an application has completed processing reports and that either a Manager or an application can remove rows associated with this state at any time.

Name

The name associated with the incoming state (Initializing, Ready, Processed).

Description

The description associated with the incoming state.

+----+--------------+-----------------------------------------+
| ID | Name         | Description                             |
+----+--------------+-----------------------------------------+
|  0 | Initializing | Manager is receiving reports.           |
|  1 | Ready        | Manager has completed reception.        |
|  2 | Processed    | Application is done processing reports. |
+----+--------------+-----------------------------------------+

lvtIncomingState Example

An example of such a table is illustrated below.

4.3. MID Category - lvtMIDCategory

+-------------+------------------+------+-----+---------+-------+
| Field       | Type             | Null | Key | Default | Extra |
+-------------+------------------+------+-----+---------+-------+
| ID          | int(10) unsigned | NO   | PRI | NULL    |       |
| Name        | varchar(50)      | NO   | UNI |         |       |
| Description | varchar(255)     | NO   |     |         |       |
+-------------+------------------+------+-----+---------+-------+

lvtMIDCategory

The lvtMIDCategory table identifies the three different MID categories as defined in the AMP. The format of the table is defined as follows.

ID: The primary key for this table, and the enumerated value of the MID category.
Name: The name associated with the MID Category (Atomic, Computed, Collection).
Description: The description associated with the MID Category.

+----+------------+-----------------+
| ID | Name       | Description     |
+----+------------+-----------------+
|  0 | Atomic     | Measured Values |
|  1 | Computed   | Computed Values |
|  2 | Collection | Array of Values |
+----+------------+-----------------+

lvtMIDCategory Example

An example of such a table is illustrated below.

4.4. OID Category - lvtMIDOIDType

+-------------+------------------+------+-----+---------+-------+
| Field       | Type             | Null | Key | Default | Extra |
+-------------+------------------+------+-----+---------+-------+
| ID          | int(10) unsigned | NO   | PRI | NULL    |       |
| Name        | varchar(50)      | NO   | UNI |         |       |
| Description | varchar(255)     | NO   |     |         |       |
+-------------+------------------+------+-----+---------+-------+

lvtMIDOIDType

The lvtMIDOIDType table identifies the four different OID categories as defined in the AMP. The format of the table is defined as follows.

ID: The primary key for this table, and the enumerated value of the OID category.
Name: The name associated with the OID Category.
Description: The description associated with the OID Category.

+----+------------------------------+-------------+
| ID | Name                         | Description |
+----+------------------------------+-------------+
|  0 | Full OID                     |             |
|  1 | Parameterized OID            |             |
|  2 | Compressed Full OID          |             |
|  3 | Compressed Parameterized OID |             |
+----+------------------------------+-------------+

lvtMIDOIDType Example

An example of such a table is illustrated below.

4.5. MID Type - lvtMIDType

+-------------+------------------+------+-----+---------+-------+
| Field       | Type             | Null | Key | Default | Extra |
+-------------+------------------+------+-----+---------+-------+
| ID          | int(10) unsigned | NO   | PRI | NULL    |       |
| Name        | varchar(50)      | NO   | UNI |         |       |
| Description | varchar(255)     | NO   |     |         |       |
+-------------+------------------+------+-----+---------+-------+

lvtMIDType

The lvtMIDType table identifies the four different MID types as defined in the AMP. The format of the table is defined as follows.

ID: The primary key for this table, and the enumerated value of the MID type.
Name: The name associated with the MID type.
Description: The description associated with the MID type.

+----+----------+-------------+
| ID | Name     | Description |
+----+----------+-------------+
|  0 | Data     |             |
|  1 | Control  |             |
|  2 | Literal  |             |
|  3 | Operator |             |
+----+----------+-------------+

lvtMIDType Example

An example of such a table is illustrated below.

4.6. Outgoing State - lvtOutgoingState

When controls are being sent via a Manager to an Agent, they will be written into various Outgoing Support table types. However, the Manager receiving these outgoing controls should not start to read them until the application has finished writing them into the database.

+-------------+--------------+------+-----+---------+-------+
| Field       | Type         | Null | Key | Default | Extra |
+-------------+--------------+------+-----+---------+-------+
| ID          | tinyint(4)   | NO   | PRI | NULL    |       |
| Name        | varchar(50)  | NO   |     |         |       |
| Description | varchar(255) | NO   |     |         |       |
+-------------+--------------+------+-----+---------+-------+

lvtOutgoingState

The lvtOutgoingState table identifies four different wait states associated with sending controls to Agents. The format of the table is defined as follows.

ID

The primary key for this table, and the enumerated value of the outgoing state. Four states are defined in this specification, as follows.

0 - Initializing: This state signifies that an application is preparing a set of controls and rows associated with this state should not be read by a Manager.
1 - Ready: This state signifies that an application has completed preparing the controls and that rows associated with this state may be processed by the Manager for sending to one or more Agents.
2 - Processing: This state signifies that the Manager is in the process of sending associated controls to one or more Agents. Rows in this state should not be modified by an application as it could affect the controls sent by the Manager.
3 - Sent: This state signifies that the Manager has completed sending the set of controls and that either a Manager or an application can remove rows associated with this state at any time.

Name

The name associated with the outgoing state (Initializing, Ready, Processing, Sent).

Description

The description associated with the outgoing state.

+----+--------------+---------------------------------+
| ID | Name         | Description                     |
+----+--------------+---------------------------------+
|  0 | Initializing | Application writing controls.   |
|  1 | Ready        | Ready for Sending to Agent.     |
|  2 | Processing   | Manager sending controls.       |
|  3 | Sent         | Manager send completed.         |
+----+--------------+---------------------------------+

lvtOutgoingState Example

An example of such a table is illustrated below.

5. ADM Support

5.1. ADM Nicknames - dbtADMNicknames

+----------------+------------------+------+-----+------------+-----------+
| Field          | Type             | Null | Key | Default    | Extra     |
+----------------+------------------+------+-----+------------+-----------+
| ID             | int(10) unsigned | NO   | PRI | NULL       | auto_incr |
| ADM_ID         | int(10) unsigned | NO   | MUL | NULL       |           |
| Nickname_UID   | int(10) unsigned | NO   |     | NULL       |           |
| Nickname_Label | varchar(25)      | NO   |     | ""         |           |
| OID            | int(10) unsigned | NO   | MUL | NULL       |           |
+----------------+------------------+------+-----+------------+-----------+

dbtADMNicknames

The dbtADMNicknames table identifies all of the nicknames associated with supported ADMs. A Nickname in the AMA is an enumeration of a common OID subtree defined in the context of an ADM. Nickname enumerations MUST be unique. The format of the table is defined as follows.

ID: The primary key for this table.
ADM_ID: This is a foreign key into the dbtADMs table and identifies the ADM that defined this nickname.
Nickname_UID: The globally unique enumeration of the common OID subtree.
Nickname_Label: A description of the nickname (e.g., "Agent ADM Reports").
OID: This is a foreign key into the dbtOIDs table and points to the common OID associated with this nickname.

5.2. Supported ADMs - dbtADMs

+---------+------------------+------+-----+---------+----------------+
| Field   | Type             | Null | Key | Default | Extra          |
+---------+------------------+------+-----+---------+----------------+
| ID      | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
| Label   | varchar(255)     | NO   | UNI |         |                |
| Version | varchar(255)     | NO   |     |         |                |
| OID     | int(10) unsigned | NO   | MUL | NULL    |                |
+---------+------------------+------+-----+---------+----------------+

dbtADMs

The dbtADMs table identifies all of the ADMs supported by the AMP Manager and associated application. The format of the table is as follows.

ID: The primary key for this table.
Label: The name of the supported ADM.
Version: The string representing the version of the ADM. A string is used to allow for a variety of version formats.
OID: This is a foreign key into the dbtOIDs table and points to the common OID associated with this ADM, if the ADM defines such a common OID.

5.3. ProtoMIDs

MIDs identifying items such as Controls may accept parameters to customize their behavior. When defined in the context of an ADM, a parameterized MID only includes the non-parameterized portion of the MID followed by the expected data types for the parameterized portion of the MID. This, essentially, acts as a template for populating a specific instance of the MID with actual data.

This "template" is referred to as a protoMID, as it is used to generate MID instances. The amp_core database schema identifies three tables used to capture protoMID definitions from ADMs: dbtProtoMIDParameter, dbtProtoMIDParameters, and dbtProtoMIDs.

5.3.1. Individual MID Parameter - dbtProtoMIDParameter

+-----------------+------------------+------+-----+---------+-----------+
| Field           | Type             | Null | Key | Default | Extra     |
+-----------------+------------------+------+-----+---------+-----------+
| ID              | int(10) unsigned | NO   | PRI | NULL    | auto_incr |
| CollectionID    | int(10) unsigned | YES  | MUL | NULL    |           |
| ParameterOrder  | int(10) unsigned | NO   |     | 0       |           |
| ParameterTypeID | int(10) unsigned | YES  | MUL | NULL    |           |
+-----------------+------------------+------+-----+---------+-----------+

dbtProtoMIDParameter

The dbtProtoMIDParameter table contains a row for each parameter associated with a protoMID. All of the parameters for a protoMID, together, are considered a "collection" of parameters. The format of the table is as follows.

ID: The primary key for this table.
CollectionID: The name of the collection for this parameter. A parameter collection is the ordered set of parameters that describe a ProtoMID. This is a foreign key into the dbtProtoMIDParameters table.
ParameterOrder: The 0-based ordering of this parameter within the collection.
ParameterTypeID: The type of this parameter. This must be one of the known AMP types and, as such, is a foreign key into the lvtDataTypes table.

5.3.2. MID Parameter Collection - dbtProtoMIDParameters

+---------+------------------+------+-----+------------+----------------+
| Field   | Type             | Null | Key | Default    | Extra          |
+---------+------------------+------+-----+------------+----------------+
| ID      | int(10) unsigned | NO   | PRI | NULL       | auto_increment |
| Comment | varchar(255)     | NO   |     | No Comment |                |
+---------+------------------+------+-----+------------+----------------+

dbtProtoMIDParameters

The dbtProtoMIDParameters table represents the ordered set of parameters associated with a ProtoMID. The format of the table is as follows.

ID: The primary key for this table.
Comment: A human-readable description of the collection. It is recommended that this reference the ProtoMID whose parameter collection is being represented (e.g, "Parameters for AddReportDefinition(MID id, MC contents)").

5.3.3. ProtoMIDs - dbtProtoMIDs

+--------------+------------------+------+-----+----------------+----------+
| Field        | Type             | Null | Key | Default        | Extra    |
+--------------+------------------+------+-----+----------------+----------+
| ID           | int(10) unsigned | NO   | PRI | NULL           | auto_inc |
| NicknameID   | int(10) unsigned | YES  | MUL | NULL           |          |
| OID          | int(10) unsigned | NO   | MUL | NULL           |          |
| ParametersID | int(10) unsigned | YES  | MUL | NULL           |          |
| DataType     | int(10) unsigned | NO   | MUL | 0              |          |
| OIDType      | int(10) unsigned | NO   | MUL | 0              |          |
| Type         | int(10) unsigned | NO   | MUL | 0              |          |
| Category     | int(10) unsigned | NO   | MUL | 0              |          |
| Name         | varchar(50)      | NO   |     | Unnamed        |          |
| Description  | varchar(255)     | NO   |     | No Description |          |
+--------------+------------------+------+-----+----------------+----------+

dbtProtoMIDs

The dbtProtoMIDs table stores all known ProtoMIDs. The format of the table is as follows.

ID: The primary key for this table.
NicknameID: The nickname associated with this MID, if applicable. This is a foreign key into the dbtADMNicknames table.
OID: The OID associated with the ProtoMID. This is a foreign key into the dbtOIDs table.
ParametersID: The parameter collection for this ProtoMID. This is a foreign key into the dbtProtoMIDParameters table.
DataType: The data type associated with this MID. This is a foreign key into the lvtDataTypes table.
OIDType: The type of OID encapsulated by this ProtoMID. This is a foreign key into the lvtMIDOIDType table.
Type: The type of MID encapsulated by this ProtoMID. This is a foreign key into the lvtMIDType table.
Type: The category of MID encapsulated by this ProtoMID. This is a foreign key into the lvtMIDCategory table.
Name: A human-readable name for this ProtoMID.
Comment: A human-readable description of the ProtoMID.

6. Agent Support

6.1. Registered Agents - dbtRegisteredAgents

+---------+------------------+------+-----+---------+----------------+
| Field   | Type             | Null | Key | Default | Extra          |
+---------+------------------+------+-----+---------+----------------+
| ID      | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
| AgentId | varchar(128)     | NO   |     | ipn:0.0 |                |
+---------+------------------+------+-----+---------+----------------+

dbtRegisteredAgents

The dbtRegisteredAgents table lists the network identifiers for each Agent known in the network. The format of the table is defined as follows.

ID: The primary key for this table.
AgentId: This is the identifier for the Agent, suitable for passing into a network send call. A string representation is selected to best capture the identifier format for a particular network.

7. MID Information

7.1. Data Collections

Data collection tables capture the Data Collection (DC) data type as defined in [AMP]. Similar to the ProtoMIDParameter(s) table, Data Collections are represented as an ordered collection of individual data items, with one table representing the collection itself, and another table holding the ordered data within the collection.

7.1.1. Data Collection Entry - dbtDataCollection

+--------------+------------------+------+-----+---------+-------+
| Field        | Type             | Null | Key | Default | Extra |
+--------------+------------------+------+-----+---------+-------+
| CollectionID | int(10) unsigned | NO   | PRI | NULL    |       |
| DataOrder    | int(10) unsigned | NO   | PRI | 0       |       |
| DataType     | int(10) unsigned | NO   | MUL | NULL    |       |
| DataBlob     | blob             | YES  |     | NULL    |       |
+--------------+------------------+------+-----+---------+-------+

dbtDataCollection

The dbtDataCollection table holds data collection entries, one per row. The format of the table is defined as follows.

CollectionID: The Data Collection to which this entry belongs.
DataOrder: The 0-based order of this entry in the encapsulating collection.
DataType: The type of this data collection. This is a foreign key to the lvtDataTypes table.
DataBlob: The binary value of the data collection entry in hexadecimal. This string does not include a pre-pended "0x" and should assume that two characters, together, form a single byte. Therefore, the hex value 0xBEEFFEED would be represented as the string value 'BEEFFEED'.

7.1.2. Data Collection - dbtDataCollections

+-------+------------------+------+-----+----------+----------------+
| Field | Type             | Null | Key | Default  | Extra          |
+-------+------------------+------+-----+----------+----------------+
| ID    | int(10) unsigned | NO   | PRI | NULL     | auto_increment |
| Label | varchar(255)     | NO   |     | Unnamed  |                |
+-------+------------------+------+-----+----------+----------------+

dbtDataCollections

The dbtDataCollections table holds information for a particular collection of data entries (from dbtDataCollection). The format of the table is defined as follows.

ID: The Data Collection identifier.
Label: A human-readable description of the Data Collection.

7.2. MID Collections

A MID Collection is an ordered set of MID values, similar to a Data Collection, which is an ordered set of Data values. One table is used to represent the MID Collection, and another table is used to capture the ordered MIDs in the collection.

7.2.1. MID Collection Entry - dbtMIDCollection

+--------------+------------------+------+-----+---------+-------+
| Field        | Type             | Null | Key | Default | Extra |
+--------------+------------------+------+-----+---------+-------+
| CollectionID | int(10) unsigned | NO   | PRI | NULL    |       |
| MidID        | int(10) unsigned | NO   | PRI | NULL    |       |
| MIDOrder     | int(10) unsigned | NO   | PRI | 0       |       |
+--------------+------------------+------+-----+---------+-------+

dbtMIDCollection

The dbtMIDCollection table holds MID collection entries, one per row. The format of the table is defined as follows.

CollectionID: The MID Collection to which this entry belongs.
MidID: The identifier for this MID. This is a foreign key into the dbtMIDs table.
MIDOrder: The 0-based order of this entry in the encapsulating collection.

7.2.2. MID Collection - dbtMIDCollections

+---------+------------------+------+-----+---------+----------------+
| Field   | Type             | Null | Key | Default | Extra          |
+---------+------------------+------+-----+---------+----------------+
| ID      | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
| Comment | varchar(255)     | YES  |     | NULL    |                |
+---------+------------------+------+-----+---------+----------------+

dbtMIDCollections

The dbtMIDCollections table holds information for a particular collection of MIDs (from dbtMIDCollection). The format of the table is defined as follows.

ID: The MID Collection identifier.
Label: A human-readable description of the MID Collection.

7.3. MIDs - dbtMIDs

+--------------+---------------------+------+-----+----------+-------------+
| Field        | Type                | Null | Key | Default  | Extra       |
+--------------+---------------------+------+-----+----------+-------------+
| ID           | int(10) unsigned    | NO   | PRI | NULL     | auto_incr   |
| NicknameID   | int(10) unsigned    | YES  | MUL | NULL     |             |
| OID          | int(10) unsigned    | NO   | MUL | NULL     |             |
| ParametersID | int(10) unsigned    | YES  | MUL | NULL     |             |
| Type         | int(10) unsigned    | NO   | MUL | NULL     |             |
| Category     | int(10) unsigned    | NO   | MUL | NULL     |             |
| IssuerFlag   | bit(1)              | NO   |     | b'0'     |             |
| TagFlag      | bit(1)              | NO   |     | b'0'     |             |
| OIDType      | int(10) unsigned    | YES  | MUL | NULL     |             |
| IssuerID     | bigint(20) unsigned | NO   |     | 0        |             |
| TagValue     | bigint(20) unsigned | NO   |     | 0        |             |
| DataType     | int(10) unsigned    | NO   | MUL | NULL     |             |
| Name         | varchar(50)         | NO   |     | Unnamed  |             |
| Description  | varchar(255)        | NO   |     | None     |             |
+--------------+---------------------+------+-----+----------+-------------+

dbtMIDs

The dbtMIDs table captures the MIDs in the database. Some MIDs will be auto-populated from ADMs. Others will be added dynamically by users of the system. As per [AMP], a MID without an identified Issuer field is assumed to be as defined in an ADM. The format of the table is defined as follows.

ID: The primary key for this table.
NicknameID: The Nickname associated with this MID, if the encapsulated OID is a compressed OID. This is an optional field but, if present, is a foreign key into the dbtADMNicknames table.
OID: The OID of the encapsulated MID. This is a foreign key into the dbtOIDs table.
ParametersID: The parameters associated with this MID, if this MID encapsulates a parameterized OID. This is a foreign key in the dbtDataCollections table, as parameters are captured as a Data Collection.
Type: The type associated with this MID. This is a foreign key into the lvtMIDType table.
Category: The category associated with this MID. This is a foreign key into the lvtMIDCategory table.
IssuerFlag: A binary value representing whether the MID has an issuer field (value 1) or not (value 0).
TagFlag: A binary value representing whether the MID has a tag field (value 1) or not (value 0).
OIDType: The type of the encapsulated OID. This is a foreign key into the lvtMIDOIDType table.
IssuerID: The optional Issuer of the MID, to be NOT NULL if the IssuerFlag is set to 1, and NULL otherwise. The IssuerID is captured in a hexadecimal binary value. It is currently assumed that the IssuerID will not exceed 64 bits.
TagValue: The optional Tag of the MID, to be NOT NULL if the TagFlag is set to 1, and NULL otherwise. The TagValue is captured in a hexadecimal binary value. It is currently assumed that the TagValue will not exceed 64 bits in length.
DataType: The data type associated with this MID. This is a foreign key into the lvtDataTypes table.
Name: A human-readable string representation of the MID Name.
TagValue: A human-readable string representation of the MID Description.

7.4. OIDs - dbtOIDs

+-------------+------------------+------+-----+------------+-----------+
| Field       | Type             | Null | Key | Default    | Extra     |
+-------------+------------------+------+-----+------------+-----------+
| ID          | int(10) unsigned | NO   | PRI | NULL       | auto_incr |
| IRI_Label   | varchar(255)     | NO   | MUL | NONE       |           |
| Dot_Label   | varchar(255)     | NO   |     | 1.2.3.4    |           |
| Encoded     | varchar(255)     | NO   |     | BEEFFEED   |           |
| Description | varchar(255)     | NO   |     | None       |           |
+-------------+------------------+------+-----+------------+-----------+

dbtOIDs

The dbtOIDs table captures the Object Identifiers encapsulated in a MID. For Full OIDs, this includes the length and octet set captured using Binary Encoding Rules (BER), as specified in [AMP]. For compressed OIDs, this includes the relative OID from some root tree, also encoded as a length and octet set captured using BER. The format of the table is defined as follows.

ID: The primary key for this table.
IRI_Label: The Internationalized Resource Identifier (IRI) representation for this OID.
Dot_Label: The dot notation representation of this OID.
Encoded: The BER-encoded representation of this OID, in hexadecimal. This string does not include a pre-pended "0x" and should assume that two characters, together, form a single byte. Therefore, the hex value 0xBEEFFEED would be represented as the string value 'BEEFFEED'.
Description: A human-readable description of the OID.

8. Outgoing Message Support

Outgoing messages are those that are written into the database by an application and read by an AMP Manager, formatted, and sent to one or more AMP Agents.

The database represents outgoing messages in two tables. One table holds information for the entire outgoing message group, and another table captures each individual outgoing message. An individual outgoing message is simply a MID collection of the MIDs to be run on the Agent.

8.1. Outgoing Messages - dbtOutgoingMessages

+------------+------------------+------+-----+---------+----------------+
| Field      | Type             | Null | Key | Default | Extra          |
+------------+------------------+------+-----+---------+----------------+
| ID         | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
| OutgoingID | int(10) unsigned | NO   | MUL | NULL    |                |
| StartTS    | bigint(20)       | NO   |     | 0       |                |
| MidCollID  | int(10) unsigned | NO   | MUL | NULL    |                |
+------------+------------------+------+-----+---------+----------------+

dbtOutgoingMessages

The dbtOutgoingMessages table captures a single MID Collection holding the set of Control MIDs to be sent to an Agent as part of a Message Group. The format of the table is defined as follows.

ID: The primary key for this table.
OutgoingID: The outgoing message group to which this outgoing message belongs. This is a foreign key into the dbtOutgoingMessageGroup table.
StartTS: The time at which the controls in the MID Collection should be run. This may be an absolute or relative time, as defined in [AMP]
MidCollID: The MID Collection comprising this outgoing message. This is a foreign key into the dbtMIDCollections table.

8.2. Outgoing Message Groups - dbtOutgoingMessageGroup

+------------+------------------+------+-----+---------+----------------+
| Field      | Type             | Null | Key | Default | Extra          |
+------------+------------------+------+-----+---------+----------------+
| ID         | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
| CreatedTS  | datetime         | YES  |     | NULL    |                |
| ModifiedTS | datetime         | YES  |     | NULL    |                |
| State      | tinyint(4)       | NO   | MUL | NULL    |                |
| AgentID    | int(10) unsigned | NO   | MUL | NULL    |                |
+------------+------------------+------+-----+---------+----------------+

dbtOutgoingMessageGroup

The dbtOutgoingMessageGroup table captures an outgoing message group, which is one or more outgoing messages. The format of the table is defined as follows.

ID: The primary key for this table.
CreatedTS: The time at which the outgoing message group was created.
ModifiedTS: The last time at which the message group was modified.
State: The current state of the outgoing message group. This state provides a contention-avoidance mechanism between an application and an AMP Manager. This is foreign keyed into the lvtOutgoingState table.
AgentID: The identifier of the Agent receiving this message group. Currently, a message group is only sent to one Agent. Sending to multiple Agents is accomplished with multiple entries in this table. This is a foreign key into the dbtRegisteredAgents table.

9. Incoming Message Support

Incoming messages are those that are written into the database by an AMP Manager and read by an application wishing to understand the status of an AMP Agent.

The database represents incoming messages in two tables. One table holds information for the entire incoming message group, and another table captures each individual incoming message.

9.1. Incoming Messages - dbtIncomingMessages

+------------+------------------+------+-----+---------+----------------+
| Field      | Type             | Null | Key | Default | Extra          |
+------------+------------------+------+-----+---------+----------------+
| ID         | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
| IncomingID | int(10) unsigned | NO   | MUL | NULL    |                |
| Content    | blob             | YES  |     | NULL    |                |
+------------+------------------+------+-----+---------+----------------+

dbtIncomingMessages

The dbtIncomingMessages table captures information returned from an AMP Agent. The format of the table is defined as follows.

ID: The primary key for this table.
IncomingID: The incoming message group to which this incoming message belongs. This is a foreign key into the dbtIncomingMessageGroup table.
Content: A Blob representing the raw values returned by an AMP Agent as passed through an AMP Manager.

9.2. Incoming Message Groups - dbtIncomingMessageGroup

+-------------+---------------------+------+-----+---------+-----------+
| Field       | Type                | Null | Key | Default | Extra     |
+-------------+---------------------+------+-----+---------+-----------+
| ID          | int(10) unsigned    | NO   | PRI | NULL    | auto_incr |
| ReceivedTS  | datetime            | YES  |     | NULL    |           |
| GeneratedTS | datetime            | YES  |     | NULL    |           |
| State       | tinyint(3) unsigned | NO   | MUL | NULL    |           |
| AgentID     | int(10) unsigned    | NO   | MUL | NULL    |           |
+-------------+---------------------+------+-----+---------+-----------+

dbtIncomingMessageGroup

The dbtIncomingMessageGroup table captures an incoming message group, which is one or more incoming messages. The format of the table is defined as follows.

ID: The primary key for this table.
ReceivedTS: The time at which the incoming message group was received by the AMP Manager.
GeneratedTS: The time at which the incoming message group was generated by the sending AMP Agent.
State: The current state of the incoming message group. This state provides a contention-avoidance mechanism between an application and an AMP Manager. This is foreign keyed into the lvtIncomingState table.
AgentID: The identifier of the Agent sending this incoming message group.

10. IANA Considerations

At this time, this schema definition has no fields registered by IANA.

11. Security Considerations

Security considerations are outside of the scope of this document.

12. Normative References

[AMA]	Birrane, E., "Asynchronous Management Architecture", Internet-Draft draft-birrane-dtn-ama-01, August 2015.
[AMP]	Birrane, E., "Asynchronous Management Protocol", Internet-Draft draft-birrane-dtn-amp-01, August 2015.
[RFC2119]	Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.

Appendix A. Acknowledgements

The following participants contributed technical material, use cases, and useful thoughts on the overall approach to this database specification: Leor Bleir of the NASA Goddard Space Flight Center, Michael Deschu and Shane Knudsen of Hammers Company, Inc. on behalf of the NASA Goddard Space Flight Center, and Paul Swencon of ASRC Space And Defense on behalf of the NASA Goddard Space Flight Center.

Authors' Addresses

Mark A. Sinkiat ASRC Space And Defense, NASA GSFC EMail: mark.a.sinkiat@nasa.gov

Samantha K. Jacobs Johns Hopkins Applied Physics Laboratory EMail: Samantha.Jacobs@jhuapl.edu

Edward J. Birrane Johns Hopkins Applied Physics Laboratory EMail: Edward.Birrane@jhuapl.edu