MVSThreadAffinity (BPX1TAF, BPX4TAF) — MVS thread affinity service

Function

The MVSThreadAffinity callable service allows a task created with pthread_create to request that a user-defined assembler routine is to be run on a specified target pthread. The requesting and target pthread must have been created with pthread_create, and both threads must be under the same initial pthread-creating thread (IPT). The requesting pthread is blocked until the requested routine has been run. The target pthread may be the IPT.

This service provides the ability for a program to manage MVS™ resources under the target pthread or IPT, instead of under the requesting pthread. Resources that can be managed with this service include load modules, opened data sets, and other MVS resources with task affinity.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1TAF):	31-bit
AMODE (BPX4TAF):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1TAF,(Routine_address,
              Parameter_list,
              Thread_ID,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4TAF with the same parameters. Routine_address and Parameter_list are 64-bit pointer fields.

Parameters

Routine_address

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

The name of a fullword (doubleword) containing the address of the routine to which control is to be passed on the target pthread. The requesting pthread is responsible for ensuring that the routine to be run is in memory when it is called, and remains there until the call is complete.

Parameter_list

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

The name of a fullword (doubleword) that contains the address of the routine parameter list. The value in this fullword is passed in register 1 when the specified routine receives control. If the routine does not require parameters, specify 0.

Thread_ID

Supplied parameter

Type:: Character string
Character set:: N/A
Length:: 8 bytes

The name of an 8-byte field that contains the target pthread under which the routine is to run. This is the value returned by the pthread_self service, or pointed to by the PTXL field PTXLTHIDPTR provided by the pthread_exit_and_get service. (See BPXYPTXL — Map the parameter list for pthread_create.) A value of all zeros will target the IPT.

Return_value

Returned parameter

Type:: Integer
Character set:: N/A
Length:: Fullword

The name of a fullword in which the MVSThreadAffinity service returns 0 if the request completes successfully, or -1 if the request is not successful.

Return_code

Returned parameter

Type:: Integer
Character set:: N/A
Length:: Fullword

The name of a fullword in which the MVSThreadAffinity service stores the return code. The MVSThreadAffinity service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The MVSThreadAffinity service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EFAULT	A bad address was received as an argument of the call; or the specified routine experienced an abnormal end or program check that was not handled by the routine's recovery. Consult Reason_code to determine the exact reason the error occurred. The following reason codes can accompany the return code: JRBadAddress and JRRoutineError.
EAGAIN	Another pthread within the process has this call pending for the specified pthread. At most one pthread can request this service at a time for a given pthread. The requesting pthread can try again later when the current pending call is complete.
EACESS	A task other than a pthread-created task or IPT is not permitted to perform this service.
EINVAL	A thread with the specified thread ID was not found. The reason code accompanying this return code is JRThreadNotFound.
EMVSERR	The passed Routine_address is zero or greater than X'7FFFFFFF'. The reason code accompanying this return code is JrInvalidRoutine.

Reason_code

Returned parameter

Type:: Integer
Character set:: N/A
Length:: Fullword

The name of a fullword in which the MVSThreadAffinity service stores the reason code. The MVSThreadAffinity service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

The specified routine to be executed receives control with the following attributes:
- Problem program state
- Key of the target pthread task
- AMODE 31
- Primary ASC mode
The register usage on entry to the specified routine is:
- R0: Undefined
- R1: Address of Parameter_list, as specified by the caller of the MVSThreadAffinity service
- R2–R12: Undefined
- R13: Address of a 72-byte work area with which the routine gains control. For AMODE 64 callers, the work area is 144 bytes long.
- R14: The return address from the specified routine to the MVSThreadAffinity. This address must be preserved by the invoked routine.
- R15: Address of the invoked routine
Only tasks created with pthread_create or the IPT can invoke this service. If a task that is not an IPT or a pthread-created task requests this service, it receives an EACCES return code.

Related services

Characteristics and restrictions

There are no restrictions on the use of the MVSThreadAffinity service.

Examples

For an example using this callable service, see BPX1TAF (MVSThreadAffinity) example.