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
Authorization: |
Supervisor state or problem state, any PSW key |
Dispatchable unit mode: |
Task |
Cross memory mode: |
PASN = HASN = SASN |
AMODE: |
31-bit |
ASC mode: |
Primary or access register (AR) |
Interrupt status: |
Enabled for I/O and external interrupts |
Locks: |
Unlocked |
Control parameters: |
All parameters must be addressable by the caller and in the
primary address space. |
Format
Figure 1. ATBGTRN
- Obtaining the Next TransactionCALL 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
- 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.
- 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.
- 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.
- A multi-trans TP cannot call Get_Transaction while a previous
call to Get_Transaction is still in progress in the same address space.