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.

This service manages MVS™ resources under the IPT, instead of under the task created with pthread_create. Some resources that can be managed with this service are:
  • 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

CALL BPX1IPT,(Routine_address,
              Parameter_list,
              Return_value,
              Return_code,
              Reason_code)

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

  1. 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
  2. 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
  3. 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.
  4. 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.
  5. The EXITRTN assembler routine cannot issue callable services after it gains control under the IPT.
  6. 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.

Parent topic: Callable services descriptions