1 karl  1.1.2.1         Using the CIM/XML Pull Operations
  2               
  3               STATUS
  4               
  5               <<< This section is being maintained during the review and checkin process
  6               to keep track of problems, errors, notes, etc.  Must be deleted before
  7               checkin to head of tree. Please feel free to add notes, etc in this
  8               section as you review/test.>>>>>>
  9               

 10 karl  1.1.2.2 2 June 2013

 11 karl  1.1.2.1 
 12               Issues  - KS
 13               1. have not installed the binary move in CIMResponseData. Please run
 14               with OPP off.
 15               2. Some problem in the processing so we are getting server crashes.
 16               Right no I am guessing that this is in the binaryCodec and am going to
 17               expand the test tools to allow testing through the localhost.
 18               
 19               3. Still way to many TODO and KS comments and KS_TEMPS.  Removing bit by bit.
 20               
 21               4. Env variable connection for the config parameters not installed.
 22               
 23               5. Issue with the threaded timer.  For some reason during tests it
 24               eventually calls the timer thread with trash for the parm (which is
 25               pointer to the EnumerationTable object). Caught because we do a valid
 26               test at beginning of the function.
 27               

 28 karl  1.1.2.2 6. Still using the templates in CIMOperationRequestDispatcher to simplify
 29               the handle... processing.  
 30               
 31               7. I think I have a way around the double move of objects in the
 32               EnumerationContext so that the outputter will just take a defined number
 33               of objects directly from the gathering cache and save the second move.
 34               
 35               8. Not yet passing all tests but getting closer now.
 36               
 37               9. Created a tag before this commit TASK_PEP317_1JUNE_2013.
 38               
 39               10. Next Tag will be TASK_PEP317_2_JUNE_2013 in the task branch
 40               
 41               

 42 karl  1.1.2.1 ===========================================
 43               
 44               OVERVIEW:
 45               
 46               The operation extensions for pull operations defined in the DMTF specification
 47               DSP0200 V 1.4 were implemented in Pegasus effective Pegasus version 2.11
 48               including Client and Server.
 49               
 50               These operations extend the CIM/XML  individual operations to operation
 51               sequences where the server must maintain state between operations in a
 52               sequence and the client must execute multiple operations to get the full
 53               set of instances or instance paths.
 54               
 55               The following new CIM/XML operations as defined in DSP0200 are included;
 56               
 57                   -OpenEnumerateInstances
 58                   -openEnumerateInstancePaths
 59                   -OpenReferenceInstances
 60                   -OpenReferenceInstancePaths
 61                   -OpenAssociatiorInstances
 62                   -OpenAssociatorInstancePaths
 63 karl  1.1.2.1     -PullInstancesWithPath
 64                   -PullInstancePaths
 65                   -CloseEnumeration
 66                   -EnumerationCount

 67 karl  1.1.2.2      OpenExecQuery

 68 karl  1.1.2.1 
 69               The following  operations have not been implemented in this version of Pegasus:
 70               
 71                   -OpenQueryInstances
 72               
 73               The following limitations on the implementation exist;
 74               
 75               1. The filterQueryLanguage and filterQuery parameters are processed by
 76                  the Pegasus client but the server returns error if there is any data in

 77 karl  1.1.2.2    either parameter. This work does not include the development of the
 78                  query language.  Note that a separate effort to extend Pegasus to use
 79                  the DMTF FQL query language is in process.

 80 karl  1.1.2.1 
 81               2. The input parameter continueOnError is processed correctly by the client
 82                  but the Pegasus server only provides for false since the server does not
 83                  include logic to continue processing responses after an error is
 84                  encountered. 
 85                  This is consistent with the statement in the specification that use of 
 86                  this functionality is optional and the fact that the DMTF agrees that all 
 87                  of the issues of continuing after errors have not been clarified.  
 88               
 89               3. The operation enumerationCount is not processed by the server today since
 90                  a) really getting the count would be the same cost as the corresponding
 91                  enumeration, b) the server does not include a history or estimating
 92                  mechanism for this to date.

 93 karl  1.1.2.2    NOTE: After a through review as part of the development of the next version
 94                  of CMPI we have concluded that this operation is probably not worth the
 95                  effort.  Since it is optional, Pegasus will only return the unknown status
 96                  at this point

 97 karl  1.1.2.1 
 98               Since the concept of sequences of operations linked together (open, pull, close)
 99               is a major extension to the original CIM/XML operation concept of completely
100               independent operations several new pieces of functionality are implemented
101               to control interOperationTimeouts, counts of objects to be returned, etc.
102               
103               TBD - Review this
104               
105               CLIENT
106               
107               The new operations follow the same pattern as the APIs for existing operations
108               in that:
109               
110               1. All errors are handled as CIMException and Exception
111               
112               2. The means of inputting parameters are the same except that there are
113                  significantly more input parameters with the open operations and for the 
114                  first time operations return parameters as well as objects in the 
115                  response.  Specifically the open and pull operations return values for 
116                  enumerationContext which is the identity for a pull sequence and 
117                  endOfSequence which is the marker the server sends in open and pull 
118 karl  1.1.2.1    responses when it has no more objects to send.
119               
120               The significant differences include:
121               
122               1. Processing of parameters on responses (i.e. the endOfSequence and
123                  enumerationContext parameters are returned for open and pull operations).
124               
125               2. Numeric arguments (Uint32 and Uint64 include the option of NULL in some
126                  cases so they are packaged inside classes Uint32Arg and Uint64Arg in the
127                  client api.
128               
129               3. The association and reference operations ONLY process instances.  They do
130                  not include the capability to return classes like reference and associator
131                  do and therefore return CIMInstance rather than CIMObject.
132               
133               4. Paths are returned in all cases (i.e OpenEnumerateInstances and
134                  PullInstancesWithPath where they were not with EnumeratInstances.
135               
136               5. The client must maintain state between operations in a sequence (using
137                  the enumerationContext parameter).
138               
139 karl  1.1.2.1 TBD- Are there more differences.
140               
141               
142               SERVER
143               
144               The Pegasus server attempts to always deliver the requested number of objects
145               for any open or pull request (the specification allows for the server to
146               deliver less than the requested number of objects and specifically to return
147               zero objects on open).  We felt that it was worth any extra cost in processing
148               to provide the client with exactly what it had requested.
149               
150               The pegasus server always closes an enumeration sequence upon receipt of any
151               error from the providers, repository, etc. Therefore the server will reject

152 karl  1.1.2.2 any request that has continueOnError = true;
153               
154               Expansion to allow the continue on error may be added in a future version.
155               In any case, the whole purpose of the continue on error is really to allow
156               input from good providers to be mixed with providers that return errors so
157               that generally this would mean simply changing the logic in the return mechanism 
158               to not shutdown when an error is received from any given provider.
159               
160               Generally we do not believe that the providers need to do much more in the
161               future to support the continueOnError other than possibly allowing the provider
162               to continue processing after it has received an error.

163 karl  1.1.2.1 
164               PROVIDERS
165               
166               This implementation requires NO changes to the existing providers.  The
167               provider APIs operate just as they do with the original operations.
168               
169               Because the server processing is different however, there may be some
170               behavior differences primarily because the client now controls the speed of
171               delivery of objects.
172               
173               In previous versions of Pegasus, the server attempts to deliver objects as
174               rapidly as then can be put on the network.  In the case of HTTP chunked requests
175               they are delivered in chunks of about 100 objects. The primary delay for the
176               providers was the processing of each segment through the server.  The server
177               is blocked so that no other segment can proceed through the server until that
178               segment is processed and sent on the network.
179               In the case of non-chunkedresponses, they are completely gathered in the serve
180               and then delivered as one non-chunked response. There were no delays for the
181               providers, just lots of possible memory use in the server.
182               
183               The responses from providers (delivered through the deliver(...) interface are
184 karl  1.1.2.1 gathered into segments of about 100 objects and this group of objects is moved
185               through the server to be delivered to the client.
186               
187               However with the inclusion of the pull operations,   The segments of objects
188               from the providers are cached in the server response path until the 
189               maxObjectCount for that request (open or pull) and that number returned in a
190               non-chunked response. Thus, if the client is slow to issue pull requests,
191               the providers might be delayed at some point to reduce memory usage in the
192               server (the delay appears as slow response tothe deliver operation).
193               
194               In other words, the time to process large sets of responses from the provider
195               now depends on the speed of handling the client.
196               
197               It is important to remember in developing providers that the Pegasus server
198               can most efficiently process responses if they are passed from the provider
199               to the server individually or in small arrays of objects rather than the
200               provider gathering very large arrays of objects and sending them to the
201               server.
202               

203 karl  1.1.2.2 NEXT GENERATION PROVIDERS
204               KS_TODO
205               

206 karl  1.1.2.1 CONFIGURATION PARAMETERS
207               
208               The server includes several configuration parameters to set limits on the
209               processing of pull operations.  All of these configuration parameters are
210               compile time parameters rather than runtime.
211               
212               1. Maximum value of minimum interoperation time.  This parameter defines the
213               maximum time allowed between the return of an open or pull response and 
214               the receipt of the next pull or a close operation before the server may 
215               close the enumeration.  The specification allows the server to set a 
216               maximum interoperation time and refuse open requests that with requested 
217               operationTimeout greater than that time.  
218               CIM_ERR_INVALID_OPERATION_TIMEOUT
219               
220               This value is set with the Pegasus environment variable
221               PEGASUS_PULL....
222               
223               2. Maximum objects returned in a single open or pull operation.  The server
224               can set a maximum limit on the number of objects that can be returned in
225               a single open or pull oepration with the maxObjectCount parameter.
226               
227 karl  1.1.2.1 3. Whether the server allows 0 as an interoperation timeout value. The value
228               zero is s special value for the interoperationTimeout in that it tells the
229               server to not timeout any enumeration sequence.
230               
231               With this value for interoperationTimeout, the only way to close an 
232               enumeration sequence is to complete all of the pulls or issue the close.  
233               If for some reason the sequence is not completed, that enumeration context 
234               would remain open indefinitly.  Since in Pegasus any open enumeration 
235               context uses resources (the context object and any provider resposnes that 
236               have not yet been issued in a response) it would appear that most 
237               platforms would not want to allow the existence of enumeration contexts 
238               that cannot be closed by the server.  
239               
240               4, maximum consecutive pull requests with 0 maxObjectCount.  The use of the
241               pull operation with maxObjectCount set to zero could be used to keep an
242               enumeration context open indefinitly (this tells the server to restart the
243               interoperationTimeout but not send any objects in the response). Therefore the
244               specification allows for the server setting maximum limits on this behavior
245               and returning the error CIM_ERR_SERVER_LIMITS_EXCEEDED if this limit is
246               exceeded.
247               Note that this is maximum CONSECUTIVE pulls so that issuing a pull with
248 karl  1.1.2.1 a non-zero count resets this counter.
249               
250               KS-TBD - Is this really logical since we can still block by just issuing
251               lots of zero request and an occansional request for one object.
252               
253               Pegaus sets the value of this limit to 1000 and allows the implementer to
254               modify it with the PEGASUS_MAXIMUM_ZERO_OBJECTCOUNT environment variable.
255               
256               5. Default operationTimeout - 
257               
258               The default of this parameter is to refuse operat
259               
260               In the current release of Pegasus these are all compile time parameters.