4.3 Writing to a Table

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


      9

      1
      0


      1


      2


      3


      4


      5


      6


      7


      8


      9

      2
      0


      1


      2


      3


      4


      5


      6


      7


      8


      9

      3
      0


      1

      0

      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.