Define_Local

Define_Local_TP can be used by a transaction scheduler to create a new local transaction program ID (TP_ID) to be associated with the transaction scheduler address space. A transaction scheduler may wish to create a new TP_ID so it can allocate outbound conversations under a TP_ID distinct from any TP_IDs it has received. The Define_Local_TP service will return the TP_ID that represents the new transaction program just created. This TP_ID can then be passed on the Allocate call or returned by the transaction scheduler extract. The Define_Local_TP service can only be used by a transaction scheduler that has identified itself to APPC/MVS.

The Define_Local_TP service gives the transaction scheduler control over defining one or more TP_IDs in the transaction scheduler address space. The transaction scheduler extract exit will be used to resolve ambiguity whenever there is more than one transaction program defined in the address space. See Extract Exit for more details on this exit.

Environment

Authorization:

Supervisor state or PSW key 0-7

Dispatchable unit mode:

Task mode

Cross memory mode:

Any PASN, any HASN, any 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. ATBDFTP - Define Local TP

CALL ATBDFTP (TP_name_length,
               TP_name,
               LU_name,
               TP_ID,
               Return_code
              );

Parameters

TP_name_length

Supplied parameter

Type: Integer
Char Set: N/A
Length: 32 bits

TP_name_length specifies the length of data contained in the TP_name parameter.

TP_name

Supplied parameter

Type: Character string
Char Set: 00640 or Type A
Length: 1 - 64 bytes

TP_name specifies the name of the local transaction program to be associated with this transaction program instance.

LU_name

Supplied parameter

Type: Character string
Char Set: Type A
Length: 8 bytes

LU_name specifies the name of the LU with which the newly created TP_ID should be associated. This must be an LU that is assigned to the transaction scheduler. If the LU_name parameter specified is all blanks, the base LU, if any, for the transaction scheduler will be used.

TP_ID

Returned parameter

Type: Character string
Char Set: N/A
Length: 8 bytes

TP_ID is a token that represents the transaction program instance that was just created.

Return_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Define_Local_TP may return one of the following decimal values in the return code parameter:

Decimal: Meaning
0: Request accepted. The TP_ID is returned in parameter TP_ID.
4: Request rejected. The LU specified was not an LU that is assigned to the transaction scheduler.
8: Request rejected. The TP name is not a valid character string.
32: The requested service is not supported in the caller's environment. For example, this return code will be given if the caller invokes any of the transaction scheduler services while holding a lock.
34: The requested transaction scheduler service must be invoked from a transaction scheduler address space.
44: APPC/MVS is not active.
48: APPC/MVS services failure.

Characteristics and Restrictions

The caller must be from a transaction scheduler address space (from the transaction scheduler address space that issued the Identify).
If an LU_name of all blanks is specified, and there is no base LU defined for the transaction scheduler, the request will be rejected with return code 4.
Transaction schedulers that call the Define_Local_TP service should not have any enabled unlocked task (EUT) functional recovery routines (FRRs) established. For more information about EUT FRRs, see the information on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide.