[ ¤193] 2.5.1 CIMClient.h Interface extensions

[ ¤194]   Note that these will be within an experimental ifdef block
[ ¤195]

[

¤196] 
//KS-PULL 

    /** The openenumerateInstances method opens a pulled
    enumeration instances context to enumerate  instances of a CIM Class 
    in the target Namespace and optionally returns instances. 

    @param enumerationContext CIMEnumerationContext, a returned parameter 
    that provides context for subsequent pull operations. This parameter is
    considered opaque to the user.

    @param  EndOfSequence Boolean parameter that the server 
    provides to define the end of the enumeration. If this 
    parameter* is returned true, the server has determined that 
    the** enumeration is complete and as closed the
    enumerationContext.

    @param nameSpace CIMNamespaceName The nameSpace parameter is a string that 
    defines the target namespace. See defintion of
    \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.

    @param className The className input parameter defines the
    Class that is the basis for the enumeration.

    @param deepInheritance If the deepInheritance input
    parameter is true, this specifies that, for each
    returned Instance of the Class, all properties of the Instance MUST
    be present (subject to constraints imposed by the other
    parameters), including any which were added by subclassing the specified
    Class. If false, each returned Instance includes only
    properties defined for the specified Class.

    The Enumerate Instances operation returns the same number of instances
    regardless of whether or not the DeepInheritance flag is set.  The
    DeepInheritance flag is only used to determine whether or not 
    the subclass property values should be returned.

    @param includeClassOrigin If the Boolean includeClassOrigin input
    parameter is true, this specifies that the
    CLASSORIGIN attribute MUST be present on all appropriate
    elements in each returned Instance. If false, no
    CLASSORIGIN attributes are present in each returned
    Instance.

    @param filterQueryLanguage If the filterQueryLanguage* 
    paramter is provided it defines an query language to be used 
    with the filterQuery. This is an optional parameter and using it may cause
    the operation to be rejected by some CIM servers.

    @param filterQuery String defining a filter query to be applied to 
    the enumeration. This is an optional parameter and using it may cause
    the operation to be rejected by some CIM Servers.  

    @param propertyList If the propertyList input parameter is not
    NULL, the members of the array define one or more CIMProperty
    names.  Each returned Instance MUST NOT include elements
    for any Properties missing from this list.  Note that if
    LocalOnly is specified as true (or
    DeepInheritance is specified as false) this acts as an
    additional filter on the set of Properties returned (for example,
    if CIMProperty A is included in the
    PropertyList but LocalOnly is set to true and
    A is not local to a returned Instance, then it will not be
    included in that Instance). If the PropertyList input parameter
    is an empty array this signifies that no Properties are included in each
    returned Instance. If the PropertyList input parameter is
    NULL this specifies that all Properties (subject to the conditions
    expressed by the other parameters) are included in each returned
    Instance.

    If the propertyList contains duplicate elements,
    the Server MUST ignore the duplicates but otherwise process the request
    normally.  If the PropertyList contains elements which are
    invalid CIMProperty names for any target Instance, the Server MUST
    ignore such entries but otherwise process the request normally.

    @param operationTimeout Int32Arg that defines the interoperation
    timeout in seconds between operations of a pull enumeration sequence.
    The server shall maintain a returned enumeration context for at least the
    time specified by this parameter.  If the parameter is set to NULL
    the server defines the operationTimeout time.  If the user sets the
    to a time greater than that allowed by the server, the server may
    its maximum timeout time in place of the supplied parameter.  If the user
    sets the timeout time to zero the server may ignore timeout time completely.
 

    @param continueOnError - Boolean parameter that defines whether the server
    should continue to return instances subsequent to a CIMException error
    occurring in the server.  If this parameter is "true" the server may
    continue processing responses subsequent to an error.  If it is "false"
    the server must terminate the response upon the first error.  This
    parameter is optional and not all servers accept it.  A server may
    generate an exception response if this parameter is set "true'.

    @param maxObjectCount - Defines the maximum number of elements that this 
    Open operation can return. Any Uint32 value is legal including 0.
    The server may deliver up to maxObjectCount objects.  The server may
    deliver fewer elements including possibly zero elements. In any case, the
    server will reset the operationTimeout so that maxObjectCount of zero can
    be used to keep a pull sequence open without receiving elements

    @return If successful, the method returns zero or more named
    Instances that meet the required criteria.

    If unsuccessful, one of the following status codes MUST be returned
    by this method, where the first applicable error in the list (starting
    with the first element of the list, and working down) is the error
    returned. Any additional method-specific interpretation of the error in
    is given in parentheses.

        

          
[

¤197] CIM_ERR_ACCESS_DENIED
          
[

¤198] CIM_ERROR_SERVER_IS_SHUTTING_DOWN  
          
[

¤199] CIM_ERR_NOT_SUPPORTED
          
[

¤200] CIM_ERR_INVALID_NAMESPACE
          
[

¤201] CIM_ERR_INVALID_OPERATION_TIMEOUT
          
[

¤202] CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED
          
[

¤203] CIM_ERR_INVALID_PARAMETER (including missing,
                duplicate, unrecognized or otherwise incorrect parameters)
          
[

¤204] CIM_ERR_INVALID_CLASS (the CIM Class that is the
                basis for this enumeration does not exist)
          
[

¤205] CIM_ERR_FILTERED_ENUMERATION_NOT_SUPPORTED
          
[

¤206] CIM_ERR_QUERY_LANGUAGE_NOT_SUPPPORTED
          
[

¤207]  CIM_ERR_INVALID_QUERY
          
[

¤208] CIM_ERR_FAILED (some other unspecified erroroccurred)
        
    */

    Array openEnumerateInstances(
        CIMEnumerationContext& enumerationContext,
        Boolean& endOfSequence,
        const CIMNamespaceName& nameSpace,
        const CIMName& className,
        const Boolean deepInheritance,
        const Boolean includeClassOrigin,
        const CIMPropertyList& propertyList = CIMPropertyList(),
        const String& filterQueryLanguage = String::EMPTY,
        const String& filterQuery = String::EMPTY,
        const Uint32Arg& operationTimeout  = Uint32Arg(),
        const Boolean continueOnError = false,
        const Uint32Arg& maxObjectCount = Uint32Arg(0)
        );

    /** 
       TBD add description
    */

    Array openEnumerateInstancePaths(
        CIMEnumerationContext& enumerationContext,
        Boolean& endOfSequence,
        const CIMNamespaceName& nameSpace,
        const CIMName& className,
        const String& filterQueryLanguage = String::EMPTY,
        const String& filterQuery = String::EMPTY,
        const Uint32Arg& operationTimeout = Uint32Arg(),
        const Boolean continueOnError = false,
        const Uint32Arg& maxObjectCount = Uint32Arg(0)
        );
    
    /** TBD description
    */
    
    Array openReferenceInstances(
        CIMEnumerationContext& enumerationContext,
        Boolean& endOfSequence,
        const CIMNamespaceName& nameSpace,
        const CIMObjectPath& objectName,
        const CIMName& resultClass = CIMName(),
        const String& role = String::EMPTY,
        const Boolean includeClassOrigin = false,
        const CIMPropertyList& propertyList = CIMPropertyList(),
        const String& filterQueryLanguage = String::EMPTY,
        const String& filterQuery = String::EMPTY,
        const Uint32Arg& operationTimeout = Uint32Arg(),
        const Boolean continueOnError = false,
        const Uint32Arg& maxObjectCount = Uint32Arg(0)
        );

    /** 
     * TBD Add Description
    */

    Array openReferenceInstancePaths(
        CIMEnumerationContext& enumerationContext,
        Boolean& endOfSequence,
        const CIMNamespaceName& nameSpace,
        const CIMObjectPath& objectName,
        const CIMName& resultClass = CIMName(),
        const String& role = String::EMPTY,
        const String& filterQueryLanguage = String::EMPTY,
        const String& filterQuery = String::EMPTY,
        const Uint32Arg& operationTimeout = Uint32Arg(),
        const Boolean continueOnError = false,
        const Uint32Arg& maxObjectCount = Uint32Arg(0)
        );
    
    /**
     * TBD Add Description
    */

    Array openAssociatorInstances(
        CIMEnumerationContext& enumerationContext,
        Boolean& endOfSequence,
        const CIMNamespaceName& nameSpace,
        const CIMObjectPath& objectName,
        const CIMName& assocClass = CIMName(),
        const CIMName& resultClass = CIMName(),
        const String& role = String::EMPTY,
        const String& resultRole = String::EMPTY,
        Boolean includeClassOrigin = false,
        const CIMPropertyList& propertyList = CIMPropertyList(),
        const String& filterQueryLanguage = String::EMPTY,
        const String& filterQuery = String::EMPTY,
        const Uint32Arg& operationTimeout = Uint32Arg(),
        const Boolean continueOnError = false,
        const Uint32Arg& maxObjectCount = Uint32Arg(0)
        );

    /** TBD Add Description
    */
    Array openAssociatorInstancePaths(
        CIMEnumerationContext& enumerationContext,
        Boolean& endOfSequence,
        const CIMNamespaceName& nameSpace,
        const CIMObjectPath& objectName,
        const CIMName& assocClass = CIMName(),
        const CIMName& resultClass = CIMName(),
        const String& role = String::EMPTY,
        const String& resultRole = String::EMPTY,
        const String& filterQueryLanguage = String::EMPTY,
        const String& filterQuery = String::EMPTY,
        const Uint32Arg& operationTimeout = Uint32Arg(),
        const Boolean continueOnError = false,
        const Uint32Arg& maxObjectCount = Uint32Arg(0)
        );

    /** The pullInstancesWithPath operation retrieves instance paths
       from an open enumeration that requests paths and represented by 
       a CIMEnumerationContext.
      
       @param enumerationContext must be a valid context returned by
       an open operation or a previous pull operation.
     
       @param endOfSequence is a Boolean parameter that is false
       until the server has returned the complete set of elements to
       be returned.
      
       @param maxObjectCount defines the maximum number of elements
       that may be returned by the server for this operation. See ***
       for a complete definition.

       If successful the operation returns zero or more CIMObjectPaths.

       If not successful the operation returns one of the following
       exceptions:
            

                
[
(k_schopmeyer) This wierd format is because I put the UL LI tags on the lines and surrounded 
the code with the 
 tag.  Looks like it decided to do something with the UL 
and LI tags.  Suggestions welcome for a better way to include code.

¤209] CIM_ERR_ACCESS_DENIED
                
[

¤210] CIM_ERR_SERVER_IS_SHUTTING_DOWN
                
[

¤211] CIM_ERR_NOT_SUPPORTED
                
[

¤212] CIM_ERR_INVALID_NAMESPACE
                
[

¤213] CIM_ERR_INVALID_NAMESPACE
                
[

¤214] CIM_ERR_INVALID_ENUMERATION_CONTEXT
                
[

¤215] CIM_ERR)PULL_HAS_BEN_ABANDONED
                
[

¤216] CIM_ERR_SERVER_LIMITS_EXCEEDED
                
[

¤217] CIM_ERR_FAILED
            

    */

    /** TBD Add Description
     */
    Array pullInstancesWithPath(
        CIMEnumerationContext& enumerationContext,
        Boolean& endOfSequence,
        const Uint32Arg& maxObjectCount = Uint32Arg(0)
        );
    /** TBD Add Description
     */
    Array pullInstancePaths(
        CIMEnumerationContext& enumerationContext,
        Boolean& endOfSequence,
        const Uint32Arg& maxObjectCount = Uint32Arg(0)
        );

    /** TBD add description */
    void closeEnumeration(
        CIMEnumerationContext& enumerationContext
        );

    /** TBD add description */
    Uint64Arg enumerationCount(
        CIMEnumerationContext& enumerationContext
        );

//KS_PULL_END

[ ¤218] 2.5.2 NumericArgs Interface Object

[ ¤219] We implemented a simple set of objects to allow the Uint32 and Uint64 objects to be passed through the CIMClient API and managed in the server while including the concept of NULL.  These classes allow the user to pass either a value or NULL through these interfaces and provide test, set, and clear functions. These are defined in common as follows:

[
(r_kumpf) Why not just use PEG_NOT_FOUND?
(k_schopmeyer) We need to implement something that will allow all possible values of Uint32 and  
Uint64 and still show CIMValue.  
  

 1. What we did which is multiple simple classes to add the NULL concept.  

2.  use CIMValue which means that we would have to dynamically test for the  
correct typing in the client.  

3. Set up extra parameters on the call to account for the NULLness.  This  
means that we also have to do something in the server since it needs to  
understand NULL also.  
  


Not sure what you mean by just use PEG_NOT_FOUND.  Lets discuss this one.  
 
RESULTS: After discussion we agreed to keep this set of new classes pending 
further understanding after the initial implementation is complete.

¤220] 
class PEGASUS_COMMON_LINKAGE Uint32Arg
{
public:

    Uint32Arg();
    Uint32Arg(const Uint32Arg& x);
    Uint32Arg(Uint32 x);
    ~Uint32Arg();
    Uint32Arg& operator=(const Uint32Arg& x);
    const Uint32& getValue() const;
    void setValue(Uint32 x);
    Boolean isNull() const;
    void setNullValue();

private:
    Uint32 _value;
    Boolean _null;
};

class PEGASUS_COMMON_LINKAGE Uint64Arg
{
public:

    Uint64Arg();
    Uint64Arg(const Uint64Arg& x);
    Uint64Arg(Uint64 x);
    ~Uint64Arg();
    Uint64Arg& operator=(const Uint64Arg& x);
    const Uint64& getValue() const;
    void setValue(Uint64 x);
    Boolean isNull() const;
    void setNullValue();

private:
    Uint64 _value;
    Boolean _null;
};



 

[ ¤221] 2.6 List of Modules that will change

• [ ¤224] CIMClient.h and CIMClient.cpp
• [ ¤225] CIMClientInterface.h
• [ ¤226] CIMClientRep.h and CimClientRep.cpp
• [ ¤227] CIMOperationResponseDecoder.h and CIMOperationResponseDecoder.cpp
• [ ¤228] CIMOperationRequestEncoder.h and CIMOperationRequestEncoder.cpp

[ ¤230]
[ ¤231]

• [ ¤232] Message.h
• [ ¤233] CIMMessage.h and CIMMessage.cpp to include the new operation and response types.
• [ ¤234] XmlWriter.h and XmlWriter.cpp -  Add new functions to represent new appends that are unique to these new operations. 
• [ ¤235] XmlReader.h and XmlReader.cpp - Add new decoding fucnction that are unique to these new operations
• [ ¤236] Extend the Exception definitions to include the new Client exception codes defined below.
• [ ¤237] Add new interface component NumericArgs that will allow Uint32 and Uint64 integers to be passed as parameters to CIM/XML operations

[ ¤238] Pegasus/Server
[ ¤239]
[ ¤240]

• [ ¤241] CIMOperationRequestDispatcdher.h and CIMOperationRequestDispatcher.cpp
• [ ¤242] CIMOperationRequestEncoder.h and CIMOperationRequestDecoder.cpp
• [ ¤243] CIMOperationResponseEncoder.h and CIMOperationResponseEncoder.cpp

[ ¤244]

[ ¤248]
[ ¤249]

[ ¤250] Test files

1. [ ¤251] Pegasus/Client/tests/PullEnumeration - Automated test of the new operations as a server test.
2. [ ¤252] Static tests - Some tests for error conditions that cannot be tested through the PullEnumeration test program.
3. [ ¤253] Common/NumericArgs (.h and .cpp) - Interfaces for the Uint32 and Uint64 parameters that must be passed through the API with NULL

[ ¤254] 2.7 New CIM_Error Exceptions

1. [ ¤257] CIM_ERR_INVALID_ENUMERATION_CONTEXT - Error response if the server cannot find the context defined in the operation.  Implemented by CIMOperationDispatcher if a Pull or Close is received for which there is no enumerationContext in the EnumerationContextTable.
2. [ ¤258] CIM_ERR_INVALID_OPERATION_TIMEOUT -  The operation timeout specified in the operation request is not supported by the server.  Typically this applies if the client  demands interoperation timeouts that are larger than the server is willing to support.  We propose that Pegasus establish a configuration parameter that would define the maximum allowable timeout but that if the request is larger than this limit, we would use our internal limit rather than the received parameter. However, there is one case where this may be returned.  I timeout parameter of zero is a request for unlimited time. Thre should be at least an option to disallow this and for the moment we return this errof if the request operationTimeout is set to zero.
3. [ ¤259] CIM_ERR_PULL_HAS_BEEN_ABANDONED -  This error would be generated by the server if an operation was terminated due to the receipt of a simultaneous close operation during the execution of the Pull/Open operation.   Pegasus will issue this error if a Close or is received while a Pull is active in the server. Pegasus server will not use this in the initial version of this funcitonality.
4. [ ¤260] CIM_ERR_FILTERED_ENUMERATION_NOT_SUPPORTED - The client defined a filter parameter with the request but the server does not support filters. ISSUE: Should we do this if either the filter and/or the filter language parameters are provided with the request. Pegasus will issue this error if either the filter or filter query language is non-null in an open request. CONCLUSION: We issue this error if either filter or querylanguage parameters exist.
5. [ ¤261] CIM_ERR_CONTINUATION_ON_ERROR_NOT_SUPPORTED -  Error response from the server if the client requests the continueOnError and the server does not support continueOnError.  In this version, we propose that Pegasus not support the continueOnError. Pegasus will provide this error in all cases where the continueOnError parameter is received with a "true" value.
6. [ ¤262] CIM_ERR_SERVER_LIMITS_EXCEEDED - The server has failed the operation because it has exceeded some server limits.  Note that this error is really much more general than just the Pull operations.
7. [ ¤263] CIM_ERR_SERVER_IS_SHUTTING_DOWN - The server is in the process of shutting down and cannot process the operation at this time. NOTE: We have not thought out when we would issue this error at this point. NOT USED BY THE PEGASUS SERVER.

[ ¤264] 2.8 New Build Options

[ ¤265] PEGASUS_PULL_OPERATION_MINIMUM_TIMEOUT

[ ¤266] Description: If set defines the minimum time in seconds that an enumeration context defining a sequence of open/pull operations will remain in existence subsequent to the completion by the server of the response to a open or pull operation.  The server may discard the enumeration context when this timout is exceeded so that any further pull/close operations using that enumeration context would generate a error from the server with the status

[ (r_kumpf) I suggest 20 seconds.
(k_schopmeyer) Agreed.
¤267] Default Value: 5 seconds

[ ¤268] Recommended Value (Development Build): 5

[ ¤269] Recommended Value (Release Build): 5

[ ¤270] Required: No

[ ¤271] Considerations: This variable is of interest only if the PEGASUS_ENABLE_PULL_OPERATIONS variable is set to TRUE.

[ ¤272] PEGASUS_ENABLE_PULL_OPERATIONS

[ ¤273] Description: If true the PULL operations (open..., pull..., close, enumerationCount) are enabled in the Pegasus server. This flag also removes the defined interfaces from the Pegasus client.

[ ¤274] Default Value: true

[ ¤275] Recommended Value (Development Build): true

[ ¤276] Recommended Value (Release Build): TBD

[ ¤277] Required: No

[ ¤278] Considerations: This variable is used to disable the use of these operations for environments where they are not to be used.  Note that since these operations are not yet in final specification status in the DMTF there may be users who elect not to allow them either in the Pegasus Server or client

[ ¤279]
[ (r_kumpf) Is there a requirement to make this configurable?
(k_schopmeyer) Very good question. Not sure but I can see why in servers there might be an interest in the admin setting sizing parameters like this IF they had sufficient information to actually make a decision. Right now, I am not sure what information they would use to make this decision. In fact I am not sure how the developers really makes a decision about this now, certainly we are guessing with the defaults.
I hesitate to make a configurable variable for which the admin can only guess.
In fact, it would be more logical in the long term to make this part of the dynamic memory management so that, for example, the more memory we use or the more outstanding operations, the smaller the max return size.
For the moment, I propose the fixed parameter just to have some parameterization that can be expanded later to dynamic or internally managed.
¤280] PEGASUS_PULL_OPERATION_MAXIMUM_OBJECT_COUNT

[ (r_kumpf) To clarify the previous comment, I think it would be better to eliminate the PEGASUS_PULL_OPERATION_MAXIMUM_OBJECT_COUNT build variable until we have a better idea about how to limit the response size.
(k_schopmeyer) AGREED. We will remove all but the enable parameter for now. We will keep the max internally but remove the external ability to set as part of the build until we understand better the impact of this new set of operations
¤281] Description: This numeric parameter defines the maximum number of objects (instances or object paths) that the Pegasus server will be allowed to return for a single open, or pull operations as part of a pull operation sequence.  If the client supplies a maxObjectCount larger than this defined number, the server will return only the number defined by this parameter.  If this parameter is defined as zero (0), the server will ignore this parameter.

[ ¤282] Default Value: 1000

[ ¤283] Recommended Value (Development Build): 1000

[ ¤284] Recommended Value (Release Build): 1000

[ ¤285] Required: No

[ ¤286] Considerations: This variable is of interest only if the PEGASUS_ENABLE_PULL_OPERATIONS variable is set to TRUE.

[ ¤287] 2.9 Issues with the DMTF Specification today

[ ¤288] The specification today is in preliminary form which means a) it may have errors which hopefully initial implementations will sort out b) this is the chance to get our vote in on any issues.  This section maintains a list of known issues with the spec or which we may want to introduce back into the spec before it goes final.

[ ¤289] Note that the goal for the specification is final this spring.

[ ¤290] 1. Error in IMETHODRESPONSE definition in DSP0201. The new operations require some way to return parameters and none was included in the definition

[ ¤291] Current:

[ ¤292] <!ELEMENT IMETHODRESPONSE (ERROR|IRETURNVALUE?))>
[ ¤293] <!ATTLIST IMETHODRESPONSE
[ ¤294]            %CIMName;>

[ ¤295] Corrected:  CR 455

[ ¤296] <!ELEMENT IMETHODRESPONSE (ERROR|IRETURNVALUE?,PARAMVALUE*))>
[ ¤297] <!ATTLIST IMETHODRESPONSE
[ ¤298]            %CIMName;>

[ ¤299] 2. The specification does not define the relationship between the Open and Pull operations so that a client could logically use either the PullInstancesWithPath or the PullInstancePaths with any open operation. This will be extended to provide a definition of the relationship and a means to generate an error if an incorrect request is made. ACTION: Add language to final specification to insure that the correct Pulls correspond to their opens.  Also we will check this within the server so that only the PullInstancesWithPath, for example, can follow an OpenEnumerateInstances, OpenAssociators, OpenReferences and only hte PullInstancePaths can be used with OpenEnumerateInstancePaths, etc.

[ ¤300] NOTE: We are finding some minor issues in the specification that are being corrected as we proceed.  Hopefully, this will be the second implementation of this extension and will be enough to allow the DMTF specifications (DSP200 and DSP200) to go final for the versions that incorporate the changes for the Pull operations.

[ ¤301] 3. The DMTF Specification does not define any relationship between the user identity and the operations of a sequence of pull operations.  Thus, it would be legal for one user to perform an open and another user to execute a pull.  This is being discussed within the DMTF but we do not intend to add tests for this pending clarification by the DMTF. PROPOSAL: We will test and not allow a change of user within an enumeration sequence.

[ ¤302] 4. What is the impact of a server NOT responding with the path component for operations like OpenEnumerateInstancesWithPath or with just the local path component?  This behavior is NOT defined in the specification.

[ ¤303] 5. Impact of losing some responses as, for example, if a client timeout occurs during one operation in the sequence.

[ ¤304] 6. Possibly clarify relationship between priority of delivering existing data and returning an error when an error is recieved with the continueOnError = false.

[ ¤305] 7. Clarify the possible forms of NULL for the return parameters.  Today, the DMTF specification requires that the parameter exist but it may be NULL.  Should we extend this to allow a missing return parameter (EndOfSequence, etc.) to have a specific meaning. Note that there are a number of open issues with the definition of the return parameters (EnumerationContext, endOfSequence, etc.) in the specification and there will be text added to the next version to clarify these issues and lack of clarity.
[ (k_schopmeyer) Post approval - New dmtf issue. The statistical data model does not allow for added operations so that today these show up as discarded statistical data. Not sure yet what the resolution of this issue will be.
¤306]

[ ¤307] 3. Rationale

[ ¤308] This will be a required part of future CIM Operation over HTTP specifications.   We feel that it is important for Pegasus to support  these operations to achieve the scalability that is becoming important  in production environments

[ ¤309] 4. Schedule

[ ¤310] The goal is that this work be included in Pegasus 2.8.0

[ ¤311] 5. Discussion

[ ¤312] Discussion vers 1.0

[ ¤313] Question:

• [ ¤315] [ (r_kumpf) What is the expected behavior if PullInstancesWithPath is called on an enumeration for which instance paths are not available?

[ ¤316] Response: This is a clear difference with the existing behavior in particular for the replacement for enumerate instances.  We are expecting the system to respond with the paths in all cases.  It would appear that the best solution is that if the providers do not respond with the path, the server must add it but at this point I have not implemented that because of the extra processing cost.   

[ ¤317] RESPONSE2: We have implemented the addition of the path component to all of the pull responses.

[ ¤318]

[ ¤319] FURTHER ACTION: I put this question back to the DMTF (i.e. can the path be null) but no response yet.  I know that the WBEMSolutions server builds the path in the server if the providers do not build it.

[ ¤320] Question:

• [ ¤322] [ (r_kumpf) Are error responses possible for these operations?

[ ¤323] Response

[ ¤324] Yes. Error responses are possible for all of these new operations.  Note also that these operations introduced some new error codes.  Note that we included more defintion of error responses in version 1.1 of the PEP

[ ¤325] Question:

[ ¤326] [ (r_kumpf) Can you please clarify the meaning of this parameter? Should 'maximum' have been 'minimum'? I would have expected that the server would ultimately own the decision about when to time out a context, not the client.
[ ¤327] ¤45] Operation Timeout value - This set the maximum time the server must wait between client pull operations before timing out the context for an existing operation sequence

[ ¤328] Response: Correct should have been mininum. This was corrected.

[ ¤329] Question:

• [ ¤330] [ ¤49] FilterQueryLanguage[Future]

[ ¤333]  

[ ¤334] Response:  At this point it is not specifically limited to a user.  This is a valid question and one that we should probably address.  However since we are using a guid for the context, we would expect it would be difficult for another user to grab a valid context.  We could consider extending this to force same user but this should probably be part of the spec, not just our limitation.

[ ¤335] RESPONSE2: While awaiting further conclusions from the DMTF we will implement this to limit to a single user.  Note that there is a similar issue with namespace.

[ ¤336]  

[ ¤337] Question:

[ ¤344]  

[ ¤345] Question:

[ ¤346] [ (r_kumpf) What is the expected behavior if a client times out while waiting for the response to a Pull operation? I wonder if it would make sense to consider a 'blocking' flag for the enumeration. If the 'blocking' flag is false, the server would return 0 instances if it didn't have any available immediately. (Think non-blocking socket operation.)
[ ¤347] ¤56] The enumeration context is to be considered opaque to the client since the form may vary from server to server.  The server may provide a different context definition with each response and the client MUST respond with the context from the most recent operation completed for the target sequence.

[ ¤348] Response: We have a real issue here in that we can assume that something will be lost if the client times out while any particular operation is in process.  This is one of those disconnect concepts. The client is timing out but the server does not really know about it.  I agree that we should look into Rogers suggestion here.

[ ¤349] RESPONS2: Further Clarification.  We do operate this way.  If the user has requested but there is nothing available, we will return the response with zero elements rather than waiting.  In the future, we probably need to consider a more complete algorithm because this one can also lead to many "smaller" responses when we have only a few objects but the client has requested a larger number.  However, in the current code we respond with what exists in the OperationAggregator when the Pull Operation is received.

[ ¤350] However, this still leaves an open issue if a client for some reason does time out.  The pull operation processing logic in the CIMOperationRequestDispatcher does not know that this happened so it would continue to deliver if another pull was received, not knowing that something was lost in the middle.  It would appear that the client must handle this by dropping the context itself.

[ ¤351]

[ ¤352] Question:

[ ¤353] [ (r_kumpf) Is there an expectation that an error will be given precedence over data if the CloseOnError flag is true?
[ ¤354] ¤100] Note that the specification does not place specific requirements on the order of transmitting an error vs.  data so that the server could elect to send either any already gathered objects and the error for the next request or substitute the error for the returned objects.

[ ¤355] Response: At this point the specification does not specifically cover this issue.  In general however, if the continueOnError is not set, we have generally agreed that the user considers the error primary and we are OK to close as soon as the error is processed through the dispatcher independent of any return objects that may exist in the dispatcher at the time.  We will shut down the enumeration as rapidly as possible and logical when a

[ ¤356] Question:

[ ¤357] (r_kumpf) This summary assumes the client specifically requests a chunked transfer encoding.
[ ¤358] ¤105]
[ ¤359] [ ¤106]

[ ¤360] RESPONSE: This text was extended.

[ ¤361] Question:

[ ¤362] [ (r_kumpf) Is an error condition communicated by throwing a CIMException?
[ ¤363] ¤237]     If unsuccessful, one of the following status codes MUST be returned

[ ¤364]  Response: Yes. same as existing error conditions.

[ ¤365] Question:

[ ¤366] [ (k_schopmeyer) Note that there is one additional interface (PullInstances) that corresponds to the returns from enumerate instances.
[ ¤367] ¤359]
[ ¤368] [ ¤360]     /* TBD add description*/

[ ¤369]

[ ¤370] Response: We are not implementing the Query function at this point so this Pull is not needed since it is tied to query.

[ ¤371]  

[ ¤372] Question:

[ ¤373] [ (k_schopmeyer) Since the specification is in preliminary status today we have a chance to be certain that the spec meets our needs before it goes final by being one of the early implementations.
[ ¤374] ¤398] This will be a required part of future CIM Operation over HTTP specifications.   We feel that it is important for Pegasus to support  these operations to achieve the scalability that is becoming important  in production environments

[ ¤375] Comments from version 1.1 and responses

[ ¤376] [ (r_kumpf) Is it correct to ignore the filter parameter? I would have thought an error such as CIM_ERR_NOT_SUPPORTED would be returned. (Tag 153 indicates this is handled as an error.)
[ ¤377] (k_schopmeyer) Change the text to read generate the defined exception if either the filter query language or the filter parameters are provided. Ignored was a poor statement from the first version of the PEP
[ ¤378] ¤101] Filters - These new operations add the concept of Filters on the operations with two parameters, FilterQueryLanguage and FilterQuery.  However, since the language is not clearly defined today, we propose that the initial

[ ¤379] RESPONSE: Modified so that we specify any use of these parameters as a server exception.

[ ¤380] [ (r_kumpf) Will these be experimental interfaces?
[ ¤381] (k_schopmeyer) Good question. I have not specified them as experimental but should probably be until we get to final spec.
[ ¤382] ¤128] Define the new operation requests in CIMClient.h and CIMClientInterface.h headers. (See section below for the interface definition)

[ ¤383] RESPONSE: Yes

[ ¤384] The Enumeration Context - The specification allows a completely opaque enumeration context that is created by the server for the open operation and returned to the client.  This context must be passed by the client for each pull operation and for the close operation.  Note that it is assumed that the server may modify the context for each pull operation so that the client must always returns the latest enumeration context received on the prior operation.  It is expected that we will use an enumeration context that is simply a guid that is unique so that the context can be found on the server when pull or close operations are received.  In addition, the server will be required to keep interoperation times on the enumeration context and to timeout and remove an enumeration context when the timer runs out.  In our c
[ ¤385] [ (r_kumpf) The previous sentence is incomplete. How is the interoperation timeout measured?
[ ¤386] ¤135]

[ ¤387] RESPONSE: Corrected

[ ¤388] [ (r_kumpf) Why is this an error? The server may elect to return fewer objects (see tag 47).
[ ¤389] (k_schopmeyer) We have a choice here to reject as invalid or simply respond with our max limit. the DMTF spec is unclear on any particular behavior.
[ ¤390] ¤155] Reject if the maxObjectCount is set higher than the server-defined limit.

[ ¤391] RESPONSE: Modified so that this is NOT an error

[ ¤392] [ ¤158] Pull Operations on existing enumeration contexts will use the Operation Aggregation object  to meter segments of objects from the providers to the correct output queue and with counts of the objects in each response corresponding to the Pull request.  In effect, the OperationAggregate is the central point where responses from the providers/repository and temporarily held and then metered out as responses to the operation originator in accordance with received pull operations.
[ ¤393] [ (r_kumpf) I guess the client has no way to specify a minimum object count? So the server could return one instance per pull operation if it wanted to, or it could always wait for maxObjectCount objects before responding?
[ ¤394] (k_schopmeyer) Correct, simply a max limit. Zero is a valid lower limit and allows the client to reset the interoperation timer without getting any new objects.
[ ¤395] ¤159]

[ ¤396] RESPONSE: No correction necessary. 

[ ¤397] [ (r_kumpf) Since the specification is preliminary (tag 440), I guess we will need a build variable to allow support for the new operations to be disabled?
[ ¤398] (k_schopmeyer) Agreed
[ ¤399] ¤181]

[ ¤400] RESPONSE: Agreed that these funcitons will be conditional operation.  This does not mean that we will disable all the code if the functions are disabled, just the operation of the functions.  Env Var added.

[ ¤401] [ ¤373]     /* TBD add description*/
[ ¤402] [ (r_kumpf) Are these interface declarations intended to be literal, or just representative? The method names should start with a lower case letter, for consistency. Also, the 'with' should have a capital W.
[ ¤403] (k_schopmeyer) Call them representative. the case was fixed and there will be one more fix over the weekend. Also adding the documentaiton.
[ ¤404] ¤374]     Array<CIMInstance> PullInstanceswithPath(

[ ¤405] RESPONSE: They were not updated when the capitalization issues were found.  Updated except that not all comments have been included.

[ ¤406] RESPONSE2: They have been updated to match CIMClient.h

[ ¤407] ¤388]     void CloseEnumeration(
[ ¤408] [ (r_kumpf) Is there a reason the CIMEnumerationContext is not const?
[ ¤409] (k_schopmeyer) Oversight since this one is IN only
[ ¤410] ¤389]         CIMEnumerationContext& enumerationContext(
[ ¤411] [ ¤390]         );

[ ¤412] RESPONSE: Modify this parameter.

[ ¤413]  

[ ¤419]  

[ ¤420] RESPONSE: we concluded that for the moment, at least, we are not using this exception since we are not yet allowing concurrent close operation. The documentation and code reflect this.

[ ¤421]  

[ ¤426]  

[ ¤427] RESPONSE: We will leave this one in the documentation noting that we do not use it. Note that the client must include this as a possible response but that the Pegasus server will not use it.

[ ¤428]
[ ¤429] Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
[ ¤430] EMC Corporation; Symantec Corporation; The Open Group.
[ ¤431]
[ ¤432] Permission is hereby granted, free of charge, to any person obtaining a copy
[ ¤433] of this software and associated documentation files (the "Software"), to
[ ¤434] deal in the Software without restriction, including without limitation the
[ ¤435] rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
[ ¤436] sell copies of the Software, and to permit persons to whom the Software is
[ ¤437] furnished to do so, subject to the following conditions:
[ ¤438]
[ ¤439] THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
[ ¤440] ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
[ ¤441] "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
[ ¤442] LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
[ ¤443] PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
[ ¤444] HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
[ ¤445] ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
[ ¤446] WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

[ ¤447]  

[ ¤448] Template last modified: March 26th 2006 by Martin Kirk
[ ¤449] Template version: 1.11