Pegasus Project Working Paper

Compiler Extensions to Support Provider Registration

Authors: Denise Eckstein, Karl Schopmeyer

Last Update 2/22/2002 10:31 AM

Document: CompilerExtensionstoSupportProviderRegistration.htm

Revision Status

0.1

KS

Draft for discussion

Introduction

This document defines a set of extensions to the Pegasus CIM Compiler to help with the process of registering providers using MOF and the compiler as the registration tool. The additional functions are felt to be requirements to create an environment in Pegasus Version 2 that is usable for provider installation and registration in running Pegasus systems.

Background

These proposed extensions started with work done by HP to define some rules and possible extensions to the system to help control the input of MOF for provider registration.

We have to assume that provider registration can be done at any time, not simply at build of a new system and must be done when the CIMOn is running. Further, it is intended that this be done by inputting MOF to the system.

This is one of the characteristics that drives us to create the version of the CIM compiler that is driven from the client interface and can input when the CIMOM is running.

Further extensions revolve around:

• The providers not necessarily knowing what is in the CIMOM when they create their registration MOF.
• Controlling input to reduce the possibility that providers can input incorrect versions of MOF.

• Mandatory use of the Version Qualifier.
• The use of the Experimental Qualifier that identifies all classes that are considered experimental and not released. Generally we should never see the experimental qualifier on any classes in a released version of the CIM MOF and should see it only on classes that change or are added for a preliminary release. All of these classes must be either moved to release or removed from the Schema to allow a schema to move to release status within the DMTF.

The Version qualifier paramater is a single string representing the version which MUST be in the form of: 

M + "." + N + "." + U

M - The major version in numeric form in which the class was changed. 
N - The minor version in numeric form in which the class was changed. 
U - The update (e.g. errata, patch, ...) in numeric form in which the class was changed.

The Definition of Provider Guidelines

The following guidelines for providers and provider writers help to understand these requirements:

1.) Provider Developer's SHOULD include the definition of all required superclasses in the MOF.
2.) All class definitions MUST include a VERSION qualifier.
3.) Use of the VERSION qualifier string MUST comply with the DMTF guidelines.  In particular, any change that breaks backward compatibility MUST be labeled with a new MAJOR version number.
4.) All included class definitions MUST contain a complete and accurate definition of the specified version of the class.
5.) Provider Developer's SHOULD assume that the DMTF qualifiers defined in CIM version 2.6 are already defined in the namespace.

This MOF Update Utility is a very simple tool that supports a majority of the provider installation scenarios.  It handles the straight-forward upgrade cases.  Situations that require more sophisticated Schema manipulation  will require developers to write a customize CIM Client application to perform the necessary checks and schema modifications.  E.g., a customized application could be developed to perform a MAJOR version upgrade.

MOF Enhancements to Support Provider Registration

General changes

1. Extend the compiler to allow class replacement. Thus, the compiler would be able to replace classes as well as install classes under circumstances defined in this document.
2. Extend the compiler to allow use through the client interface. The proposed solution is to provide two versions of the compiler. One would be used through the reposiotory interface (as is done today). The second version would use the client interface and would be used only when the CIMServer was running.

Specific option additions

1. Add a new parameter to the cimmof command line, --experimental, to control handling of the experimental classes and qualifiers.

Class Replacement Rules and the –experimental Option

The compiler must be capable not only of installing new classes into the repository but of replacing them under selected circumstances. In part these circumstances are controlled by the CIMOM itself because the modify class or the delete class and add class functions will be used to replace classes and there is a set of rules imposed by the CIMOM on the ability to either modify classes or to delete existing classes.

These rules apply primarily to:

• Deletion of classes when there are either subclasses or instances of a class in existence.
• Modification of qualifiers or properties of a class to maintain validity of any subclasses or instances.

In addition, there will be a general requirement that in certain cases, the rejection of a single class if it is not installable is not enough, the entire MOF must be rejected to assure that the repository is maintained valid. This is defined specifically in the following paragraphs

However, some specific rules that were defined specifically:

NOTE: References to the Minor version defined below also apply to the update parameter in the Version qualifier.

The --experimental option is a new CIM compiler command line option to help control the replacement of classes. In general, setting this option removes certain limitations on the replacement of classes in conjunction with the experimental and version qualifiers on the classes themselves.

A complete MOF input must be rejected if:

• It would require replacing a class definition with either a MAJOR version update or with an earlier MAJOR version number.
• If the --experimental parameter IS NOT specified and it would require replacing an EXPERIMENTAL class definition with either an updated EXPERIMENTAL class definition or RELEASED class definition. The justification is that replacing an EXPERIMENTAL with a RELEASED or EXPERIMENTAL class could break other classes. It is important that this action be explicit.
• It would require replacing a RELEASED class definition with an EXPERIMENTAL class definition.

A class definition within a MOF must be ignored if:

• It would result in replacing a class definition with one with an earlier MINOR version number.

An existing class definition will be replaced if ...

• It represents an MINOR version update. <<DENISE. This has been in from first note from you but it is in conflict with everything else>>
• If the --experimental parameter IS specified and it would require replacing an EXPERIMENTAL class definition with either an updated EXPERIMENTAL class definition or RELEASED class definition.

A qualifier declaration within a MOF must be ignored if:

1. It would result in replacing an existing qualifier declaration.

NOTE: Note the use of the word ignored vs. rejected. The requirement is to reject the entire MOF file under certain circumstances.

This means that somehow the compiler must predetermine if there are any reasons for rejecting the MOF BEFORE it puts any classes into the repository. While this implies a multiplass compiler, we hope that there is some way this can be creatively accomplished without major changes to the compiler (ex. creating a super process that would simply call the compiler with different options for the check phase).

--Version Option

The –Version option is a proposal, but not an absolute requirement. However, the version qualifier is now understood to be important information to maintaining the validity of a CIM repository. There is at least one good reason to provide this as a compiler test (probably in addition to having an internal test) – It would be logical to insure that no mof in a mof file was installed if there were classes without the version qualifier.

Therefore, it appears that there should be ways to:

• Limit the entry of new classes to the repository that do not have the version qualifier
• Assure that the version qualifier has the correct version format on classes being created or modified
• Apply the qualifier in mass to a set of classes imported via the compiler.

.

If the option is present with the string value (x.x.x) the CIM compiler would add the Version("X.X.X") qualifier to any class that does not have this qualifier and is being added to the repository or modified.

If the option is present without the string value(x.y.z) it could allow the compiler to accept MOF that did not have the version qualifier defined for classes.

If the –version option (or an equivalent pragma (see below) is not defined, the MOF will be rejected if any class does not have the version qualifier.

If the qualifier is defined for any class, the CIM compiler (or in reality the CIMOM itself) will confirm that the version string is of the form <integer> “.” <integer> “.” integer

Note that we have seriously considered proposing that there be a version pragma that would accomplish what is being proposed for the command line. This would be a more logical solution. However, the negative of that proposal today is that a new pragma touches on the DMTF specifications and until and unless we achieved DMTF agreement to the pragma, we would be out of scope with any MOF that had this pragma. It is still a useful concept but we do not want to require it when it is not part of the DMTF standards.

Since starting with version 2.6 (march 2002) all DMTF schemas will have the Version qualifier, the demand for this option has been reduced. The originators would be willing to discuss options or possible deletion of this requirement if it was a severe schedule burden.

NOTE: The version option and/or pragma is a proposed extension but is not absolutely required for Pegasus version 2.0. If it is possible to do this extension or part of the extensio within the timeframe of version 2.0, we will do it. If not, it will be considered in the future.