attach_execmvs (BPX1ATM, BPX4ATM) — Attach an MVS program

Function

The attach_execmvs service attaches a task to run an MVS™ executable program in a newly created child process of the caller. The new process is run in a subtask in the same address space.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1ATM):	31-bit
AMODE (BPX4ATM):	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 BPX1ATM,(Program_name_length,
              Program_name,
              Argument_length,
              Argument,
              Exit_routine_address,
              Exit_parameter_list_address,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4ATM with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.

Parameters

Program_name_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length, in the range of 1 to 8 bytes, of the name of the MVS program.

Program_name

Supplied parameter

Type:: Character string
Character set:: Conforms to naming conventions for members of MVS PDSs
Length:: Specified by the Program_name_length parameter

The name of a field that contains the name of the MVS program to be run. The MVS program name must conform to the naming conventions for members of MVS partitioned data sets (PDSs). The program name is from 1 to 8 characters long; the program name is the member name without any qualifiers. The specified Program_name must be in uppercase.

Argument_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the argument that is to be passed to the program. The argument can be from 0 to 4096 bytes long.

Argument

Supplied parameter

Type:: Character string
Length:: Specified by the Argument_length parameter

The name of a field of length Argument_length that contains the argument that is to be passed to the MVS program.

Exit_routine_address

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

The name of a fullword (doubleword) that contains the address of the user's exit routine. If a user exit is not to be invoked, define Exit_routine_address as the name of a fullword (doubleword) that contains 0. Currently the exit must be RMODE 31, and therefore the address must reside below the 2-gigabyte bar.

Exit_parameter_list_address

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

The name of a fullword (doubleword) that contains the address of the user exit parameter list. The value contained in this fullword (doubleword) is in register 1 when the user exit receives control. If the user exit is not to be invoked or does not require parameters, define Exit_parameter_list_address as the name of a fullword (doubleword) containing 0.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the attach_execmvs service returns the process ID of the created child process, if it is successful. If it is not successful, the service returns -1.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the attach_execmvs service stores the return code. The attach_execmvs 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 attach_execmvs service can return one of the following values in the Return_code parameter:

Return_code	Explanation
E2BIG	The number of bytes used by the new process image's argument list is greater than the system-imposed limit of 4096 bytes. The following reason code can accompany the return code: JRMVSArgTooBig.
EFAULT	The user exit program checked. The following reason code can accompany the return code: JRExitRtnError.
ENAMETOOLONG	The specified MVS program name is too long. The length specified by Program_name_length is longer than 8 bytes.
ENOENT	The specified MVS program was not found in the link pack area (LPA) or in a link list data set (LNKLST); or the program name argument points to an empty string. The following reason code can accompany the return code: JRExecNmLenZero.
ENOMEM	The new process requires more memory than is permitted by the hardware or the operating system. The following reason codes can accompany the return code: JRExecFileTooBig and JRNoSpace.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the attach_execmvs service stores the reason code. The attach_execmvs 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 result of a call to the attach_execmvs service is that a subtask is attached to the calling task to run the specified program in a newly created child process. The newly created subtask becomes the initial thread of the newly created child process.
The new child process has similarities to the process that calls attach_execmvs (called the parent process), except for the following:
- The child process has a unique process ID (PID) that does not match any active process group ID.
- The child has a different parent process ID (namely, the process ID of the process that called attach_execmvs).
- The child has its own copy of the parent's file descriptors. Each file descriptor in the child refers to the same open file as the corresponding file descriptor in the parent.
  Tip: BPX1ATM only propagates file descriptors, not streams. If the target program is MVS-style, there is no consideration for fd0, fd1, and fd2 being used as the standard streams when the child program starts.
- If a z/OS UNIX file has its FCTLCLOFORK or FCTLCLOEXEC flag set on, it is not inherited by the child process. These flags are set with the fcntl service. For more information, see the fcntl service Parameters.
- The child has its own copy of the parent's open directory streams. Each open directory stream in the child can share directory stream positioning with the corresponding directory stream of the parent.
- The process and system utilization times for the child are set to zero.
- Any file locks previously set by the parent are not inherited by the child.
- The child process has no interval timers set. This is similar to the results of a call to the alarm service with Wait_time specified as zero.
- The child has no pending signals.
- The child process does not get a copy of the parent's storage, as it would if it were created via a call to the fork service.
- The child process created by this service is terminated when its parent terminates.
The input passed to the MVS executable program by the service is consistent with the input passed to MVS programs. On input, the MVS program receives a single-entry parameter list pointed to by register 1. The high-order bit of the sole parameter entry is set to 1.
The sole parameter entry is the address of a 2-byte length field followed by an argument string. The length field describes the length of the data that follows it. If a null argument and argument length are specified in the call, the length field specifies 0 bytes on input to the executable program.
The MVS program to be run receives control with the following attributes:
- Problem program state
- TCB key of caller
- AMODE=31(64), taken from the executable
- Primary ASC mode
The specified program can be located in the link pack area (LPA), in a link list data set, job library, step library, or task library. The program search order that is followed is identical to that of the MVS Attach service when the EP parameter is specified.
The user exit receives control with the following attributes:
- Problem program state
- PSW key of caller
- AMODE=31(64)
- Primary ASC mode
The register usage on entry to the user exit in AMODE 31 is:
- R0: Undefined.
- R1: Address of the user exit parameter list as specified by the caller of the exec service.
- R2–R12: Undefined
- R13: Address of a 96-byte work area in the same key as the caller of the exec service.
- R14: The return address from the user exit to the exec service. This address must be preserved by the user exit.
- R15: Address of the user exit.
The register usage on entry to the user exit in AMODE 64 is:
- R0: Undefined.
- R1: 64-bit address of the user exit parameter list as specified by the caller of the exec service.
- R2–R12: Undefined
- R13: 64-bit address of a 96-byte work area in the same key as the caller of the exec service. Bits 0–32 of this address are 0.
- R14: The 64-bit return address from the user exit to the attach_exec service. This address must be preserved by the user exit. Bits 0–32 of this address are 0.
- R15: Information about the caller. Bit 61 is on and bit 62 is off, indicating an AMODE 64 caller. Bit 63 is also off, indicating that the addressing mode should not be changed on return to the caller, and that a BRANCH ON CONDITION (BCR) should be used for the return. The other bits in R15 are not relevant. Because R15 does not contain the address of the exit routine on entry, BRANCH RELATIVE instructions should be used for branching within the user exit.
The TASKLIB, STEPLIB, or JOBLIB DD data set allocations that are active for the calling task at the time of the call to the attach_execmvs service are propagated to the new process image. This causes the program that is invoked to run with exactly the same MVS program search order as its invoker.
To support the creation and propagation of a STEPLIB environment to the new process image, attach_execmvs allows for the specification of a STEPLIB environment variable. The following are the accepted values for the STEPLIB environment variable and the actions taken for each value:
1. STEPLIB=NONE. No Steplib DD is to be created for the new process image.
2. STEPLIB=CURRENT. The TASKLIB, STEPLIB or JOBLIB DD data set allocations that are active for the calling task at the time of the call to the exec service are propagated to the new process image, if they are found to be cataloged. Uncataloged data sets are not propagated to the new process image.
3. STEPLIB=Dsn1:Dsn2:,...DsnN. The specified data sets, Dsn1:Dsn2:...DsnN, are built into a STEPLIB DD in the new process image.
  Note: The actual name of the DD is not STEPLIB, but a system-generated name that has the same effect as a STEPLIB DD. The data sets are concatenated in the order specified. The specified data sets must follow standard MVS data set naming conventions. Data sets found to be in violation of this standard are ignored. If the data sets do follow the standard, but:
  - The caller does not have the proper security access to a data set
  - A data set is uncataloged, or is not in load library format
  then the data set is ignored. Because the data sets in error are ignored, the executable file may run without the proper STEPLIB environment. If a data set is in error due to improper security access, a X'913' abend is generated. The dump for this abend can be suppressed by your installation.
If the STEPLIB environment variable is not specified, the default behavior of the attach_execmvs service is the same as if STEPLIB=CURRENT were specified.

If the program to be invoked is a set-user-ID or set-group-ID file and the user-ID or group-ID of the file is different from that of the current process image, the data sets to be built into the STEPLIB environment for the new process image must be found in the system sanction list for set-user-id and set-group-id programs. Only those data sets that are found in the sanction list are built into the STEPLIB environment for the new process image. For detailed information about the sanction list, see z/OS UNIX System Services Planning. For information about STEPLIB performance considerations, see the section on tuning performance in z/OS UNIX System Services Planning.
If the calling parent task is in a WLM enclave, the child task is joined to the same WLM enclave. This allows WLM to manage the parent and child as one "business unit of work" entity for system accounting and management purposes.
A thread that issues an attach_exec or attach_execmvs may receive an A03 abend if any attached children are still running. To avoid the A03 abend, the thread that issued the attach can use waitpid (BPX1WAT) to determine when the attached process has completed, then call mvsprocclp (BPX1MPC) to allow time for a full MVS subtask termination to occur after the child process has terminated.

Related services

Characteristics and restrictions

The user exit is given control in the newly created child process on the attached task before the invocation of the specified program. This exit can be used by the caller to alter the environment of the child process, similarly to the way in which a program would alter the child's environment after a call to fork, but before the call to execmvs. The user exit should not attempt to use any kernel services from the exit. Signals cannot be delivered while in the user exit, because the attach_execmvs service is still in progress and signal delivery is inhibited.

The setuid, setgid, setegid and seteuid services, if invoked from a process created by this service, affect the calling process and any other processes that exist in the address space.

If exec or execmvs is invoked from a process that was created via the attach_execmvs service, the initial thread task of the process and all of its subtasks are terminated, and a new task is attached to run the specified program. The initial thread task in such a process is the task that was created as a result of the call to the attach_execmvs service. The call to exec or execmvs does not result in the ending of any other tasks in the calling jobstep, nor does it end other processes in the address space. Because of this behavior, only unauthorized, non-privileged programs are supported on the invocation of exec and execmvs.

APF-authorized programs can be invoked from this service if the caller is APF authorized.

Examples

For an example using this callable service, see BPX1ATM (attach_execmvs) example.

MVS-related information

Because the newly created child process runs on a subtask in the same address space as the caller, it has access to the same MVS environment as the caller. This includes the same allocation (DDs) and storage environment. Because of this, programs that run on each of these tasks should be careful not to interfere with other programs running in the same environment. Although the child subtask has access to the same storage as the calling task, it does not share any user subpools with the calling task. For this reason, it cannot free user storage obtained by the calling task.