• Article

sqloptions:clientPID 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:clientPID login option enables the client to specify the client process ID 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:clientPID
          SOAP-ENV:mustUnderstand="1"
          value="ID of client process "/>

</SOAP-ENV:Header>

The sqloptions:clientPID login option appears as a SOAP header. It is made up of one element, named sqloptions:clientPID. The element has one mandatory attribute, value. This is a long integer value (64-bit signed). The value attribute gives the client process ID to set for the login. This appears in the hostprocess column in the sys.sysprocesses compatibility view.

Only one instance of the sqloptions:clientPID option can appear in a request. This 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:clientPID 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 contain the initiate attribute, an error is generated.

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

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

Examples

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