• Article

sqloptions:applicationName 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:applicationName login option enables the client to specify the name of the application used 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">
  <SOAP-ENV:Header>
    <sqloptions:applicationName SOAP-ENV:mustUnderstand="1" value="application name" />
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
       
  </SOAP-ENV:Body>
</SOAP-ENV:Header>

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

Only one instance of the sqloptions:applicationName optional header can appear in a single SOAP request. This header cannot appear in a SOAP response. Multiple instances of the option will generate an error.

The server might limit the range of the recognized values of the sqloptions:applicationName 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 that is used to initiate a SOAP session. If this option appears in any request with a sqloptions:sqlSession header that does not also contain the initiate attribute, an error is generated.

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

<xs:element name="applicationName" form="qualified">
    <xs:annotation>
        <xs:documentation>
            Set the application 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 application 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:applicationName 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:applicationName SOAP-ENV:mustUnderstand="1" value="HeadTrax" />
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <sql:sqlbatch>
      <sql:BatchCommands>
         SELECT DISTINCT program_name FROM sysprocesses
         WHERE program_name='HeadTrax'
      </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>
                  <program_name>HeadTrax</program_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

SOAP Extension Headers