2.2.2.1.4 Put Changes

The Put Changes sub-request has the following format.

Put Changes Request (4 bytes): A 32-bit Stream Object Header (section 2.2.1.5.2) that specifies a Put Changes request.

Storage Index Extended GUID (variable): An Extended GUID (section 2.2.1.7) that specifies the data element identifier of a Storage Index in the request’s Data Element Package (section 2.2.1.12). The Storage Index specifies the changes that will be applied by the protocol server.

Expected Storage Index Extended GUID (variable): An Extended GUID that specifies the data element identifier of a Storage Index, and the expected Storage Index in the Data Element Package of the request.

If the Extended GUID does not have the corresponding data element in the Data Element Package of the request, the protocol server MUST return a Cell Error failure value of 16 indicating the referenced data element not found failure, as specified in section 2.2.3.2.1. When the protocol server applies updates to the server’s Storage Index, it first checks the specified expected Storage Index.

If the expected Storage Index was specified and the key that is to be updated in the protocol server’s Storage Index exists in the expected Storage Index, the corresponding values in the protocol server’s Storage Index and the expected Storage Index MUST match; otherwise, the protocol server MUST return a Cell Error failure value of 12 indicating a coherency failure, as specified in section 2.2.3.2.1. If the values match, the protocol server MUST ensure that the Storage Index update is atomically updated such that no other update is overwritten.

If the expected Storage Index was not specified or the key that is to be updated in the protocol server’s Storage Index does not exist in the expected Storage Index, the Imply Null Expected if No Mapping flag MUST be evaluated. If this flag is zero, the protocol server MUST apply the change without checking the current value; otherwise, if the flag specifies one, the protocol server MUST only apply the change if no mapping exists (the key that is to be updated in the protocol server’s Storage Index doesn’t exist or it maps to nil). If the flag specifies one and a mapping exists, the protocol server MUST return a Cell Error failure value of 12 indicating a coherency failure, as specified in section 2.2.3.2.1.

A – Imply Null Expected if No Mapping (1 bit): A bit that specifies the behavior of checking the current Storage Index value prior to update, if no expected Storage Index entry is specified by the client.

The expected Storage Index is the basis for what the client believes is the current state of the Storage Index, if set to one; otherwise, the expected Storage Index is not specified.

B – Partial (1 bit): A bit that specifies that this is a partial Put Changes, and not the full changes. When the flag is set to true, the Storage Index Extended GUID (variable) MUST NOT be specified.

C – Partial Last (1 bit): A bit that specifies if this is the last Put Changes in a partial set of changes. When the flag is set to true, the Storage Index Extended GUID (variable) MUST be specified.

D – Favor Coherency Failure Over Not Found (1 bit): A bit that specifies to force a coherency check on the server, if a Referenced Data Element Not Found (section 2.2.3.2.1) failure occurred. This might result in a Coherency Failure returned instead of Referenced Data Element Not Found.

E – Abort Remaining Put Changes on Failure (1 bit): If set, a bit that specifies to abort remaining Put Changes on failure. Its value is ignored by the server.

F - Multi-Request_Put_Hint (1 bit): A bit that specifies to reduce the number of auto coalesces
during multi-request put scenarios. If only one request for a Put Changes, this bit is zero.

G – Return Complete Knowledge If Possibe (1 bit): A bit that specifies to return the complete Knowledge (section 2.2.1.13) from the server, provided that this request has exclusive access to the Knowledge. Exclusive Knowledge access is only granted on Coalesce, and therefore complete Knowledge will not be returned in non-coalescing sub-requests. This attribute MAY be set. If set, this attribute will be ignored by the server.

H – Last Writer Wins On Next Change (1 bit): A bit that specifies to allow the Put Changes to be subsequently overwritten on the next Put Changes, even if a client is not coherent with this change.

ContentVersionCoherencyCheck (variable): A Binary Item (section 2.2.1.3) which MUST be ignored.<18>

Author Logins (variable): A String Item Array (section 2.2.1.14) structure that defines author login information.<19>

Reserved (1 byte): MUST be ignored.

Additional Flags (variable): An optional Additional Flags structure (section 2.2.2.1.4.1) with various flags that specify the desired behavior for the Put Changes request. <20>

Lock Id (20 bytes, optional): An optional Lock Id structure (section 2.2.2.1.4.2) that specifies the lock ID of the file on the server.<21>

Client Knowledge (variable): An optional Knowledge (section 2.2.1.13) that represents the knowledge of the client. It does not affect the Put Changes but allows the server to the Resultant Knowledge (section 2.2.3.1.3) in the Put Changes response.

Diagnostic Request Option Input (5 bytes): An optional Diagnostic Request Option Input structure (section 2.2.2.1.4.3) that specifies the desired diagnostic behavior for the Put Changes request.<22>