mvsprocclp (BPX1MPC, BPX4MPC) — Clean up kernel resources

Function

The mvsprocclp callable service cleans up the z/OS UNIX-related resources for an entire process or on a thread-by-thread basis. After cleaning up resources, the mvsprocclp service terminates the thread or the entire process with the final thread.

Requirements

Parameters

Status_field

Supplied parameter

Type:

Structure

Length:

Fullword

The name of a fullword status field. The status field is a one-word area that is mapped by BPXYWAST, the WAIT status word. The WAST area should be initialized to zero. If the caller wants to set a specific exit status, then either WASTEXITCODE or WASTSIGTERM should be set. If the invocation of this service causes a full process cleanup to occur and the contents of the status field conform to the allowable exit status values, the contents are made available to the parent when the wait service is issued. For the mapping of the status field and a description of the allowable exit status values see BPXYWAST — Map the wait status word.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword to which the mvsprocclp service returns one of the following values:

Value	Explanation
0	Thread-related resources were cleaned up for the calling thread.
1	Process-related resources were cleaned up for the calling process.
-1	The service failed to clean up process resources.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

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

Return_code	Explanation
EMVSERR	The specified terminating status value did not conform to the allowable values. The call failed with a Return_value of -1 and a Reason_Code of JrInvTermStat.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword where the mvsprocclp service stores the reason code. The mvsprocclp 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 mvsprocclp service normally cleans up only the thread-related data for the calling thread. The two following situations, however, cause full process cleanup to occur:
   • If the call is made from the initial thread of the process and no other threads exist in the process.
   • If the call is made from the last thread that is left in the process and that thread is not the initial thread, and the initial thread has not performed any z/OS UNIX system calls.

   In these two cases, both the thread-related and process-related resources are cleaned up and z/OS UNIX process termination is performed. See the _exit service for a description of z/OS UNIX process ending.

2. An important distinction between this service and the _exit service is that this service does not actually cause the user's tasks to end. The _exit service has the added effect of causing a full MVS-like ending, in that all the tasks in the executing process are ended. The mvsprocclp service cleans up only the process-related resources and causes a process termination to occur, leaving the other MVS-related resources in the address space unaffected.
3. The mvsprocclp service does not trigger a core dump when the dump flag is on in the status word.
4. For message queues, each thread is removed from the send and receive waiting chains (the message to be sent is lost). End of memory may require the message queue to be rebuilt.
5. When shared memory is being used, each process is terminated and the shared memory segment attached to the terminating process is detached. If the last attachment is removed and a shmctl RMID had been issued, the segment is removed from the system.
6. If semaphores are being used, each thread is removed from the waiting chain. The adjustment values are associated with the process, not the thread. The adjustments are made to each semaphore set atomically. If an adjustment would cause a semaphore value to overflow a limit (0 or SEM#MAX_VAL), no adjustment is made to that semaphore. Adjustments will continue for the set. No assumptions may be made as to the order in which the semaphore sets will be adjusted.

   When semval changes, the waiting chain is searched and other threads may regain control (as with semop, semctl operations). As adjustments are completed, sem_pid and sem_otime are updated for each semaphore set.

7. Even if full process termination does not occur, mvsprocclp will cause the terminating thread to wait up to 60 seconds for subtask termination. If the caller is the IPT, a reason code will be returned to indicate that a subtask is still attached.
8. By default, when an mvsprocclp call results in a full process cleanup, all processes that are found in the caller's subtask tree are terminated with a sigkill signal.

   If the ThliUndubCallerOnly flag is on in the caller's THLI when the mvsprocclp service is called, mvsprocclp does not attempt to terminate processes in the caller's subtask tree.

   You cannot use the ThliUndubCallerOnly flag to clean up the first process dubbed in the address space while other processes exist in the caller's address space. The mvsprocclp service will fail with return code EMVSERR and reason code JRActiveProcess.

9. WASTEXITCODE is a two-byte field that can be set to any value from 1 to 255. This is considered a user specified value for successful termination.
10. WASTSIGTERM is a two-byte field that can be set to any valid signal number (defined in BPXYSIGH). If the signal specified is SIGKILL (x'09'), then the termination request is treated as an abnormal termination, as if the task was abtermed.

Related services

• _exit (BPX1EXI, BPX4EXI) — End a process and bypass the cleanup
• wait (BPX1WAT, BPX4WAT) — Wait for a child process to end

Characteristics and restrictions

1. The mvsprocclp service is provided for non-C applications that invoke z/OS UNIX services. As a rule-of-thumb, if your program causes the task to be dubbed, issue mvsprocclp when it is complete. If your program is already dubbed when invoked, do not call mvsprocclp when exiting. If you know the termination of your program will cause the task to terminate, you can allow end-of-task processing to perform mvsprocclp for you. To determine if your program is already dubbed, you can test STCBOTCB in mapping macro IHASTCB. If this field is 0, it is not dubbed. You can also use the querydub callable service (querydub (BPX1QDB, BPX4QDB) — Obtain the dub status of the current task).
2. If a thread issued an attach_exec or an attach_execmvs, mvsprocclp can be called to allow up to 60 seconds for a full MVS™ subtask termination to complete. Although mvsprocclp would not trigger the termination of a subtask, a thread that exited the system while subtasks were attached would force those subtasks to terminate with an abend.