mvsiptaffinity (BPX1IPT, BPX4IPT) — Run a program on the IPT thread
Function
The mvsiptaffinity callable service allows a task created with pthread_create to request that a user-defined assembler routine run on its initial pthread-creating thread (IPT). The requesting pthread is blocked until the requested routine has been executed.
- Load modules
- Opened data sets
- Other MVS resources with task affinity
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1IPT): | 31-bit |
AMODE (BPX4IPT): | 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
|
AMODE 64 callers use BPX4IPT with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.
Parameters
- Routine_address
- Supplied parameter
- Type:
- Address
- Length:
- Fullword (doubleword)
The name of a fullword (doubleword) containing the address of the routine control is passed to on the pthread's IPT. 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) containing 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.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the mvsiptaffinity service returns -1 if it is not successful. If it is successful, the mvsiptaffinity service returns 0.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the mvsiptaffinity service stores the return code. The mvsiptaffinity service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The mvsiptaffinity 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 abend or program check that was not handled by the routines recovery. The following reason codes can accompany the return code: JRBadAddress and JRRoutineError. EAGAIN Another pthread within the process has this call pending. At most one pthread can request this service at a time. The requesting task can try again later when the current pending call is complete. EACCES A task other than a pthread-created task is not permitted to perform this service. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword where the mvsiptaffinity service stores the reason code. The mvsiptaffinity service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.
Usage notes
- The specified routine to be executed receives control with the
following attributes:
- Problem program state
- Key of the IPT task
- AMODE 31(64), according to the AMODE of the caller
- 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 mvsiptaffinity 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 mvsiptaffinity service. This address must be preserved by the invoked routine.
- R15: Address of the invoked routine
- Only tasks created with pthread_create can invoke this service. If a task that was created using MVS non-POSIX interfaces requests this service, or if it is an IPT itself, it receives an EACCES return code.
- At most one pthread can have this service request pending at a time. If a pthread already has this service pending, when another pthread requests this service, the last pthread receives an EAGAIN return code. It is the caller's responsibility to serialize the invocation of mvsiptaffinity, or contain retry logic if the EAGAIN return code is obtained.
- The EXITRTN assembler routine cannot issue callable services after it gains control under the IPT.
- The specified routine can establish its own recovery environment. However, even if recovery is not established, the mvsiptaffinity service establishes its own recovery environment while running under the IPT. For all recoverable errors, this recovery routine retries, returning the EFAULT return code to the requestor. It also ensures that any recovery routine established by the IPT itself is not entered unexpectedly.
Related services
There are no related services.
Characteristics and restrictions
There are no restrictions on the use of the mvsiptaffinity service.
Examples
For an example using this callable service, see BPX1IPT (mvsiptaffinity) example.