• Article

sqloptions:hostname 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:hostName login option enables the client to specify the host name 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:hostname 
          SOAP-ENV:mustUnderstand="1"
          value="hostName"/>
    
</SOAP-ENV:Header>

The sqloptions:hostName login option appears as a SOAP header. It is made up of one element, named sqloptions:hostName. The element has one mandatory attribute, value, a text value. This gives the host name to set for the login. This appears in the hostname column in the sys.sysprocesses compatibility view.

Only one instance of the sqloptions:hostName 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:hostName 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 headerthat does not also contain the initiate attribute, an error is generated.

The following is a schema fragment for the sqloptions:hostName:

<xs:element name="hostName" form="qualified">
    <xs:annotation>
        <xs:documentation>
            Set the host name 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 host name to set for the login.
                </xs:documentation>
            </xs:annotation>
        </xs:attribute>
    </xs:complexType>
</xs:element>

Examples

The following are examples of using the sqloptions:hostname 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:hostName SOAP-ENV:mustUnderstand="1" value="recep35" />
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <sql:sqlbatch>
      <sql:BatchCommands>
        SELECT hostname FROM sysprocesses 
        WHERE spid=@@spid AND hostName='recep35'
      </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>
                <hostname>recep35</hostname>
              </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

SOAP Extension Headers