quiesce (BPX1QSE, BPX4QSE) — Quiesce a file system

Function

The quiesce callable service quiesces a file system, making the files in it unavailable for use. After the file system is quiesced, the system can back up the data in it.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1QSE):	31-bit
AMODE (BPX4QSE):	64-bit
ASC mode:	Primary mode
Serialization:	Enabled for interrupts
Locks:	No locks held
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1QSE,(File_system_name,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4QSE with the same parameters.

Parameters

File_system_name

Supplied parameter

Type:: Character string
Character set:: Printable characters
Length:: 44 bytes

The name of a 44-character field that contains the file system name. The name must be left-justified and padded with blanks.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the quiesce service returns one of two values:

0, if the request is successful and the file system was mounted at the time of the request.
-1, if the request is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

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

Return_code	Explanation
EAGAIN	The resource was temporarily unavailable. The following reason code can accompany the return code: JRLockErr.
EBUSY	The file system that was specified is being unmounted or has already been quiesced; or there are no more locks available. The following reason codes can accompany the return code: JROutOfLocks, JRQuiesced, and JRUnmountInProgress.
EINVAL	The file system that was specified cannot be quiesced. The following reason code can accompany the return code: JRInvalidParms.
ENODEV	The file system that was specified is not mounted. The following reason code can accompany the return code: JrFileSysNotThere.
EPERM	The user cannot request this service because it lacks the required permission. The following reason code can accompany the return code: JRUserNotPrivileged.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the quiesce service stores the reason code. The quiesce 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

After a quiesce service request, the file system is unavailable for use until a subsequent unquiesce service request is received.
Users accessing files in a quiesced file system are suspended until an unquiesce request for the file system is processed.

Related services

unquiesce (BPX1UQS, BPX4UQS) — Unquiesce a file system

Characteristics and restrictions

To quiesce a file system, the requester must be a superuser or, at least, have READ access to the SUPERUSER.FILESYS.MOUNT resource found in the UNIXPRIV class. This is the same authority that is required for mounting or unmounting a file system.

When a system joins the sysplex and processes mounts during initialization, any file system mounted in the sysplex that is in a quiesced state will not be mounted on that system at that time. When the quiesced file system is unquiesced, that file system will be mounted on any systems in the sysplex that do not have it already mounted.

Examples

For an example using this callable service, see BPX1QSE (quiesce) example.