4.3 Writing to a Table

Figure 8: Writing to a table
The preceding figure shows the sequence for a COMA client that attempts to update a description of the partition in the Partitions table on behalf of a client application that requests to make this change. The COMA client has already performed the initialization and read table steps, as shown in section 4.1 and section 4.2. It is after performing these steps that the client is now attempting a table write operation.
The client calls the ICatalogTableWrite::WriteTable (section 3.1.4.9.1) method by setting the parameters, as follows:
The client determines the query appropriate to do an update. In this case, pQueryCellArray is set to NULL with its size cbQueryCellArray set to zero.
The client sets pQueryComparision to NULL and sets its size cbQueryComparision to 0.
The client first determines the property that it wishes to modify. In this case this is the Description field of the Partitions table (section 3.1.1.3.7). The old values and the new values of the field are given in the following table.
Property
Old value
New value
PartitionIdentifier
{41e90f3e-56c1-4633-81c3-6e8bac8bdd70}
{41e90f3e-56c1-4633-81c3-6e8bac8bdd70}
Name
"Base Application Partition"
"Base Application Partition"
Description
""
"The base application partition"
Deleteable
"Y"
"Y"
Changeable
"N"
"N"
As the client is only changing the Description field, it sets up the fPropertyStatus (section 2.2.1.8) values for the ppTableDataFixedWriteBuffer, as follows.
Property
fPropertyStatus
Meaning
PartitionIdentifier
0x01
Not null
Name
0x01
Not null
Description
0x03
Not null and changed
Deleteable
0x01
Not null
Changeable
0x01
Not null
This is all the information the client needs to prepare the ppTableDataFixedWriteBuffer buffer, which it does in the following way.
0
1
2
3
4
5
6
7
8
91
0
1
2
3
4
5
6
7
8
92
0
1
2
3
4
5
6
7
8
93
0
10
0
0
0
0
0
0
1
0
0
0
0
0
0
0
1
0
0
0
0
0
0
1
1
0
0
0
0
0
0
0
1
0
0
0
0
0
0
0
1
Padding
0x41E90F3E
0x463356C1
0x8B6EC381
0x70DD8BAC
0x00000000
0x00000038
0x00000059
0x0000004E
The client now prepares the ppTableDataVariable buffer.
00
01
02
03
04
05
06
07
08
09
0a
0b
0c
0d
0e
0f
00
B
a
s
e
A
p
p
10
l
I
c
a
t
I
o
n
20
P
a
r
t
I
t
I
30
o
n
\0
\0
T
h
e
40
b
a
s
e
a
p
p
50
l
I
c
a
t
I
o
n
60
P
a
r
t
I
t
I
70
o
n
\0
\0
The client sets the reserved parameters pReserved1, pReserved2, and pReserved3 to NULL.
The client then makes the call.
HRESULT ICatalogTableWrite::WriteTable( [in] GUID* pCatalogIdentifier = { 6e38d3c4-c2a7-11d1-8dec-00c04fc2e0c7}, [in] GUID* pTableIdentifier = { e4ad9fd6-d435-4cf5-95ad-20ad9ac6b59f}, [in] DWORD tableFlags = 0x00000000, [in, size_is(cbQueryCellArray), unique] char* pQueryCellArray = NULL, [in] ULONG cbQueryCellArray = 0x00000000, [in, size_is(cbQueryComparison), unique] char* pQueryComparison = { Pointer to zero sized buffer}, [in] ULONG cbQueryComparison = 0x00000000, [in] DWORD eQueryFormat = 0x00000001, [in, size_is(cbTableDataFixedWrite)] char* pTableDataFixedWrite = { Buffer containing the fixed size data}, [in] ULONG cbTableDataFixedWrite = , [in, size_is(cbTableDataVariable)] char* pTableDataVariable = { Buffer containing the variable size data}, [in] ULONG cbTableDataVariable = , [in, size_is(cbReserved1)] char* pReserved1 = NULL, [in] ULONG cbReserved1 = 0x00000000, [in, size_is(cbReserved2)] char* pReserved2 = NULL, [in] ULONG cbReserved2 = 0x00000000, [in, size_is(cbReserved3)] char* pReserved3 = NULL, [in] ULONG cbReserved3 = 0x00000000, [out, size_is( , *pcbTableDetailedErrors)] char** ppTableDetailedErrors = {Pointer to receive the buffer for detailed errors}, [out] ULONG* pcbTableDetailedErrors = {Pointer to receive the size of ppTableDetailedErrors} );The server receives the call and performs the following verification steps:
It verifies that the arguments conform to the syntax specified in section 3.1.4.9.1.
It verifies that the pTableIdentifier matches a table that it supports. In this case, it matches the Partitions table.
It verifies that the tableFlags are supported for the Partitions table.
It verifies that the query passed in is supported for the Partitions table.
It verifies the query specified is indeed allowed for the Partitions table.
The server then unmarshals the pTableDataFixedWrite and pTableDataVariable buffers to get the updates. It appropriately updates its store. Since in this case everything succeeds, the server returns S_OK.
HRESULT = S_OK. ICatalogTableWrite::WriteTable( [in] GUID* pCatalogIdentifier = {unchanged}, [in] GUID* pTableIdentifier = {unchanged}, [in] DWORD tableFlags = {unchanged}, [in, size_is(cbQueryCellArray), unique] char* pQueryCellArray = {unchanged}, [in] ULONG cbQueryCellArray = {unchanged}, [in, size_is(cbQueryComparison), unique] char* pQueryComparison = {unchanged}, [in] ULONG cbQueryComparison = {unchanged}, [in] DWORD eQueryFormat = {unchanged}, [in, size_is(cbTableDataFixedWrite)] char* pTableDataFixedWrite = {unchanged}, [in] ULONG cbTableDataFixedWrite = {unchanged}, [in, size_is(cbTableDataVariable)] char* pTableDataVariable = {unchanged}, [in] ULONG cbTableDataVariable = {unchanged}, [in, size_is(cbReserved1)] char* pReserved1 = { unchanged}, [in] ULONG cbReserved1 = { unchanged}, [in, size_is(cbReserved2)] char* pReserved2 = { unchanged}, [in] ULONG cbReserved2 = {unchanged}, [in, size_is(cbReserved3)] char* pReserved3 = { unchanged}, [in] ULONG cbReserved3 = {unchanged}, [out, size_is( , *pcbTableDetailedErrors)] char** ppTableDetailedErrors = NULL, [out] ULONG* pcbTableDetailedErrors = 0x00000000 );The COMA client, on successful completion of the call, now calls ICatalogUtils::WaitForEndWrites (section 3.1.4.17.2).
The server receives the call and ensures that all pending writes on its store are completed. The server then returns S_OK.