WSDL-to-PL/I segmentation APIs exit routine (DFSPWSHK)

The IMS WSDL-to-PL/I segmentation API exit routine (DFSPWSHK) gets control during execution of DFSPWSIO APIs DFSXGETS, DFSXSETS, DFSQGETS, and DFSQSETS.

The DFSPWSIO APIs are used and referenced by the PL/I application templates that are generated by IBM® Developer for System z® for the WSDL-to-PL/I top-down development scenario in IMS Enterprise Suite SOAP Gateway. You can use the DFSPWSHK exit routine to inspect, modify, or replace the buffer that contains the current SOAP header, body, or fault data structure before it is sent (DFSXSETS, DFSQSETS) or received (DFSXGETS, DFSQGETS). The programming pattern that is employed by this exit routine is that of an event handler where specific events are received from DFSPWSIO APIs (see the dfs_in_event_type parameter).

Because the DFSPWSIO APIs are invoked in both IMS Connect (DFSXSETS, DFSXGETS) and IMS message processing dependent regions (DFSQGETS, DFSQSETS), the DFSPWSHK exit routine must reside in a load library that is in STEPLIB of both dependent region types.

About this routine

The following table shows the attributes of the IMS WSDL-to-PL/I segmentation API exit routine.

Table 1. IMS WSDL-to-PL/I segmentation API exit routine attributes
Attribute	Description
IMS environments	DB/DC, DBCTL, DCCTL.
Naming convention	The user exit routine must be named DFSPWSHK.
Binding	This exit routine must be linked as serially reusable (REUS=SERIAL).
IMS callable services	This exit routine is not eligible to use IMS callable services.
Sample routine location	IMS.SDFSSRC distribution library.

This exit routine must be written as a FETCHABLE, EXTERNAL PL/I procedure and must not be linked with a module that contains a MAIN procedure.

Parameters

The following table describes the parameters to this exit routine.

Table 2. DFSPWSHK exit routine parameter list
Name	Declaration	Description
dfs_in_version	char(36) byaddr inonly	A read-only-string-by-reference that contains the version of the DFSPWSIO segmentation APIs that invoked this event handler. The version is represented as a 36-character GUID.
dfs_in_event_type	fixed bin(31) byvalue inonly	A read-only-integer-by-value that indicates the current event type for which this event handler is being invoked. Use the dfs_in_struct* and dfs_out_struct* parameters to inspect, modify, or replace the data structure buffer that is associated with the current event. The following event types are supported: dfs_event_type=1 (DFSXSETS): This event type is reported immediately before a data structure buffer that was supplied on a call to the DFSXSETS API is segmented and copied into the IMS Connect output buffer as part of an IMS request message. dfs_event_type=2 (DFSQGETS): This event type is reported immediately after a data structure buffer has been recovered from one or more segments of an IMS request message but before the data structure buffer is returned to the caller of the DFSQETS API. dfs_event_type=3 (DFSQSETS): This event type is reported immediately before a data structure buffer that was supplied on a call to the DFSQSETS API is segmented and inserted into the IMS Message Queue as part of an IMS response message. dfs_event_type=4 (DFSXGETS): This event type is reported immediately after a data structure buffer has been recovered from segments of an IMS response message but before the data structure buffer is returned to the caller of the DFSXGETS API.
dfs_in_namespace	wchar(1024) varying byaddr	A read-only-string-by-reference that contains the target namespace of the service that is associated with the current event.
dfs_in_service_name	wchar(512) varying byaddr inonly	A read-only-string-by-reference that contains the name of the service that is associated with the current event.
dfs_in_port_name	wchar(512) varying byaddr inonly	A read-only-string-by-reference that contains the name of the port that is associated with the current event.
dfs_in_operation_name	wchar(512) varying byaddr inonly	A read-only-string-by-reference that contains the name of the operation that is associated with the current event.
dfs_in_struct_type	fixed bin(31) byvalue inonly	A read-only-integer-by-value that indicates the type of the input structure that is associated with the current event. The following structure types are supported: dfs_in_struct_type=1: ASOAP Header structure. dfs_in_struct_type=2: A SOAP Body structure. dfs_in_struct_type=3: A SOAP Fault structure.
dfs_in_struct_name	wchar(100) varying byaddr inonly	A read-only-string-by-reference that contains the name of the structure that is associated with the current event.
dfs_in_struct_ptr	pointer byvalue inonly	A read-only-pointer-by-value to a buffer which contains the structure that is associated with the current event.
dfs_in_struct_size	fixed bin(31) byvalue inonly	A read-only-integer-by-value that provides the length in bytes of the structure that resides in the buffer pointed to by the dfs_in_struct_ptr parameter.
dfs_in_struct_state	fixed bin(31) byvalue inonly	A read-only-integer-by-value that indicates the state of the input structure buffer (see parameters dfs_in_struct*) that is associated with the current event. States other than the default are the result of previous calls to this event handler. The following states are supported: dfs_in_struct_state=0 (default): The contents of the buffer have not been modified, nor has the buffer been replaced with a newly-allocated one. dfs_in_struct_state=1: The contents of the buffer have been modified, but the buffer has not been replaced with a newly-allocated one. dfs_in_struct_state=2: The contents of the buffer have not been modified, but the buffer has been replaced with a newly-allocated one. dfs_in_struct_state=3: The contents of the buffer have been modified, and the buffer has been replaced with a newly-allocated one.
dfs_out_struct_ptr	pointer byaddr	A pointer-by-reference in which to write the address of a buffer that contains the modified or unmodified structure that is associated with the current event. The address can be that of the original buffer that is pointed to by the dfs_in_struct_ptr parameter. Or it can be that of a newly-allocated replacement buffer. The lifetime of the replacement buffer is managed by DFSPWSIO. Default value := dfs_in_struct_ptr Restriction: If Language Environment® callable services are used to allocate a new buffer, then this module must be compiled with PL/I option CHECK(NOSTORAGE).
dfs_out_struct_state	fixed bin(31) byaddr	An integer-by-reference in which to specify the state of the structure buffer that is pointed to by the dfs_out_struct_ptr parameter. This state represents an update to the state that is provided in the dfs_in_struct_state parameter. The following states are supported: dfs_out_struct_state=0: The contents of the buffer have not been modified, nor has the buffer been replaced with a newly-allocated one. dfs_out_struct_state=1: The contents of the buffer have been modified, but the buffer has not been replaced with a newly-allocated one. dfs_out_struct_state=2: The contents of the buffer have not been modified, but the buffer has been replaced with a newly-allocated one. dfs_out_struct_state=3: The contents of the buffer have been modified, and the buffer has been replaced with a newly-allocated one. Default value := dfs_in_struct_state