Corrigendum:
U064
Date:
September 2005
Document:
C051
Systems Management: Common Management
Programming Interface (CMPI)
Code:
1047 09/05 C051/U064
Editing instructions are shown in red.
Added or modified blocks of text are shown boxed.
Change Number:
U064/1
Title:
Internationalization Support
Qualifier:
Major Technical
Rationale:
Change Request WSI-031 was approved and implemented during the Company Review of CMPI (C051). It changed all occurrences of char* to wchar*. However, after publication WSI-031 was withdrawn because, as defined in the Specification (Section 4.2), and as implemented, CMPI does not use wchar to support internationalization. Instead, it uses UTF-8 encoding throughout its implementation(s). UTF-8 is a much more effective way to support internationalization.
Change:
Change all occurrences of wchar to char.
Change Number:
U064/2
Title:
Convenience Macros and C++ Wrappers
Qualifier:
Minor Editorial
Rationale:
CMPI convenience macros are referred to in the text but are not included in the document.
Change:
Remove all references to the CMPI convenience macros and C++ convenience files.
Change Number:
U064/3
Title:
Missing element in _CMPIBroker
Qualifier:
Major Technical
Rationale:
The CMPIBroker structure definition is missing the element "const void *hdl".
Change:
In Section 3.2, change the definition of _CMPIBroker to:

 
typedef struct _CMPIBroker {
  const void *hdl;
  const CMPIBrokerFT *bft;
  const CMPIBrokerEncFT *eft;
  const CMPIBrokerExtFT *xft;
} CMPIBroker;
Change Number:
U064/4
Title:
_CreateMI function should use const
Qualifier:
Major Technical
Rationale:
The _CreateMI function should use const values for some parameters.
Change:
In Section 5.1.1, change the definition of the _CreateMI function to:

 
CMPI<mi-type>MI *<mi-name>_Create<mi-type>MI(const CMPIBroker*,
                  const CMPIContext*, CMPIStatus*);
Change Number:
U064/5
Title:
_Generic_CreateMI function should use const
Qualifier:
Major Technical
Rationale:
The Generic _CreateMI function should use const values for some arguments.
Change:
In Section 5.1.2, change the definition of the _Generic_CreateMI function to:

 
CMPI<mi-type>MI*_Generic_Create<mi-type$gt;MI(const CMPIBroker*,
                  const CMPIContext*, const char*, CMPIStatus*)
Change Number:
U064/6
Title:
Missing const in MI function tables
Qualifier:
Major Technical
Rationale:
The definition of "void *hdl" in the MI function is missing the const attribute.
Change:
In Section 5.1.3.1, change the definition of _CMPIInstanceMI to:
  
typedef struct _CMPIInstanceMI {
  const void* hdl;
  struct _CMPIInstanceMIFT* ft;
} CMPIInstanceMI;

In Section 5.1.3.2, change the definition of _CMPIAssociationMI to:
  
typedef struct _CMPIAssocationMI {
  const void* hdl;
  struct _CMPIAssociationMIFT* ft;
} CMPIAssociationMI;

In Section 5.1.3.3, change the definition of _CMPIMethodMI to:
  
typedef struct _CMPIMethodMI {
  const void* hdl;
  struct _CMPIMethodMIFT* ft;
} CMPIMethodMI;

In Section 5.1.3.4, change the definition of _CMPIIndicationMI to:
  
typedef struct _CMPIIndicationMI {
  const void* hdl;
  struct _CMPIIndicationMIFT* ft;
} CMPIIndicationMI;

In Section 6.7, change the definition of _CMPIArgs to:
  
typedef struct _CMPIArgs {
  const void* hdl;
  struct _CMPIArgsFT* ft;
} CMPIArgs;
Change Number:
U064/7
Title:
Incorrect use of const in invokeMethod function call
Qualifier:
Major Technical
Rationale:
The final argument in the invokeMethod function call should not have the const attribute.
Change:
In Section 5.1.3.3, change the definition of the invokeMethod function to:
  
CMPIStatus (*invokeMethod)
  (CMPIMethodMI*, const CMPIContext*
  const CMPIResult*, const CMPIObjectPath*,
  const char*, const CMPIArgs*, CMPIArgs*);

In Section 5.4, change the SYNOPSIS section of the CMPIMethodMIFT.invokeMethod() reference page to:
  
CMPIMethodMI* mi,
  const CMPIContext* ctx,
  const CMPIResult* rslt,
  const CMPIObjectPath* op,
  const char* method,
  const CMPIArgs* in,
  CMPIArgs* out)
Change Number:
U064/8
Title:
No mention of CMPIPropertyMIFT
Qualifier:
Major Technical
Rationale:
The definition of CMPIPropertyMIFT is missing.
Change:
Add a new Section 5.1.3.5 as follows:

5.1.3.5 CMPIPropertyMIFT 
typedef struct _CMPIPropertyMIFT {
  int ftVersion;
  int miVersion;
  const char *miName;
  CMPIStatus (*cleanup)
    (CMPIPropertyMI* mi, const CMPIContext* ctx,
     CMPIBoolean terminating);
  CMPIStatus (*setProperty)
    (CMPIPropertyMI* mi, const CMPIContext* ctx,
     const CMPIResult* rslt, const CMPIObjectPath* op,
     const char *name, const CMPIData data);
  CMPIStatus (*getProperty)
    (CMPIPropertyMI*,const CMPIContext*,const CMPIResult*,
     const CMPIObjectPath*, const char*);
};

Add an additional reference page in Section 5.1.4 as follows:

CMPIPropertyMIFT.cleanup()
NAME
CMPIPropertyMIFT.cleanup() - perform cleanup prior to unloading the Property provider
SYNOPSIS
CMPIStatus CMPIPropertyMIFT.cleanup(
  CMPIPropertyMI* mi,
  const CMPIContext* ctx,
  CMPIBoolean terminating)
DESCRIPTION
The CMPIPropertyMIFT.cleanup() function is called prior to the unloading of the provider.

The mi argument is a pointer to a CMPIPropertyMI structure.

The ctx argument is a pointer to a CMPIContext structure containing the Invocation Context.

When true, the terminating argument indicates that the MB is in the process of terminating and thatcleanup must be done. When set to false, the MI may respond with CMPI_IRC_DO_NOT_UNLOAD, or CMPI_IRC_NEVER_UNLOAD, indicating that unload will interfere with current MI processing.
RETURN STATUS
The CMPIPropertyMIFT.cleanup() function returns a CMPIStatus structure.

The following CMPIrc codes shall be recognized:
CMPI_RC_OK Operation successful.
CMPI_RC_ERR_FAILED Unspecific error occurred.
CMPI_RC_DO_NOT_UNLOAD Operation successful - do not unload now.
CMPI_RC_NEVER_UNLOAD Operation successful - never unload.

ERRORS
None.
EXAMPLES
None.
APPLICATION USAGE
None.
SEE ALSO
None.
CHANGE HISTORY
Added in Issue 2.


Renumber Sections 5.6 and 5.7 to 5.7 and 5.8 respectively. Add a new Section 5.6, entitled Property MI Signatures, containing the following two reference pages:
CMPIPropertyMIFT.setProperty()
NAME
CMPIPropertyMIFT.setProperty() - set the named property value of an Instance defined by the <op> argument
SYNOPSIS
CMPIStatus CMPIPropertyMIFT.setProperty(
  CMPIPropertyMI* mi,
  const CMPIContext* ctx,
  const CMPIResult* rslt,
  const CMPIObjectPath* op,
  const char *name,
  const CMPIData data)
DESCRIPTION
The CMPIPropertyMIFT.setProperty() function sets a named property value of an Instance.

The mi argument is a pointer to a CMPIPropertyMI structure.

The ctx argumant is a pointer to a CMPIContext structure containing the Invocation Context.

The rslt argument points to the result data container.

The op argument points to the source ObjectPath containing namespace, classname, and key components.

The name argument points to a string containing the property name.

The data argument is a CMPIData structure containing the datavalue to be assigned to the property
RETURN STATUS
The CMPIPropertyMIFT.setProperty() function returns a CMPIStatus structure.

The following CMPIrc codes shall be recognized:
CMPI_RC_OK Operation successful.
CMPI_RC_ERR_FAILED Unspecific error occurred.
CMPI_RC_ERR_ACCESS_DENIED Not authorized.
CMPI_RC_ERR_NOT_SUPPORTED Operation not supported by this MI.
CMPI_RC_ERR_INVALID_NAMESPACE The namespace is invalid.
CMPI_RC_ERR_INVALID_PARAMETER The parameter is invalid.
CMPI_RC_ERR_INVALID_CLASS The CIM class does not exist in the specified namespace.
CMPI_RC_ERR_NOT_FOUND Instance not found.
CMPI_RC_ERR_NO_SUCH_PROPERTY Entry not found.
CMPI_RC_ERR_TYPE_MISMATCH Value types incompatible.
 
ERRORS
None.
EXAMPLES
None.
APPLICATION USAGE
None.
SEE ALSO
None.
CHANGE HISTORY
Added in Issue 2.

CMPIPropertyMIFT.getProperty()
NAME
CMPIPropertyMIFT.getProperty() - get a named property value of an Instance defined by the <op> argument
SYNOPSIS
CMPIStatus CMPIPropertyMIFT.getProperty(
  CMPIPropertyMI* mi,
  const CMPIContext* ctx,
  const CMPIResult* rslt,
  const CMPIObjectPath* op,
  const char* name)
DESCRIPTION
The CMPIPropertyMIFT.getProperty() gets a named property value of an Instance.

The mi argument is a pointer to a CMPIPropertyMI structure.

The ctx argumant is a pointer to a CMPIContext structure containing the Invocation Context.

The rslt argument points to the result data container. 

The op argument points to the source ObjectPath containing namespace, classname, and key components.

The name argument points to a string containing the property name.
RETURN STATUS
The CMPIAssociationMIFT.getProperty() function returns a CMPIStatus structure.

The following CMPIrc codes shall be recognized:
CMPI_RC_OK Operation successful.
CMPI_RC_ERR_FAILED Unspecific error occurred.
CMPI_RC_ERR_ACCESS_DENIED Not authorized.
CMPI_RC_ERR_INVALID_NAMESPACE The namespace is invalid.
CMPI_RC_ERR_INVALID_PARAMETER The parameter is invalid.
CMPI_RC_ERR_INVALID_CLASS The CIM class does not exist in the specified namespace.
CMPI_RC_ERR_NOT_FOUND Instance not found.
CMPI_RC_ERR_NO_SUCH_PROPERTY Entry not found.
 
ERRORS
None.
EXAMPLES
None.
APPLICATION USAGE
None.
SEE ALSO
None.
CHANGE HISTORY
Added in Issue 2.
Change Number:
U064/9
Title:
Ambiguous argument name
Qualifier:
Major Technical
Rationale:
The definition of CMPIPropertyMIFT is missing.
Change:
In Section 5.5, make the following changes to the CMPIIndicationMIFT.activateFilter(), CMPIIndicationMIFT.authorizeFilter(), CMPIIndicationMIFT.deactivateFilter() and CMPIIndicationMIFT.mustPoll() reference pages:

In the SYNOPSIS, change the name of the eventType argument to className.

In the DESCRIPTION, change the description of the eventType to:
The className argument is the class name extracted from the filter FROM clause.
Change Number:
U064/10
Title:
Incorrect entry in _CMPIContextFT function table
Qualifier:
Major Technical
Rationale:
There is an erroneous entry in the _CMPIContextFT function table.
Change:
In Section 5.7, remove the following lines from definition of _CMPIContextFT:

  
void* (*reserved1)
  (const CMPIContext*,CMPIStatus*);
Change Number:
U064/11
Title:
Missing argument in newArray function call
Qualifier:
Major Technical
Rationale:
There is an argument missing from the newArray function call definition.
Change:
In Section 6.1, change the newArray function call definition to:

  
CMPIArray* (*newArray)
  (const CMPIBroker*, CMPICount,
  CMPIType, CMPIStatus*);
Change Number:
U064/12
Title:
The severity argument in the CMPIBrokerEncFT.logMessage function call has no defined values
Qualifier:
Minor Technical
Rationale:
With no defined values, the programmer cannot make effective use of the severity argument.
Change:
Add a new Section 4.8 as follows:

4.8 CMPI Severity Codes
The following severity codes are recognized: 
typedef enum _CMPISeverity {
  CMPI_SEV_ERROR   = 1,
  CMPI_SEV_INFO    = 2,
  CMPI_SEV_WARNING = 3,
  CMPI_DEV_DEBUG   = 4
}

On the CMPIBrokerEncFT.logMessage() reference page, add the following text after the first sentence of the DESCRIPTION:

This function exists to provide a mechanism by which to provide information about errors.

Replace the DESCRIPTION of the severity argument with:

The severity argument describes the severity of log message. Severity levels are defined in Section 4.8.
Change Number:
U064/13
Title:
The level argument in the CMPIBrokerEncFT.trace function call has no defined values
Qualifier:
Minor Technical
Rationale:
With no defined values, the programmer cannot make effective use of the level argument.
Change:
Add a new Section 4.9 as follows:

4.9 CMPI Level Codes
The following level codes are recognized: 
typedef enum _CMPILevel {
  CMPI_LEV_INFO     = 1, /* generic information */
  CMPI_LEV_WARNING  = 2, /* warnings */
  CMPI_LEV_VERBOSE  = 3  /* detailed/specific information */
}

On the CMPIBrokerEncFT.trace() reference page, add the following text after the first sentence of the DESCRIPTION:
This function exists to provide a mechanism by which debugging information may be generated.

Replace the DESCRIPTION of the level argument with:

The level argument describes the level of log message. Levels are defined in Section 4.9.
Change Number:
U064/14
Title:
The ordering of functions in the _CMPIInstanceFT function table is inconsistent with historical implementations
Qualifier:
Major Technical
Rationale:
The order of the functions in the _CMPIInstanceFT function table was changed in a way that is incompatible with historical CMPI implementations.
Change:
Change the _CMPIInstanceFT function table to:

  
typedef struct _CMPIInstanceFT {
  int ftVersion;
  CMPIStatus (*release)
    (CMPIInstance*);
  CMPIInstance* (*clone)
    (const CMPIInstance*,CMPIStatus*);
  CMPIData (*getProperty)
    (const CMPIInstance*,const char*, CMPIStatus*);
  CMPIData (*getPropertyAt
    (const CMPIInstance*,unsigned int, CMPIString**,
     CMPIStatus*);
  unsigned int (*getPropertyCount)
    (const CMPIInstance*,CMPIStatus*);
  CMPIStatus (*setProperty)
    (const CMPIInstance*,const char*, const CMPIValue*,
     CMPIType);
  CMPIObjectPath* (*getObjectPath)
    (const CMPIInstance*,CMPIStatus*);
  CMPIStatus (*setPropertyFilter)
    (const CMPIInstance*, const char**,const**);
  CMPIStatus (*setObjectPath)
    (CMPIInstance*, const CMPIObjectPath*);
>} CMPIInstanceFT;
Change Number:
U064/15
Title:
The setProperty function does not perform semantic checking
Qualifier:
Major Technical
Rationale:
The CMPIInstanceFT.setProperty function definition does not define whether or not the function checks for valid property names.
Change:
In Section 6.5, on the CMPIInstanceFT.setProperty() reference page, add the following text after the first sentence of the DESCRIPTION:
The CMPIInstanceFT.setProperty() function does not perform any semantic checking.
Change Number:
U064/16
Title:
Typographical error
Qualifier:
Minor Editorial
Rationale:
"int" has been mis-spelled "inc"
Change:
In Section 8.9, on the CMPIBrokerExtFT.threadOnce() reference page, change the SYNOPSIS to:

  
int CMPIBrokerExtFT.threadOnce(
  int *once, void (*function)(void)
);
Change Number:
U064/17
Title:
CMPIPredOp is referenced but not defined
Qualifier:
Major Technical
Rationale:
The CMPIPredOp enumeration is referenced but not defined.
Change:
Add a new Section 4.5.5, as follows:

4.5.5 CMPIPredOp 
typedef enum _CMPIPredOp {
  CMPI_PredOp_Equals              =1,
  CMPI_PredOp_NotEquals           =2,
  CMPI_PredOp_LessThan            =3,
  CMPI_PredOp_GreaterThanOrEquals =4,
  CMPI_PredOp_GreaterThan         =5,
  CMPI_PredOp_LessThanOrEquals    =6,
  CMPI_PredOp_Isa                 =7,
  CMPI_PredOp_NotIsa              =8,
  CMPI_PredOp_Like                =9,
  CMPI_PredOp_NotLike             =10
}
Change Number:
U064/18
Title:
Typographical error
Qualifier:
Minor Editorial
Rationale:
brokerClassification used in place of brokerCapabilities. In addition, brokerCapabilities is incorrectly designated as a function.
Change:
In Section 8.1, change the single instance of brokerClassification to brokerCapabilities.

Remove the "()" from all occurrences of brokerCapabilities().
Change Number:
U064/19
Title:
The order of arguments to the _CMPIBrokerFT.modifyInstance function is inconsistent
Qualifier:
Major Technical
Rationale:
The order of arguments to the _CMPIBrokerFT.modifyInstance function is defined inconsistently.
Change:
In Section 8.1, in the definition of the _CMPIBrokerFT structure, change the definition of modifyInstance to:

  
CMPIStatus (*modifyInstance)
  (const CMPIBroker*, const CMPIContext*,
  const CMPIObjectPath*, CMPIInstance*,
  const char**);
Change Number:
U064/20
Title:
Duplicate Text
Qualifier:
Minor Editorial
Rationale:
The definition of the _CMPIBrokerExtFT structure appears twice.
Change:
In Section 8.9, delete one instance of the _CMPIBrokerExtFT structure definition.
Change Number:
U064/21
Title:
Undefined ftVersion Values
Qualifier:
Minor Technical
Rationale:
No values are defined for ftVersion
Change:
In Section 5.1.3. add the following text to the end of the second paragraph:

For this version of the CMPI Technical Standard, the value of ftVersion should be 100.
Change Number:
U064/22
Title:
SetPropertyFilter
Qualifier:
Major Technical
Rationale:
The setPropertyFilter incorrectly adds additional property names to an MB filter. This can result in the requested instance having more properties than the propertyList argument specified by the CIM user contains. This violates the CIM over XML specification which states: "The returned Instance MUST NOT include elements for any Properties missing from this list."

However, this function can also be used by the provider writer as a means of "priming" the instance. The priming feature is not available in the CMPI 1.0 Technical Standard. It may be added to a future version  (via a new function).
Change:
In Section 6.5, on the CMPIInstanceFT.setPropertyFilter() reference page, make the following changes:

Add the following text at the end of the first paragraph of the DESCRIPTION:

The MB may not support this function.

Add the following at the end of the RETURN VALUE section:
CMPI_RC_ERR_NOT_SUPPORTED The MB does not support this function.
Change Number:
U064/23
Title:
exitThread not documented
Qualifier:
Major Technical
Rationale:
exitThread is not documented.
Change:
In Section 8.9, add the following reference page:
CMPIBrokerExtFT.exitThread()
NAME
CMPIBrokerExtFT.exitThread() - causes the current thread to exit with the passed in return code using POSIX threading semantics
SYNOPSIS
int CMPIBrokerExtFT.exitThread(
  CMPI_THREAD_RETURN return_code)
DESCRIPTION
The CMPIBrokerExtFT.exitThread() function causes the current thread to exit with the passed in return code using POSIX threading semantics.

The return_code argument is the return code that should be used for the thread.
RETURN STATUS
The CMPIBrokerEXtFT.exitThread() function never returns.
Change Number:
U064/24
Title:
CMPISint32 and CMPIUint32 are not properly defined
Qualifier:
Minor Technical
Rationale:
The CMPIUint32 and CMPISint32 are defined as long, which on Linux (32-bit and 64-bit) is a 4-byte value. However, on other platforms (e.g., HP-UX), this value changes size depending from 32-bit to 64-bit. Making these values 32-bit by using int assures that it is 4-byte long.
Change:
In Section 4.3, change the definitions of CMPIUint32 and CMPISint32 to:
typedef unsigned int CMPIUint32;
typedef signed int CMPISint32;
Change Number:
U064/25
Title:
CMPI_THREAD_CDECL is not defined
Qualifier:
Minor Technical
Rationale:
No value is provided for the CMPI_THREAD_CDECL macro.
Change:
In Section 8.9, delete the definition of CMPI_THREAD_CDECL.

Add the following text as a new paragraph after the fourth paragraph:

The CMPI_THREAD_CDECL is operating system-specific and should be defined appropriately for each operating system. For example, currently the macro on Windows is __stdcall, while under zOS it is defined as __cdecl.
Change Number:
U064/26
Title:
CMPIIndicationMIFT.activateFilter filter argument incorrectly described.
Qualifier:
Minor Editorial
Rationale:
There is additional, incorrect descriptive text for the filter argument.
Change:
In Section 5.5, on the CMPIIndicationMIFT.activateFIlter() reference page, in the DESCRIPTION, delete the second sentence from the description of the filter argument.
Change Number:
U064/27
Title:
Incorrect specification of UTC string format.
Qualifier:
Minor Editorial
Rationale:
In CMPIBrokerEncFT.newDateTimeFromChars() and CMPIDateTimeFT.getStringFormat(), the UTC string format is incorrectly specified.
Change:
In Section 5.5 on the CMPIBrokerEncFT.newDateTimeFromChars() reference page, add the following text at the end of the first paragraph of the DESCRIPTION:
The utcTime argument contains a Date/Time value expressed in the character format defined in the CIM XML v2 specification.

In Section 6.8 on the CMPIDateTimeFT.getStringFormat() reference page, change the first paragraph of the DESCRIPTION to:

The CMPIDateTimeFT.getStringFormat() function shall return the value of a DateTime as a string formatted using the character format defined in the CIM XML v2 specification.

End of Corrigendum