If you are using zFS and need to determine the file
system owner, see the z/OS Distributed File Service zFS Administration.
You can use the MODIFY command to control
z/OS UNIX System Services and to terminate
a
z/OS UNIX
process or thread. You can also use it to shut down
z/OS UNIX initiators
and to request a SYSMDUMP for a process.
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: - 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.
- 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:
To display process information for a process id of '117440514'
enter:
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:
To shut down the fork() service, enter:
F BPXOINIT,SHUTDOWN=FORKS
BPXIxxxE FORK SERVICE HAS BEEN SHUTDOWN SUCCESSFULLY. ISSUE F
BPXOINIT,RESTART=FORKS TO RESTART FORK SERVICE.
Example 3:
To restart the fork() service, enter:
F BPXOINIT,RESTART=FORKS
Example 4:
Sample outputs of the MODIFY BPXOINIT,FILESYS command:
- F BPXOINIT,FILESYS=DISPLAY,GLOBAL
BPXM027I COMMAND ACCEPTED.
BPXF040I MODIFY BPXOINIT,FILESYS PROCESSING IS COMPLETE.
BPXF242I 2006/10/05 13.30.41 MODIFY BPXOINIT,FILESYS=DISPLAY,GLOBAL
SYSTEM LFS VERSION ---STATUS--------------------- RECOMMENDED ACTION
SY1 1. 9. 0 VERIFIED NONE
SY2 1. 9. 0 VERIFIED NONE
SY3 1. 9. 0 VERIFIED NONE
CDS VERSION= 2 MIN LFS VERSION= 1. 9. 0
DEVICE NUMBER OF LAST MOUNT= 10
MAXIMUM MOUNT ENTRIES= 500 MOUNT ENTRIES IN USE= 9
MAXIMUM AMTRULES= 50 AMTRULES IN USE= 0
MAXSYSTEM= 8
SYSTEM PERFORMING ZFS RECYCLE
(Since 2006/10/05 13.30.36)
SY2
ACTIVE QUEUE
RECYCLING EXCLUSIVE
- F BPXOINIT,FILESYS=DISPLAY,FILESYSTEM=POSIX.SY4.HFS
BPXM027I COMMAND ACCEPTED.
BPXF035I 2000/05/12 11.55.34 MODIFY BPXOINIT,FILESYS=DISPLAY
--------------NAME-------------------------- DEVICE MODE
POSIX.SY4.HFS 23 RDWR
PATH=/SY4
PARM=SYNC(04)
STATUS=ACTIVE LOCAL STATUS=ACTIVE
OWNER=SY1 RECOVERY OWNER=SY1 AUTOMOVE=Y PFSMOVE=Y
TYPENAME=HFS MOUNTPOINT DEVICE= 12
MOUNTPOINT FILESYSTEM=POSIX.SYSPLEX9.HFS1
ENTRY FLAGS=90000000 FLAGS=40000000 LFSFLAGS=08000000
LOCAL FLAGS=40000000 LOCAL LFSFLAGS=2A000000
SY1 BPXF040I MODIFY BPXOINIT,FILESYS PROCESSING IS COMPLETE.
- F BPXOINIT,FILESYS=DISPLAY,FILESYSTEM=POSIX.ZFS.ETC
BPXM027I COMMAND ACCEPTED.
BPXF035I 2000/05/12 11.55.34 MODIFY BPXOINIT,FILESYS=DISPLAY
--------------NAME-------------------------- DEVICE MODE
POSIX.ZFS.ETC 23 RDWR
PATH=/SY1/etc
PARM=SYNC(04)
STATUS=ACTIVE LOCAL STATUS=ACTIVE
OWNER=SY1 RECOVERY OWNER=SY1 AUTOMOVE=Y PFSMOVE=Y
TYPENAME=ZFS MOUNTPOINT DEVICE= 12
MOUNTPOINT FILESYSTEM=POSIX.SYSPLEX9.ZFS1
ENTRY FLAGS=90000000 FLAGS=40000000 LFSFLAGS=08000000
LOCAL FLAGS=40000000 LOCAL LFSFLAGS=2A000000
SY1 BPXF040I MODIFY BPXOINIT,FILESYS PROCESSING IS COMPLETE.
Example 5:
In response to message BPXM056E z/OS UNIX SYSTEM
SERVICES LATCH CONTENTION DETECTED, enter the MODIFY or F BPXOINIT,RECOVER=LATCHES
command to resolve the contention. You will receive one of the followings
in response to the command:
f bpxoinit,recover=latches
BPXM067I UNIX SYSTEM SERVICES LATCH CONTENTION RESOLVED
f bpxoinit,recover=latches
BPXM057E UNIX SYSTEM SERVICES LATCH CONTENTION NOT RESOLVING