Send_Error

Equivalent to:
  • LU 6.2 (MC_)Send_Error
  • CPI Send_Error (CMSERR)

Informs the partner program that the local program has detected an error.

Requirements

Format

Figure 1. ATBSERR - LU 6.2 Send Error

CALL ATBSERR(
        Conversation_id,
        Request_to_send_received,
        Notify_type,
        Error_Direction,
        Return_code
       );

Parameters

Conversation_id
Supplied parameter
  • Type: Character string
  • Char Set: No restriction
  • Length: 8 bytes

Conversation_id, sometimes called the resource identifier, identifies a conversation to the system.

Request_to_send_received
Returned parameter
  • Type: Integer
  • Char Set: N/A
  • Length: 32 bits

Request_to_send_received specifies whether or not Request_to_send notification has been received.

Valid return values for this parameter are:
Value
Meaning
0
Request_to_send_not_received

Indicates that Request_to_send notification has not been received.

1
Request_to_send_received

The partner program has issued a Request_to_send, requesting the local program to enter Receive state.

If Return_code indicates Program_parameter_check or Program_state_check, a value is not returned in Request_to_send_received.

Notify_type
Supplied parameter
  • Type: Structure
  • Char Set: N/A
  • Length: 4-8 bytes
Specifies the type of processing and notification (synchronous or asynchronous) requested for this service. Programs can request asynchronous processing, which returns control to the program immediately and later notifies the program by ECB when the service is complete. The possible types are:
  • None

    No notification is requested. The service is performed synchronously, and control is returned to the caller when processing is complete. All returned parameters are set on return to the caller. To specify no notification, set the parameter value to a four-byte structure containing binary zeros.

  • ECB

    Programs can request asynchronous processing by specifying an ECB to be posted when processing completes. To specify an ECB, set the parameter to an eight-byte structure containing a fullword binary one (X'00000001') followed by the address of a fullword area to be used as the ECB. The ECB must reside in the home address space.

    When you specify an ECB, control is returned before processing is complete, with only the return code set. If the asynchronous request was accepted, the return code is set to 0 to indicate that the service is being processed asynchronously. Other returned parameters are filled in during asynchronous processing, and the specified ECB is posted when all returned parameters are set. The completion code field in the ECB contains the return code for the service.

Error_Direction
Supplied parameter
  • Type: Integer
  • Char Set: N/A
  • Length: 32 bits
Error_Direction specifies the direction of the data flow in which the program detected an error. This parameter is significant only if the Send_Error service is issued in Send_Pending state.
Valid values for this parameter are:
Value
Meaning
0
Receive_Error

Specifies that the program detected an error in the data it received from another program.

1
Send_Error

Specifies that the program detected an error while preparing to send data to the partner program.

Return_code
Returned parameter
  • Type: Integer
  • Char Set: N/A
  • Length: 32 bits

Return_code specifies the return code that is returned to the local program. In cases where an error code is returned, the program should not examine any other returned variable associated with the call as nothing is placed in the variables.

See the following section for descriptions of return codes that can be returned to a caller of Send_Error.

Return Codes

If Send_Error is called in Send state, possible values for Return_code are:
Decimal Value
Meaning
0
OK
3
Conversation_type_mismatch
5
PIP_not_specified_correctly
6
Security_not_valid
8
Sync_lvl_not_supported_pgm
9
TPN_not_recognized
10
TP_not_available_no_retry
11
TP_not_available_retry
17
Deallocated_abend
20
Product_specific_error
22
Program_error_purging
24
Program_parameter_check
25
Program_state_check
26
Resource_failure_no_retry
27
Resource_failure_retry
30
Deallocated_abend_SVC
31
Deallocated_abend_timer
33
SVC_error_purging
100
Take_backout
130
Deallocated_abend_bo
131
Deallocated_abend_svc_bo (basic conversations only)
132
Deallocated_abend_timer_bo (basic conversations only)
133
Resource_failure_no_retry_bo
134
Resource_failure_retry_bo
Note: Return codes 100 through 134 are possible values only for conversations with a synchronization level of syncpt.
If Send_Error is called in Receive state, possible values for Return_code are:
Decimal Value
Meaning
0
OK
18
Deallocated_normal
20
Product_specific_error
24
Program_parameter_check
25
Program_state_check
26
Resource_failure_no_retry
27
Resource_failure_retry
133
Resource_failure_no_retry_bo
134
Resource_failure_retry_bo
135
Deallocated_normal_bo
Note: Return codes 133 through 135 are possible values only for conversations with a synchronization level of syncpt.
If Send_Error is called in Send-pending state, possible values for Return_code are:
Decimal Value
Meaning
0
OK
17
Deallocated_abend
20
Product_specific_error
22
Program_error_purging
24
Program_parameter_check
25
Program_state_check
26
Resource_failure_no_retry
27
Resource_failure_retry
30
Deallocated_abend_SVC
31
Deallocated_abend_timer
33
SVC_error_purging
100
Take_backout
130
Deallocated_abend_bo
131
Deallocated_abend_svc_bo (basic conversations only)
132
Deallocated_abend_timer_bo (basic conversations only)
133
Resource_failure_no_retry_bo
134
Resource_failure_retry_bo
Note: Return codes 100 through 134 are possible values only for conversations with a synchronization level of syncpt.
If Send_Error is called in Confirm, Sync_point, Sync_point_send, or Sync_point_deallocate state, possible values for Return_code are:
Decimal Value
Meaning
0
OK
20
Product_specific_error
24
Program_parameter_check
25
Program_state_check
26
Resource_failure_no_retry
27
Resource_failure_retry
133
Resource_failure_no_retry_bo
134
Resource_failure_retry_bo
Note: Return codes 133 and 134 are possible values only for conversations with a synchronization level of syncpt.

The following table describes all of the possible return codes for Send_Error:

Table 1. Return Codes for the Send_Error Service
Return Code Value, Meaning, and Action
0 Value: OK

Meaning: The call completed successfully.

System Action: If the call specified a Notify_type of ECB, APPC/MVS posts the ECB specified on the Notify_type parameter when APPC/MVS finishes processing the call asynchronously.

Application Programmer Response: None required.

3 Value: Conversation_type_mismatch

Meaning: The partner LU rejected an allocate request. The local TP called the Allocate service and specified a value of Basic_conversation or Mapped_conversation on the Conversation_type parameter. The partner TP does not support the respective basic or mapped conversation protocol boundary.

System Action: The system returns this return code on a call that occurs after the call to Allocate.

Application Programmer Response: When requesting the allocate, change the Conversation_type parameter to specify a conversation type that the partner TP supports.

5 Value: PIP_not_specified_correctly

Meaning: The partner LU rejected an allocate request. The partner TP defined one or more initialization parameter (PIP) variables, which APPC/MVS does not support.

System Action: The system returns this return code on a call that occurs after the call to Allocate. The system does not return this code to callers of the CPI Communications Allocate call.

Application Programmer Response: Ask the partner system programmer to change the partner TP so it does not expect PIP data from the TP running on MVS.

6 Value: Security_not_valid

Meaning: The partner LU rejected an allocate request. The specified security information is not valid.

System Action: The system returns this return code on a call that occurs after the call to Allocate.

Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format.

8 Value: Sync_lvl_not_supported_pgm

Meaning: The partner LU rejected an allocate request. The local TP specified a synchronization level (on the Sync_level parameter) that the partner TP does not support.

System Action: The system returns this return code on a call that occurs after the call to Allocate.

Application Programmer Response: See Allocate for an explanation of the Sync_level parameter. When requesting the allocate, ensure that the Sync_level parameter specifies a correct value.

9 Value: TPN_not_recognized

Meaning: The partner LU rejected an allocate request. The local TP specified a partner TP that the partner LU does not recognize.

System Action: The system returns this return code on a call that occurs after the call to Allocate.

Application Programmer Response: See the application programmer response for return code six for this service.

10 Value: TP_not_available_no_retry

Meaning: The partner LU rejected an Allocate request. The local TP specified a partner TP that is known to the partner LU, but the partner LU cannot start the TP. The condition is not temporary. The TP should not retry the Allocate request.

System Action: The system returns this return code on a call that occurs after the call to Allocate.

Application Programmer Response: See the application programmer response for return code six for this service.

11 Value: TP_not_available_retry

Meaning: The partner LU rejected an allocate request. The local TP specified a partner TP that the partner LU recognizes but cannot start. The condition might be temporary.

System Action: The system returns this return code on a call that occurs after the call to Allocate.

Application Programmer Response: Retry the Allocate request. If the error persists, see Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format.

17 Value: Deallocated_abend

Meaning: A partner TP called the Deallocate service. The request specified a Deallocate_type of Deallocate_abend.

System Action: If the partner TP was in Receive state when it called Deallocate, the system purges information sent by the local TP that was not received by the partner TP. The system returns this return code to the local TP when it calls an APPC service in Send or Receive state.

Application Programmer Response: See the application programmer response for return code six for this service.

18 Value: Deallocated_normal

Meaning: A partner TP called the Deallocate service for a basic or mapped conversation. The request specified a Deallocate_type of Deallocate_sync_level or Deallocate_flush.

System Action: The system returns this return code to the local TP when it calls a service while the conversation is in Receive state.

Application Programmer Response: None required.

20 Value: Product_specific_error

Meaning: The system found a product-specific error.

System Action: The system might write symptom records, which describe the error, to the logrec data set.

Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format. If necessary, see Diagnosing Product-Specific Errors for more information about product-specific errors.

22 Value: Program_error_purging

Meaning: A partner TP called the Send_Error service for a basic or mapped conversation. The conversation for the partner TP was in Receive or Confirm state.

System Action: The system returns this return code to the local TP when it calls an APPC service before sending any information. If the TP called Send_Error while in Receive state and before it received all the information that the partner TP sent, the system might purge the data. If the TP called Send_Error while in Receive or Confirm state but after it received all the information that the partner TP sent, the system does not purge the data.

Application Programmer Response: See the application programmer response for return code six for this service.

24 Value: Program_parameter_check
Meaning: The local TP called an APPC service. One of the following errors occurred in one or more parameters specified on the call:
  • An unauthorized caller specified a Notify_type of ECB.
  • The Sync_level field for the conversation was equal to sync_level_none.

System Action: The system returns this return code to the caller of the APPC service in error.

Application Programmer Response: See the application programmer response for return code six for this service.

25 Value: Program_state_check

Meaning: The local TP called a service while running in a state in which the call is not valid. The TP should not examine any other returned variables associated with the call because nothing is placed in those variables.

System Action: The state of the conversation remains unchanged. For a list of states that are valid for each call, see APPC/MVS Conversation State Table. The conversation was in send state and the TP started, but the TP did not finish sending a logical record.

Application Programmer Response: See the application programmer response for return code six for this service.

26 Value: Resource_failure_no_retry

Meaning: An error caused the conversation to terminate. The condition is not temporary. The application should not try to run the transaction until the condition is corrected.

System Action: The system terminates the conversation.

Application Programmer Response: See the application programmer response for return code six for this service.

27 Value: Resource_failure_retry

Meaning: An error caused the conversation to terminate. The condition might be temporary.

System Action: The system terminates the conversation.

Application Programmer Response: Retry the transaction.

30 Value: Deallocated_abend_SVC

Meaning: The partner TP called Deallocate with a Deallocate_type of Deallocate_abend_SVC.

System Action: If the partner TP was in Receive state when it called Deallocate, the system purges all information that was sent by the local TP but was not yet received by the partner TP. The system returns this return code to the local TP when it calls a service while in Send or Receive state.

Application Programmer Response: See the application programmer response for return code six for this service.

31 Value: Deallocated_abend_timer

Meaning: A partner TP called the Deallocate service with a Deallocate_type of Deallocate_abend_timer.

System Action: If the partner TP was in Receive state when it called Deallocate, the system purges all information that was sent by the local TP but was not yet received by the partner TP. The system returns this return code to the local TP when it calls a service while in Send or Receive state.

Application Programmer Response: See the application programmer response for return code six for this service.

33 Value: SVC_error_purging

Meaning: A partner TP called the Send_Error service, and LU services on the partner LU specified a value of SVC for the type of call. The conversation for the partner TP was in Receive or Confirm state, and the call might have caused information to be purged.

System Action: The system normally returns this code to the local TP after the system sends some information to the partner TP. However, the system can also return this code to the local TP before it sends any information.

Application Programmer Response: See the application programmer response for return code six for this service.

100 Value: Take_backout
Meaning: This value is returned only when all of the following conditions are true:
  • The Sync_level is set to syncpt.
  • The conversation is not in Initialize state.
  • The program is using protected resources that must be backed out.

System Action: The system returns this return code to the caller of the service.

Application Programmer Response: Before it can use this conversation or any other protected conversations associated with the current context again, the local TP must issue a Backout call to restore all protected resources to their status as of the last synchronization point.

130 Value: Deallocated_abend_bo

Meaning: This return code is returned only for conversations with Sync_level set to syncpt.

The partner program issued a Deallocate call with Deallocate_type set to deallocate_abend, or the partner LU has done so because of a partner program abnormal-end condition.

System Action: If the conversation for the partner program was in Receive state when the call was issued, information sent by the local program and not yet received by the partner program is purged. The conversation is now in Reset state.

Application Programmer Response: Before it can use any other protected conversations associated with the current context again, the local TP must issue a Backout call to restore all protected resources to their status as of the last synchronization point.

131 Value: Deallocated_abend_SVC_bo

Meaning: This return code is returned only for conversations with Sync_level set to syncpt.

The partner TP called Deallocate with a Deallocate_type of deallocate_abend_SVC.

System Action: If the partner TP was in Receive state when it called Deallocate, the system purges all information that was sent by the local TP but was not yet received by the partner TP. The system returns this return code to the local TP when it calls a service while in Send or Receive state.

Application Programmer Response: Before it can use any other protected conversations associated with the current context again, the local TP must issue a Backout call to restore all protected resources to their status as of the last synchronization point.

132 Value: Deallocated_abend_timer_bo

Meaning: This return code is returned only for conversations with Sync_level set to syncpt.

A partner TP called the Deallocate service with a Deallocate_type of deallocate_abend_timer.

System Action: If the partner TP was in Receive state when it called Deallocate, the system purges all information that was sent by the local TP but was not yet received by the partner TP. The system returns this return code to the local TP when it calls a service while in Send or Receive state.

Application Programmer Response: Before it can use any other protected conversations associated with the current context again, the local TP must issue a Backout call to restore all protected resources to their status as of the last synchronization point.

133 Value: Resource_failure_no_retry_bo

Meaning: This return code is returned only for conversations with Sync_level set to syncpt.

An error caused the conversation to terminate. The condition is not temporary. The application should not try to run the transaction until the condition is corrected.

The system terminates the conversation.Before it can use any other protected conversations associated with the current context again, the local TP must issue a Backout call to restore all protected resources to their status as of the last synchronization point.

System Action: The system terminates the conversation.

Application Programmer Response: Before it can use any other protected conversations associated with the current context again, the local TP must issue a Backout call to restore all protected resources to their status as of the last synchronization point.

134 Value: Resource_failure_retry_bo

Meaning: This return code is returned only for conversations with Sync_level set to syncpt.

An error caused the conversation to terminate. The condition might be temporary.

System Action: The system terminates the conversation.

Application Programmer Response: Before it can use any other protected conversations associated with the current context again, the local TP must issue a Backout call to restore all protected resources to their status as of the last synchronization point.

135 Value: Deallocated_normal_bo

Meaning: This return code is returned only for conversations with Sync_level set to syncpt.

When the Send_Error call is issued in Receive state, incoming information is purged by the system. This purged information might include an abend deallocation notification from the partner program or system. The conversation is now in Reset state.

System Action: /The system returns this return code to the caller of the service.

Application Programmer Response: Before it can use any other protected conversations associated with the current context again, the local TP must issue a Backout call to restore all protected resources to their status as of the last synchronization point.

Restrictions

TPs that call the Send_Error service while in task mode should not have any enabled unlocked task (EUT) functional recovery routines (FRRs) established. For more information about EUT FRRs, see the section on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide.