The main function of a request header handler is to build a SOAP <Header> element appropriate for the operation. You can do this by creating a SOAP header object and associating with it the required number of SOAP header entries. The handler has an OUTPUT parameter (hSOAPHeader) that you can use to pass the SOAP header that you have built to OpenEdge to insert into the outgoing SOAP message. Any changes you make in the handler to the SOAP header object or its constituent SOAP header-entryref objects are integrated into the SOAP message when the handler completes execution. Thus, if the SOAP header that you return in this procedure contains SOAP header entries, OpenEdge sends out the SOAP message containing a corresponding header element. If you do not set the SOAP header object OUTPUT parameter (hSOAPHeader), OpenEdge does not include a header in the outgoing SOAP message.

If you create a SOAP header in the handler, with potentially multiple SOAP header entries, you are responsible for cleaning up the memory that is used for it. As an aid for deleting this object, and its memory, you can set the lDeleteOnDone parameter for output. Setting this parameter to TRUE, directs OpenEdge to delete the SOAP header object after OpenEdge has copied the object's contents to the outgoing message. Otherwise, your application must manage the lifetime of this object and determine when the object gets destroyed.