sqloptions:clientInterface Header Element

This feature will be removed in a future version of Microsoft SQL Server. Avoid using this feature in new development work, and plan to modify applications that currently use this feature.

The sqloptions:clientInterface login option enables the client to specify the client interface for the login, for example:

<SOAP-ENV:Header
  xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sqloptions="https://schemas.microsoft.com/sqlserver/2004/SOAP/Options">
    <sqloptions:clientInterface
          SOAP-ENV:mustUnderstand="1"
          value="name of client interface to use for login" />

</SOAP-ENV:Header>

The sqloptions:clientInterface login option appears as a SOAP header. It is made up of one element, named sqloptions:clientInterface. The element has one mandatory attribute, value, a text value. This gives the client interface to set for the login. This appears in the client_interface_name column of the sys.dm_exec_sessions compatibility view.

Only one instance of the sqloptions:clientInterface option can appear in a request. The option cannot appear in a response. Multiple instances of the option will generate an error.

The server might limit the range of the recognized values of the sqloptions:clientInterface value. If a client submits a value outside the allowed range, the server will silently truncate the value in an undefined manner.

If SOAP sessions are being used, this option must appear in the same request as the sqloptions:sqlsession initiate attribute. If this option appears in any request with a sqloptions:sqlSession header that does not also contain an initiate attribute, an error is generated.

The following is a schema fragment for the sqloptions:clientInterface option:

<xs:element name="clientInterface" form="qualified">
    <xs:annotation>
        <xs:documentation>
            Set the client interface for the login.
        </xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:attribute use="required" name="value" type="xs:string" form="unqualified">
            <xs:annotation>
                <xs:documentation>
                    The client interface to set for the login.
                </xs:documentation>
            </xs:annotation>
        </xs:attribute>
    </xs:complexType>
</xs:element>

Examples

The following are examples of using the sqloptions:clientInterface header within SOAP request and response messages.

Request

<SOAP-ENV:Envelope xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:sql="https://schemas.microsoft.com/sqlserver/2004/SOAP"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:sqlparam="https://schemas.microsoft.com/sqlserver/2004/SOAP/types/SqlParameter"
                   xmlns:sqlsoaptypes="https://schemas.microsoft.com/sqlserver/2004/SOAP/types"
                   xmlns:sqloptions="https://schemas.microsoft.com/sqlserver/2004/SOAP/Options">
  <SOAP-ENV:Header>
    <sqloptions:clientInterface SOAP-ENV:mustUnderstand="1" value="ADO.NET SOAP 2.1" />
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <sql:sqlbatch>
      <sql:BatchCommands>
          SELECT client_interface_name FROM sys.dm_exec_sessions 
          WHERE session_id=@@spid AND client_interface_name='ADO.NET SOAP 2.1'
      </sql:BatchCommands>
    </sql:sqlbatch>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Response

<SOAP-ENV:Envelope xml:space="preserve" 
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope/" 
                   xmlns:sql="https://schemas.microsoft.com/sqlserver/2004/SOAP" 
                   xmlns:sqlsoaptypes="https://schemas.microsoft.com/sqlserver/2004/SOAP/types" 
                   xmlns:sqlrowcount="https://schemas.microsoft.com/sqlserver/2004/SOAP/types/SqlRowCount" 
                   xmlns:sqlmessage="https://schemas.microsoft.com/sqlserver/2004/SOAP/types/SqlMessage" 
                   xmlns:sqlresultstream="https://schemas.microsoft.com/sqlserver/2004/SOAP/types/SqlResultStream" 
                   xmlns:sqltransaction="https://schemas.microsoft.com/sqlserver/2004/SOAP/types/SqlTransaction" 
                   xmlns:sqltypes="https://schemas.microsoft.com/sqlserver/2004/sqltypes">
  <SOAP-ENV:Body>
    <sql:sqlbatchResponse>
      <sql:sqlbatchResult>
        <sqlresultstream:SqlRowSet xsi:type="sqlsoaptypes:SqlRowSet">
          <diffgr:diffgram xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
            <SqlRowSet1 xmlns="urn:schemas-microsoft-com:sql:SqlRowSet1">
              <row>
                <client_interface_name>ADO.NET SOAP 2.1</client_interface_name>
              </row>
            </SqlRowSet1>
          </diffgr:diffgram>
        </sqlresultstream:SqlRowSet>
        <sqlresultstream:SqlRowCount xsi:type="sqlrowcount:SqlRowCount">
          <sqlrowcount:Count>1</sqlrowcount:Count>
        </sqlresultstream:SqlRowCount>
      </sql:sqlbatchResult>
    </sql:sqlbatchResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

See Also

Reference