ICAL call

Format for the SENDRECV subfunction

>>-ICAL--aib--request_area--response_area----------------------><

Format for the RECEIVE subfunction

>>-ICAL--aib--response_area------------------------------------><

Parameters

aib

Specifies the application interface block (AIB) that is used for the call. This parameter is an input and output parameter.

You must initialize the following fields in the AIB:

AIBERRXT

This 4-byte length field contains the additional error information that is returned by OTMA, IMS Connect, IMS TM Resource Adapter, the IMS Enterprise Suite SOAP Gateway server, or user-written IMS Connect client applications. The default is 0.

AIBID

Eye catcher. This 8-byte field must contain DFSAIBbb.

AIBLEN

AIB lengths. This field must contain the actual length of the AIB that the application program obtained.

AIBOALEN

A 4-byte field that, when an ICAL call is issued, must contain the length of the request area.

When a response to an ICAL call is received, if the response data is too large to fit in the response area, the AIBOALEN field contains the total length of the entire response data. When the response area is too small to fit all of the response data, the AIB return code is X'100' and the AIB reason code is X'00C'. For any other return codes that are received with a response, this field is unchanged.

When partial data is returned, you can use the value of this field to determine how much space is required in the response data buffer. Your application program can then expand the buffer and issue an ICAL call with the RECEIVE subfunction code to retrieve the complete response message.

AIBOAUSE

A 4-byte field that, when an ICAL is issued, contains the length of the output response area that is specified in the call list.

When a response to an ICAL call is received, IMS updates the field to contain the length of the response message that is returned in the response area. If only partial data is returned because the response area is not large enough, AIBOAUSE contains the length of the data that is returned in the response area, and AIBOALEN contains the total length of the response message.

AIBREASN

AIB reason code.

AIBRETRN

AIB return code.

AIBRSFLD

The time to wait for the synchronous call process to complete. This 4-byte field contains a time value in 100th of a second.

The valid range is 0 - 999999. The system default is 10 seconds.

• If the specified value is larger than the maximum value, the maximum value is used.
• If the value is set to 0, then the timeout value that is specified in the OTMA descriptor is used. If there is no timeout value in the OTMA descriptor, the system default is used for the timeout.
• If the timeout value specified on the OTMA destination descriptor differs from the timeout value specified on the ICAL call, OTMA uses the smaller of the two values.

When the timeout value is reached, the IMS application that issues the synchronous callout request receives a return code of X'0100' and a reason code of X'0104'. The message is discarded.

AIBRSNM1

OTMA descriptor name. This 8-byte, alphanumeric, left-aligned field must contain the name of the OTMA descriptor that defines the destination of the IMS call.

AIBRSNM2

This 8-byte, alphanumeric, left-aligned field contains the logical terminal name used to override the LTERM name in the I/O PCB of the IMS application program for the target transaction of an ICAL call for synchronous program switch. The name specified in the AIB is used instead of any name specified in the OTMA destination descriptor. However, if no name is specified in AIBRSNM2, the name from the OTMA descriptor is used. If no name is found in the descriptor or in the AIB, the IMS application terminal symbolic (PSTSYMBO) is used as the default logical terminal name for the target transaction.

AIBSFUNC

Subfunction code. This field must contain an 8-byte subfunction code. The valid subfunction codes are:

SENDRECV

The IMS application program uses this subfunction to send a message and wait for the response. This subfunction is used for synchronous program-to-program communication.

RECEIVE

The IMS application program uses this subfunction to retrieve the complete response data from a previous incomplete ICAL call. If a SENDRECV subfunction call completes with AIB return code X'0100' and reason code X'000C', the response data did not fit in the response area. The application program can expand the response area and then retrieve the complete response with the RECEIVE subfunction call.

AIBUTKN

Map name. If specified, this 1- to 8-byte alphanumeric, left-justified field contains the 1- to 8-character map name used for message formatting or service identification purpose. This map name is included in the OTMA state data prefix sent to the destination for callout.

request_area

Specifies the request area to use for this call. This parameter is an input parameter.

This request area contains the request message data that is sent from the IMS application program to the application that is specified in the OTMA descriptor. The AIBOALEN field specifies the length of the request message data. Because the ICAL call bypasses the IMS TM message queue, the format of the request area does not require the LLZZ fields.

If the OTMA descriptor specifies that the request message must be routed to another IMS application program (TYPE=IMSTRAN), the LLZZ fields and transaction code must be specified in the first 8 bytes of the data area that follows the LLZZ. For transactions specified with MULTSEG, the request data must include the entire multi-segment message. The standard IMS LLZZ format is required for each segment, but the transaction code is only required for the first segment.

LL

Specifies the length of the segment.

ZZ

Sets the segment to binary zeros.

response_area

Specifies the response area to use for this call. This parameter is an output parameter.

If the response area is not large enough to contain all of the returned data, IMS returns partial data. When partial data is returned, the AIBOAUSE field contains the length of the returned data in the response area, and AIBOALEN contains the actual length of the response message.

Because an ICAL call for synchronous callout bypasses the IMS TM message queue, the format of the response area does not require the LLZZ fields. However, ICAL calls for synchronous program switch to another IMS application do require the LLZZ fields. The LLZZ fields for a synchronous program switch are populated by the output from the target IMS application. Synchronous program switch requests do not bypass the message queue.

If the original request message was routed to another IMS application program, the response data follows the standard LLZZ format for each segment in the response message.

Usage: SENDRECV subfunction

An ICAL call is used in an IMS application program for synchronous callout that does not use the IMS message queue. Because the IMS message queue is not used, synchronous callout messages are not constrained to the 32 KB message segment restriction.

However, An ICAL call that is used in an IMS application program for synchronous program switch processing to an IMS transaction does use the IMS message queue. The 32 KB message limit applies to synchronous program switch requests.

Before you run the IMS application that issues this call:

• The OTMA descriptor for the outbound destination routing information must be already defined.
• If the ICAL request is for synchronous callout, the external application or server that the IMS application is calling out to must be configured to listen for callout messages with the IMS OTMA RESUME TPIPE function. If the RESUME TPIPE is not set up before the ICAL call times out, a timeout error is returned to the IMS application.
• If the ICAL request is for synchronous program switch, the target is an IMS transaction that is defined with the TRANSACT macro or the equivalent type-2 commands CREATE TRAN and UPDATE TRAN. The transaction must be started.
• For a synchronous program switch request in a shared queues environment, all of the IMS systems in the same shared queues group must have a MINVERS value of 13.1.

When the synchronous callout timeout value is specified in both the OTMA destination descriptor and the DL/I ICAL call, IMS uses the lower value of the two.

For a synchronous program switch, the target transaction can be in the same IMS system, in an IMS that is accessible through shared queues, or in a remote IMS that is accessible with MSC. The synchronous program switch request is queued as an OTMA transaction, but OTMA is not required.

The target application of a synchronous program switch can issue an additional synchronous program switch request before returning to the original application program. You can chain together any number of synchronous program switch requests. However, consider the timeout value for each ICAL call when making nested synchronous program switch requests. Also, there must be an IMS dependent region available for each of the target transactions to be scheduled. Lastly, consider that a multi-switch program flow can hold database locks until the entire sequence of switches is resolved. Two or more applications in the same synchronous program switch chain can encounter database locking contention with each other.

If the ICAL call for a synchronous program switch request times out, or if more than one response is returned after the first one, IMS treats further responses as late messages. The default response to a late message is to dequeue it. If you want to retain late messages, you can configure a tpipe in the OTMA destination descriptor for request to hold the late responses, or you can code a DFSMSCE0 exit routine to reroute them.

Synchronous program switch requests made from Fast Path regions do not support late response messages. Any late response message is discarded, including subsequent redundant responses.

If a late response message for a synchronous program switch request is routed to an OTMA client, but the original request was not initiated from an OTMA client, you must use the DFSYIOE0 exit routine to re-build the default 1 KB OTMA message user data prefix for the response message.

If the destination descriptor for a synchronous program switch request is configured to queue late messages to a tpipe or reroute them with a DFSMSCE0 user exit routine, OTMA transaction expiration checking at the application GU time is disabled for the message.

Depending on the transaction security specifications (TRN=Y), the IMS region that is running the application that issues an ICAL request calls RACF® and the DFSCTRN0 user exit to determine if the user is authorized to issue the ICAL call. For APPC or OTMA transactions, additional security specifications are checked. If the security level for APPC or OTMA is set to NONE, then RACF and the DFSCTRN0 user exit are not called even if TRN=Y is specified.

For a synchronous program switch request, IMS schedules the transaction as an OTMA transaction. The OTMA security configuration (NONE, CHECK, FULL, or PROFILE) is used even if OTMA is not active. The default security setting is FULL, which is also used if OTMA is not enabled for the IMS system.

You can change the synchronous program switch security configuration with by issuing the following command:

/SECURE OTMA TMEMBER DFSYICAL value

DFSYICAL is the dedicated synchronous program switch processing TMEMBER. It is not used for other types of requests. Replace value with NONE, CHECK, FULL, or PROFILE as appropriate.

When OTMA security is set to FULL for DFSYICAL, IMS always creates an ACEE in the dependent region when it is scheduled. IMS uses this ACEE if security checks are necessary.

When OTMA security is set to CHECK for DFSYICAL, IMS does not create an ACEE at scheduling time. IMS creates an ACEE in the control region if security checks are necessary.

When OTMA security is to set to NONE for DFSYICAL, no security check is performed.

Usage: RECEIVE subfunction

When a SENDRECV subfunction call returns too much data to fit in the allocated response buffer (AIB return code X'0100' and reason code X'000C'), the value of the AIBOLEN field is updated with the length of the complete response message. Expand the size of the response area and then issue an ICAL call with the RECEIVE subfunction code to retrieve the complete response message.

The complete response data for the original ICAL call is held in the IMS control region until one of the following events occurs:

• The application issues a new ICAL call with the SENDRECV subfunction code is issued
• The IMS application reaches a sync point or terminates abnormally
• The IMS application issues a ROLB or CHECKPOINT call

Restrictions

ICAL calls for external callout have the following restrictions:

• Coordinated two-phase commit between the IMS application program and the external application program is not supported.
• An ICAL call cannot be issued from IMS in a shared-queues environment that is not connected to IMS Connect.

Synchronous program switch requests have the following restrictions:

• The OTMA Input/Output Edit exit routine (DFSYIOE0) is not called for a synchronous program switch request or response message.
• The TM and MSC Message Routing and Control exit routine (DFSMSCE0) is not called for a synchronous program switch request.
• The target transaction is not part of the RRS commit scope of the initiating application program.
• BMP and JBP applications cannot make synchronous program switch requests in a DBCTL environment.
• The target transaction has read-only access to Fast Path MSDBs.
• The target transaction cannot be an IMS conversational transaction.
• All of the participating IMS systems in a shared queues environment must have a DBRC MINVERS value of 13.1 or greater.

Return codes and reason codes

The following table lists the return codes and reason codes for the ICAL call.

Table 1. Return codes and reason codes for the ICAL call

Return code	Reason code	Extended reason code	Description
X'0000'	X'0000'	X'0000'	Call was completed successfully. Proceed.
X'0100'	X'000C'	X'0000'	Partial output response data was returned. Issue a new ICAL call with the RECEIVE subfunction code and an expanded response data area to retrieve the complete response message.
X'0100'	X'000C'	X'000D'	An IMS informational or error message was returned in response to a synchronous program switch request.
X'0100'	X'0100'	The default value is 0. If the value is non-zero, it is set by the external application.	Error message was returned in the output response data.
X'0100'	X'0100'	X'000D'	The synchronous program switch request was returned with an IMS message.
X'0100'	X'0100'	X'0004'	An IMS informational or error message was returned in response to a synchronous program switch request.
X'0100'	X'0104'	X'0004'	The request timed out. The ICAL was not sent to the external application.
X'0100'	X'0104'	X'0008'	The request timed out. The ICAL was sent, but the ACK was not received.
X'0100'	X'0104'	X'000C'	The request timed out. The ICAL was sent, but the response was not received.
X'0100'	X0104'	X'0010'	The request timed out. The ICAL was sent, but IMS failed to process the response.
X'0100'	X'0104'	X'0020'	The request timed out. The ICAL request for synchronous program switch was sent, but no response was received.
X'0100'	X'0108'	The default value is 0. If the value is non-zero, it is set by the external application.	Request message was rejected by the external application.
X'0100'	X'010C'	X'0000'	The synchronous call was cleared by a command (such as a /STOP or /PSTOP command).
X'0100'	X'0110'	X'0000'	The request message was rejected because the specified transaction is not supported. Either the trancode was not found or the specified transaction was an IMS conversational transaction, a CPIC transaction, or an IMS command transaction.
X'0100'	X'0110'	X'0004'	The request message was rejected because the user is not authorized to issue a synchronous program switch request.
X'0100'	X'0110'	X'0005'	The request message was rejected because the tmember that IMS uses to process synchronous program switch requests (DFSYICAL) is stopped. Issue the command /START TMEMBER DFSYICAL to resolve the problem.
X'0100'	X'0110'	X'0006'	The request message was rejected because the tpipe that IMS uses to process synchronous program switch requests (DFSTPIPE of the OTMA tmember DFSYICAL) is stopped. Issue the command /START TMEMBER DFSYICAL TPIPE DFSTPIPE to resolve the problem.
X'0100'	X'0110'	X'000D'	The request message was rejected because IMS failed to get an internal storage YTIB to process the message.
X'0100'	X'0110'	X'000E'	The request message was rejected because IMS failed to activate DFSYTIB0 to process the message.
X'0100'	X'0110'	X'0010'	The TMEMBER or TPIPE name for late response message routing is invalid because it contains invalid characters. Check the destination descriptor.
X'0100'	X'0110'	X'0011'	The TMEMBER or TPIPE name for late response message routing is missing from the destination descriptor. If either value is specified, both must be included.
X'0100'	X'0110'	X'0012'	The TMEMBER or TPIPE name for late response message routing is incorrect. Check the destination descriptor.
X'0100'	X'0110'	X'0013'	The SMEM and SYNCTP parameters are mutually exclusive.
X'0100'	X'0110'	X'0014'	The TPIPE name for late message processing is either missing or invalid in the destination descriptor.
X'0100'	X'0110'	X'0015'	The request message was rejected because the request was made in a shared queues environment with different IMS MINVERS values. The IMS systems in the shared queues group must have the MINVERS value 13.1.
X'0100'	X'0110'	X'0016'	The request is rejected due to OTMA global message flood condition. Too many OTMA message blocks (TIB) were allocated in the system.
X'0100'	X'0110'	X'0020'	The request message was rejected because the input data length is incorrect. The length of the segment must match the LLZZ value specified on the request. The total length of all segments in the request must match the AIBOALEN value in the AIB.
X'0100'	X'0110'	X'0030'	The request message was rejected because the transaction is currently unavailable.
X'0100'	X'0110'	X'0031'	The request message was rejected because the transaction is stopped.
X'0100'	X'0110'	X'0033'	The request message was rejected because the destination name for the program switch is an RCNT.
X'0100'	X'0110'	X'0034'	The request message was rejected because the destination name for the program switch is a CNT.
X'0100'	X'0110'	X'0035'	The request message was rejected because the destination transaction can only accept a single input segment. Multiple input segments were specified for the request.
X'0100'	X'0110'	X'0036'	The request message was rejected because an IMS queue manager encountered an insert error.
X'0100'	X'0110'	X'0037'	The request message was rejected because an IMS queue manager encountered an internal error.
X'0100'	X'0110'	X'0038'	The request message was rejected because a queue overflow was detected.
X'0100'	X'0110'	X'0039'	The request message was rejected because IMS failed to process the Fast Path transaction.
X'0100'	X'0110'	X'003A'	The request message was rejected because IMS queue manager failed to update the message prefix.
X'0100'	X'0110'	X'003B'	The request message was rejected because IMS failed to enqueue the transaction.
X'0100'	X'0110'	X'0060'	The request message was rejected because the synchronous program switch was canceled before a reply was received.
X'0100'	X'0110'	X'0061'	The request message was rejected because the target transaction does not reply to the IOPCB and does not perform a program-to-program switch. The ICAL is rejected to avoid a timeout. This rejection occurs when the REPLYCHK descriptor is set to YES for the destination transaction. If there is an asynchronous response for the ICAL, you can set REPLYCHK to NO and this ICAL is treated as valid.
X'0100'	X'0110'	X'0070'	IMS failed to process the response message for the synchronous program switch ICAL call. The length of an output message segment was greater than the 32K limit.
X'0100'	X'0110'	X'0071'	IMS failed to process the response message for the synchronous program switch ICAL call. IMS is running out of LUMP storage space to process the response message.
X'0100'	X'0110'	X'0072'	IMS failed to process the response message for the synchronous program switch ICAL call. IMS failed to allocate storage from subpool 231, which is required to process the response message.
X'0100'	X'0110'	X'0073'	IMS failed to retrieve the response message from the IMS message queue.
X'0104'	X'0210'	X'0000'	Input area length (AIBOALEN) is set to zero.
X'0104'	X'0214'	X'0000'	Output area length (AIBOAUSE) is set to zero.
X'0104'	X'0218'	X'0000'	Subfunction code is not known or invalid.
X'0104'	X'0610'	X'0000'	Request input area address parameter is missing
X'0104'	X'0614'	X'0000'	Response output area address parameter is missing.
X'0104'	X'1020'	X'0000'	Descriptor name is invalid.
X'0104'	X'1024'	X'0000'	Timeout value is invalid.
X'0104'	X'1028'	X'0000'	The ICAL RECEIVE call was rejected because no additional response data is available. Either the additional response data from a previous ICAL SENDRECV call was already retrieved, or a subsequent ICAL SENDRECV call cleared the response buffer.
X'0108'	X'0008'	X'0000'	IMS failed to release PSTICALO (internal storage) for the ICAL call.
X'0108'	X'0010'	X'0000'	Unable to obtain private storage. The size of the input request data might be too large.
X'0108'	X'0570'	X'0000'	The ICAL RECEIVE call was rejected because the internal buffer storage at PSTICALO is invalid.
X'0108'	X'0580'	X'0004'	Unable to send the request message to the external application. IMS is shutting down.
X'0108'	X'0580'	X'0008'	Unable to send the request message to the external application. The IMS callout function is disabled.
X'0108'	X'0580'	X'000C'	Unable to send the request message to the external application. The OTMA member was not found or is inactive.
X'0108'	X'0580'	X'0010'	Unable to send the request message to the external application. The OTMA TPIPE was not found or is stopped.
X'0108'	X'0580'	X'0014'	Unable to send the request message to the external application. IMS failed to obtain storage to queue a request.
X'0108'	X'0580'	X'0018'	Unable to send the request message to the external application. IMS failed to obtain LUMP storage to process the message.
X'0108'	X'0580'	X'001C'	Unable to send the request message to the external application. IMS failed to contact OTMA to process the ICAL call.
X'0108'	X'0580'	X'0100'	IMS failed to obtain the required LUMP storage space to process the synchronous program switch request.
X'0108'	X'0580'	X'0104'	OTMA failed to process the synchronous program switch. See the associated X'67D0' log record.
X'0108'	X'0584'	X'0004'	Unable to process the response output message from the external application. No data in the response message.
X'0108'	X'0584'	X'0008'	Unable to process the response output message from the external application. The XCF buffer length for the response message is incorrect.
X'0108'	X'0584'	X'000C'	Unable to process the response message from the external application. IMS failed to allocate storage for the response message processing.
X'0108'	X'0584'	X'0010'	Unable to process the response message from the external application. A null segment was found in a multi-segment response message.
X'0108'	X'0588'	The default value is 0. If the value is non-zero, it is set by IMS Connect.	IMS Connect failed to process the response. No response data returned.
X'0108'	X'058C'	The default value is 0. If the value is non-zero, it is set by IMS Connect.	IMS Connect failed to process the response. Complete or partial raw data from the external client application is returned.