SOAP/AM Client Development > Accessing a Web Service > Calling a Web Service Method > 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 CDF2C utility can be used to convert CDF definitions to C language IPM structures that exceed this limit.

 

IPMs generated with CDF2C have the following request and response header structures:

 

typedef struct __soapam_rq_hdr

{

 short                               message_code;

 short                               request_timeout;

 unsigned long                       stream_length;

 short                               variable_reply;

 short                               reserved[11];

} soapam_rq_hdr_def;

 

typedef struct __soapam_rp_hdr

{

 short                               reply_code;

 short                               info_code;

 short                               info_detail;

 unsigned long                       stream_length;

 short                               reserved[11];

} soapam_rp_hdr_def;

 

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.

 

The SOAP/AM Client Sample Pack includes a sample C program, lmstest.c, which illustrates how to use the stream protocol with both Pathway and standalone instances of the SOAPAMCP process. The program communicates with a Web services that requires request and response IPMs which exceed 10K bytes. The Sample Pack can be found at the Download Center at the NuWave web site.