Controlling z/OS UNIX System Services (z/OS UNIX)

If you are using zFS and need to determine the file system owner, see the z/OS File System Administration.

 
F BPXOINIT,{APPL=appl_data}
           {DUMP=pid}
           {FILESYS={DISPLAY[,FILESYSTEM=filesystemname]}[,OVERRIDE]}
                             |,ALL
                             |,EXCEPTION
                             |,GLOBAL
                    {DUMP                               }
                    {FIX                                }
                    {REINIT                             }
                    {RESYNC                             }
                    {UNMOUNT,FILESYSTEM=filesystemname  }
                    {UNMOUNTALL                         }
           {FORCE=pid[.tid]}
           {RESTART=FORKS}
           {RECOVER=LATCHES}
           {SHUTDOWN={FILEOWNER | FILESYS | FORKINIT | FORKS}}
           {SUPERKILL=pid}
           {TERM=pid[.tid]}
 

The parameters are:

BPXOINIT

The name of the job.

APPL=appl_data

Allows information to pass straight through to the application. appl_data is a string that is passed back to the invoker in whatever format the application expects it.

Note: BPXOINIT does not accept any APPL= parm values. You will receive the error message BPXM029I APPL= KEYWORD WAS IGNORED BY BPXOINIT.

DUMP=pid

Requests a SYSMDUMP. A SIGDUMP signal is sent to the specified process. pid is the decimal form of the process id to be terminated.

FILESYS=

Indicates that a file system diagnostic or recovery operation is to be performed.

This function is applicable only to a sysplex environment where shared file system has been enabled by specifying SYSPLEX(YES) in the BPXPRMxx parmlib member named during system initialization. The command is intended to help diagnose and correct certain shared file system problems or errors that impact one or more systems in a sysplex environment.

Use this command with caution with an exception of the DISPLAY option, and only under the direction of an IBM® service representative.

To obtain the best results, issue this command at the system with the highest shared file system software service level. To determine which system is executing with the highest shared file system software service level, issue the command

F BPXOINIT,FILESYS=DISPLAY,GLOBAL

and select the system with the highest “LFS Version” value.

Specify one of the following functions:

DISPLAY or D

Display the type BPXMCDS couple data set information relating to the shared file system file system. D is an alias of DISPLAY.

Specify one of the following display options:

ALL

Displays all file systems in the shared file system hierarchy.

EXCEPTION

Displays all file systems that are in an exception state. A file system is in an exception state if one of the following criteria is met:

• State = Mount in progress
• State = Unmount in progress
• State = Quiesce in progress
• State = Quiesced
• State = Unowned
• State = In recovery
• State = Unusable
• The file system state in the couple data set representation is inconsistent with the local file system.

FILESYSTEM=filesystemname

Displays information for the specified file system.

GLOBAL

Displays the current sysplex state, consisting of the following items:

• The active systems in the sysplex (system name, logical file system (LFS) version, verification status, recommended recovery action).
• The type BPXMCDS couple data set version number.
• The minimum LFS version required to enter the BPXGRP sysplex group.
• The device number of the last mounted file system.
• The maximum and in-use mounts.
• The maximum and in-use AMTRULES.
• The active "serialization categories," which systems are associated with each category, and the time that each "serialization category" was first started. The following serialization categories are defined:
  • SYSTEMS PERFORMING INITIALIZATION
  • SYSTEMS PERFORMING MOVE
  • SYSTEMS PERFORMING QUIESCE
  • SYSTEMS PERFORMING UNMOUNT
  • SYSTEMS PERFORMING MOUNT RESYNC
  • SYSTEMS PERFORMING LOCAL FILE SYSTEM RECOVERY
  • SYSTEMS PERFORMING FILE SYSTEM TAKEOVER RECOVERY
  • SYSTEMS RECOVERING UNOWNED FILE SYSTEMS
  • SYSTEMS PERFORMING REPAIR UNMOUNT
  • The system settings for MAXUSERMOUNTSYS and MAXUSERMOUNTUSER
  • The highwater marks for MAXUSERMOUNTSYS and MAXUSERMOUNTUSER

GLOBAL is the default display option.

DUMP

Initiate an SVC dump to capture all of the file system sub-records in the active type BPXMCDS couple data set.

FIX

Perform automatic file system and couple data set diagnosis and repair. As a part of the file system analysis, the system performs an analysis of possible file system latch contention on each system in the sysplex. An operator message identifies any possible problems. The system also analyzes file system serialization data that is maintained in the couple data set, and corrects it if an error is detected. It reports the status of the analysis in an operator message.

Note that the system initiates a dump of critical file system resources as a part of the FIX function. The dump is captured prior to the diagnosis and repair. If, however, a dump was captured due to a FIX or DUMP function that was initiated within the previous 15 minutes, the dump is suppressed.

Perform FIX prior to the UNMOUNTALL and REINIT functions.

REINIT

Re-initialize the file system hierarchy on all systems in the Z/OS Unix sharing group based on the ROOT and MOUNT statements in the BPXPRMxx parmlib member used by each system during its initialization. (Any changes to the BPXPRMxx parmlib member that are made after the system's initialization are not included in the REINIT processing. The system uses a cached version of the file system parmlib statements that is maintained in kernel storage. It does not re-process the parmlib member.)

Note that the system where the MODIFY command is issued will become the z/OS Unix file system owner to those file systems common to all systems in the sysplex (such as the ROOT file system) unless the SYSNAME() parameter is specified on the parmlib MOUNT statement.

The intended use of this function is to re-initialize the file system hierarchy after an UNMOUNTALL has been performed. However, you can issue REINIT at any time; those file systems that are already mounted will not be affected when REINIT processes the cached parmlib mount statements.

Note: If any unmount processing is occurring when the REINIT is issued, some file systems might not be mounted when REINIT completes; the REINIT command should be issued again.

REINIT is not applicable to MKDIR support in the BPXPRMxx parmlib member. The directory mountpoints are not available and thus cause successive mounts to fail.

Note: The REINIT is not applicable to the ALTROOT parmlib statement. To re-enable the ALTROOT, you must explicitly process the ALTROOT statement using the SETOMVS system command.

RESYNC

Perform a file system hierarchy check on all systems. If a system has not mounted a file system that is active in the shared file system hierarchy, it is mounted locally and thus made available to local applications.

UNMOUNT

Unmount the file system specified by the filesystem= parameter. The file system cannot have any active mount points for other file systems. You must unmount those file systems first.

UNMOUNTALL

Unmount all file systems in the sysplex file system hierarchy, including the root file system. When processing is complete, mount SYSROOT on all systems.

Always issue the FIX function before performing the UNMOUNTALL function.

OVERRIDE

Normally only one MODIFY command for a FILESYS= function can be active on each system. Additionally, only one instance of the MODIFY command in the sysplex can be active for the FIX, UNMOUNT, UNMOUNTALL, and REINIT functions. If you specify the OVERRIDE parameter, the system accepts multiple invocations of this command on each system for the DISPLAY, DUMP, and RESYNC functions. Note, however, that the second invocation may be delayed.

The primary intent of the OVERRIDE parameter is to allow issuance of the DISPLAY functions while there is still a MODIFY in progress and the MODIFY appears to be delayed.

FORCE=

Indicates that the signal interface routine cannot receive control before the thread is terminated.

pid.tid

pid is the decimal form of the process id to be terminated. tid is the hexadecimal form of the thread id to be terminated.

RESTART=FORKS

Enables the system to resume normal processing. Suspended dub requests are resumed.

RECOVER=LATCHES

This command ends user tasks that are holding latches for an excessive amount of time. You can enter this command manually or provide an automation script allowing the system to automatically respond to message BPXM056E to aid in resolution of excessive latch contention. The command is primarily intended as an aid in resolving latch hangs that are caused by user task usage of z/OS UNIX System Services. The command can also be used to terminate a system task that holds latches, if the system task is not critical. However, it might not be able to resolve latch hangs caused by critical internal system tasks in the OMVS kernel address space, if the owning system task is in critical system code that cannot be interrupted.

Note:

1. Only use this command if message BPXM056E is outstanding. The command causes one of the following:
   • If the contention can be resolved, the system DOMs the BPXM056E message. After the contention is resolved, the system issues message BPXM067I to indicate that condition.
   • If the contention cannot be resolved, the system issues message BPXM057E to indicate that condition.
   See the following examples for the message output under different conditions.
2. MVS™ isolates the abnormal termination to individual tasks, but this command can result in the termination of an entire process. It is important to note that the abnormal termination will be caused by a non-retryable 422-1A5 abend that will cause the generation of a system dump, because of the likelihood of an internal system problem. Additionally, if more than one latch is in contention, multiple tasks might be abended and result in requests for multiple dumps.

SHUTDOWN=FILEOWNER

Unmounts the z/OS UNIX System Services file systems. Also prevents the system from becoming a filesystem owner through a move or recovery operation until z/OS® UNIX System Services is recycled.

SHUTDOWN=FILESYS

Unmounts the z/OS UNIX System Services file systems.

SHUTDOWN=FORKINIT

Shuts down the z/OS UNIX initiators. Normally, these initiators shut themselves down in 30 minutes. Attempts to purge JES2 (command= P JES2) cannot complete until z/OS UNIX initiators have shut down.

SHUTDOWN=FORKS

Requests a shutdown of the fork() service by preventing future forks and non-local spawns. The kernel cannot obtain additional WLM fork initiators for fork and spawn. It attempts to terminate all WLM fork initiator address spaces that are running processes created by fork or non-local spawn. All other services remain up, but any new dub requests are suspended until the fork() service is restarted.

SUPERKILL=pid

Indicates that a terminating signal is sent to the target process.

Guideline: SUPERKILL=pid ends the entire process and any subprocesses within the address space. Because SUPERKILL=pid is a stronger form of the TERM= and FORCE= parameters, only use this command if you are not able to end the process using F BPXOINIT TERM= and FORCE= commands.

pid

pid is the decimal form of the process ID to be ended.

TERM=

Indicates that the signal interface routine can receive control before the thread is terminated.

pid.tid

pid is the decimal form of the process id to be terminated. tid is the hexadecimal form of the thread id to be terminated.

Example 1:

DISPLAY OMVS,pid=117440514

BPXO070I 14.16.58 DISPLAY OMVS 177
OMVS     000E ACTIVE
USER     JOBNAME  ASID        PID       PPID STATE   START     CT_SECS
MEGA     TC1      0021  117440514  117440515 HKI   14.16.14       .170
  LATCHWAITPID=         0 CMD=ACEECACH
 THREAD_ID        TCB@     PRI_JOB  USERNAME   ACC_TIME SC  STATE
 0496146000000000 009E0438 OMVS                    .050 PTJ  KU
 04961D0800000001 009D5E88 OMVS     WELLIE1        .002 SLP JSN
 049625B000000002 009D8798 OMVS     WELLIE1        .003 SLP JSN
 04962E5800000003 009D5090 OMVS     WELLIE1        .012 SLP JSN
 0496370000000004 009D5228 OMVS     WELLIE1        .011 SLP JSN
 04963FA800000005 009D5A88 OMVS     WELLIE1        .010 SLP JSN
 0496485000000006 009D8048 OMVS     WELLIE1        .011 SLP JSN
 049650F800000007 009D81E0 OMVS     WELLIE1        .011 SLP JSN
 049659A000000008 009D8378 OMVS     WELLIE1        .011 SLP JSN
 0496624800000009 009D8510 OMVS     WELLIE1        .011 SLP JSN
 04966AF00000000A 009D8930 OMVS     WELLIE1        .030 SLP JSN

 f bpxoinit,force=117440514.04962E5800000003
 BPXM027I COMMAND ACCEPTED.

f bpxoinit,term=117440514.0496624800000009
BPXM027I COMMAND ACCEPTED.

Example 2:

F BPXOINIT,SHUTDOWN=FORKS
BPXIxxxE FORK SERVICE HAS BEEN SHUTDOWN SUCCESSFULLY. ISSUE F
BPXOINIT,RESTART=FORKS TO RESTART FORK SERVICE.

Example 3:

F BPXOINIT,RESTART=FORKS

Example 4:

Example 5: