execmvs (BPX1EXM, BPX4EXM) — Run an MVS program

Function

The execmvs service runs an MVS™ executable program that is in the link pack area (LPA) or LNKLST concatenation. If it is invoked from an address space that contains multiple processes, the program can come from a STEPLIB.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1EXM):	31-bit
AMODE (BPX4EXM):	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 BPX1EXM,(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 BPX4EXM 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 of the name of the MVS program.

Program_name

Supplied parameter

Type:: Character string
Character set:: No restriction
Length:: Specified by the Program_name_length parameter

The name of a field that contains the name of the MVS program that is 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 except for unauthorized callers calling authorized programs. For unauthorized callers calling authorized programs, the argument can be from 0 to 100 bytes long. If you want to allow an unauthorized caller to pass an argument greater than 100 bytes to a program, a BPX.EXECMVSAPF.program_name FACILITY class profile needs to be defined for that program.

Argument

Supplied parameter

Type:: Integer
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.

The data that is contained in the Argument parameter should not include pointers to private storage. The execmvs service frees all private storage while cleaning up the previous job step.

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.

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 that is 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) that contains 0. Currently the exit must be RMODE 31, and therefore the address must reside below the 2-gigabyte bar.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the execmvs service returns -1 if it is not successful. If it is successful, the execmvs service does not return.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the execmvs service stores the return code. The execmvs 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 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 that is specified by Program_name_length is longer than 8 bytes.
ENOENT	The specified MVS program was not found in the link pack area or in a link list data set, LNKLST; or the program name argument points to an empty string. STEPLIB needs to be included in a multiprocess environment. The following reason code can accompany the return code: JRExecNmLenZero.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the execmvs service stores the reason code. The 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 following characteristics of the calling process are changed when the new executable is given control by the execmvs service:
- The prior process image is replaced with a new process image for the executable program that is to be run.
- All open files that are marked close-on-exec and all open directory streams are closed.
- All signals that have sigaction settings are reset to their default actions.
The input that is passed to the MVS executable file by the service is consistent with the input that is passed to MVS programs. On input, the MVS program receives a single-entry parameter list that is 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 file.
The call can invoke both unauthorized and authorized MVS programs:
- Unauthorized programs receive control in problem program state, with PSW key 8.
- Authorized programs receive control in problem program state, with PSW key 8 and APF authorization.
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 execmvs service.
- R2–R12: Undefined
- R13: Address of a 96-byte work area in the same key as the caller of the execmvs service.
- R14: The return address from the user exit to the execmvs 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 execmvs service.
- R2–R12: Undefined
- R13: Address of a 96-byte work area in the same key as the caller of the execmvs service.
- R14: The return address from the user exit to the execmvs service. This address must be preserved by the user exit.
- R15: 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.
When the exec or execmvs service is called in any environment except single task, single RB, and no linkage stack, z/OS UNIX issues a quiesce_force to terminate all of its subtasks. The subtasks receive a 422 abend with a reason code of 000001A0.
The TASKLIB, STEPLIB, or JOBLIB DD data set allocations that are active for the calling task at the time of the call to the execmvs service are propagated to the new process image if the data sets that they represent are found to be cataloged. Uncataloged data sets are not propagated to the new process image. This causes the program that is invoked to run with the same MVS program search order as its invoker.
To support the creation and propagation of a STEPLIB environment to the new process image, the execmvs service 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 that is specified. The specified data sets must follow standard MVS data set naming conventions. Data sets that are found to be in violation of this standard are ignored. If the data sets follow the standard, but:
  - The caller does not have the proper security access to a data set, or
  - A data set is uncataloged or not in load library format
  the data set is ignored. Because the data sets that are in error are ignored, the executable file may run without the proper STEPLIB environment. If a data set is in error because of 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 execmvs service is the same as if STEPLIB=CURRENT were specified.

If the program that is 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 that are 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 Using sanction lists in z/OS UNIX System Services Planning. For information about STEPLIB performance considerations, see Tuning performance in z/OS UNIX System Services Planning.
If the calling task is in a WLM enclave, the new process image task is joined to the same WLM enclave. This allows WLM to manage the old and new process images as one "business unit of work" entity for system accounting and management purposes.
If an unauthorized caller attempts to pass an argument greater than 100 bytes to an authorized program, the caller will abend with ABENDEC6 reason code 0B26C048 pr ABEND306 reason code 44. If the caller needs to be allowed to execute the program with an argument greater than 100 bytes, then a BPX.EXECMVSAPF.program_name profile should be defined or have the program owner rebind the program specifying the LONGPARM option.

Related services

exec (BPX1EXC, BPX4EXC) — Run a program

Characteristics and restrictions

When the execmvs service is called from any process except one that was created via the attach_exec or attach_execmvs service, the program must be located either in the link pack area (LPA) or in a link list data set (LNKLST).
When the execmvs service is called from a process that was created via the attach_exec or attach_execmvs service, the specified program can be located in the link pack area, 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.
If the execmvs service is invoked from a process that contains one task, one request block (RB), and no linkage stack entries, the process is ended by an SVC 3 instruction. This action results in a normal return to the operating system. Almost all forked processes run in this manner. In all other cases, the system ends all tasks (threads) in the caller with a nonretryable 422 abend, reason code 000001A0.
The user exit cannot invoke any z/OS UNIX services. If it attempts to invoke a z/OS UNIX service, the service fails or the caller is abended, depending on the service that is attempted. Signals cannot be delivered to the caller of the exec service while the user exit is in control.
The program that is invoked by the execmvs service must be enabled to run in 31-bit addressing mode (AMODE=31).

Examples

For an example using this callable service, see BPX1EXM (execmvs) example.

MVS-related information

Because the service must create a new process image for the specified program to run within, the prior process image is completely cleaned up. In MVS terms, the system ends a step within a job and then inserts a new step for the specified program to run in. Any MVS task-related resources that existed in the old job step are cleaned up. The new job step that is created has no allocations associated with it, with the exception of the MVS data sets that may be built into the STEPLIB environment for the new process image. When the newly created job step ends, the flow of the job continues, as it normally does, to the next sequential step in the job, depending on the completion code of the ending step.