DFSQGETS

The DFSQGETS API retrieves a SOAP structure from the IMS Message Queue and returns the information to the caller in a high-level language structure.

The structures and variables referred to in this topic are defined in the include file DFSPWSH (see Include file DFSPWSH).

Usage:
  • You must retrieve all structures in the IMS Message Queue using DFSQGETS before invoking DFSQSETS to put structures into it.
Limitations:
  • DFSQGETS supports the retrieval of SOAP Body and SOAP Fault structures only. The SOAP Header structure is not supported.

Parameters:

Table 1. Parameters for DFSQGETS
Parameter Type Usage Description
@dfs_async_msg_header_ptr POINTER BYVALUE Input A pointer-by-value to the instance of @dfs_async_msg_header that the Message Processing Program (MPP) retrieves from the IMS Message Queue prior by issuing a Get Unique (GU) call using the CEETDLI interface.
Important: This instance must be passed on all calls to DFSQGETS and DFSQSETS.
@dfs_iopcb_ptr POINTER BYVALUE Input A pointer-by-value to the I/O PCB that was passed to the Message Processing Program (MPP) on entry by IMS. DFSQGETS uses this I/O PCB when invoking CEETDLI to interact with the IMS Message Queue.
Note: If the return code from DFSQGETS is 999 then inspect the I/O PCB to determine the cause of the error.
@dfs_struct_type SIGNED FIXED BIN(31) BYVALUE Input An integer-by-value specifying the type of the language structure to retrieve from the IMS Message Queue. The following constants defined in the include file DFSPWSH can be used: @dfs_soap_body_struct.
@dfs_struct_name WCHAR(100) VARYING BYADDR Input A string-by-reference containing the name of the language structure to retrieve from the IMS Message Queue. The value of this parameter must correspond to the value of the parameter @dfs_struct_type.
@dfs_struct_ptr POINTER BYADDR Output A pointer-by-reference to a newly allocated storage block containing the returned language structure.
Important: This storage block resides in the same address space as the caller. Therefore it is highly recommended that the caller free this storage block when it is no longer needed.
@dfs_struct_size SIGNED FIXED BIN(31) BYADDR Output An integer-by-reference containing the size in bytes of the returned language structure.
@dfs_cee_feedback_ptr POINTER BYVALUE Input A pointer-by-value to an instance of @dfs_cee_feedback defining a Language Environment® Condition Token. This instance is updated each time DFSQGETS invokes Language Environment Callable Services.
Note: If the return code from DFSQGETS is 998 then 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.
@dfs_debug BIT(1) OPTIONAL Input An optional bit indicating whether DFSQGETS should display trace information (see Trace output for WSDL-to-PL/I segmentation APIs).

Return codes:

The return codes for DFSQGETS are constants defined in the DFSPWSH include file:

Table 2. Return codes for DFSQGETS
Type: Name: Value:
SIGNED FIXED BIN(31) @dfs_success 000
@dfs_omitted_parameter 100
@dfs_invalid_pointer 101
@dfs_invalid_struct_type 102
@dfs_struct_not_found 103
@dfs_struct_name_mismatch 104
@dfs_invalid_struct_order 105
@dfs_cee_call_failure 998
@dfs_dli_call_failure 999

Example invocation of DFSQGETS

01: /* Invoke API DFSQGETS to retrieve the SOAP body
02: * language structure from the IMS Message Queue.
03: */
04: @dfs_struct_name      = 'RequestBodyStruct';
05: @dfs_cee_feedback_ptr = addr(@dfs_cee_feedback);
06: @dfs_debug = '0'b;
07:
08: @return_code =
09:    DFSQGETS(@dfs_async_msg_header_ptr,
10:    @dfs_iopcb_mask_ptr, @dfs_soap_body_struct,
11:    @dfs_struct_name, @dfs_struct_ptr,
12:    @dfs_struct_size, @dfs_cee_feedback_ptr,
13:    @dfs_debug);
14:
15: if (@return_code != @dfs_success) then do;
16:    display('MYMPP#handle_myOperation(): '
17:       || 'ERROR, DFSQGETS @dfs_soap_body_struct, '
18:       || '@return_code: '|| trim(@return_code) || '.');
19:    return;
20: end; else do;
21:    RequestBodyStruct_ptr = @dfs_struct_ptr;
22: end;