Include file DFSPWSH
The include file DFSPWSH defines the PL/I structures used with the WSDL-to-PL/I segmentation APIs DFSQGETS, DFSQSETS, DFSXGETS, and DFSXSETS.
The include file DFSPWSH is located on the z/OS® server in the data set DFSSSAMP installed by IMS.
The following code shows the first part of DFSPWSH, before the definition of the segmentation APIs:
First part of the include file DFSPWSH
/********************************************************************
* IBM IMS Web service segmentation APIs
* IMS Connect and IMS MPP
* DFSPWSH
*
* This file must be included by all IMS service provider MPPs
* developed using the IBM Ratinal Developer for System z WSDL2PLI
* support for IMS Enterprise Suite SOAP Gateway.
*
* @since 1.0.0.0, 1F64F288-F037-469F-987B-60BF1FBE4B4B
* @version 2.0.0.0, 2FFA2F75-8D4F-4951-80D5-D2444181745C
********************************************************************/
%push;
%noprint;
%include CEEIBMCT;
%include CEEIBMAW;
%pop;
/********************************************************************
* Required, symmetric asynchronous message header segment for use
* with DFSPWSIO APIs: DFSQGETS, DFSQSETS, DFSXGETS, DFSXSETS.
* @version 2.0.0.0, 2FFA2F75-8D4F-4951-80D5-D2444181745C
********************************************************************/
dcl 01 @dfs_async_msg_header_ptr pointer;
dcl 01 @dfs_async_msg_header unaligned
based(@dfs_async_msg_header_ptr),
02 ll fixed bin (15) init(0),
02 zz fixed bin (15) init(0),
02 trancode char (08) init(''),
02 header_guid char (36) init
('2FFA2F75-8D4F-4951-80D5-D2444181745C'),
02 service_context,
03 target_namespace wchar (1024) varying init(''),
03 service_name wchar (0512) varying init(''),
03 port_name wchar (0512) varying init(''),
03 operation_name wchar (0512) varying init(''),
02 language_binding,
03 struct_max_segment_size fixed bin(31) init(32767),
03 soap_header_bit bit (1) aligned init('0'b),
03 soap_header,
04 header_struct_name wchar (100) varying init(''),
04 header_struct_segment_num fixed bin (31) init(0),
04 header_struct_segment_cnt fixed bin (31) init(0),
04 header_struct_size fixed bin (31) init(0),
04 header_struct_ptr pointer,
03 soap_body_bit bit (1) aligned init('0'b),
03 soap_body,
04 body_struct_name wchar (100) varying init(''),
04 body_struct_segment_num fixed bin (31) init(0),
04 body_struct_segment_cnt fixed bin (31) init(0),
04 body_struct_size fixed bin (31) init(0),
04 body_struct_ptr pointer,
03 soap_fault_bit bit (1) aligned init('0'b),
03 soap_fault,
04 fault_struct_name wchar (100) varying init(''),
04 fault_struct_segment_num fixed bin (31) init(0),
04 fault_struct_segment_cnt fixed bin (31) init(0),
04 fault_struct_size fixed bin (31) init(0),
04 fault_struct_ptr pointer;
dcl @dfs_async_msg_header_size fixed bin(31)
value(storage(@dfs_async_msg_header));
/********************************************************************
* IMS I/O Program Communication Block (IOPCB) declarations and
* constants.
********************************************************************/
dcl 01 @dfs_iopcb_mask_ptr pointer;
dcl 01 @dfs_iopcb_mask unaligned based(@dfs_iopcb_mask_ptr),
02 iopcb_lterm char(8),
02 resv char(2),
02 iopcb_status_code char(2),
02 iopcb_date decimal fixed(7,0),
02 iopcb_time decimal fixed(6,9),
02 iopcb_msg_seq_number fixed bin(31),
02 iopcb_mod_name char(8),
02 iopcb_user_id char(8);
/********************************************************************
* @param @dfs_STRUCT_TYPE constants for use with DFSPWSIO APIs:
* DFSQGETS, DFSQSETS.
********************************************************************/
dcl @dfs_soap_header_struct fixed bin(31) value(1);
dcl @dfs_soap_body_struct fixed bin(31) value(2);
dcl @dfs_soap_fault_struct fixed bin(31) value(3);
/********************************************************************
* Return code constants for use with DFSPWSIO APIs:
* DFSQGETS, DFSQSETS, DFSXGETS, DFSXSETS.
********************************************************************/
dcl @dfs_success fixed bin(31) value(000);
dcl @dfs_omitted_parameter fixed bin(31) value(100);
dcl @dfs_invalid_pointer fixed bin(31) value(101);
dcl @dfs_invalid_struct_type fixed bin(31) value(102);
dcl @dfs_struct_not_found fixed bin(31) value(103);
dcl @dfs_struct_name_mismatch fixed bin(31) value(104);
dcl @dfs_invalid_struct_order fixed bin(31) value(105);
dcl @dfs_invalid_struct_size fixed bin(31) value(106);
dcl @dfs_invalid_struct_name fixed bin(31) value(107);
dcl @dfs_struct_already_set fixed bin(31) value(108);
dcl @dfs_invalid_segment_size fixed bin(31) value(109);
dcl @dfs_icon_buf_exhausted fixed bin(31) value(997);
dcl @dfs_cee_call_failure fixed bin(31) value(998);
dcl @dfs_dli_call_failure fixed bin(31) value(999);
/********************************************************************
* IMS CEETDLI interface declarations and constants.
********************************************************************/
dcl @dfs_dli_get_unique char (4) value('GU ');
dcl @dfs_dli_get_next char (4) value('GN ');
dcl @dfs_dli_insert char (4) value('ISRT');
dcl @dfs_dli_message_exists char (2) value('CF');
dcl @dfs_dli_end_segments char (2) value('QD');
dcl @dfs_dli_end_messages char (2) value('QC');
dcl @dfs_dli_status_ok char (2) value(' ');
dcl @dfs_message_max_data fixed bin(31) value(2147123205);
dcl @dfs_segment_max_data fixed bin(31) value(32763);
/********************************************************************
* Language Environment declarations and constants.
********************************************************************/
dcl 1 @dfs_cee_feedback feedback;
/********************************************************************
* Note: The remainder of this file contains declarations for
* the APIs that enable the XML Converters
* running in IMS Connect and the MPP running in an MPR to
* exchange messages that conform to a protocol that provides
* service invocation context and unique language bindings for
* each part of a SOAP message: header, body, fault.
*******************************************************************/
dcl @dfs_icon_buf_ptr pointer init(null());
dcl @dfs_icon_buf_size fixed bin(31) init(0);
dcl @dfs_icon_buf_used fixed bin(31) init(0);
dcl @dfs_struct_name wchar(100) varying init('');
dcl @dfs_struct_ptr pointer init(null());
dcl @dfs_struct_size fixed bin(31) init(0);
dcl @dfs_cee_feedback_ptr pointer init(null());
dcl @dfs_commit_structs bit(1) init('0'b);
dcl @dfs_debug bit(1) init('0'b);
dcl @return_code fixed bin(31) init(0);
/********************************************************************
* DFSQGETS,
* Get a language structure that contains either a SOAP Header,
* SOAP Body, or SOAP Fault. Language structures are retrieved
* from the IMS Message Queue using the CEETDLI interface. All
* language structures must retrieved from the IMS Message Queue
* prior to setting language structures using API DFSQSETS.
*
* @param @dfs_async_msg_header_ptr,
* A pointer-by-value to the instance of @dfs_async_msg_header
* that was retrieved from the IMS Message Queue by issuing
* a GU using the CEETDLI interface prior to invoking the API.
* This same instance must be passed on subsequent calls to
* DFSQGETS and DFSQSETS.
*
* @param @dfs_iopcb_ptr,
* A pointer-by-value to the I/O PCB that was passed to the
* MPP by IMS. The I/O PCB will be used by the API when invoking
* CEETDLI to interact with the IMS Message Queue. If a return
* code of 999 is received from the API, inspect the I/O PCB
* to determine the cause of the error.
*
* @param @dfs_struct_type,
* An integer-by-value that specifies which language structure
* to retrieve from the MPP's input message. The following
* constants defined in include file DFSPWSH may be used:
* @dfs_soap_header_struct, @dfs_soap_body_struct,
* @dfs_soap_fault_struct.
*
* @param @dfs_struct_name,
* A string-by-reference which contains the name of the
* language structure that the API should retrieve from the
* IMS Message Queue. This value of this parameter must
* correspond to the value of parameter @dfs_struct_type.
*
* @param @dfs_struct_ptr,
* A pointer-by-reference into which the API will write the
* address of newly-allocated storage into which the requested
* language structure has been copied from the IMS Message
* Queue. The storage allocated by the API resides in the
* same address space as the caller. Therefore, it is highly
* recommended that the storage be explicilty freed by the
* caller when no longer needed.
*
* @param @dfs_struct_size,
* An integer-by-reference into which the API will write the
* size in bytes of the language structure.
*
* @param @dfs_cee_feedback_ptr,
* A pointer-by-value to an instance of @dfs_cee_feedback
* which defines a Language Environment Condition Token.
* The supplied instance is updated each time the API invokes
* Language Environment Callable Services. If a return code of
* 998 is received from the API, use the publication Language
* Environment Run-Time Messages (SA22-7566-10) to inspect
* the contents of the condition token and determine the
* cause of the error.
*
* @param @dfs_debug,
* An optional bit that indicates whether or not
* trace information should be displayed by the API.
* Under normal circumstances trace information is written
* to standard out and therefore can be found in the
* job log of the Message Processing Region.
*
* @return One of the following codes will be returned by the API,
* o @dfs_success
* o @dfs_omitted_parameter
* o @dfs_invalid_pointer
* o @dfs_invalid_dfs_struct_type
* o @dfs_struct_not_found
* o @dfs_struct_name_mismatch
* o @dfs_invalid_struct_order
* o @dfs_cee_call_failure
* o @dfs_dli_call_failure
********************************************************************/
dcl DFSQGETS entry(pointer byvalue, pointer byvalue,
fixed bin(31) byvalue, wchar(100) varying byaddr,
pointer byaddr, fixed bin(31) byaddr, pointer byvalue,
bit(1) optional) returns(fixed bin(31));
/********************************************************************
* DFSQSETS,
* Set a language structure that contains either the SOAP
* Header, SOAP Body, or SOAP Fault. This API does not
* insert language structures into the IMS Message Queue
* until instructed to do so via parameter @dfs_commit_structs.
* Therefore it is an error to deallocate or otherwise
* invalidate structure pointers passed to the API via parameter
* @dfs_struct_ptr before instructing the API to commit (insert)
* all structures to the IMS Message Queue.
*
* @param @dfs_async_msg_header_ptr,
* A pointer-by-value to the instance of @dfs_async_msg_header
* that was supplied on a previous call to DFSQGETS or DFSQSETS.
* Subsequent calls to this API must specify the same instance
* of @dfs_async_msg_header as it will be progressively updated.
*
* @param @dfs_iopcb_ptr,
* A pointer-by-value to the IOPCB that was passed to the
* MPP by IMS. The IOPCB will be used by the API when invoking
* CEETDLI to interact with the IMS Message Queue. If a return
* code of 999 is received from the API, inspect the I/O PCB
* to determine the cause of the error.
*
* @param @dfs_struct_type,
* An integer-by-value that specifies which language structure
* to set in the IMS Message Queue. The following
* constants defined in include file DFSPWSH may be used:
* @dfs_soap_header_struct, @dfs_soap_body_struct,
* @dfs_soap_fault_struct.
*
* @param @dfs_struct_name,
* A string-by-reference which contains the name of the
* language structure that corresponds to the supplied value of
* the @dfs_struct_type parameter.
*
* @param @dfs_struct_ptr,
* A pointer-by-value to the language structure that
* corresponds to the values specified for parameters
* @dfs_struct_type and @dfs_struct_name.
*
* @param @dfs_struct_size,
* An integer-by-value that specifies the size in bytes of the
* language structure supplied via parameter @dfs_struct_ptr.
*
* @param @dfs_commit_structs,
* A bit-by-value that indicates whether the API should
* insert the current and all previously supplied language
* structures into the IMS Message Queue.
*
* @param @dfs_cee_feedback_ptr,
* A pointer-by-value to an instance of @dfs_cee_feedback
* which defines a Language Environment Condition Token.
* The supplied instance is updated each time the API invokes
* Language Environment Callable Services. If a return code of
* 998 is received from the API, use the publication Language
* Environment Run-Time Messages (SA22-7566-10) to inspect
* the contents of the condition token and determine the
* cause of the error.
*
* @param @dfs_debug,
* An optional bit that indicates whether or not
* trace information should be displayed by the API.
* Under normal circumstances trace information is written
* to standard out and therefore can be found in the
* job log of the Message Processing Region.
*
* @return One of the following codes will be returned by the API,
* o @dfs_success
* o @dfs_omitted_parameter
* o @dfs_invalid_pointer
* o @dfs_invalid_dfs_struct_type
* o @dfs_invalid_struct_order
* o @dfs_invalid_struct_size
* o @dfs_invalid_struct_name
* o @dfs_struct_already_set
* o @dfs_invalid_segment_size
* o @dfs_cee_call_failure
* o @dfs_dli_call_failure
********************************************************************/
dcl DFSQSETS entry(pointer byvalue, pointer byvalue,
fixed bin(31) byvalue, wchar(100) varying byaddr,
pointer byvalue, fixed bin(31) byvalue, bit(1) byvalue,
pointer byvalue, bit(1) optional) returns(fixed bin(31));
/********************************************************************
* DFSXGETS,
* Get a language structure that contains either the SOAP
* Header, SOAP Body, or SOAP Fault. Since the IMS Message
* Queue is not available to XML Conversion in IMS Connect,
* language structures are retrieved from the IMS Connect input
* buffer. The expected format of the IMS Connect input buffer
* is an [LLZZDATA]+ byte stream. This API is for use by PL/I
* XML Converters running in IMS Connect. It is not to be used
* by an MPP.
*
* @param @dfs_async_msg_header_ptr,
* A pointer-by-value to the instance of @dfs_async_msg_header
* that was retrieved from the first segment of the IMS Connect
* input buffer prior to invoking the API.
*
* @param @dfs_icon_buf_ptr,
* A pointer-by-value to the IMS Connect input message buffer.
* The expected format of the buffer is an array of LLZZDATA.
*
* @param @dfs_icon_buf_size,
* An integer-by-value that specifies the length in bytes of
* the buffer supplied in parameter @dfs_icon_buf_ptr.
*
* @param @dfs_struct_type,
* An integer-by-value that specifies which language structure
* to retrieve from the MPP's input message. The following
* constants defined in include file DFSPWSH may be used:
* @dfs_soap_header_struct, @dfs_soap_body_struct,
* @dfs_soap_fault_struct.
*
* @param @dfs_struct_name,
* A string-by-reference which contains the name of the
* language structure that the API should retrieve from the
* IMS Connect input buffer. This value of this parameter
* must correspond to the value of parameter @dfs_struct_type.
*
* @param @dfs_struct_ptr,
* A pointer-by-reference into which the API will write the
* address of a buffer that contains the bytes of the structure
* that corresponds to the values specified for parameters
* @dfs_struct_type and @dfs_struct_name. This buffer must be
* freed by the XML Converter prior to returning to IMS Connect
* because the Language Environment enclave in which the XML
* Converters execute is persistent.
*
* @param @dfs_struct_size,
* An integer-by-reference into which the API will write the
* size in bytes of the structure that corresponds to the
* specified values of parameters @dfs_struct_type
* and @dfs_struct_name.
*
* @param @dfs_cee_feedback_ptr,
* A pointer-by-value to an instance of @dfs_cee_feedback
* which defines a Language Environment Condition Token.
* The supplied instance is updated each time the API invokes
* Language Environment Callable Services. If a return code of
* 998 is received from the API, use the publication Language
* Environment Run-Time Messages (SA22-7566-10) to inspect
* the contents of the condition token and determine the
* cause of the error.
*
* @param @dfs_debug,
* An optional bit that indicates whether or not
* trace information should be displayed by the API.
* Under normal circumstances trace information is written
* to standard out and therefore can be found in the
* IMS Connect job log.
*
* @return One of the following codes will be returned by the API,
* o @dfs_success
* o @dfs_omitted_parameter
* o @dfs_invalid_pointer
* o @dfs_invalid_dfs_struct_type
* o @dfs_struct_not_found
* o @dfs_struct_name_mismatch
* o @dfs_invalid_struct_order
* o @dfs_icon_buf_exhausted
* o @dfs_cee_call_failure
********************************************************************/
dcl DFSXGETS entry(pointer byvalue, pointer byvalue,
fixed bin(31) byvalue, fixed bin(31) byvalue,
wchar(100) varying byaddr, pointer byaddr, fixed bin(31) byaddr,
pointer byvalue, bit(1) optional) returns(fixed bin(31));
/********************************************************************
* DFSXSETS,
* Set a language structure that contains either the SOAP
* Header, SOAP Body, or SOAP Fault. This API does not
* copy language structures into the IMS Connect output buffer
* until instructed to do so via parameter @dfs_commit_structs.
* Therefore it is an error to deallocate or otherwise
* invalidate structure pointers passed to the API via parameter
* @dfs_struct_ptr before instructing the API to commit (copy)
* all structures to the IMS Connect output buffer.
* This API is for use by PL/I XML Converters running in IMS
* Connect. It is not to be used by an MPP.
*
* @param @dfs_async_msg_header_ptr,
* A pointer-by-value to the instance of @dfs_async_msg_header
* that will be sent as the first segment of the IMS message.
*
* @param @dfs_icon_buf_ptr,
* A pointer-by-value to the IMS Connect output message buffer.
* The expected format of the buffer is an array of LLZZDATA.
*
* @param @dfs_icon_buf_size,
* An integer-by-value that specifies the length in bytes of
* the buffer supplied in parameter @dfs_icon_buf_ptr.
*
* @param @dfs_icon_buf_used,
* An integer-by-reference into which the API will write
* the number of bytes that were required to format the
* language structure as a multi-segment IMS message
* in the IMS Connect output buffer. The value of this
* parameter will always be greater than the actual size
* of the language structure by at least 4 bytes.
*
* @param @dfs_struct_type,
* An integer-by-value that specifies which language structure
* to set in the IMS Connect output buffer. The following
* constants defined in include file DFSPWSH may be used:
* @dfs_soap_header_struct, @dfs_soap_body_struct,
* @dfs_soap_fault_struct.
*
* @param @dfs_struct_name,
* A string-by-reference which contains the name of the
* language structure that corresponds to the supplied value of
* the @dfs_struct_type parameter.
*
* @param @dfs_struct_ptr,
* A pointer-by-value to the language structure that
* corresponds to the values specified for parameters
* @dfs_struct_type and @dfs_struct_name.
*
* @param @dfs_struct_size,
* An integer-by-value that specifies the size in bytes of the
* language structure.
*
* @param @dfs_commit_structs,
* A bit-by-value that indicates whether the API should
* copy the current and all previously supplied language
* structures into the IMS Connect output buffer.
*
* @param @dfs_cee_feedback_ptr,
* A pointer-by-value to a Language Environment Condition Token
* (@dfs_cee_feedback) that is updated by the API after each
* invocation of a Language Environment Callable Service. When
* a RETURN_CODE of 998 is received from the API, use the
* publication Language Environment Run-Time Messages
* (SA22-7566-10) to inspect the contents of the condition
* token and determine the cause of the error.
*
* @param @dfs_debug,
* An optional bit that indicates whether or not
* trace information should be displayed by the API.
* Under normal circumstances trace information is written
* to standard out and therefore can be found in the
* IMS Connect job log.
*
* @return One of the following codes will be returned by the API,
* o @dfs_success
* o @dfs_omitted_parameter
* o @dfs_invalid_pointer
* o @dfs_invalid_dfs_struct_type
* o @dfs_invalid_struct_order
* o @dfs_invalid_struct_size
* o @dfs_invalid_struct_name
* o @dfs_struct_already_set
* o @dfs_invalid_segment_size
* o @dfs_icon_buf_exhausted
* o @dfs_cee_call_failure
********************************************************************/
dcl DFSXSETS entry(pointer byvalue, pointer byvalue,
fixed bin(31) byvalue, fixed bin(31) byaddr,
fixed bin(31) byvalue, wchar(100) varying byaddr,
pointer byvalue, fixed bin(31) byvalue, bit(1) byvalue,
pointer byvalue, bit(1) optional) returns(fixed bin(31));
/********************************************************************
* DFSB64E,
* This API encodes an input buffer using the base64 encoding
* scheme specified by RFC 3548 available at
* http://tools.ietf.org/html/rfc3548.
*
* @param @bin_input_buf_ptr (input),
* A pointer-by-value to the binary buffer to encode in base64.
* The base64 sequence will be encoded in UTF-16.
*
* @param @bin_input_buf_len (input),
* An integer-by-value that specifies the length in bytes of
* the binary buffer supplied in parameter @bin_input_buf_ptr.
*
* @param @b64_output_buf_ptr (input),
* A pointer-by-value to a buffer in which to write the base64
* representation of the supplied binary buffer
* @bin_input_buf_ptr(1:@bin_input_buf_len). The buffer pointed
* to by this parameter must have a minimum length in bytes of
* [4 * floor( ( @bin_input_buf_len + 2 ) /3 ]. If this
* parameter is set to null, the API will write the length
* in bytes of the base64 result to parameter
* @b64_output_buf_len but will not actually perform encoding.
*
* @param @b64_output_buf_len (input),
* An integer-by-reference into which the API will write the
* length in bytes of the base64 sequence that was written to
* the buffer pointed to by parameter @b64_output_buf_ptr.
* Recall that result will be encoded in UTF-16.
*
* @return This API does not return any codes.
********************************************************************/
dcl DFSB64E entry(pointer byvalue, fixed bin(31) byvalue,
pointer byvalue, fixed bin(31) byaddr);
/********************************************************************
* DFSB64D,
* This API decodes a base64 input buffer by reversing the
* encoding scheme specified by RFC 3548
* available at http://tools.ietf.org/html/rfc3548.
*
* @param @b64_input_buf_ptr (input),
* A pointer-by-value to the base64 buffer to decode.
* The base64 sequence must be encoded in UTF-16.
*
* @param @b64_input_buf_len (input),
* An integer-by-value that specifies the length in bytes of
* the base64 buffer supplied in parameter @b64_input_buf_ptr.
*
* @param @bin_output_buf_ptr (input),
* A pointer-by-value to a buffer in which to write the decoded
* representation of the supplied base64 buffer
* @b64_input_buf_ptr(1:@b64_input_buf_len). If this
* parameter is set to null, the API will write the length
* in bytes of the decoded result to parameter
* @bin_output_buf_len but will not actually perform decoding.
*
* @param @bin_output_buf_len (input),
* An integer-by-reference into which the API will write the
* length in bytes of the decoded result that was written
* to the buffer pointed to by parameter @bin_output_buf_ptr).
*
* @return This API does not return any codes.
********************************************************************/
dcl DFSB64D entry(pointer byvalue, fixed bin(31) byvalue,
pointer byvalue, fixed bin(31) byaddr);