Get_Transaction

When APPC/MVS transaction programs are assigned a TP schedule type of multi-trans in the TP profile, those TPs can use the Get_Transaction service to hold consecutive conversations with multiple partner programs, without having to be terminated and reinitialized for each conversation.

TPs call Get_Transaction apart from the actual APPC conversation, in a part of the TP called a multi-trans shell. The multi-trans shell gets control first, during initialization, and issue Get_Transaction when the program is ready to handle the first incoming conversation request. Before issuing Get_Transaction to request consecutive conversations, the multi-trans shell is responsible for doing whatever cleanup is necessary to ensure that consecutive users maintain their data integrity and are isolated from one another and from resources used exclusively by the shell.

When APPC/MVS initiates a multi-trans TP, the TP's initial execution environment is set by a generic userid specified in the TP profile. When a conversation begins, the environment of the multi-trans TP changes to reflect the calling partner's security, accounting, and distribution characteristics. The environment is thus "personalized" for each consecutive caller that receives control from a subsequent Get_Transaction request. The multi-trans TP returns to its generic execution environment at termination or by issuing a Return_Transaction call from its multi-trans shell.

In response to each Get_Transaction call, the APPC/MVS transaction scheduler looks for the next incoming allocate request for the program. When it finds a request, APPC/MVS returns control from the Get_Transaction service with a return code of zero. The multi-trans shell then passes control to the part of the program that holds the actual conversation. Each Get_Transaction call deallocates any conversation received in response to a previous Get_Transaction call with a deallocate Type(Abend). For multi-trans TPs processing protected conversations, APPC/MVS causes all protected resources updated since the last commit or backout to be backed out if the multi-trans TP did not issue a Backout or Commit call prior to calling Get_Transaction to retrieve the next incoming allocate request.

For examples of using the Get_Transaction service with a multi-trans shell, see Examples of Multi-Trans Scheduling.

Requirements

Format

Figure 1. ATBGTRN - Obtaining the Next Transaction
CALL ATBGTRN(
        Return_code
       );

Parameters

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.

Valid return values for this parameter are:
Decimal Value
Description
0
An inbound transaction was obtained and is ready to run.
8
The Get_Transaction request waited for an interval based on installation response time goals and current demand for initiators in this class, up to a maximum of 5 minutes. No more work was available. The caller can call the Get_Transaction service again to wait for more work to arrive. The caller's execution environment is the environment that was set by the generic userid specified in the caller's TP profile.
12
The APPC/MVS transaction scheduler was not active. The caller cannot call the Get_Transaction service again to wait for more work to arrive.
16
Because of conditions in the TP or the TP's profile, no work was available. The calling environment is not valid because:
  • The TP is not scheduled as multi-trans
  • The TP was not running under an APPC/MVS transaction scheduler initiator
  • The calling program was in cross memory mode or SRB mode when it called the Get_Transaction service.

The caller's execution environment remains unchanged from when the TP called the Get_Transaction service.

Verify that the TP was running under the APPC transaction scheduler, in task mode. Verify that the TP's profile specified a TPSCHED_TYPE of MULTI_TRANS.

20
System error.
24
A previous call to the Get_Transaction or Return_Transaction service is still in progress in the same address space.

The caller's security and job control language (JCL) environment remain unchanged when the Get_Transaction service is called. However, the security and JCL environment may change when the previous Get_Transaction or Return_Transaction call ends.

28
The operator entered one or more commands (or the system administrator entered a configuration definition) that caused no more work to be available. The caller cannot call the Get_Transaction service again to wait for more work to arrive. The TP should terminate. The caller's execution environment is the environment that was set by the generic userid specified in the caller's TP profile.
Note: The system can return this code in the following situations:
  • The system operator entered a SET command that executed a CLASSDEL statement in an ASCHPMxx parmlib member, which specified that an APPC scheduler class is to be deleted. The scheduler class is running the multi-trans TP; the multi-trans TP has not called Get_Transaction service.
  • The APPC scheduler forced the multi-trans TP to terminate so the APPC scheduler can run other work in the same APPC scheduler class.
  • The system administrator updated the profile for the multi-trans TP while the multi-trans TP was either running or waiting for work.

Validate that the CLASS statement in the TP profile for the multi-trans TP is correct. If no errors are found, validate that no other TP profile has the same class name specified on the CLASS statement.

Restrictions

  1. Transaction programs that call the Get_Transaction 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.
  2. When a multi-trans TP creates subtasks, only one task can call Get_Transaction at a time. This is because each call to Get_Transaction changes the caller's execution environment until the subtask either terminates or calls Return_Transaction and receives a return code of zero.
  3. When a multi-trans TP creates a new jobstep task or subtask, the new jobstep task or subtask (and all of its subtasks) cannot call Get_Transaction.
  4. A multi-trans TP cannot call Get_Transaction while a previous call to Get_Transaction is still in progress in the same address space.
Parent topic: APPC/MVS Advanced TP Callable Services