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.
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.
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.
This document is the concept PEP that lays out the reviews the requirements, and lays out the architecture for the proposed solutions.
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:
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.
Based on the above, the following is an initial estimate of dates (See the schedule section for more detail on dates an progress):
- 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.
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
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
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
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.
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.
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? ) )>
|
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.
<<<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.
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.
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:
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.
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.
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.
PHASE 1 - Extension of Infrastructure (PEP 245)
PHASE 2 - Modification of the existing Error Handling Calls in the OpenPegasus CIMServer and providers. (PEP263)
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.
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 myInstancecomplete instanceCIMError err1.setInstance(myCIMInstance); / converts instance to CIMerror
The proposed implementation of this Class is in Section 5 (CIMError Class)
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
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;} } }
These changes are actually made to Exception.h and Exception.cpp
Append any created error instances to the output buffer
Get the CIM_Error instances from the received response and attach to the error.
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);
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
// 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; };
Both unit tests and end-end tests will be provided to test the basic creation, transmission, and reception of CIMErrors.
Unit tests:
End-End Tests
Not yet completed.
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
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; };
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 |
This implementation is expected to be platform independent.
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 |
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 |
===========================================================================================================
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.
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.
[ (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.
[ (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.
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:
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
[ ¤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
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.
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.
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.
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