Using the Stream Protocol

The request/response stream protocol may be used in those instances when the Web service you are accessing requires request and/or response IPMs that are larger then the IPM message size limit imposed by the Guardian file system. When streaming a request to the SOAPAMCP process, you indicate the length of the stream in the soapam_rq_hdr and then write the request to the process in sequential blocks of arbitrary size. The SOAPAMCP process can also stream the Web service response back to your application in the same fashion. Note that the DDL method of IPM generation cannot create IPM structures larger than 32,767 bytes, however, the DDL2 utility can create IPM definitions up to 2MB.

The standard SOAPam requests and response header structures are shown below:

DEF soapam-rq-hdr.
  02 message-code                        TYPE BINARY 16.
  02 request-timeout                     TYPE BINARY 16.
  02 stream-length                       TYPE BINARY 32 UNSIGNED.
  02 variable-reply                      TYPE BINARY 16.
  02 reserved                            TYPE BINARY 16
                                         OCCURS 11 TIMES.
END.

DEF soapam-rp-hdr.
  02 reply-code                          TYPE BINARY 16.
  02 info-code                           TYPE BINARY 16.
  02 info-detail                         TYPE BINARY 16.
  02 stream-length                       TYPE BINARY 32 UNSIGNED.
  02 reserved                            TYPE BINARY 16
                                         OCCURS 11 TIMES.
END.

By setting the request header stream-length variable to a non-zero value you indicate your desire to use the streaming protocol for the Web service request and response. Set this value to the actual size of your request and write the message to the SOAPAMCP process in sequential blocks of arbitrary size. SOAPAMCP will not begin processing the Web service request until the number of bytes indicated by stream-length is received. When the response is returned, the SOAPAMCP process will return the length of the response stream in the response header stream-length variable. Your application should issue a sufficient number of read operations to the SOAPAMCP process in order to read the entire response.

The variable-reply header field may be used to optimize the response from SOAPAMCP. Setting this field to a non-zero value causes SOAPAMCP to truncate the reply to the length of the actual response data. For example, a service reply IPM of 50K will require two response IPMs when using the stream protocol. However, if the service only returns 10K of data, processing the entire 50K response is inefficient.  By setting the variable_reply request header field to non-zero will cause SOAPAMCP to truncate the response to 10K and return one response IPM. The truncated reply size will be reflected in the reply stream-length header field.

Note that if you are using Pathsend to communicate with the SOAPAMCP process you must initiate a Pathsend dialog with the SOAPAMCP server class to ensure that your requests and responses are routed to and from the same SOAPAMCP process instance. Refer to the TS/MP Pathsend and Server Programming Manual for more information on Pathsend dialog programming.