Pegasus Enhancement Proposal (PEP)

PEP #: 245

Title: Incorporation of CIM_Error into OpenPegasus Infrastructure

Authors: Mike Brasher, Karl Schopmeyer

Type: Functional PEP

Version History:

Version Date Status Authors Change Description
1.0 18 feb. 2006 draft K. Schopmeyer Initial Submission
1.1 21 April 2006 draft K. Schopmeyer Extend with corrections from initial review.  Also adds details on the infrastructure implementation.
1.2 12 June 2006 draft K. Schopmeyer, M. Brasher Fix comments from V 1.1
1.3 5 Sept 2006 draft K. Schopmeyer, M. Brasher Fix comments from V 1.2
1.4 27 Sept 06 draft K. Schopmeyer

M.Brasher

 Fix Editorial Comments from 1.3. Note that this is a functional PEP.

 

Abstract: Proposal for infrastructure functionality for incorporation of CIM_Error into OpenPegasus 2.6. This is an extension to incorporate the DMTF defined functionality to allow CIM_Error instances to be created by the server and passed to the client as components of cim/xml. This PEP defines the infrastructure and a set of APIs within the server and client.  It does not define the changes needed to incorporate DMTF defined message catalogs because those catalogs have not been defined to date.  This should be considered phase 1 of a multiphase project.  This PEP defines the basic requirements, DMTF definition of the functionality, API changes and functional changes to allow creating cim_error instances, moving them from the server to the client, and accessing them in the client.

NOTE: This PEP was approved for Pegasus 2.6 in Architecture Team ballot 122 on 29 September 2006

Proposed Externally Visible Changes: Modification of Exception APIs to generate CIM_Error messages in the CIMServer and providers and to extract CIM_Errors transmitted from a CIMServer. Modification of the CIM/XML transmitted from server to client to pass any CIM_Error instances generated by the server for a particular operation along with the existing information (status code and description)  in the ERROR element.

1. Problem Statement

The DMTF Specifications now specify as an option the ability to supplement the existing error information generated by CIM Servers with additional information defined as instances of the DMTF Class CIM_Error. This has been in the specifications for several versions now and there are a number of OpenPegasus users interested in implementing this functionality.

2. Requirements, Constraints or Assumptions

  1. Implement the functionality to defined and create CIM_Error information into CIM Server response messages based on the DMTF definitions.
  2. Implement this in a manner that allows backward compatibility both for servers and clients that do not implement the functionality within the DMTF constraints.  In general, we must assure that what we provide on the client side continues to work for servers that do not provide CIM_Error information and that the CIM_Error information we provide does not break existing clients.  This should not require anything special from the Pegasus client or server.  The client will be designed so that CIM_Error information is always optional. It is expected that since the CIM_Error additions on the CIM/XML encoding are optional, their existence in a response for a client that does NOT expect them should not cause the client to break.  The DMTF rules require that the client simply ignore them.  However, during the period of testing and particularly interoperability testing, it would be helpful if there was a means that Pegasus could be flagged to NOT send CIM_Error information simply as a means to aid testing.
  3. Pegasus must provide the additional CIM_Error responses required by the HTTP specification section 2.3.1.3. This means that Pegasus must be capable of providing instances of CIM_Error representing the detailed error information required in addition to the error code now supplied.
  4. The Pegasus CIM Client must be capable of dealing with both servers that are capable of returning the additional error information and those that are NOT capable of returning this information.
  5. The Pegasus CIM Listener infrastructure must be capable of delivering the error definitions defined in the HTTP specification 2.4.1.3 as response to indications received. The Client MUST be capable of operating with exactly the same error definitions that exist today.
  6.  The existing exception mechanism with the existing codes must continue to operate. We cannot break backward compatibility.
  7. There is a requirement for provider exception generation to be backward compatible. There is also a requirement for providers to be able to generate CIM_Error exceptions. The generation of CIM_Error based messages is NOT exclusively a server function.  In fact, today, the first use as defined in the SNIA SMI-s specification would be messages probably generated by providers.
     

3. Acceptance Criteria

The acceptance criteria for this PEP are;

1. Acceptance of the overall concepts for CIM_Error defined in the PEP.

2. Acceptance of the proposal for Pegasus infrastructure and Interface modifications defined in the PEP to support CIMError.

4. Proposed Solution

4.1 Overview

CIM_Error is a DMTF defined extension to the CIM Model and HTTP Operations that extends CIM operation errors from the simple set of errors defined today to a more general error processing model where Operation errors are encapsulated in a Class (CIM_Error class which is already in the model) and instances of this class are transmitted with the response in addition to the simple error code that is transmitted today. This new capability must be backward compatible. The existing mechanism MUST BE kept in place and the CIM_Error reporting added to the existing functionality. Thus, all of the structure for error reporting and error generation must be kept and this capability added.

This document is the concept PEP that lays out the reviews the requirements, and lays out the architecture for the proposed solutions.

4.2 Proposed Activity List

We propose that the total activity for CIM_Error incorporation into Pegasus be broken into two separate phases:

Phase 1 -  Define the concept and define and implement the common infrastructure so that CIM_Errors can be defined, attached to responses in the server and can be gotten and analyzed by the CIMClient. When phase one is complete server and provider components will be able to generate CIM_Error instances that a CIMClient can use and the Pegasus CIMClient will be able to work with received CIM_Error messages.

Phase 1 consists of the following steps:

  1. Define overview of required functionality to reach agreement within Pegasus Architecture team on goals and overall functionality. This is this Concept PEP.  The initial versions of this PEP represented the concepts.
  2. Write Functional PEP defining the required detailed changes to Pegasus and Pegasus APIs. This is a Functional PEP in Pegasus Terms. Note that it may not be necessary to create separate PEPs if the work is determined to be not to extensive. That will be determined as we proceed.
  3. Implement the infrastructure components and any API extensions so that CIM_Errors can be created in the server and providers, processed through Pegasus and extracted in Clients. This version of this PEP represents the implementation of the infrastructure changes to create CIM_Errors in the server, pass them in the client, and for the client application to request them.
  4. Create test programs for the modified infrastructure, both unit tests and end-end tests.

Phase 2 - Modification of OpenPegasus implementation to use CIM_Error internally as part of generating errors within the server and Pegasus standard providers.  Phase two will be represented by a separate PEP (PEP 263).

The activity is broken into these two phases because, while all of the basic definitions required to implement phase one are in place today, much of the background necessary to implement phase 2 are simply not in place because of dependence on the DMTF message catalogs. We are dependent on at least some understanding of the DMTF standard message catalogs and catalog structures or suffer the real risk of creating something that is incompatible with DMTF directions.

  1. Implement changes to the CIMServer and any Pegasus defined providers that are part of the Pegasus CVS to incorporate CIM_Error processing. Note that this MAY also include some changes to the Clients in the Pegasus CVS to account for CIM_errors that are generated in addition to the current error code.

4.3 Proposed Dates for these Activities

The final dates are unclear today because the due date for 2.6 is unclear. This is probably in the range of Q2 or Q3 2006. However, it is also clear that we need to get the requirements and design pinned down much earlier for a number of reasons including : 1. Time to do it right, 2) possible delays in discussions with DMTF, 3) Symantec interested in seeing movement on this issue which they are paying us to do.

Based on the above, the following is an initial estimate of dates (See the schedule section for more detail on dates an progress):

  1. Mar 10 2006 - Concept PEP available.
  2. Apr 1 2006 - Detailed Function PEP for infrastructure available. NOTE: We intend that this PEP serve both as the concept PEP and the functional PEP for phase one
  3. Apr 30 2006 - Infrastructure Code Functionally Complete and ready for commit to 2.6 CVS.
  4. Phase Two - Modifications to the calls to add creating CIM_Errors. This objective has no defined date so far because it is unclear how extensive the changes will be or how much the standard DMTF error message catalogs, etc. must be taken into account or even modified to make this work. However, we believe that this is still within the scope of Pegasus 2.6.

4.4 Proposed responsibility for Activities

Inova Development will take responsibility for defining and implementing the infrastructure. This includes:

- Completing this PEP. Inova Development would like to work in conjunction with other interested parties in completing this PEP. - Any additional PEPs involved in defining the infrastructure, CIM_Error object, and APIs for inputting and retrieving CIM_Error data. - Implementing this client and server infrastructure and tests for the changes to the Pegasus infrastructure.

- Inova Development will produce the infrastructure corresponding to this  PEP including test programs to provide a complete tested infrastructure.

However, the changes to actually move to the new APIs  that defines specific CIM_Errors for Pegasus Exceptions and includes CIM_Error information in the Pegasus environment is fairly extensive and also depends on the existence of DMTF message catalogs. We feel that this will require cooperation from a number of people and groups and may extend over a long period of time as the DMTF develops error message catalogs. Therefore Inova Development does NOT want to take sole responsibility for this work.

4.5 DMTF Specification Background

This section provides background on the specifications that are driving this work.
  1. CIM Model - CIM_Error class. Currently experimental and in the model starting about CIM 2.8 or 2.9.
  2. CIM Operations over HTTP (v 1.2 Preliminary) - See CRs below
  3. DSP 201 (V 2.2 Preliminary) - Representation of CIM in XMLCIM XML - (See CRs below and details of the changes in the following sections)

It appears that all of the CRs defined below have been incorporated into the the DMTF specifications so that the list of CRs below is provided only for background information. Note that the CR references may not be universally available since they require DMTF membership.

CRs applicable to this issue

  1. CR 909 - CIM_Error incorporation into the model. (cim 2.8 OR 9)
  2. CR 910 - New “Exception” Qualifier. (in Spec dsp0004, VERSION 2.3)
  3. CR 913 - Extensions to Interop specifications to support the return of detailed error information (August 2002)
  4. CR 1252 - CIM_Error Company review feedback changes, Feb 2004
  5. CR 1341 - Add CIM_Error “Message” properties to CIM_AlertIndication to Event model
  6. CR 1251 - (CIMOp over HTTP 1.2, CIM XML V2.2, XML DTD V2.3) DetailError Change : allow return of multiple instances of CIM_Error. (Interop144)
  7. CR 1253 - (CIM V2.9 Preliminary) CIM_Error.MessageFormatString Company review feedback changes in the Interop Model. (interop146)
  8. CR 1273 - (CIM V2.9) - Add Status Code and Description to CIM_Error to Interop model - (Interop147)
  9. CR 1308 - (CIM V2.9 Preliminary) Add Status Code and Description to CIM_Error in Interop model (Interop147.005)
  10. CR 1309 - (CIM Ops over HTTP 1.2.0) Clarify handling of CIM_Error.CIMStatusCode (Interop158)
  11. CR 1341 - (CIM V2.9 Preliminary) Add CIM_Error “Message” properties to CIM_AlertIndication to Event model

Applicable DMTF Specification Sections

The following sections of the CIM Specifications treat the CIM_Error Functionality
CIM Operations over HTTP Spec (1.2 Preliminary)
The following sections of the CIM Operations over HTTP Specification were modified in version 1.2 prelim to incorporate CIM_Error extensions:

2.3.1.3. Status Codes

This section defines the status codes and detailed error information that may be returned by a conforming CIM Server application. The value of an <ERROR> subelement within a <METHODRESPONSE> or <IMETHODRESPONSE> element includes

  1. a mandatory status code,
  2. an optional human-readable description of the status code,
  3. and zero or more CIM_Error instances.

The following table defines the status codes that may be returned by a conforming CIM Server application as the value of the CODE attribute of an <ERROR> subelement. In addition to returning a status code, a conforming CIM Server MAY return zero or more <INSTANCE> subelements as part of an <ERROR> element. Each <INSTANCE> subelement MUST be an instance of CIM_Error. For each instance of CIM_Error, the value of CIMStatusCode MUST comply with the definition of expected error codes for the CIM Operation Request. A CIM Client MAY ignore any <INSTANCE> subelements.

The symbolic names defined in the table below do not appear on the wire. They are used here solely as a convenient way to refer to an error in other parts of this specification.

Not all methods would be expected to return all the status codes listed below. For intrinsic methods, the relevant section on each method in this specification defines the expected error codes to be returned. For extrinsic methods the specification of which of the following codes can be used is described in the section on Extrinsic Method Invocation .

2.4.1.3. Status Codes

This section defines the status codes and detailed error information that may be returned by a conforming CIM Listener. The value of an <ERROR> subelement within a <EXPMETHODRESPONSE> element includes

  1. a mandatory status code,
  2. an optional human-readable description of the status code,
  3. and zero or more CIM_Error instances.

The symbolic names defined in the table below do not appear on the wire. They are used here solely as a convenient way to refer to an error in other parts of this specification.

Not all methods would be expected to return all the status codes listed below.

In addition to returning a status code, a conforming CIM Listener MAY return zero or more <INSTANCE> subelements as part of an <ERROR> element. Each <INSTANCE> subelement MUST be an instance of CIM_Error. For each instance of CIM_Error, the value of CIMStatusCode MUST comply with the definition of expected error codes for the CIM Export Request. A CIM Client MAY ignore any <INSTANCE> subelements.

XML Spec Specific paragraphs (Version 2.2 Preliminary)

The following sections of the Representation of CIM in XML Specification (V 2.2, Preliminary) include references to the CIM_Error extension:

3.2.6.12. ERROR

The ERROR element is used to define a fundamental error which prevented a method from executing normally. It consists of a status code, an optional description and zero or more instances containing detailed information about the error.

<!ELEMENT ERROR (INSTANCE*) <!ATTLIST ERROR CODE CDATA #REQUIRED DESCRIPTION CDATA #IMPLIED>

The CODE attribute contains a numerical status code indicating the nature of the error. The valid status codes are defined in [9]. The DESCRIPTION attribute, if present, provides a human-readable description of the error.

Sections describe operations that can product ERRORs

3.2.6.10. METHODRESPONSE

The METHODRESPONSE defines the response to a single CIM extrinsic method invocation. It contains either an ERROR subelement (to report a fundamental error which prevented the method from executing), or a combination of an optional return value and zero or more out parameter values.

<!ELEMENT METHODRESPONSE (ERROR|(RETURNVALUE?,PARAMVALUE*))> <!ATTLIST METHODRESPONSE %CIMName>

The NAME attribute defines the name of the method that was invoked.

3.2.6.11. IMETHODRESPONSE

The IMETHODRESPONSE defines the response to a single intrinsic CIM method invocation. It contains either an ERROR subelement (to report a fundamental error which prevented the method from executing), or an optional return value. <!ELEMENT IMETHODRESPONSE (ERROR|IRETURNVALUE?)> <!ATTLIST IMETHODRESPONSE %CIMName>

The NAME attribute defines the name of the method that was invoked.

3.2.6.20. EXPMETHODRESPONSE

The EXPMETHODRESPONSE defines the response to a single export method invocation. It contains either an ERROR subelement (to report a fundamental error which prevented the method from executing), or an optional return value.

<!ELEMENT EXPMETHODRESPONSE (ERROR|IRETURNVALUE?)> <!ATTLIST EXPMETHODRESPONSE %CIMName>

The NAME attribute defines the name of the export method that was invoked.

3.2.6.23. SIMPLEREQACK

The SIMPLEREQACK defines the acknowledgement response to a Simple CIM Operation asynchronous request. The ERROR subelement is used to report a fundamental error which prevented the asynchronous request from being initiated.

<!ELEMENT SIMPLEREQACK (ERROR?)> <!ATTLIST SIMPLEREQACK INSTANCEID CDATA #REQUIRED>

The InstanceID attribute is a string that uniquely identifies, within the scope of the responding entity, the asynchronous request.

4.6 Open Issues and Current Question List

  1. What are the issues of internationalization for CIM_Error messages? There are some issues here in that while Pegasus implements internationalization of our internal messages (Exceptions), we do not implement internationalization of CIM Class/instance information today. The introduction of CIM_Error begins to marry the issues of internationalization between errors which we do internationalize and CIM Classes in the form of the CIM_Error class. Thus, while Pegasus does not generally implement internationalization of CIM Models today, it is expected that the text within the CIM_Error instances may well be internationalized because much of this is derived from the current Pegasus internationalized error message mechanisms.
  2. Mixing CIM_Error and chunking - There is a significant issue in mixing CIM_error and chunking.  (See 4.7.1 below)
  3. Issues with multiple definitions for StatusCode - It became apparent during the work that we have multiple different definitions today for CIMStatus code.  In the file Common/CIMStatusCode.h we include codes 1 - 17.  In the current CIM Operations specification there are two additional codes (19 and 20 (skipping 18).  Finally in the CIM_Error class, there are now all 20 codes. This is a DMTF issue that will have to be resolved with a DMTF/WIP CR.
  4. Relationship of the ERROR element StatusCode and description to the similar information contained in the CIM_Error instances. (See 4.7.3 below)
  5. CIM_Error Class existence in the repository (See 4.7.2 below).

4.7 Discussion of Open Issues

4.7.1 Mixing CIM_Error and Chunking

Today the DMTF CIM/XML definition does not allow the xml error entity to exist on a response for which objects are included.  However, the concept of chunking is that responses could be started before the full size and content of the response is known.  If a response has been started, and an error is found, there is no way to include the xml error entity (to which the CIM_error components are attached).  This issue is discussed in a special section below.  Today, the cim_error functionality can be tested by turning off chunking so that the entire reponse is generated before the first response component is transmitted.  However, that is unacceptable as a long term solution.

The current definition of the IMEDTHODRESPONSE in the DMTF CIMXML specification is:

The IMETHODRESPONSE defines the response to a single intrinsic CIM method invocation.  It contains either an ERROR subelement (to report a fundamental error which prevented the method from executing), or an optional return value.
 

<!ELEMENT IMETHODRESPONSE (ERROR|IRETURNVALUE?)>
<!ATTLIST IMETHODRESPONSE
           %CIMName;>

The NAME attribute defines the name of the method that was invoked.

However, in the case of chunked responses,  Pegasus, at least, may begin returning response information before the response has been completly generated. This is true for and of the operations that return multiple objects such as enumerates, assocations, etc. Note that this is independt of whether there are multiple providers involved in the response. In this case,  the server may be committed to the IRETURNVALUE response before finding out that what should be returned is an ERROR response. With the current specification, there is NO way to append the ERROR response to the already transmitted IRETURNVALUE response.

Today, Pegasus handles this issue by NOT sending an ERROR response at all if the IRETURNVALUE has already begun transmission.  Instead, it puts the error code and description into the trailer of the response message as follows:

HTTP/1.1 200 OK
Content-Type: application/xml; charset="utf-8"
transfer-encoding: chunked
CIMOperation: MethodResponse
Trailer: CIMStatusCode, CIMStatusCodeDescription, Content-Language
CIMStatusCode: 5
CIMStatusCodeDescription: CIM_ERR_INVALID_CLASS%3A%20The%20specified%20class%20d
oes%20not%20exist%3A%20%22blah%22

If Pegasus turns off the chunking/segmenting feature of responses, it properly responses with an XML ERROR entity.

However, there is no way within the current specifications for the server to first start the output and then switch to providing the error reponse through the ERROR entity.  Note that this is not an issue with CIM_Error. It is a problem that started with chunking and the implication that chunking could lead to more efficient CIM_Server responses by allowing the responses to be incrementally returned before they were completely gathered.  The text and DTD definitions clearly define the syntax  the IMETHODRESPONSE  to include either  ERROR or IRETURNVALUE. Thus once the IRETURNVALUE has started output there is no way to append the ERROR entity.

At the same time as this error becomes apparent, it is clearly not a logical option to return to the mechanism whereby a complete return message must be generated before a response can be started.  The inefficiency of this method for large responses is so significant that it should not be considered an option. 

SOLUTIONS for the Chunking Problem

At this point the most probably solution is to propose an extension to CIM/XML whereby the error entity could be attached after the IRETURNVALUE entity in a response.  Thus, the xml DTD would be extended to provide new methods such as the one below: NOTE: New methods are required for backward compatibility

 <!ELEMENT EIMETHODRESPONSE (( ERROR|IRETURNVALUE? ) | ( IRETURNVALUE  ERROR? ) )>
<!ATTLIST EIMETHODRESPONSE
           %CIMName;>

ACTIONS: This change is not something that can be implemented specifically by Pegasus. It must be a change to the CIM/XML specification. We propose that this change be proposed immediately as a CR to the DMTF WIP work group.

COMMENT ON THIS ISSUE(12 June 2006)/KS: Today this issue is in the early stages of discussion with the DMTF WIP group.  However, since the change proposed above creates a situation where data and errors could both be sent from the server, it immediately opened the door to the issue of partial responses and errors and whether this should be considered.  I believe today that the WIP group does consider this particular issue just a bug but the discussion has not yet run its course so we do not have a resolution.

COMMENT ON THIS ISSUE 7 Sept 2006)/KS: CRs have been prepared and are being submitted to the WIP working group now.  There is a CR specifically to provide the new RESPONSE elements where data and ERROR elements can be mixed and a second CR to provide some additional headers that will be required to fully support chunking and server segmenting.

However, this issue should not stop us from completing our implementation with that outstanding issue.  Just as today where we do not receive the ERROR element with chunked responses, we would not receive the ERROR element AND is corresponding CIM_Error attachments with chunked responses until this issue is resolved.

4.7.2 Issue of CIM_Error versioning and CIM_Error existence in the repository namespaces

<<<This section is new with version 1.2>>>

One of the earlier comments to this PEP asked questions about versioning of the CIM_Error class and the tie between instances of CIM_Error generated by responses and namespaces.  There  were there questions of versions of the CIM_Error class, is it required in each namespace, etc.

There are, however,  issues that should be considered:

a. What version of the Class CIM_Error is implemented in any particular Pegasus version in CIMError and its corresponding C++ facade? We have no way to provide this information today and really do not have it documented right now.  Further, since generally we are NOT providing qualifiers with CIM_Error instances provided back to the provider, there is no way for the provider to know this. This the CIMError version will be documented in the CIMError.h file which will suffice for now, especially if we use CIMError only internally within the CIMServer environment.

b. The API allows the translation between instances of the CIM_Error facade class and real CIM_Instances.  Thus, it allows the introduction of instances that might be generated as real CIM_Instances to be put into CIM_Errors.  This process does not today consider any versioning of the CIM_Error class.  What do we do in the future if the CIM_Error class grows or is modified?  This is particularly important because today CIM_Error in the CIM 2.13 model is still experimental and subject to any possible change (PLEASE CHECK THIS).  This means that a) our CIMError implementation should probably remain experimental, b) we should probably use the CIMError facade only internally and not make it part of the public API at least until the DMTF CIM_Error is changed from Experimental status.

4.7.3 Relation of ERROR Element Status and Information to Information in CIM_Error

With the advent of the CIM_Error element into the CIM/XML encoding, there could be both Status/Description properties in the ERROR element and also in the the CIM_Error object(s). There is no interoperable behavior defined for the relationship between these entities.  Discussions have indicated that one logical solution is to ignore any information in the ERROR element if CIM_Error instances exist and to use the information from the instance(s). This could be logical if it was defined as interoperable behavior but this still leaves the issue of multiple CIM_Error instances.

NOTE: For the infrastructure component defined in this PEP, we will require that the Server/Provider CIM_Exception creation interfaces provide both the ERROR information and the CIM_Error instances and leave any resolution to resolution in the DMTF.

4.8 Overall Architecture of CIM_Error Handling

CIM_Error is an extension to the Server-Client operations protocol to allow:

This change is considered an extension to the existing error handling and operates by adding information to the error mechanisms in the CIMServer and CIMListener, not by completely replacing them.

For OpenPegasus this represents changes in several areas:

Pegasus CIM Server

  1. Extension of Server error generation to possibly generate more specific errors and passage of possibly multiple errors from the source in the server or provider where they are generated to the code that prepares responses (xmlwriter). The mechanism will be extended by defining a new C++ Class (CIM_error) that can be attached to exceptions generated within the server and providers. Thus, the generator of a CIMException will have the capability to add a detailed CIM_Error instance to the Exception.
  2. Expansion of the operation  response and xml generation mechanism in the xmlwriter to prepare more complex error indications than the error data/or/code response that is generated today. The xml generation mechanism in the server (src/Pegasus/Server/CIMOperationResponseCoder.cpp must be expanded to provide for expanding CIM_Error instances attached to the response message into xml and attaching them to the error response message.

Pegasus CIM Client Extensions

  1. Extension of the Pegasus client  infrastructure (src/Pegasus/CIMClient/CIMClient.cpp and src/Pegasus/CIMCLient/CIMOperationResponseDecoder.cpp) to accept this more complex error information and process it. Note that this must allow compatibility with the existing client interface and not change the behavior of existing client applications. This means that when an existing client is used, this code MUST provide the same code and error interface to the client that is used today despite the fact that it is receiving  more information from the server.
  2. Extension of the client to provide an additional mechanism to pass this information to the client application if desired by the application. It is assumed that future client applications will want to make use of this additional information and therefore will want access to the details of the errors returned. The use of the additional information must be optional (it will be the client application responsibility to request CIM_Error information). This is consistent with the form today where the base information is simply an exception try/catch and the error status information can be requested within the catch block. The client application will be able to access CIM_error information through additinal methods on the Exception ( ex. to get count of CIM_Errors attached and to get each error instance).

Pegasus CIM Listener Export Server

Extend the Listener infrastructure to support returning instances of CIM_Error in addition to error codes.

NOTE: It is not clear today if there will be any extension to the listener itself or if CIM_Errors can be completely implemented at the infrastructure level.

Pegasus CIM/XML Export Client

Extend to expect and handle the additional error codes from CIM_Listeners.   It is assumed that in the initial implementation, CIM_Errors received would simply be logged.

4.9 Public OpenPegasus API Extensions

This PEP proposes that the following additional Public Interfaces be added to Pegasus.  We expect that they would be considered experimental for Pegasus 2.6 but would hope to remove this limitation by Pegasus 2.7

1. The C++ Facade for the CIM_Error class. This is required by a) the CIM Server, b) CIM Clients accessing CIM_Error information, c) CIM Providers that wish to generate CIM_errors in addition to those that would be generated internally by specific exception calls.

2. Extensions to CIMException to allow CIM Clients to access CIM_error information when exceptions are generated at the client.  This includes the additional methods to return CIM_error information pertaining to the CIMException.

3. Extensions to CIMException to allow construction of CIMExceptions that contain CIM_Error elements and to manipulate these elements (add, count, remove, access) which are attached to a CIMException.

3. (PHASE 2) Extensions to specific CIM_Exceptions to provide additional information required to create CIM_Error enabled exceptions.  Note that these exception extensions are NOT defined in the current proposal because there is NO clear definition of the CIM_Errors that would be attached and the exact information to be generated.

4.10 Mating this concept to DMTF MessageIDs

The goal of CIM_Error is not only to provide more detailed error information but to provide it based on standard catalogs of messages defined by standards organizations such as the DMTF and SNIA.  If an implementation simply creates more detailed errors, it does not solve the issues of interoperable programable reaction to errors. The error reporting may be standard but it is not really interoperable.  By having specifications for catalogs of messages, the messages for many errors can be standardized so that clients can react in a common manner.

Today there is a work group in DMTF responsible for the CIM_Messages work.  However, this group today is concentrating on the commonality of formats, the tools, etc.  It does not yet have a set of common CIM_Errors that could be applied to Pegasus.

Today, Pegasus includes within the infrastructure and those providers that have been internationalized about 1500 separate error responses defined (this count is from the message files).  Eventually, the goal would be that the majority of these messages be standard CIM_Error messages.  This cannot be done until such time as there are messages to which we could standardize.

However, provision of the CIM_Error infrastructure and the standard api extensions for the providers will allow providers today to start using CIM_Error as the means of generating errors with more specific information as that information is defined in other specifications.

Therefore, we propose a multiphase project as defined below.

4.11 Project Phasing

This extension requires change to a number of different components in the Pegasus environment (CIM_Listener, CIM Client, CIM Server). It is clear that not all of the components need to be completed nor do all of the functionality tied to each component be complete for this to be a usable function. However, it is logical to finish this work completely as part of the Pegasus 2.6 release to provide a complete release. Generally it would appear that the following is a logical ordering:

PHASE 1 - Extension of Infrastructure (PEP 245)

  1. CIM_Error Class - Define the new Class CIM_Error that will create a single instance of a CIMInstance representing a CIM_Error. This class will include both the basic constructor, assign, copy, and setters and getters for the various properties in the CIMError class. This class will construct a CIM_Instance for the CIM_Error class. See section Pegasus Cxx Class Implementation.
  2. CIMServer Infrastructure - This includes the xml generation of CIMError instances with the CIMError XML element for responses, modifications to the response message infrastructure(CIMMessage.*), to CIMException to accept CIM_error input as a component of exceptions, and other components of the response aggregation that must be modified to allow gathering multiple CIM_Error instances into the aggregated response message and insuring that the cim_error instances are kept as the segmented message is  passed through the system so that the ERROR element encoder has a complete set of CIM_error instances available to generate the xml representations as part of the ERROR response cimxml message.
  3. Extension to CIM Client to extract the extended information and make it available to the client application. An extension is required to the Excetpion interface to be able to pass CIM_Error information from the infrastructure back up to the client application.
  4. Development of tests - Development of both unit tests and end-end tests to test this extended infrastructure.
     

PHASE 2 - Modification of the existing Error Handling Calls in the OpenPegasus CIMServer and providers. (PEP263)

  1. CIM_Server changes to the error generation both within the server and providers. This includes modifying the specific error generator mechanisms to generate any additional CIM_Error information so that it can be attached to the internal response message. Note that this task will involve working with some of the CIMExceptions to actually generate CIM_Error responses internally to the exception and in other cases, providing extensions so that the code defining the exception can create CIM_Error instances and attach them to the exception.
  2. Modification of Error Generation Instances in the CIMServer  and Pegasus Providers to add CIMError information

4.12 Implementation Definition

4.12.1 The CIM_Error Class

The new error information is to be provided through a new CIM Class, CIM_Error. This class was added to the CIM Model about 2 years ago in the CIM_Interop model. It remains today an experimental class (See the experimental version of the cim 2.10 model). This class represents the information that would be passed from server to client as detailed error information. The actual mof is in section CIM_Error Class MOF Definition below. This section defines the information requirements of the class and defines the Cxx class implementation that will be used as the basis to create and read CIM_Error information.
CIM_Error Class Information Requirements

The proposal is to generate a new class in Common (CIM_Error) specifically to handle the passage of CIM_Error information. This class will include the constructors, setters, and getters specifically required to process the information required to build instances of this class and to process instances created and extract information from instances of this C++ class.

To deliver instances of this class, the following information is required (i.e. the properties of this class):
  1. ErrorType Enum representing the type of error. New information.
  2. OtherErrorType Possible extensions to the ErrorType Enum above. New information.
  3. OwningEntity REQUIRED New information. String defining owning entity for the definition of the format of the Message described in this instance.
  4. MessageID REQUIRE New information. Uniquely identifies within the scope of theOwningEntity the format of the Message.
  5. Message REQUIRED New information. The formatted Message. Constructed by applying the dynamic content from Message Arguments to the formatting string uniquely identified within the OwningEntity by the MessageID
  6. MessageArguments[] New information. An array of strings that defines the dynamic content of the message
  7. PerceivedSeverity REQUIRED New information.
  8. ProbableCause REQUIRED New information.
  9. ProbableCauseDescription New information.
  10. RecommendedActions[] New information.
  11. ErrorSource New information.
  12. ErrorSourceFormat New information.
  13. CIMStatusCode REQUIRED The current error codes defined in DSP201
  14. CIMStatusCodeDescription - The descriptions being delivered today upon generation of errors
Pegasus CIM_Error Class Implementation
A new C++ class will be created to represent CIM_Errors. This class allow creating CIM_Error objects with all of the required CIM_Error parameters. This class will be capable of creating CIM_Error instances including all of the required data. All of the CIM “Enumerated” types will be represented internally by Cxx enums corresponding to the Values and ValueMaps. The setters will include:
  1. ErrorType - This will be a Cxx enum representing the type of error based on the definition in the CIM_Error CIM Class
  2. OwningEntity - TBD
  3. MessageID - TBD
  4. Message - TBD
  5. MessageArguments[]
  6. PerceivedSeverity
  7. ProbableCause
  8. ProbablyCauseDescription
  9. RecommendedActions[]
  10. ErrorSource
  11. ErrorSourceFormat

In addition the class will include methods to map a CIMError to and from a CIMInstance as follows:

Creating a CIMInstance from a CIMError

   CIMError err1(...)
   CIMInstance myInstance =  err1. getInstance(...);
Creating a CIMError from a CIMInstance:
   CIMInstance myInstance
   complete instance
   CIMError err1.setInstance(myCIMInstance);    / converts instance to CIMerror

The proposed implementation of this Class is in Section 5 (CIMError Class)

Example of CIMError

Constructing a CIMError

CIMError err1(  PegasusOwningEntityName,
       "MessageIDString",
       "Text Of Message",
       CIMError::PERCEIVED_SEVERITY_LOW, 
       CIMError::PROBABLE_CAUSE_UNEXPECTED_INFORMATION, 
       CIMError::CIM_STATUS_CODE_CIM_ERR_FAILED);
CIMInstance instance = err1.getInstance();

Note that this is considerably less code than creating a CIMError simply through the use of CIMInstance which might look something like:

 

CIMInstance err1;

         err1.addProperty("OwningEntity", PegasusOwningEntityName);

         err1.addProperty("MessageID", "MessageIDString");

         err1.addProperty("Message", "Text Of Message");

         err1.addProperty("PercievedSeverity", 2);

         ....

Discussion of use of CIMError Class

 

CIMError is a facade that represents a simplified way to create instances of a class

4.12.2 CIM Client Changes

CIMClient Interface Changes
The CIMClient application will receive CIM_Errors as an extension to the CIMException mechanism.   Just as the error status code and error status description are available today as part of a CIMException catch block, a possible array of CIM_Error instances will be made available through the same mechanism by providing additional calls to a) determine if any CIMError instances are attached to an exception and b) retrieving each CIMError instance.

This proposal does NOT propose changing the basic functionality for errors, the exception. The CIM_Error information is supplemental.  Existing clients that do not know about CIMError will not be affected.

Methods to be added  to CIMException specifically to support the client are accessing CIMError instances as part of exception processing.:

The following is an example of how this work: 

try
{
    ... execute the CIM Operation
}

/*  
    The addition here of a possible array of CIM_error instances that the client would receive as part of each
    response message. 
*/
catch(CIMException exception)
{
    if e.getCode() != CIM_ERR_NOT_FOUND
    {
         ... do something  because the Error code was NOT CIM_ERR_NOT_FOUND
    }
    /* ask if there were any CIM_Error instances attached
    */
    if (e.getErrorCount != 0)
    {
         for (Uint32 i = 0 ; i < e.getErrorCount() ; i++)
         { 
             CIMInstance errorInstance = e.getError();
             ... analyze the individual cim error instance;
         }
    }
}
CIMException handling
Extend the CIMException handling to allow for presenting a CIM_Error as defined above in CIMClient handling.

These changes are actually made to Exception.h and Exception.cpp

CIMClientRep.cpp
Simple change to Get the cimException from the cimResponse rather than the code and message individually

4.12.3 CIM_Server Changes

The following changes are proposed for the Server components.
XmlWriter.cpp

Append any created error instances to the output buffer

XmlReader.cpp

Get the CIM_Error instances from the received response and attach to the error.

CIMException.cpp and CIMException.h
Expand CIMException to handle receiving CIM_Error instances as part of exceptions thrown as an optional parameter.

In addition, there may be cases where we will be expected to generate CIM_Error messages from directly within CIMExceptions rather than or in addition to those received by the throw. This would be those cases where we already knew the full set of information to be generated by the exception and its CIM_Error and the generator of the throw could contribute nothing new.

The new functionality in CIMException to support generation of CIM_Error instances in CIMExceptions is:

1. addErrror() method  to CIMException

 /* Adds a single error instance to a CIMException
@param instance CIMInstance is the instance of CIM_Error
that is to be added to the CIMException. This instance is
NOT checked by the infrastructure for correct type.
*/
void addError(const CIMInstance& instance);

     Allows adding a CIMInstance representing a CIM_Error to an existing CIMException.

 2. removeError() method to CIMException

      /** removes the instance defined by the index from
        an array of instances in the CIMException
        @param index Uint32 index of instance to remove.
        @exceptions ... out-of-range exception
    */
    void removeError(Uint32 index);

   Allows removing any instance in an array of CIM_Error instances attached to a CIMException.

3. getErrorCount() method to CIMException

 /* get the count of CIM_Error instances attached to the CIMException.
Normally this method is used by the client to determine if any
CIM_Error instances are attached to a CIMException and as the
end test if the user decides to get the exception instances.
@return Uint32 count of CIM_Error instances attached to a CIMException.
0 indicates that there are no instances attached.
*/
Uint32 getErrorCount();

4. getError() gets one CIMInstance representing a CIMError

 /* get a single CIM_Error instance that is attached to a CIMException.
@param Uint32 index that defines the index to a particular CIMInstance
attached to the CIMException. The index must be less than the value of
the return from getErrorCount()
Return CIMInstance the instance defined by the index.
exception: returns out-of-range exception if the index is outside the
range of the array of CIM_Instances attached to the CIMExcepton.
EXAMPLE
    try
    { .. Execute CIM Operation
    }
    catch(CIMExcepton e)
    {
        if (e.getErrorCount() > 0 )
        {
            for (Uint32 i = 0 ; i < getErrorCount() ; i++)
            ... get and process each CIM_Error instance
        }
    }
*/
CIMInstance getError(Uint32 index);

In addition we propose new CIMException constructors so that the CIM_Error instances can be added at the time a CIMException is thrown without requiring that the CIMException be created before the exception is thrown.  The new constructors are of the form:

 /** Construct a CIMException with status code, message
and a CIM_Error instance attached to the exception. Note that
this allows the CIMStatusCode and Description in the CIMError
to be different than those attached to the call.
@param code CIMStatus code defining the error
@param message String defining the message text
@param instance CIMInstance containing the CIM_Error
instance.
*/
CIMException(CIMStatus code,
     const String& message,

     const CIMInstance& instance);

 

/** ...

*/

CIMException(

     CIMStatus code,

     const String& message,

     const Array<CIMInstance>& instances);

and internally for the MSG_LoaderParams interface

CIMException(

     CIMStatus code,

     const MessageLoaderParams& msgParams,

     const CIMInstance& instance);

 

CIMException(

     CIMStatus code,

     const MessageLoaderParams& msgParams,

     const Array<CIMInstance>& instances);

  4.12.4 Provider Interface

Two new interfaces will be made available to the provider interface:

1. A new function in in exception.h which is used to attach CIM_Error instances to an exception.

The CIM_Error header file is shown below and the addError function is as follows:

    void addError(const CIMInstance& instance);

A CIMException with attached error can therefore be created as follows:

    CIMException myException;

 

    CIMError err1;

    ... add property values;

 

    myException.addError(err1.setInstance());

 

    throw myException;

 

2. The CIMException constructors defined above so that CIMExceptions can be created with CIMError attached.

 

NOTE: There are a set of Provider CIMExceptions define in src/Pegasus/Provider/ProviderException.h.  These are specific exceptions and we will not know

Existing Providers
No changes proposed to existing providers to implement the infrastructure for Phase one.

5. Background Information

5.1 CIM_Error Class MOF Definition

From the CIM_Interop model (V 2.9), the CIM_Error class definition is as follows: 
// Copyright (c) 2005 DMTF.  All rights reserved.
// ==================================================================
//  CIM_Error
// ==================================================================
   [Indication, Experimental, Exception, Version ( "2.8.1000" ), 
    Description (
       "CIM_Error is a specialized class that contains information "
       "about the severity, cause, recommended actions and other data "
       "related to the failure of a CIM Operation. Instances of this "
       "type MAY be included as part of the response to a CIM "
       "Operation. \n"
       "\n"
       "CIM_Errors like CIM_Indications do not persist, and therefore "
       "do not have keys. Currently, this is only allowed by defining "
       "a concrete class with the Indication qualifier. Until the CIM "
       "Specification is modified to allow other concrete classes "
       "without keys, the CIM_Error class MUST be qualified by both "
       "Indication and Exception. After this, the Indication qualifier "
       "can be removed.")]
class CIM_Error {

      [Description (
          "Primary classification of the error. The following values "
          "are defined: \n"
          "2 - Communications Error. Errors of this type are "
          "principally associated with the procedures and/or processes "
          "required to convey information from one point to another. \n"
          "3 - Quality of Service Error. Errors of this type are "
          "principally associated with failures that result in reduced "
          "functionality or performance. \n"
          "4 - Software Error. Error of this type are principally "
          "associated with a software or processing fault. \n"
          "5 - Hardware Error. Errors of this type are principally "
          "associated with an equipment or hardware failure. \n"
          "6 - Environmental Error. Errors of this type are "
          "principally associated with a failure condition relating "
          "the to facility, or other environmental considerations. \n"
          "7 - Security Error. Errors of this type are associated with "
          "security violations, detection of viruses, and similar "
          "issues. \n"
          "8 - Oversubscription Error. Errors of this type are "
          "principally associated with the failure to allocate "
          "sufficient resources to complete the operation. \n"
          "9 - Unavailable Resource Error. Errors of this type are "
          "principally associated with the failure to access a "
          "required resource. \n"
          "10 -Unsupported Operation Error. Errors of this type are "
          "principally associated with requests that are not "
          "supported."), 
       ValueMap { "0", "1", "2", "3", "4", "5", "6", "7", "8", "9",
          "10" }, 
       Values { "Unknown", "Other", "Communications Error",
          "Quality of Service Error", "Software Error",
          "Hardware Error", "Environmental Error", "Security Error",
          "Oversubscription Error", "Unavailable Resource Error",
          "Unsupported Operation Error" }]
   uint16 ErrorType;

      [Description (
          "A free-form string describing the ErrorType when 1, "
          "\"Other\", is specified as the ErrorType."), 
       ModelCorrespondence { "CIM_Error.ErrorType" }]
   string OtherErrorType;

      [Required, Description (
          "A string that uniquely identifies the entity that owns the "
          "definition of the format of the Message described in this "
          "instance. OwningEntity MUST include a copyrighted, "
          "trademarked or otherwise unique name that is owned by the "
          "business entity or standards body defining the format.")]
   string OwningEntity;

      [Required, Description (
          "An opaque string that uniquely identifies, within the scope "
          "of the OwningEntity, the format of the Message.")]
   string MessageID;


      [Required, Description (
          "The formatted message. This message is constructed by "
          "applying the dynamic content of the message, described in "
          "MessageArguments, to the format string uniquely identified, "
          "within the scope of the OwningEntity, by MessageID.")]
   string Message;

      [Description (
          "An array containing the dynamic content of the message.")]
   string MessageArguments[];

      [Required, Description (
          "An enumerated value that describes the severity of the "
          "error from the notifier's point of view: \n"
          "2 - Low should be used for noncritical issues such as "
          "invalid parameters, incorrect usage, unsupported "
          "functionality. \n"
          "3 - Medium should be used to indicate action is needed, but "
          "the situation is not serious at this time. \n"
          "4 - High should be used to indicate action is needed NOW. \n"
          "5 - Fatal should be used to indicate a loss of data or "
          "unrecoverable system or service failure."), 
       ValueMap { "0", "2", "3", "4", "5" }, 
       Values { "Unknown", "Low", "Medium", "High", "Fatal" }]
   uint16 PerceivedSeverity;

      [Required, Description (
          "An enumerated value that describes the probable cause of "
          "the error."), 
       ValueMap { "0", "1", "2", "3", "4", "5", "6", "7", "8", "9",
          "10", "11", "12", "13", "14", "15", "16", "17", "18", "19",
          "20", "21", "22", "23", "24", "25", "26", "27", "28", "29",
          "30", "31", "32", "33", "34", "35", "36", "37", "38", "39",
          "40", "41", "42", "43", "44", "45", "46", "47", "48", "49",
          "50", "51", "52", "53", "54", "55", "56", "57", "58", "59",
          "60", "61", "62", "63", "64", "65", "66", "67", "68", "69",
          "70", "71", "72", "73", "74", "75", "76", "77", "78", "79",
          "80", "81", "82", "83", "84", "85", "86", "87", "88", "89",
          "90", "91", "92", "93", "94", "95", "96", "97", "98", "99",
          "100", "101", "102", "103", "104", "105", "106", "107",
          "108", "109", "110", "111", "112", "113", "114", "115",
          "116", "117", "118", "119", "120", "121", "122", "123",
          "124", "125", "126", "127", "128", "129", "130" }, 
       Values { "Unknown", "Other", "Adapter/Card Error",
          "Application Subsystem Failure", "Bandwidth Reduced",
          "Connection Establishment Error",
          "Communications Protocol Error",
          "Communications Subsystem Failure",
          "Configuration/Customization Error", "Congestion",
          "Corrupt Data", "CPU Cycles Limit Exceeded",
          "Dataset/Modem Error", "Degraded Signal",
          "DTE-DCE Interface Error", "Enclosure Door Open",
          "Equipment Malfunction", "Excessive Vibration",
          "File Format Error", "Fire Detected", "Flood Detected",
          "Framing Error", "HVAC Problem", "Humidity Unacceptable",
          "I/O Device Error", "Input Device Error", "LAN Error",
          "Non-Toxic Leak Detected", "Local Node Transmission Error",
          "Loss of Frame", "Loss of Signal", 
          //31 
          "Material Supply Exhausted", "Multiplexer Problem",
          "Out of Memory", "Output Device Error",
          "Performance Degraded", "Power Problem",
          "Pressure Unacceptable",
          "Processor Problem (Internal Machine Error)", "Pump Failure",
          "Queue Size Exceeded", "Receive Failure", "Receiver Failure",
          "Remote Node Transmission Error",
          "Resource at or Nearing Capacity", "Response Time Excessive",
          "Retransmission Rate Excessive", "Software Error",
          "Software Program Abnormally Terminated",
          "Software Program Error (Incorrect Results)",
          "Storage Capacity Problem", "Temperature Unacceptable",
          "Threshold Crossed", "Timing Problem", "Toxic Leak Detected",
          "Transmit Failure", "Transmitter Failure",
          "Underlying Resource Unavailable", "Version Mismatch",
          "Previous Alert Cleared", 
          //60 
          "Login Attempts Failed", "Software Virus Detected",
          "Hardware Security Breached", "Denial of Service Detected",
          "Security Credential Mismatch", "Unauthorized Access",
          "Alarm Received", "Loss of Pointer", "Payload Mismatch",
          "Transmission Error", "Excessive Error Rate",
          "Trace Problem", "Element Unavailable", "Element Missing",
          "Loss of Multi Frame", "Broadcast Channel Failure",
          "Invalid Message Received", "Routing Failure",
          "Backplane Failure", "Identifier Duplication",
          "Protection Path Failure", "Sync Loss or Mismatch",
          "Terminal Problem", "Real Time Clock Failure",
          "Antenna Failure", "Battery Charging Failure",
          "Disk Failure", "Frequency Hopping Failure",
          "Loss of Redundancy", "Power Supply Failure",
          "Signal Quality Problem", 
          //91 
          "Battery Discharging", "Battery Failure",
          "Commercial Power Problem", "Fan Failure", "Engine Failure",
          "Sensor Failure", "Fuse Failure", "Generator Failure",
          "Low Battery", "Low Fuel", "Low Water", "Explosive Gas",
          "High Winds", "Ice Buildup", "Smoke", "Memory Mismatch",
          "Out of CPU Cycles", "Software Environment Problem",
          "Software Download Failure", "Element Reinitialized",
          "Timeout", "Logging Problems", "Leak Detected",
          "Protection Mechanism Failure", 
          //115 
          "Protecting Resource Failure", "Database Inconsistency",
          "Authentication Failure", "Breach of Confidentiality",
          "Cable Tamper", "Delayed Information",
          "Duplicate Information", "Information Missing",
          "Information Modification", "Information Out of Sequence",
          "Key Expired", "Non-Repudiation Failure",
          "Out of Hours Activity", "Out of Service",
          "Procedural Error", "Unexpected Information" }, 
       MappingStrings { "Recommendation.ITU|X733.Probable cause",
          "Recommendation.ITU|M3100.probableCause",
       "ITU-IANA-ALARM-TC" }, 
       ModelCorrespondence { "CIM_Error.ProbableCauseDescription" }]
   uint16 ProbableCause;

      [Description (
          "A free-form string describing the probable cause of the "
          "error."), 
       ModelCorrespondence { "CIM_Error.ProbableCause" }]
   string ProbableCauseDescription;

      [Description (
          "A free-form string describing recommended actions to take "
          "to resolve the error.")]
   string RecommendedActions[];

      [Description (
          "The identifying information of the entity (i.e., the "
          "instance) generating the error. If this entity is modeled "
          "in the CIM Schema, this property contains the path of the "
          "instance encoded as a string parameter. If not modeled, the "
          "property contains some identifying string that names the "
          "entity that generated the error. The path or identifying "
          "string is formatted per the ErrorSourceFormat property."), 
       ModelCorrespondence { "CIM_Error.ErrorSourceFormat" }]
   string ErrorSource;

      [Description (
          "The format of the ErrorSource property is interpretable "
          "based on the value of this property. Values are defined as: "
          "\n0 - Unknown. The format is unknown or not meaningfully "
          "interpretable by a CIM client application. \n"
          "1 - Other. The format is defined by the value of the "
          "OtherErrorSourceFormat property. \n"
          "2 - CIMObjectHandle. A CIM Object Handle, encoded using the "
          "MOF syntax defined for the objectHandle non-terminal, is "
          "used to identify the entity."), 
       ValueMap { "0", "1", "2" }, 
       Values { "Unknown", "Other", "CIMObjectHandle" }, 
       ModelCorrespondence { "CIM_Error.ErrorSource",
          "CIM_Error.OtherErrorSourceFormat" }]
   uint16 ErrorSourceFormat = 0;

      [Description (
          "A string defining \"Other\" values for ErrorSourceFormat. "
          "This value MUST be set to a non NULL value when "
          "ErrorSourceFormat is set to a value of 1 (\"Other\"). For "
          "all other values of ErrorSourceFormat, the value of this "
          "string must be set to NULL."), 
       ModelCorrespondence { "CIM_Error.ErrorSourceFormat" }]
   string OtherErrorSourceFormat;

      [Required, Description (
          "The CIM status code that characterizes this instance. \n"
          "This property defines the status codes that MAY be return "
          "by a conforming CIM Server or Listener. Note that not all "
          "status codes are valid for each operation. The "
          "specification for each operation SHOULD define the status "
          "codes that may be returned by that operation. \n"
          "The following values for CIM status code are defined: \n"
          "1 - CIM_ERR_FAILED. A general error occurred that is not "
          "covered by a more specific error code. \n"
          "2 - CIM_ERR_ACCESS_DENIED. Access to a CIM resource was not "
          "available to the client. \n"
          "3 - CIM_ERR_INVALID_NAMESPACE. The target namespace does "
          "not exist. \n"
          "4 - CIM_ERR_INVALID_PARAMETER. One or more parameter values "
          "passed to the method were invalid. \n"
          "5 - CIM_ERR_INVALID_CLASS. The specified Class does not "
          "exist. \n"
          "6 - CIM_ERR_NOT_FOUND. The requested object could not be "
          "found. \n"
          "7 - CIM_ERR_NOT_SUPPORTED. The requested operation is not "
          "supported. \n"
          "8 - CIM_ERR_CLASS_HAS_CHILDREN. Operation cannot be carried "
          "out on this class since it has instances. \n"
          "9 - CIM_ERR_CLASS_HAS_INSTANCES. Operation cannot be "
          "carried out on this class since it has instances. \n"
          "10 - CIM_ERR_INVALID_SUPERCLASS. Operation cannot be "
          "carried out since the specified superclass does not exist. "
          "\n11 - CIM_ERR_ALREADY_EXISTS. Operation cannot be carried "
          "out because an object already exists. \n"
          "12 - CIM_ERR_NO_SUCH_PROPERTY. The specified Property does "
          "not exist. \n"
          "13 - CIM_ERR_TYPE_MISMATCH. The value supplied is "
          "incompatible with the type. \n"
          "14 - CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED. The query "
          "language is not recognized or supported. \n"
          "15 - CIM_ERR_INVALID_QUERY. The query is not valid for the "
          "specified query language. \n"
          "16 - CIM_ERR_METHOD_NOT_AVAILABLE. The extrinsic Method "
          "could not be executed. \n"
          "17 - CIM_ERR_METHOD_NOT_FOUND. The specified extrinsic "
          "Method does not exist. \n"
          "18 - CIM_ERR_UNEXPECTED_RESPONSE. The returned response to "
          "the asynchronous operation was not expected. \n"
          "19 - CIM_ERR_INVALID_RESPONSE_DESTINATION. The specified "
          "destination for the asynchronous response is not valid. \n"
          "20 - CIM_ERR_NAMESPACE_NOT_EMPTY. The specified Namespace "
          "is not empty."), 
       ValueMap { "1", "2", "3", "4", "5", "6", "7", "8", "9", "10",
          "11", "12", "13", "14", "15", "16", "17", "18", "19", "20",
          "21.." }, 
       Values { "CIM_ERR_FAILED", "CIM_ERR_ACCESS_DENIED",
          "CIM_ERR_INVALID_NAMESPACE", "CIM_ERR_INVALID_PARAMETER",
          "CIM_ERR_INVALID_CLASS", "CIM_ERR_NOT_FOUND",
          "CIM_ERR_NOT_SUPPORTED", "CIM_ERR_CLASS_HAS_CHILDREN",
          "CIM_ERR_CLASS_HAS_INSTANCES", "CIM_ERR_INVALID_SUPERCLASS",
          "CIM_ERR_ALREADY_EXISTS", "CIM_ERR_NO_SUCH_PROPERTY",
          "CIM_ERR_TYPE_MISMATCH",
          "CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED",
          "CIM_ERR_INVALID_QUERY", "CIM_ERR_METHOD_NOT_AVAILABLE",
          "CIM_ERR_METHOD_NOT_FOUND", "CIM_ERR_UNEXPECTED_RESPONSE",
          "CIM_ERR_INVALID_RESPONSE_DESTINATION",
          "CIM_ERR_NAMESPACE_NOT_EMPTY", "DMTF Reserved" }, 
       MappingStrings { "DSP0201.DMTF|ERROR.CODE|2.2" }, 
       ModelCorrespondence { "CIM_Error.CIMStatusCodeDescription" }]
   uint32 CIMStatusCode;

      [Description (
          "A free-form string containing a human-readable description "
          "of CIMStatusCode. This description MAY extend, but MUST be "
          "consistent with, the definition of CIMStatusCode."), 
       MappingStrings { "DSP0201.DMTF|ERROR.DESCRIPTION|2.2" }, 
       ModelCorrespondence { "CIM_Error.CIMStatusCode" }]
   string CIMStatusCodeDescription;
};

4.13 Testing

Both unit tests and end-end tests will be provided to test the basic creation, transmission, and reception of CIMErrors.

Unit tests:

  1. Common/tests/CIMError/CIMError.cpp New
  2. Exception - Extended

End-End Tests

Not yet completed.

4.14 Modules Changed

The list of Modules Changed to date is as follows:

? src/Pegasus/Common/CIMError.cpp
? src/Pegasus/Common/CIMError.h
? src/Pegasus/Common/Helper.cpp
? src/Pegasus/Common/Helper.h
? src/Pegasus/Common/tests/CIMError
M src/Pegasus/Client/CIMClientRep.cpp
M src/Pegasus/Common/CIMExceptionRep.h
M src/Pegasus/Common/Exception.cpp
M src/Pegasus/Common/Exception.h
M src/Pegasus/Common/ExceptionRep.h
M src/Pegasus/Common/HTTPConnection.cpp
M src/Pegasus/Common/Makefile
M src/Pegasus/Common/XmlReader.cpp
M src/Pegasus/Common/XmlWriter.cpp
M src/Pegasus/Common/tests/Makefile
M src/Pegasus/Common/tests/XmlReader/XmlReader.cpp
M src/Pegasus/Common/tests/XmlReader/getErrorElement.xml
 

5.2 Proposed CIMError Facade Class Declaration

CIMError Class Interface

The CIMError Class is defined as follows:

/* CIMError is a specialized class that contains information about the 
severity, cause, recommended actions and other data related to the failure 
of a CIM Operation. This class is defined in the DMTF Interop schema. 
Instances of this type MAY be included by a CIMServeras part of the 
response to a CIM Operation as part of an ERROR entity. CIMErrors like 
CIM_Indications do not persist, and therefore do not have keys. 
Currently, this is only allowed by defining a concrete class with the 
Indication qualifier. Until the CIM Specification is modified to allow 
other concrete classes without keys, the CIMError class MUST be qualified 
by both Indication and Exception. After this, the Indication qualifier 
can be removed. This class is implemented as a Pegasus CIMInstance but 
becasue of the special nature of the usage of the class specific accessors 
and modifiers are provided for each property in the class. NOTE: In the 
initial version, only a single public constructor is provided that 
requires setting all of the required properties in any constructed 
CIMError class. This class also provides specific enumerations for
those properties in the CIM_Error class that are mof enumerations
(values and valuemaps). 
*/ 

class CIMError { public: 

/** Enumeration of the possible values in the 
ErrorType Property of the CIM_Error Class
*/
enum ErrorTypeEnum
{
ERROR_TYPE_UNKNOWN = 0,
ERROR_TYPE_OTHER = 1,
ERROR_TYPE_COMMUNICATIONS_ERROR = 2,
ERROR_TYPE_QUALITY_OF_SERVICE_ERROR = 3,
ERROR_TYPE_SOFTWARE_ERROR = 4,
ERROR_TYPE_HARDWARE_ERROR = 5,
ERROR_TYPE_ENVIRONMENTAL_ERROR = 6,
ERROR_TYPE_SECURITY_ERROR = 7,
ERROR_TYPE_OVERSUBSCRIPTION_ERROR = 8,
ERROR_TYPE_UNAVAILABLE_RESOURCE_ERROR = 9,
ERROR_TYPE_UNSUPPORTED_OPERATION_ERROR = 10,
};

/** Enumeration of the possiblle values in the
Perceived Severity Property of the CIM_Error Class
*/
enum PerceivedSeverityEnum
{
PERCEIVED_SEVERITY_UNKNOWN = 0,
PERCEIVED_SEVERITY_UNUSED_1 = 1,
PERCEIVED_SEVERITY_LOW = 2,
PERCEIVED_SEVERITY_MEDIUM = 3,
PERCEIVED_SEVERITY_HIGH = 4,
PERCEIVED_SEVERITY_FATAL = 5,
};

/** Enumeration of the possible values in the 
ProbableCause Property of hte CIM_Error Class
*/
enum ProbableCauseEnum
{
PROBABLE_CAUSE_UNKNOWN = 0,
PROBABLE_CAUSE_OTHER = 1,
PROBABLE_CAUSE_ADAPTER_CARD_ERROR = 2,
PROBABLE_CAUSE_APPLICATION_SUBSYSTEM_FAILURE = 3,
PROBABLE_CAUSE_BANDWIDTH_REDUCED = 4,
PROBABLE_CAUSE_CONNECTION_ESTABLISHMENT_ERROR = 5,
PROBABLE_CAUSE_COMMUNICATIONS_PROTOCOL_ERROR = 6,
PROBABLE_CAUSE_COMMUNICATIONS_SUBSYSTEM_FAILURE = 7,
PROBABLE_CAUSE_CONFIGURATION_CUSTOMIZATION_ERROR = 8,
PROBABLE_CAUSE_CONGESTION = 9,
PROBABLE_CAUSE_CORRUPT_DATA = 10,
PROBABLE_CAUSE_CPU_CYCLES_LIMIT_EXCEEDED = 11,
PROBABLE_CAUSE_DATASET_MODEM_ERROR = 12,
PROBABLE_CAUSE_DEGRADED_SIGNAL = 13,
PROBABLE_CAUSE_DTE_DCE_INTERFACE_ERROR = 14,
PROBABLE_CAUSE_ENCLOSURE_DOOR_OPEN = 15,
PROBABLE_CAUSE_EQUIPMENT_MALFUNCTION = 16,
PROBABLE_CAUSE_EXCESSIVE_VIBRATION = 17,
PROBABLE_CAUSE_FILE_FORMAT_ERROR = 18,
PROBABLE_CAUSE_FIRE_DETECTED = 19,
PROBABLE_CAUSE_FLOOD_DETECTED = 20,
PROBABLE_CAUSE_FRAMING_ERROR = 21,
PROBABLE_CAUSE_HVAC_PROBLEM = 22,
PROBABLE_CAUSE_HUMIDITY_UNACCEPTABLE = 23,
PROBABLE_CAUSE_I_O_DEVICE_ERROR = 24,
PROBABLE_CAUSE_INPUT_DEVICE_ERROR = 25,
PROBABLE_CAUSE_LAN_ERROR = 26,
PROBABLE_CAUSE_NON_TOXIC_LEAK_DETECTED = 27,
PROBABLE_CAUSE_LOCAL_NODE_TRANSMISSION_ERROR = 28,
PROBABLE_CAUSE_LOSS_OF_FRAME = 29,
PROBABLE_CAUSE_LOSS_OF_SIGNAL = 30,
PROBABLE_CAUSE_MATERIAL_SUPPLY_EXHAUSTED = 31,
PROBABLE_CAUSE_MULTIPLEXER_PROBLEM = 32,
PROBABLE_CAUSE_OUT_OF_MEMORY = 33,
PROBABLE_CAUSE_OUTPUT_DEVICE_ERROR = 34,
PROBABLE_CAUSE_PERFORMANCE_DEGRADED = 35,
PROBABLE_CAUSE_POWER_PROBLEM = 36,
PROBABLE_CAUSE_PRESSURE_UNACCEPTABLE = 37,
PROBABLE_CAUSE_PROCESSOR_PROBLEM__INTERNAL_MACHINE_ERROR_ = 38,
PROBABLE_CAUSE_PUMP_FAILURE = 39,
PROBABLE_CAUSE_QUEUE_SIZE_EXCEEDED = 40,
PROBABLE_CAUSE_RECEIVE_FAILURE = 41,
PROBABLE_CAUSE_RECEIVER_FAILURE = 42,
PROBABLE_CAUSE_REMOTE_NODE_TRANSMISSION_ERROR = 43,
PROBABLE_CAUSE_RESOURCE_AT_OR_NEARING_CAPACITY = 44,
PROBABLE_CAUSE_RESPONSE_TIME_EXCESSIVE = 45,
PROBABLE_CAUSE_RETRANSMISSION_RATE_EXCESSIVE = 46,
PROBABLE_CAUSE_SOFTWARE_ERROR = 47,
PROBABLE_CAUSE_SOFTWARE_PROGRAM_ABNORMALLY_TERMINATED = 48,
PROBABLE_CAUSE_SOFTWARE_PROGRAM_ERROR__INCORRECT_RESULTS_ = 49,
PROBABLE_CAUSE_STORAGE_CAPACITY_PROBLEM = 50,
PROBABLE_CAUSE_TEMPERATURE_UNACCEPTABLE = 51,
PROBABLE_CAUSE_THRESHOLD_CROSSED = 52,
PROBABLE_CAUSE_TIMING_PROBLEM = 53,
PROBABLE_CAUSE_TOXIC_LEAK_DETECTED = 54,
PROBABLE_CAUSE_TRANSMIT_FAILURE = 55,
PROBABLE_CAUSE_TRANSMITTER_FAILURE = 56,
PROBABLE_CAUSE_UNDERLYING_RESOURCE_UNAVAILABLE = 57,
PROBABLE_CAUSE_VERSION_MISMATCH = 58,
PROBABLE_CAUSE_PREVIOUS_ALERT_CLEARED = 59,
PROBABLE_CAUSE_LOGIN_ATTEMPTS_FAILED = 60,
PROBABLE_CAUSE_SOFTWARE_VIRUS_DETECTED = 61,
PROBABLE_CAUSE_HARDWARE_SECURITY_BREACHED = 62,
PROBABLE_CAUSE_DENIAL_OF_SERVICE_DETECTED = 63,
PROBABLE_CAUSE_SECURITY_CREDENTIAL_MISMATCH = 64,
PROBABLE_CAUSE_UNAUTHORIZED_ACCESS = 65,
PROBABLE_CAUSE_ALARM_RECEIVED = 66,
PROBABLE_CAUSE_LOSS_OF_POINTER = 67,
PROBABLE_CAUSE_PAYLOAD_MISMATCH = 68,
PROBABLE_CAUSE_TRANSMISSION_ERROR = 69,
PROBABLE_CAUSE_EXCESSIVE_ERROR_RATE = 70,
PROBABLE_CAUSE_TRACE_PROBLEM = 71,
PROBABLE_CAUSE_ELEMENT_UNAVAILABLE = 72,
PROBABLE_CAUSE_ELEMENT_MISSING = 73,
PROBABLE_CAUSE_LOSS_OF_MULTI_FRAME = 74,
PROBABLE_CAUSE_BROADCAST_CHANNEL_FAILURE = 75,
PROBABLE_CAUSE_INVALID_MESSAGE_RECEIVED = 76,
PROBABLE_CAUSE_ROUTING_FAILURE = 77,
PROBABLE_CAUSE_BACKPLANE_FAILURE = 78,
PROBABLE_CAUSE_IDENTIFIER_DUPLICATION = 79,
PROBABLE_CAUSE_PROTECTION_PATH_FAILURE = 80,
PROBABLE_CAUSE_SYNC_LOSS_OR_MISMATCH = 81,
PROBABLE_CAUSE_TERMINAL_PROBLEM = 82,
PROBABLE_CAUSE_REAL_TIME_CLOCK_FAILURE = 83,
PROBABLE_CAUSE_ANTENNA_FAILURE = 84,
PROBABLE_CAUSE_BATTERY_CHARGING_FAILURE = 85,
PROBABLE_CAUSE_DISK_FAILURE = 86,
PROBABLE_CAUSE_FREQUENCY_HOPPING_FAILURE = 87,
PROBABLE_CAUSE_LOSS_OF_REDUNDANCY = 88,
PROBABLE_CAUSE_POWER_SUPPLY_FAILURE = 89,
PROBABLE_CAUSE_SIGNAL_QUALITY_PROBLEM = 90,
PROBABLE_CAUSE_BATTERY_DISCHARGING = 91,
PROBABLE_CAUSE_BATTERY_FAILURE = 92,
PROBABLE_CAUSE_COMMERCIAL_POWER_PROBLEM = 93,
PROBABLE_CAUSE_FAN_FAILURE = 94,
PROBABLE_CAUSE_ENGINE_FAILURE = 95,
PROBABLE_CAUSE_SENSOR_FAILURE = 96,
PROBABLE_CAUSE_FUSE_FAILURE = 97,
PROBABLE_CAUSE_GENERATOR_FAILURE = 98,
PROBABLE_CAUSE_LOW_BATTERY = 99,
PROBABLE_CAUSE_LOW_FUEL = 100,
PROBABLE_CAUSE_LOW_WATER = 101,
PROBABLE_CAUSE_EXPLOSIVE_GAS = 102,
PROBABLE_CAUSE_HIGH_WINDS = 103,
PROBABLE_CAUSE_ICE_BUILDUP = 104,
PROBABLE_CAUSE_SMOKE = 105,
PROBABLE_CAUSE_MEMORY_MISMATCH = 106,
PROBABLE_CAUSE_OUT_OF_CPU_CYCLES = 107,
PROBABLE_CAUSE_SOFTWARE_ENVIRONMENT_PROBLEM = 108,
PROBABLE_CAUSE_SOFTWARE_DOWNLOAD_FAILURE = 109,
PROBABLE_CAUSE_ELEMENT_REINITIALIZED = 110,
PROBABLE_CAUSE_TIMEOUT = 111,
PROBABLE_CAUSE_LOGGING_PROBLEMS = 112,
PROBABLE_CAUSE_LEAK_DETECTED = 113,
PROBABLE_CAUSE_PROTECTION_MECHANISM_FAILURE = 114,
PROBABLE_CAUSE_PROTECTING_RESOURCE_FAILURE = 115,
PROBABLE_CAUSE_DATABASE_INCONSISTENCY = 116,
PROBABLE_CAUSE_AUTHENTICATION_FAILURE = 117,
PROBABLE_CAUSE_BREACH_OF_CONFIDENTIALITY = 118,
PROBABLE_CAUSE_CABLE_TAMPER = 119,
PROBABLE_CAUSE_DELAYED_INFORMATION = 120,
PROBABLE_CAUSE_DUPLICATE_INFORMATION = 121,
PROBABLE_CAUSE_INFORMATION_MISSING = 122,
PROBABLE_CAUSE_INFORMATION_MODIFICATION = 123,
PROBABLE_CAUSE_INFORMATION_OUT_OF_SEQUENCE = 124,
PROBABLE_CAUSE_KEY_EXPIRED = 125,
PROBABLE_CAUSE_NON_REPUDIATION_FAILURE = 126,
PROBABLE_CAUSE_OUT_OF_HOURS_ACTIVITY = 127,
PROBABLE_CAUSE_OUT_OF_SERVICE = 128,
PROBABLE_CAUSE_PROCEDURAL_ERROR = 129,
PROBABLE_CAUSE_UNEXPECTED_INFORMATION = 130,
};

/** Enumeration of the possible values for the
ErrorSourceFormat Property of the CIM_Error Class
*/
enum ErrorSourceFormatEnum
{
ERROR_SOURCE_FORMAT_UNKNOWN = 0,
ERROR_SOURCE_FORMAT_OTHER = 1,
ERROR_SOURCE_FORMAT_CIM_OBJECT_HANDLE = 2,
};

/** Enumeration of possible values for the
CIMStatus Code Property of the CIM_Error Class
*/
enum CIMStatusCodeEnum
{
CIM_STATUS_CODE_CIM_ERR_FAILED = 1,
CIM_STATUS_CODE_CIM_ERR_ACCESS_DENIED = 2,
CIM_STATUS_CODE_CIM_ERR_INVALID_NAMESPACE = 3,
CIM_STATUS_CODE_CIM_ERR_INVALID_PARAMETER = 4,
CIM_STATUS_CODE_CIM_ERR_INVALID_CLASS = 5,
CIM_STATUS_CODE_CIM_ERR_NOT_FOUND = 6,
CIM_STATUS_CODE_CIM_ERR_NOT_SUPPORTED = 7,
CIM_STATUS_CODE_CIM_ERR_CLASS_HAS_CHILDREN = 8,
CIM_STATUS_CODE_CIM_ERR_CLASS_HAS_INSTANCES = 9,
CIM_STATUS_CODE_CIM_ERR_INVALID_SUPERCLASS = 10,
CIM_STATUS_CODE_CIM_ERR_ALREADY_EXISTS = 11,
CIM_STATUS_CODE_CIM_ERR_NO_SUCH_PROPERTY = 12,
CIM_STATUS_CODE_CIM_ERR_TYPE_MISMATCH = 13,
CIM_STATUS_CODE_CIM_ERR_QUERY_LANGUAGE_NOT_SUPPORTED = 14,
CIM_STATUS_CODE_CIM_ERR_INVALID_QUERY = 15,
CIM_STATUS_CODE_CIM_ERR_METHOD_NOT_AVAILABLE = 16,
CIM_STATUS_CODE_CIM_ERR_METHOD_NOT_FOUND = 17,
CIM_STATUS_CODE_CIM_ERR_UNEXPECTED_RESPONSE = 18,
CIM_STATUS_CODE_CIM_ERR_INVALID_RESPONSE_DESTINATION = 19,
CIM_STATUS_CODE_CIM_ERR_NAMESPACE_NOT_EMPTY = 20,
};

/** Default constructor creates a single CIMInstance representing the
CIM_Error. In builds in all of the properties in a CIM_Error and
sets them to NULL.
*/
CIMError();

/** Constructor for minimum legal CIM_Error instance. Requires input of
all of the properties defined as required properties for CIM_Error.
@param messageID String
@param message String
@param perceivedSeverity PerceivedSeverityEnum
@param probableCause ProbableCauseEnum
@param cimStatusCode CIMStatusCodeEnum
@exceptions TBD
<p><b>example</b>
CIMError err1(PegasusOwningEntityName,
"MessageIDString",
"Text Of Message",
CIMError::PERCEIVED_SEVERITY_LOW,
CIMError::PROBABLE_CAUSE_UNEXPECTED_INFORMATION,
CIMError::CIM_STATUS_CODE_CIM_ERR_FAILED);
*/
CIMError(const String& owningEntity,
const String& messageID,
const String& message,
const PerceivedSeverityEnum& perceivedSeverity,
const ProbableCauseEnum& probableCause,
const CIMStatusCodeEnum& cimStatusCode);

/** Copy constructor.
*/
CIMError(const CIMError& x);

/** Destructor.
*/
~CIMError();

/** Accessor for the ErrorType property value in a CIM_Error
Instance.
@param value ErrorTypeEnum that is the current value of
the Property in the CIM_Error Instance.
@return bool returns true if the property is NOT Null.
returns false the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getErrorType(ErrorTypeEnum& value) const;

/** Modify the ErrorType property value for the CIM_Error
instance.
@ param value ErrorTypeEnum representing the value to be
set in the property. if the null property equals true,
this value is ignored.
@param null boolean that is defaulted to false. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
@exception Generates exceptions if missing
*/
void setErrorType(ErrorTypeEnum value, bool null = false);

/** Accessor for the OwningEntity property value in a CIM_Error
Instance.
@param value String that is the current value of
the ErrorType Property in the CIM_Error Instance.
@return bool returns true if the property is NOT Null.
returns false the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getOwningEntity(String& value) const;

/** Modify the OwningEntity property value for the CIM_Error
instance.
@ param value String representing the value to be
set in the property. If the null property equals true,
this value is ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
@exception Generates exceptions if TBD 
*/
void setOwningEntity(const String& value, bool null = false);

/** Accessor for the OtherErrorType property value in a CIM_Error
Instance.
@param value String that is the current value of
the OtherErrorType Property in the CIM_Error Instance.
@return bool returns true if the property is NOT Null.
returns false the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getOtherErrorType(String& value) const;

/** Modify the OtherErrorType property value for the CIM_Error
instance.
@param value String representing the value to be
set in the property. If the null property equals true,
this value is ignored.
@param null bool Sets the property to null if this parameter
is true, overriding any property value setting.
@exception Generates exceptions if TBD 
*/
void setOtherErrorType(const String& value, bool null = false);

/** Accessor for the MessageID property value in a CIM_Error
Instance.
@param value String that is the current value of
the MessageID Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getMessageID(String& value) const;

/** Modify the MessageID property value for the CIM_Error
instance.
@ param value String representing the value to be
set in the property. If the null property equals true,
this value is ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setMessageID(const String& value, bool null = false);

/** Accessor for the Message property value in a CIM_Error
Instance.
@param value String that is the current value of
the MessageID Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getMessage(String& value) const;

/** Modify the Message property value for the CIM_Error
instance.
@ param value String representing the value to be
set in the property. If the null property equals true,
this value is ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setMessage(const String& value, bool null = false);

/** Accessor for the MessageArguments property value in a CIM_Error
Instance.
@param value Array<String> that is the current value of
the MessageArguments Array Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getMessageArguments(Array<String>& value) const;

/** Modify the MessageArguments property value for the CIM_Error
instance.
@ param value Array<String> representing the value to be
set in the property. If the null property equals true,
this value is ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setMessageArguments(const Array<String>& value, bool null = false);

/** Accessor for the PerceivedSeverity property value in a CIM_Error
Instance.
@param value PerceivedSeverityEnum that is the current value of
the MessageArguments Array Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getPerceivedSeverity(PerceivedSeverityEnum& value) const;

/** Modify the PerceivedSeverity property value for the CIM_Error
instance.
@ param value PerceivedSeverityEnum representing the value to be
set in the property. If the null property equals true,
this value is ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setPerceivedSeverity(PerceivedSeverityEnum value, bool null = false);

/** Accessor for the ProbableCause property value in a CIM_Error
Instance.
@param value ProbableCauseEnum that is the current value of
the MessageArguments Array Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getProbableCause(ProbableCauseEnum& value) const;

/** Modify the ProbableCause property value for the CIM_Error
instance.
@ param value ProbableCauseEnum representing the value to be
set in the property. If the null property equals true,
this value is ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setProbableCause(ProbableCauseEnum value, bool null = false);

/** Accessor for the ProbableCauseDescription property value in a 
CIM_Error Instance.
@param value ProbableCauseEnumDescription that is the current value of
the MessageArguments Array Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getProbableCauseDescription(String& value) const;

/** Modify the ProbableCauseDescription property value for the CIM_Error
instance.
@ param value ProbableCauseEnumDescription representing the value to be
set in the property. If the null property equals true,
this value is ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setProbableCauseDescription(const String& value, bool null = false);

/** Accessor for the RecommendedActions property value in a 
CIM_Error Instance.
@param value Array<String> that is the current value of
the RecommendedActions Array Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getRecommendedActions(Array<String>& value) const;

/** Modify the RecommendedActions property value for the CIM_Error
String instance.
@ param value Array<String> representing the values to be
set in the property. If the null property equals true,
this value is ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setRecommendedActions(const Array<String>& value, bool null = false);

/** Accessor for the ErrorSource property value in a 
CIM_Error Instance.
@param value String that is the current value of
the RecommendedActions Array Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getErrorSource(String& value) const;

/** Modify the ErrorSource property value for the CIM_Error
instance.
@ param value String representing the values to be
set in the property. If the null property equals true,
this value is ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setErrorSource(const String& value, bool null = false);

/** Accessor for the ErrorSourceFormat property value in a 
CIM_Error Instance.
@param value ErrorSourceFormatEnum that is the current value of
the RecommendedActions Array Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getErrorSourceFormat(ErrorSourceFormatEnum& value) const;

/** Modify the ErrorSourceFormat property value for the CIM_Error
instance.
@ param value String representing the values to be
set in the property. If the null property is true,
this value should be ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setErrorSourceFormat(ErrorSourceFormatEnum value, bool null = false);

/** Accessor for the OtherErrorSourceFormat property value in a 
CIM_Error Instance.
@param value String that is the current value of
the OtherErrorSourceFormat Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getOtherErrorSourceFormat(String& value) const;

/** Modify the OtherErrorSourceFormat property value for the 
CIM_Error instance.
@ param value String representing the values to be
set in the property. If the null property is true,
this value should be ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setOtherErrorSourceFormat(const String& value, bool null = false);

/** Accessor for the CIMStatusCode property value in a 
CIM_Error Instance.
@param value CIMStatusCodeEnum that is the current value of
the CIMStatusCode Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getCIMStatusCode(CIMStatusCodeEnum& value) const;

/** Modify the CIMStatusCode property value for the 
CIM_Error instance.
@ param value String representing the values to be
set in the property. If the null property is true,
this value should be ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setCIMStatusCode(CIMStatusCodeEnum value, bool null = false);

/** Accessor for the CIMStatusCode property value in a 
CIM_Error Instance.
@param value String that is the current value of
the CIMStatusCode Property in the CIM_Error Instance.
@return bool returns true if the property has a legitimate value 
(is NOT Null).
It returns false if the value of the property is Null. 
This value should be tested before accessing the returned
value because the returned value will be invalid if
the variable is null.
@exception Generates CIM_ERR_TYPE_MISMATCH exception
if property missing
*/
bool getCIMStatusCodeDescription(String& value) const;

/** Modify the CIMStatusCodeDescription property value for the 
CIM_Error instance.
@ param value String representing the values to be
set in the property. If the null property is true,
this value should be ignored.
@param null boolean that is defaulted to zero. If set
true, this causes the property to be set to NULL, overriding
any value in the property.
*/
void setCIMStatusCodeDescription(const String& value, bool null = false);

/** Get reference to internal CIMInstance. This function tests the
properties for validy and to assure that all properties that are
required in the mof are in the CIMInstance
@return CIMInstance with the target CIM_Error
<p><b>example</b>
CIM_Error err1;
CIM_Error err2;
err1.setProbableCause(PROBABLE_CAUSE_ADAPTER_CARD_ERROR);
err2.setInstance(err1.getInstance());

*/
const CIMInstance& getInstance() const;

/** Set the internal instance (and throw an exception if instance
argument has an incompatible property types). This function tests the
properties for validy and to assure that all properties that are
required in the mof are in the CIMInstance.

@param instance CIMInstance which is the CIM_Error

@exception CIMExceptions TypeMismatchException if there is a 
property type mismatch and NoSuchPropertyException
if a required property is missing.

<p><b>example</b>
CIM_Error err1;
CIMInstance instance1 err1.getInstance();
*/
const void setInstance(const CIMInstance& instance);

/** Print this object to standard output. This is a diagnostic outut
and the exact format of the output cannot be depended on. It prints
the name and value of each property in the CIM_Error instance.
*/
void print() const;

private:

CIMInstance _inst;
};

6. Globalization Checklist

Phase 1 - No changes to any messages are planned for Phase 1

ID Globalization Requirement Planned?

(Yes/No)

 Comments
1 All translatable text messages have been added to the OpenPegasus message files.    
2      
3      
4      

 

Phase two - This may require extensive modifications to globalization.  That will be considered in a separate PEP.

7. Platform Considerations

This implementation is expected to be platform independent.

8. OpenPegasus Release Roadmap

Functionality Under Development
X.X.X		 Contributor Tested
X.X.X		 Community Tested

X.X.X

 Released

Experimental

X.X.X

 Released
X.X.X
CIM_Error (Phase 1) 2.6 2.7
CIM_Error Message Mods (Phase 2)       2.7  

8 Schedule

PEP  Milestone Planned Date Revised Date Actual Date Comments
Concept PEP Approval March 2006 Never really approved
Functional PEP Approval April 2006 Sept 06
Functionality Complete (FC) April 2006
Certification Test Complete (CTC) TBD

 

9. Discussion

===========================================================================================================

COMMENTS FROM VERSION 1.2

[ (dave_sudlik) We discussed this, but maybe I misunderstood. I thought that we could complete a 'phase 2' implementation using our own message catalogs, and then we'd have a 'phase 3' to migrate to DMTF standard message catalogs.
 ¤56] The activity is broken into these two phases because, while all of the basic definitions required to implement phase one are in place today, much of the background necessary to implement phase 2 are simply not in place because of dependence on the DMTF message catalogs.

RESPONSE: It seemed to be illogical to actually do our own message catalogs and create a full set of catalogs, CIM_Error messages etc. since we feel that the actual message catalogs will be drastically different than anything we would do and will probably require extensive changes.

[ (dave_sudlik) Can we update this based on our current 2.6 dates?
 ¤58] 4.3 Proposed Dates for these Activities

RESPONSE: Updated

[ (dave_sudlik) typo: infrasturcture
 ¤65] -

RESPONSE: Fixed.

[ (dave_sudlik) Again: does it really 'depend on the existance of DMTF message catalogs'?
 ¤66]

RESPONSE: Again, it is a matter of level of effort.

[ (dave_sudlik) incomplete sentence?
 ¤71] It appears that all of the CRs defined below have been incorporated into the

RESPONSE: Fixed.

[ (dave_sudlik) typo: product
 ¤107] Sections describe operations that can product ERRORs

RESPONSE: Fixed.

[ (dave_sudlik) Are there direct conflicts between what we have, and what is listed in the CIM spec and the CIM_Error MOF?
 ¤126] Issues with multiple definitions for StatusCode - It became apparent during the work that we have multiple different definitions today for CIMStatus code.  In the file Common/CIMStatusCode.h we include codes 1 - 17.  In the current CIM Operations specification there are two additional codes (19 and 20 (skipping 18).  Finally in the CIM_Error class, there are now all 20 codes.

RESPONSE:  Not sure yet.  I need to generate a CR and will answer that question as the CR is generated.

[ (dave_sudlik) typo: probably
 ¤152] At this point the most probably solution is to propose an extension to cimxml whereby the error entity could be attached after the IRETURNVALUE entity in a response.  Thus, the xml DTD would look like:

[ (k_schopmeyer) Roger proposed that we NOT make CIM_Error publicly available since this is a C++ facade for a particular version of a class and will not self-modify if the class definition is updated. However, the use of the facade makes life significantly simpler for the client writer (accessing properties in a single call) that it is a shame not to make this available to the client writer. At this point we do not have a clear answer. The possibilites are A) not make CIM_Error available and simply return the CIM_Instance representing the error. Easy for us, harder for the client B)make only CIM_Error available so that any Pegasus code is commited to a particular version of the CIM_Error class. C) make both CIM_Error and the corresponding CIM_Instance available with appropriate warnings comments, etc.
(dave_sudlik) I assume we're talking about the difference between something like CIMError.getCIMStatusCode, versus CIMInstance findProperty/getProperty. Let's discuss.
(r_kumpf) Suggested clarification (for DMTF CR?): CIM_Error instances returned in a CIM response must be consistent with the CIM_Error class definition in the target namespace. If a CIM_Error class is not defined in the target namespace, CIM_Error instances must not be included in the response.
 ¤163] <<<This section is new with version 1.2>>>

RESPONSE: At this point we agree that the CIMError facade class not be public for several reasons, but specifically because the DMTF CIM_Error is experimental and subject to non-compatible changes.  However, we would like to revisit this if CIM_Error experimental status is removed in a future version.

With respect to the issue of the CIM_Error class in a namespace and the use of CIM_Error in responses it seems logical to state that CIM_Error responses will only be transmitted for those namespaces in which the Client can receive a valid response to a getClass(namespace, "CIM_Error");.  Note that this has not been implemented at this point and there are several possibilities in implementing this but we feel that it is a logical limitation.  However, we also expect this to be part of a CR to the DMTF and they may change the rules.

[ (dave_sudlik) Are you referring to those in Exception.h (eg. IndexOutOfBoundsException, etc)? Would there be any value in creating a CIM_Error instance in these exceptions that contains essentially duplicate information? What about those in ProviderException.h?
 ¤188] 3. Extensions to specific CIM_Exceptions to provide additional information required to create CIM_Error enabled exceptions.  Note that these exception extensions are NOT defined in the current proposal because there is NO clear definiton of the CIM_Errors that would be attached and the exact information to be generated.

RESPONSE: Within the DMTF the conception is that errors be programatically actionable.  Therefore, when the catalogs arrive, an error like "index-out-of-bounds" MUST be translated to some error code/instance that is considered interoperable and actionable.  Actionable means things like (can I retry? can I used already received data? etc. can be answered by the client software.  Thus YES, our errors will be mapped at some point to common errors.  I would assume that we keep the text but that the DMTF must have catagories of errors and information in CIM_Error that allow the software to make decisions and which are common across all platforms.

[ (dave_sudlik) Can we agree this is phas 3 (to be listed under section 4.11)?
 ¤189] 4.10 Mating this concept to DMTF MessageIDs

[ (r_kumpf) What is the algorithm for aggregating errors? What StatusCode is chosen for the error response?
 ¤199]

RESPONSE: None today.  We are working on DMTF CR.

CIMServer Infrastructure

[ (dave_sudlik) Good question. It would seem to me that there is enough variable information (eg. ErrorSource) that we couldn't make this fixed -- but then again, the variable information seems to be optional in the CIM_Error.
 ¤237] QUESTION: Do we have to deal with all CIMExceptions through this or can we force some of them to automatically generate the CIM_Error instance internally as part of the exception? In a sense, are there exceptions where the CIM_Error information is fixed and can be defined within the CIMException?

RESPONSE: Not sure myself.  We are trying to create the interfaces and code today to allow moving these decisions to the future.

[ (l_j.lamers) Are we sure the providers and provider writers have a common pattern to prevent interoperability issues? Will the implementation assure client interoperability?
 ¤937] CIMClient Interface Changes

RESPONSE: At the level of the response messages yes.  At the level of common semantics we have a lot of work to do.

[ (r_kumpf) It would be clearer to group the CIMException interface changes together (as Common interface changes?) rather than split out the Client and Provider changes. Really three new methods are proposed: getErrorCount(), getError(), and addError(). With this organization, it becomes clear that the statement at tag 948 is incorrect or at least misleading, because a client could modify the array by adding a new Error element.
 ¤939] The methods to be added to CIMException are:

  1. [ ¤940]  Uint32 getErrorCount() - returns count of CIMError instances attached to the ERROR element.
  2. [ (dave_sudlik) Is the method getError() or getCIMError()?
     ¤941]      CIMInstance getCIMError() - returns a single instance of CIMError.

RESPONSE: Moved all the CIMException changes to a single place in this document.

[ (r_kumpf) I made this comment in the last version, but it does not seem to have been acknowledged. I am not in favor of externalizing a Pegasus interface that is specific to a particular CIM class definition. To date, the Pegasus interfaces are at the metaschema level. Introducing an interface at the schema level has some unattractive implications and seems to set a dangerous precedent. For example, I don't see how versioning can be done effectively with this solution. The CIMError class would model a particular version of the DMTF's CIM_Error class. This would restrict a provider from returning properties that may have been added in a later version of the CIM_Error class. In effect, the CIM Server infrastructure would need to roll to a new version before a provider could be installed that returns the new properties. Also, has the DMTF guaranteed that subclasses of the CIM_Error class are not allowed? And how would the Pegasus CIMError class deal with incompatible changes in the DMTF CIM_Error class (such as when the CIM 3.0 schema is released)? There are good reasons to leave the Pegasus interfaces at the metaschema level and not to attempt to model a particular class in the schema.
(dave_sudlik) (just thinking out loud...) Could CIMError inherit from CIMInstance, and provide 'helper functions' for its properties. We would version CIMError in this case so providers could know which 'helper functions' are available.

Or maybe to be more specific, have CIMErrorRep inherit from CIMInstanceRep with a CIMError facade that includes 'helper functions'.
 ¤964] 1. CIMError.h which allows defining error instances to be attached to CIMResponses

RESPONSE: We agree at this point.  CIMError will not be externalized now.  However, it is clear that something like this for a class that is, in effect, a part of the required infrastructure needs more than just the standard meta tools since it will be used throughout the environment and the standard tools will leave us with excessive code and error prone coding.  I propose we first try to get this code in without that class public, get CIM_Error out of experimental and revisit this in Pegasus 2.7.

[ (r_kumpf) I understand that the DMTF spec allows multiple CIM_Errors to be contained in the response sent to the client. Is the intent in Pegasus to allow multiple CIM_Errors in a single response from a provider, or would we return multiple errors to the client only if we get errors from multiple providers?
 ¤968] A CIMException with attached error can therefore be created as follows:

RESPONSE: There is no limit.  Clearly the majority of errors probably include only a single error instance.  But at this point, there is no limit placed on how many error instances a single element of the environment can generate.  We went ahead and provide constructors in CIMException so that either a single CIMException or multiples could be attached ot a CIMException to cover this.

=============================================================================================================

COMMENTS FROM VERSION 1.1

  • [ (a_dunfey) Is there a requirement that the server somehow recognize old clients that do not support CIM_Error and not deliver CIM_Error instances as part of a response? What would happen if a Pegasus 2.5.1-based client application received a CIM_Error as a response from a GetInstance operation?
    (k_schopmeyer) From my understand of the Specs, existing Clients 'should' work OK. However, I can understand where during the transistion there may be cases where we have to work with clients that do not handle CIMError correctly and some sort of a 'temorary' variable to not add the CIM_Error instances to the response might be helpful. This would probably mean some sort of dynamic config varaible and not sure if this is worthwhile or not. I am open to suggestions.
    (dave_sudlik) Doesn't this just come down to, will existing clients silently ignore any INSTANCE subelements of an ERROR element?
     ¤32]     Implement the incorporation of CIM_Error information into CIM Server response messages based on the DMTF definitions.
  • [ (r_kumpf) I think the 'do not' should be removed from this sentence.
    (k_schopmeyer) Agreed. The sense was backwards.
     ¤33]     Implement this in a manner that allows backward compatibility both for servers and clients that do not implement the functionality within the DMTF constraints.
  • [ ¤34] Pegasus must provide the additional CIM_Error responses required by the HTTP specification section 2.3.1.3. This means that Pegasus must be capable of providing instances of CIM_Error representing the detailed error information required in addition to the error code now supplied.
  • [ (dave_sudlik) Is this something for the Query Capabilities control provider?
  • COMMENT: KARL No it is not.  This is simply the issue of cimxml and optional elements.
     ¤35]     The Pegasus CIM Client must be capable of dealing with both servers that are capable of returning the additional error information and those that are NOT capable of returning this information.
  • [ (r_kumpf) Does the Pegasus CIMListener currently return error responses? In what case would the CIMListener need to be enhanced to return CIM_Error responses? What is the 'Client' that is referred to here? Is it the CIMExportClient?
     ¤36]     The Pegasus CIM Listener infrastructure must be capable of delivering the error definitions defined in the HTTP specification 2.4.1.3 as response to indications received.The Client MUST be capable of operating with exactly the same error definitions that exist today.
  • COMMENT: The DMTF Specification defines the ESPMETHODRESPONSE element that includes the ERROR element. This ERROR element includes status code, descriptive text and optional CIM_Errors.  (See section 2.4.1.3 of the CIM Operations over HTTP spec, version 1.2 preliminary).  The Pegasus CIMExportRequestDecoder implements sending ERROR elements so we expect that this must be expanded to allow the passage of CIM_Error objects.  However, today the number of errors passed through this interface seems to be small and the primary emphasis has been on the error responses to operations (in part because there have been some CIM_Errors defined in the SNIA SMIs specification so that the priority of implementing either the infrastructure or actual CIM_Errors for the listener is not clear. 
  •  
  • [ (dave_sudlik) I understand this is a concept PEP, but I'd like to see in this PEP some indication of how provider exceptions will be addressed (I think this could be addressed by Roger's comment on tag 176).
     ¤38]     There is a requirement for provider exception generation to be backward compatible. There is also a requirement for providers to be able to generate CIM_Error exceptions. The generation of CIM_Error based messages is NOT exclusively a server function.  In fact, today, the first use as defined in the SNIA SMI-s specification would be messages probably generated by providers.
  • COMMENT: Any entity that can generate exceptions will be capable of generating CIM_Errors.  Thus, this will move to the providers just as it is implemented in the Server.

  • [ ¤39]
  •  
  • (dave_sudlik) Has it been determined if there will be a separate functional PEP for the stage 1 work? I don't see a placeholder PEP (263 is the functional PEP for stage 2 work). It would help set the expectation level for this PEP.
     ¤52]      COMMENT: THis PEP covers both the concepts and the implementation of the Infrastructure.
    Write Functional PEP defining the required detailed changes to Pegasus and Pegasus APIs. This is a Functional PEP in Pegasus Terms. Note that it may not be necessary to create separate PEPs if the work is determined to be not to extensive. That will be determined as we proceed.
  • [ ¤53]
  •  
    1. [ (dave_sudlik) I assume you're referring here to Clients in src/Clients (eg. Pegasus commands), and not test clients. I would expect that test clients are not changed -- consider this a backward compatibility test, and new test clients would be written to verify CIM_Error. (thought -- maybe clients like TestClient could have a run-time option to include CIM_Error support, default is to operate as today).
       ¤57]
      Implement changes to the CIMServer and any Pegasus defined providers that are part of the Pegasus CVS to incorporate CIM_Error processing. Note that this MAY also include some changes to the Clients in the Pegasus CVS to account for CIM_errors that are generated in addition to the current error code.

      [ ¤58]   COMMENT: Generally we do not expect to change all test clients. However, in the process of developing tests it might be useful to modify some test clients to provide adequate end-end tests.

    [ (dave_sudlik) PEP 263.
    ¤59]     NOTE: Phase 2 functionality will be documented in a separate PEP (CIM Error message modificaitons for CIMError information).

    COMMENT: PEP Number added

     

  • [ (r_kumpf) What are the DMTF's intentions for the definition of this class in the standard schema? Are CIM_Error instances associated with a namespace? I.e., should the CIM_Errors that are returned in a response be consistent with the schema of the CIM_Error definition in the namespace of the request? If not, then where does a client get the schema for the CIM_Error instances that are returned? And how are differing CIM_Error definitions managed across namespaces?
     ¤70]

    •  

    COMMENT:  KS: 12 June 2006  - CIM_Error is considered a transient class.  The DMTF has not placed any requirements, limitations, rules, etc. on it use in particular namespaces or its existence in certain namespaces. Within the Proposed implementation, we are providing a C++ facade for CIM_Error so that for our implementation, the actual instantiation of the class in any particular namespace is not considered critical since the class definition is embodied in the C++ facade.  The client does not have to get the CIM Class itself.  Since this is buried in our implementation, the issue of different versions of CIM_Error does not apply to the errors generated from within the CIM_Server.  That is our issue internally.  However, there is an open issue with providers.  We expect that providers will use the same interfaces as the CIM_Server (exceptions) to generate errors and so will be tied to the version of CIM_Error that is defined in the C++ Facade for CIM_Error. However, the mechanism does exist for CIM_Errors to be created from Pegasus CIMInstances and that could lead to other issues which we have not looked at to date.

    [ (r_kumpf) 'Missing' should be 'Mixing'?
    (k_schopmeyer) agreed
     ¤130]     Missing CIM_Error and Chunking

    COMMENT: Corrected.

    [ (a_dunfey) Is there a DMTF CR for the above changes? Do you have an idea as to how long it would take for such a change to be adopted, i.e. in the Pegasus v2.6 timeframe?
    (k_schopmeyer) I have one in process now and in the process of talking to several other WIP members to determine if we are really correct and what the best way to solve this is. May kinow more by 19 May morning.
    (dave_sudlik) I believe we've discussed this, but some clients also allow an application to start processing data before it's all been received.
     ¤159]     Note that this definition adds the entities in red to the IMETHODRESPONSE Element.. This means that we want the IMETHODRESPONSE Element to either return IRETURNVALUE or ERROR or IRETURNVALUE followed by optional ERROR.  If the ERROR follows IRETURNVALUE, the behavior is that it overrides the IRETURNVALUE and that the IRETURNVALUE should not be used.

    COMMENT: This issue is in the process of resolution within WIP today but that resolution is NOT complete.  However, this issue should not stop us from completing our implementation with that outstanding issue.  Just as today where we do not receive the ERROR element with chunked responses, we would not receive the ERROR element AND is corresponding CIM_Error attachments with chunked responses until this issue is resolved.

  • [ (dave_sudlik) You say 'it will be the client application responsibility to request CIM_Error information.' Is it really something that is 'requested'? Or will it always be there beginning in 2.6, and a client may choose to use or ignore it? Or am I misunderstanding your use of the word 'request'?
     ¤173]
    Extension of the client to provide an additional mechanism to pass this information to the client application if desired by the application. It is assumed that future client applications will want to make use of this additional information and therefore will want access to the details of the errors returned. The use of the additional information must be optional (it will be the client application responsibility to request CIM_Error information). This is consistent with the form today where the base information is simply an exception try/catch and the error status information can be requested within the catch block.

    • COMMENT: It will be the responsibility of the Client application to request the information just as today, it requests the Code and description information.  It will be avialable within the infrastructure and attached to the exception as another call just as the getStatusCode(), etc. are today.

    [ (r_kumpf) Do you have a complete summary of the impacts to the external interfaces? Here is what I've come up with so far:

    Are there others?
    (dave_sudlik) Yes, I'd like to see a section on externals as described by Roger. I'd also like to see a section on Dependencies. The two that come to mind right now are (1) DMTF resolution to chunking and CIM_Error, and (2) DMTF message catalogs. CR numbers that we can track would also be good.

    COMMENT: We have a section on open issues. I assume that this sufficies for Dependencies.

    COMMENT: Redid the section that covers this as section 4.9. Note that new constructors for the exception classes are dependent on the defintion of the errors themselves and additional information required.  We did not define them at this point awaiting additional information on the DMTF message catalogs.

    [ (dave_sudlik) So we will proceed in 2.6 with our non-standard CIM_Error messages, right?
     ¤183]     Today, Pegasus includes within the infrastructure and those providers that have been internationalized about 1500 separate error responses defined (this count is from the message files).  Eventually, the goal would be that the majority of these messages be standard CIM_Error messages.  This cannot be done until such time as there are messages to which we could standardize.  We have also not expanded ProviderException.h because we are unsure if we really want to do a general expansion with a predefined set of additional parameters or provide implement the additional parameters required for the CIM_Error completely within the CIM_Server.  If the CIM_Errors to be generated for a specific error that is defined in ProviderExtension.h is completely defined by the CIM_Server implementation, there is no need for the interface to be expanded.  All information for generation of the error would come from the server.  However, if there are issues where the provider itself would be required to define some of this information (ex. severity, etc.) then we MUST have new interfaces to that the provider can provide the additional information.  At this point there were so many undefined elements around the DMTF message catalogs that we put off defining changes until we have a clearer concept of what the DMTF is going to do.

    COMMENT: At this point, I consider the actual conversion of CIMExceptions to include CIM_Erros to be part of PEP 263 and dependent on the DMTF for at least some guidance.  IT does not appear to be a big gain for us to actually create CIM_Errors based on the the existing Pegasus exception information since the major goal of the whole effort is generation of common error definitions, not definitions particular to a particular server.

    Copyright (c) 2004 EMC Corporation; Hewlett-Packard Development Company, L.P.; IBM Corp.; The Open Group; VERITAS Software Corporation

    Permission is hereby granted, free of charge, to any person obtaining a copy  of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

     THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED  "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Template last modified: July 6, 2004 by Denise Eckstein
    Template version: 1.11A