Usando tipos de dados XML

O SQL Server 2005 introduziu um tipo de dados xml que permite armazenar documentos e fragmentos XML em um banco de dados do SQL Server. O tipo de dados xml é interno no SQL Server e tem algumas semelhanças com outros tipos internos, como int e varchar. Assim como em outros tipos internos, você pode usar o tipo de dados xml como um tipo de coluna ao criar uma tabela; como um tipo de variável, de parâmetro ou de retorno de função; ou em funções CAST e CONVERT.

Considerações sobre programação

O XML pode ser autodescritivo no sentido de que pode opcionalmente incluir um cabeçalho de XML que especifica a codificação do documento, por exemplo:

<?xml version="1.0" encoding="windows-1252"?><doc/>

O padrão XML descreve como um processador XML pode detectar a codificação usada para um documento examinando os primeiros bytes desse documento. Há riscos de a codificação especificada pelo aplicativo entrar em conflito com a especificada pelo documento. No caso de documentos passados como parâmetros associados, o XML é tratado como dados binários pelo SQL Server, por isso nenhuma conversão é feita e o analisador XML pode usar a codificação especificada no documento sem problemas. Entretanto, no caso de dados XML associados como WSTR, o aplicativo precisa garantir que o documento está codificado como Unicode. Assim, talvez seja necessário carregar o documento em um DOM, alterar a codificação para Unicode e serializar o documento. Senão, poderão ocorrer conversões de dados, gerando XML inválido ou corrompido.

Também há risco de conflitos quando o XML é especificado em literais. Por exemplo, as expressões a seguir são inválidas:

INSERT INTO xmltable(xmlcol) VALUES('<?xml version="1.0" encoding="UTF-16"?><doc/>')

INSERT INTO xmltable(xmlcol) VALUES(N'<?xml version="1.0" encoding="UTF-8"?><doc/>')

Provedor OLE DB do SQL Server Native Client

DBTYPE_XML é um novo tipo de dados específico ao XML no provedor do OLE DB do SQL Server Native Client. Além disso, é possível acessar dados XML pelos tipos de OLE DB existentes DBTYPE_BYTES, DBTYPE_WSTR, DBTYPE_BSTR, DBTYPE_XML, DBTYPE_STR, DBTYPE_VARIANT e DBTYPE_IUNKNOWN. Os dados armazenados em colunas de tipo XML podem ser recuperados de uma coluna em um conjunto de linhas do provedor do OLE DB do SQL Server Native Client nos formatos a seguir:

• Uma cadeia de caracteres de texto

• Um ISequentialStream

Observação
O provedor do OLE DB do SQL Server Native Client não inclui um leitor SAX, mas o ISequentialStream pode ser passado facilmente para objetos SAX e DOM em MSXML.

O ISequentialStream deveria ser usado para recuperação de documentos XML extensos. As mesmas técnicas usadas para outros tipos de valor extenso também se aplicam ao XML. Para obter mais informações, consulte Usando tipos de valor grande.

Os dados armazenados em colunas de tipo XML em um conjunto de linhas também podem ser recuperados, inseridos ou atualizados por um aplicativo por meio das interfaces comuns como IRow::GetColumns, IRowChange::SetColumns e ICommand::Execute. De maneira semelhante ao caso da recuperação, um aplicativo pode passar uma cadeia de caracteres de texto ou um ISequentialStream para o provedor do OLE DB do SQL Server Native Client.

Observação
Para enviar dados XML em formato de cadeia de caracteres pela interface ISequentialStream, você precisa obter o ISequentialStream especificando DBTYPE_IUNKNOWN e definir o respectivo argumento pObject como nulo na associação.

Quando os dados XML recuperados estão truncados porque o buffer de consumidor é muito pequeno, a extensão poderá ser retornada como 0xffffffff, o que significará que ela é desconhecida. Isso é condizente com sua implementação como tipo de dados transmitidos ao cliente sem enviar as informações de extensão antes dos dados reais. Em alguns casos, a extensão real pode ser retornada quando o provedor executou o buffer do valor inteiro, como IRowset::GetData e onde ocorre a conversão de dados.

Os dados XML enviados ao SQL Server são tratados como dados binários pelo servidor. Isso impede a ocorrência de qualquer conversão e permite que o analisador XML autodetecte a codificação de XML. Além disso, permite que uma variedade mais ampla de documentos XML (por exemplo, aqueles codificados em UTF-8) seja aceita como entrada no SQL Server.

Se o XML de entrada estiver associado como DBTYPE_WSTR, o aplicativo deverá garantir que já tem codificação Unicode para evitar qualquer possibilidade de corrompimento por conversões de dados indesejadas.

Coerções e associações de dados

A tabela a seguir descreve a associação e coerção que ocorrem ao usar os tipos de dados listados com o tipo de dados xml do SQL Server.

1Se um tipo de servidor diferente de DBTYPE_XML for especificado com ICommandWithParameters::SetParameterInfo e o tipo de acessador for DBTYPE_XML, ocorrerá um erro quando a instrução for executada (para DB_E_ERRORSOCCURRED, o status do parâmetro é DBSTATUS_E_BADACCESSOR); caso contrário, os dados serão enviados para o servidor, mas ele retornará um erro indicando que não há conversão implícita do XML para o tipo de dados do parâmetro.

2Foge ao escopo deste tópico.

3O formato é UTF-16, não há BOM (marca de ordem de byte), não há especificação de codificação, não há terminação nula.

4O formato é UTF-16, não há BOM, não há especificação de codificação, há terminação nula.

5O formato consiste em caracteres multibyte codificados em página de código de cliente com terminador nulo. A conversão a partir do Unicode fornecido pelo servidor pode causar corrompimento dos dados, por isso essa associação é altamente desestimulada.

6BY_REF pode ser usado.

7Os dados UTF-16 precisam ser iniciados com BOM. Senão, a codificação poderá não ser reconhecida corretamente pelo servidor.

8A validação pode acontecer no tempo do acessador de criação ou no tempo de busca. O erro é DB_E_ERRORSOCCURRED; status da associação definido como DBBINDSTATUS_UNSUPPORTEDCONVERSION.

9Os dados são convertidos em Unicode usando a página de código de cliente antes de serem enviados para o servidor. Se a codificação de documento não corresponder à página de código de cliente, poderá haver corrompimento dos dados, por isso a associação é altamente desestimulada.

10Um BOM sempre é adicionado aos dados enviados para o servidor. Se os dados já forem iniciados com um BOM, isso resultará em dois BOMs no início do buffer. O servidor usa o primeiro BOM para reconhecer a codificação como UTF-16 e então o descarta. O segundo BOM é interpretado como um caractere de espaço incondicional de largura zero.

11O formato é UTF-16, não há especificação de codificação, um BOM é adicionado aos dados recebidos do servidor. Se uma cadeia de caracteres vazia for retornada pelo servidor, um BOM ainda será retornado para o aplicativo. Se a extensão do buffer for um número ímpar de bytes, os dados serão truncados corretamente. Se o valor inteiro for retornado em partes, elas poderão ser concatenadas para reconstituir o valor correto.

12Se a extensão do buffer for menor do que dois caracteres – ou seja, não houver espaço suficiente para terminação nula – será informado um erro de estouro.

Observação
Nenhum dado é retornado para valores de XML NULL.

O padrão XML exige que o XML codificado em UTF-16 seja iniciado com um código de caractere UTF-16 com BOM 0xFEFF. Ao trabalhar com associações WSTR e BSTR, o SQL Server Native Client não exige ou adiciona um BOM porque a codificação é insinuada pela associação. Ao trabalhar com associações BYTES, XML ou IUNKNOWN, a intenção é proporcionar simplicidade ao lidar com outros processadores XML e sistemas de armazenamento. Nesse caso, um BOM deve estar presente com o XML codificado em UTF-16, e o aplicativo não precisa verificar a codificação real, porque a maioria dos processadores XML (incluindo o SQL Server) deduz a codificação inspecionando os primeiros bytes do valor. Os dados XML recebidos do SQL Server Native Client usando as associações BYTES, XML ou IUNKNOWN são sempre codificados em UTF-16 com um BOM e sem uma declaração de codificação inserida.

Conversões de dados fornecidas por serviços de núcleo de OLE DB (IDataConvert) não são aplicáveis a DBTYPE_XML.

A validação ocorre quando os dados são enviados para o servidor. As alterações de codificação e validação do lado do cliente devem ser manipuladas pelo aplicativo, e é altamente recomendável que você não processe os dados XML diretamente, mas sim use um leitor DOM ou SAX para processá-los.

DBTYPE_NULL e DBTYPE_EMPTY podem ser associados a parâmetros de entrada, mas não a parâmetros ou resultados de saída. Quando eles são associados para parâmetros de entrada, o status precisa ser definido como DBSTATUS_S_ISNULL ou DBSTATUS_S_DEFAULT.

DBTYPE_XML pode ser convertido em DBTYPE_EMPTY e DBTYPE_NULL, sendo que DBTYPE_EMPTY pode ser convertido em DBTYPE_XML, mas DBTYPE_NULL não pode ser convertido em DBTYPE_XML. Isso é condizente com DBTYPE_WSTR.

DBTYPE_IUNKNOWN é uma associação com suporte (conforme mostrado na tabela anterior), mas não há nenhuma conversão entre DBTYPE_XML e DBTYPE_IUNKNOWN. DBTYPE_IUNKNOWN não pode ser usado com DBTYPE_BYREF.

Adições e alterações do conjunto de linhas do OLE DB

O SQL Server Native Client adiciona novos valores ou alterações a muitos dos conjuntos de linhas de esquema principais do OLE DB.

Os conjuntos de linhas de esquema de COLUMNS e PROCEDURE_PARAMETERS

Entre as adições aos conjuntos de linhas de esquema de COLUMNS e PROCEDURE_PARAMETERS estão as colunas a seguir.

O conjunto de linhas de esquema de PROVIDER_TYPES

No conjunto de linhas de esquema de PROVIDER_TYPES, o valor de COLUMN_SIZE é 0 para o tipo de dados xml e o DATA_TYPE é DBTYPE_XML.

O conjunto de linhas de esquema de SS_XMLSCHEMA

Um novo conjunto de linhas de esquema de SS_XMLSCHEMA é introduzido para que os clientes recuperem as informações de esquema XML. O conjunto de linhas de SS_XMLSCHEMA contém as colunas a seguir.

O escopo de cada esquema XML é definido por nome de catálogo, de esquema e de coleção de esquema, além de URI (identificador de recurso uniforme) de espaço de nome de destino. Além disso, também é definido um novo GUID com o nome DBSCHEMA_XML_COLLECTIONS. O número de restrições e colunas restringidas para o conjunto de linhas de esquema de SS_XMLSCHEMA é definido da seguinte maneira.

Adições e alterações do conjunto de propriedades do OLE DB

O SQL Server Native Client adiciona novos valores ou alterações a muitos dos conjuntos de propriedades principais do OLE DB.

O conjunto de propriedades de DBPROPSET_SQLSERVERPARAMETER

Para oferecer suporte ao tipo de dados xml por meio do OLE DB, o SQL Server Native Client implementa o novo conjunto de propriedades de DBPROPSET_SQLSERVERPARAMETER, que contém os valores a seguir.

O conjunto de propriedades de DBPROPSET_SQLSERVERCOLUMN

Para oferecer suporte à criação de tabelas na interface ITableDefinition, o SQL Server Native Client adiciona três colunas novas ao conjunto de propriedades de DBPROPSET_SQLSERVERCOLUMN.

Assim como os valores de SSPROP_PARAM, todas essas propriedades são opcionais e o padrão é vazio. SSPROP_COL_XML_SCHEMACOLLECTION_CATALOGNAME e SSPROP_COL_XML_SCHEMACOLLECTION_SCHEMANAME só poderão ser especificados se SSPROP_COL_XML_SCHEMACOLLECTIONNAME for especificado. Na passagem do XML para o servidor, se esses valores forem incluídos, serão verificados quanto à existência (validade) com base no banco de dados atual, e os dados de instância serão verificados com base no esquema. Em todos os casos, para que sejam válidos eles ficam todos vazios ou todos preenchidos.

Adições e alterações de interface do OLE DB

O SQL Server Native Client adiciona novos valores ou alterações a muitas das interfaces do OLE DB de núcleo.

A interface ISSCommandWithParameters

Para oferecer suporte ao tipo de dados xml por meio do OLE DB, o SQL Server Native Client implementa várias alterações, incluindo a adição da interface ISSCommandWithParameters. Essa nova interface herda as propriedades principais da interface do OLE DB ICommandWithParameters. Além dos três métodos herdados de ICommandWithParameters; GetParameterInfo, MapParameterNames e SetParameterInfo, ISSCommandWithParameters oferece os métodos GetParameterProperties e SetParameterProperties usados para manipular tipos de dados específicos de servidor.

Observação
A interface ISSCommandWithParameters também utiliza a nova estrutura SSPARAMPROPS.

A interface IColumnsRowset

O SQL Server Native Client adiciona as seguintes colunas específicas do SQL Server ao conjunto de linhas retornado pelo método IColumnRowset::GetColumnsRowset. Estas colunas contêm o nome de três partes de uma coleção de esquemas XML. Para colunas não XML ou colunas de XML não digitadas, as três colunas assumem o valor padrão de NULL.

A interface IRowset

Uma instância de XML em uma coluna de XML é recuperada pelo método IRowset::GetData. Dependendo da associação especificada pelo cliente, uma instância de XML pode ser recuperada como DBTYPE_BSTR, DBTYPE_WSTR, DBTYPE_VARIANT, DBTYPE_XML, DBTYPE_STR, DBTYPE_BYTES ou como uma interface via DBTYPE_IUNKNOWN. Se o consumidor especificar DBTYPE_BSTR, DBTYPE_WSTR ou DBTYPE_VARIANT, o provedor converterá a instância de XML para o tipo solicitado pelo usuário e a colocará no local especificado na associação correspondente.

Se o consumidor especificar DBTYPE_IUNKNOWN e definir o argumento pObject como NULL ou definir o argumento pObject como IID_ISequentialStream, o provedor retornará uma interface ISequentialStream para o consumidor para que este possa transmitir os dados XML da coluna. ISequentialStream retornará os dados XML como um fluxo de caracteres Unicode.

Ao retornar um valor XML associado a DBTYPE_IUNKNOWN, o provedor informará um valor de tamanho de sizeof (IUnknown *). Observe que esse procedimento é condizente com a abordagem adotada quando uma coluna é associada como DBTYPE_IUnknown ou DBTYPE_IDISPATCH e por DBTYPE_IUNKNOWN/ISequentialStream quando não é possível determinar o tamanho exato da coluna.

A interface IRowsetChange

Há duas maneiras de um consumidor atualizar uma instância de XML em uma coluna. A primeira é pelo objeto de armazenamento ISequentialStream criado pelo provedor. O consumidor pode chamar o método ISequentialStream::Write para atualizar diretamente a instância de XML retornada pelo provedor.

A segunda abordagem é pelos métodos IRowsetChange::SetData ou IRowsetChange::InsertRow. Nessa abordagem, uma instância de XML no buffer do consumidor pode ser especificada em uma associação de tipo DBTYPE_BSTR, DBTYPE_WSTR, DBTYPE_VARIANT, DBTYPE_XML ou DBTYPE_IUNKNOWN.

No caso de DBTYPE_BSTR, DBTYPE_WSTR ou DBTYPE_VARIANT, o provedor armazena a instância de XML que reside no buffer do consumidor na coluna adequada.

No caso de DBTYPE_IUNKNOWN/ISequentialStream, se o consumidor não especificar um objeto de armazenamento, precisará criar um objeto ISequentialStream com antecedência, associar o documento XML ao objeto e passar esse objeto para o provedor pelo método IRowsetChange::SetData. O consumidor também pode criar um objeto de armazenamento, definir o argumento pObject como IID_ISequentialStream, criar um objeto ISequentialStream e passar o objeto ISequentialStream para o método IRowsetChange::SetData. Em ambos os casos, o provedor pode recuperar o objeto XML pelo objeto ISequentialStream e inseri-lo em uma coluna adequada.

A interface IRowsetUpdate

A interface IRowsetUpdate oferece funcionalidade para atualizações atrasadas. Os dados disponíveis aos conjuntos de linhas não estarão disponíveis para outras transações enquanto o consumidor não chamar o método IRowsetUpdate:Update.

A interface IRowsetFind

O método IRowsetFind::FindNextRow não funciona com o tipo de dados xml. Quando IRowsetFind::FindNextRow é chamado e o argumento hAccessor especifica uma coluna de DBTYPE_XML, é retornado DB_E_BADBINDINFO. Isso ocorre independentemente do tipo de coluna que está sendo pesquisada. Para qualquer outro tipo de associação, FindNextRow apresentará falha com DB_E_BADCOMPAREOP se a coluna a ser pesquisada for do tipo de dados xml.

Driver ODBC do SQL Server Native Client

No driver ODBC do SQL Server Native Client, inúmeras alterações foram feitas em várias funções para oferecer suporte ao tipo de dados xml.

SQLColAttribute

A função SQLColAttribute tem três novos identificadores de campo, incluindo SQL_CA_SS_XML_SCHEMACOLLECTION_CATALOG_NAME, SQL_CA_SS_XML_SCHEMACOLLECTION_SCHEMA_NAME e SQL_CA_SS _XML_SCHEMACOLLECTION_NAME.

O driver ODBC do SQL Server Native Client informa SQL_SS_LENGTH_UNLIMITED para as colunas de SQL_DESC_DISPLAY_SIZE e SQL_DESC_LENGTH.

SQLColumns

A função SQLColumns tem três novas colunas, incluindo SS_XML_SCHEMACOLLECTION_CATALOG_NAME, SS_XML_SCHEMACOLLECTION_SCHEMA_NAME e SS_XML_SCHEMACOLLECTION_NAME. A coluna TYPE_NAME existente é usada para indicar o nome do tipo de XM, e o DATA_TYPE para um parâmetro ou coluna de tipo de XML é SQL_SS_XML.

O driver ODBC do SQL Server Native Client informa SQL_SS_LENGTH_UNLIMITED para os valores de COLUMN_SIZE e CHAR_OCTET_LENGTH.

SQLDescribeCol

O driver ODBC do SQL Server Native Client informa SQL_SS_LENGTH_UNLIMITED quando não é possível determinar o tamanho da coluna na função SQLDescribeCol.

SQLGetTypeInfo

O driver ODBC do SQL Server Native Client informa SQL_SS_LENGTH_UNLIMITED como o COLUMN_SIZE máximo para o tipo de dados xml na função SQLGetTypeInfo.

SQLProcedureColumns

A função SQLProcedureColumns tem as mesmas adições de coluna da função SQLColumns.

O driver ODBC do SQL Server Native Client informa SQL_SS_LENGTH_UNLIMITED como o COLUMN_SIZE máximo para o tipo de dados xml.

Conversões com suporte

Ao converter de tipos de dados SQL para C, é possível converter SQL_C_WCHAR, SQL_C_BINARY e SQL_C_CHAR em SQL_SS_XML, com as estipulações a seguir:

• SQL_C_WCHAR: o formato é UTF-16, não há BOM, há terminação nula.

• SQL_C_BINARY: o formato é UTF-16, não há terminação nula. Um BOM é adicionado aos dados recebidos do servidor. Se uma cadeia de caracteres vazia for retornada pelo servidor, um BOM ainda será retornado para o aplicativo. Se a extensão do buffer for um número ímpar de bytes, os dados serão truncados corretamente. Se o valor inteiro for retornado em partes, elas poderão ser concatenadas para reconstituir o valor correto.

• SQL_C_CHAR: o formato consiste em caracteres multibyte codificados em página de código de cliente com terminação nula. A conversão a partir do UTF-16 fornecido pelo servidor pode causar corrompimento dos dados, por isso essa associação é altamente desestimulada.

Ao converter de tipos de dados C para SQL, é possível converter SQL_C_WCHAR, SQL_C_BINARY e SQL_C_CHAR em SQL_SS_XML, com as estipulações a seguir:

• SQL_C_WCHAR: um BOM sempre é adicionado aos dados enviados para o servidor. Se os dados já forem iniciados com um BOM, isso resultará em dois BOMs no início do buffer. O servidor usa o primeiro BOM para reconhecer a codificação como UTF-16 e então o descarta. O segundo BOM é interpretado como um caractere de espaço incondicional de largura zero.

• SQL_C_BINARY: nenhuma conversão é executada e os dados são passados para o servidor "no estado atual". Os dados UTF-16 precisam ser iniciados com um BOM; senão, a codificação poderá não ser reconhecida corretamente pelo servidor.

• SQL_C_CHAR: os dados são convertidos em UTF-16 no cliente e enviados para o servidor da mesma maneira que SQL_C_WCHAR (inclusive a adição de um BOM). Se o XML não for codificado na página de código de cliente, isso poderá causar corrompimento dos dados.

O padrão XML exige que o XML codificado em UTF-16 seja iniciado com um código de caractere UTF-16 com BOM 0xFEFF. Ao trabalhar com uma associação SQL_C_BINARY, o SQL Server Native Client não exige ou adiciona um BOM porque a codificação é insinuada pela associação. A intenção é proporcionar simplicidade ao lidar com outros processadores XML e sistemas de armazenamento. Nesse caso, um BOM deve estar presente com o XML codificado em UTF-16, e o aplicativo não precisa verificar a codificação real, porque a maioria dos processadores XML (incluindo o SQL Server) deduz a codificação inspecionando os primeiros bytes do valor. Os dados XML recebidos do SQL Server Native Client usando associações de SQL_C_BINARY sempre são codificados em UTF-16 com um BOM e sem uma declaração de codificação inserida.

Consulte também

Referência

ISSCommandWithParameters (OLE DB)

Outros recursos

Recursos do SQL Server Native Client