v_export (BPX1VEX, BPX4VEX) — Export a file system

Function

The v_export service controls whether a file system is being exported by the server that makes this call.

Both local and remote access to this file system are controlled by the server while it is being exported.

Requirements

Operation	Presentation
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1VEX):	31-bit
AMODE (BPX4VEX):	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 BPX1VEX,(OSS,
              Function,
              File_system_name,
              VFS_token,
              Vnode_token,
              Mnte_length,
              Mnte,
              Attr_length,
              Attr,
              Vol_Handle,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4VEX with the same parameters.

Parameters

OSS

Supplied and returned parameter

Type:: Structure
Length:: OSS#LENGTH (from the BPXYOSS macro)

The name of an area that contains operating-system-specific parameters. This area is mapped by the BPXYOSS macro (see BPXYOSS — Map operating system specific information).

Function

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the function to perform:

Export the file system. This activates the server's control over the file system.
Unexport the file system. This deactivates the server's control over the file system.

File_system_name

Supplied parameter

Type:: Character string
Length:: 44 bytes

The name of a 44-character field that identifies the file system that is to be exported or unexported. The name must be left-justified and padded with blanks.

This is the name that is specified on the mount of the file system. It is an MVS™ data set name in uppercase letters without surrounding quotation marks.

VFS_token

Returned parameter

Type:: Token
Length:: 8 bytes

The name of an 8-byte area in which the v_export service returns the VFS token of the file system.

Vnode_token

Returned parameter

Type:: Token
Length:: 8 bytes

The name of an 8-byte area in which the v_export service returns a vnode token of the root of the file system.

Mnte_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the area that is to be passed in the Mnte parameter.

The length of this area must be large enough to contain a mount entry header (MnteH) and one mount entry (Mnte). These fields are mapped by the BPXYMNTE macro (see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference).

Mnte

Returned parameter

Type:: Structure
Length:: Specified by the Mnte_length parameter

The name of an area, of length Mnte_length, in which the v_export service returns information about the file system. This area is mapped by the BPXYMNTE macro (see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference).

Attr_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the area that is to be passed in the Attr parameter. To determine the value of Attr_length, use the ATTR structure (see BPXYATTR — Map file attributes for v_ system calls).

Attr

Returned parameter

Type:: Structure
Length:: Specified by the Attr_length parameter

The name of an area, of length Attr_length, in which the v_export service returns the file attribute structure for the root. This area is mapped by the ATTR structure (see BPXYATTR — Map file attributes for v_ system calls).

Vol_Handle

Supplied parameter

Type:: Token
Length:: 16 bytes

The name of a 16-byte area that is to be associated with the exported file system and passed to the exporter exit with each call that is related to this file system.

This parameter is not interpreted by the LFS.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the v_export service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

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

Return_code	Explanation
EINVAL	Parameter error; for example, the file system that is to be exported or unexported is not mounted or is a sysplex client; or one of the supplied areas was too small. The following reason codes can accompany the return code: JrFileSysNotThere, JrBadEntryCode, JrSmallAttr, JrSmallMnte, JrInvalidOSS, JRCantExpClient.
EBUSY	The file system that is to be unexported is not exported by this server.
EIO	The file system is being unmounted (JrQuiescing).
EAGAIN	The file system has been quiesced (JrQuiesced), or is being asynchronously mounted (JrAsynchMount).
EALREADY	The file system that is to be exported is already being exported; or the file system that is to be unexported is not currently exported.
EMFILE	The maximum number of vnode tokens have been created.
ENFILE	An error occurred while storage was being obtained for a vnode token.
EPERM	The operation is not permitted. The caller of the service is not registered as a file exporter.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the v_export service stores the reason code. The v_export service returns a Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

Vnode tokens that are returned by the v_export service are not inherited across a fork callable service.
VFS tokens that are returned by the v_export service are inherited across a fork callable service.
The caller is responsible for freeing the vnode token that is returned by the v_export service, by calling the v_rel() service when it is no longer needed.
The caller must be registered as a server of type file exporter.
Refer to DFS-style file exporters for more information about file exporters.
The v_export service is used to gain access to the file system for the server, and is similar to v_rpn() in this respect.
V_export(), though, also activates the server's control over local access through use of the exporter exit that is specified on v_reg(). V_export() acts against a whole mounted file system, while v_rpn() acts against the files underneath arbitrary directories.
The file system is quiesced before it is exported or unexported, and new requests against the file system are suspended while it is being quiesced. If there is a lot of activity against this file system, the v_export request might take some time to complete, and might cause noticeable pauses for the users.
The mount point pathname is not returned in the Mnte structure that is returned by v_export.
On a call to unexport a file system, the VFS_token, Vnode_token, Mnte, Attr, and Vol_Handle parameters are not significant, though they are syntactically required for the call. The Mnte_length and Attr_length fields can be specified as 0, in this case.
The exporter exit is called during an unexport to notify it about this event.
When a file system that is mounted with read/write access is shared within a sysplex, it can be exported if it is sysplex-unaware, but only from the sysplex server (owner) system. If it is mounted with read-only access, it can be exported from any system. Any attempts to remount a read-only file system that is exported on a non-owner system will fail. If a read-only file system is exported on the owner and then is remounted with read/write access, the remount will succeed and the file system will become sysplex-unaware after the remount. That is, the non-owner system is function-shipped in read/write mode to the owner system, where it is then exported. This process maintains the integrity of the file system. When the file system is remounted in read-only mode, it becomes sysplex-aware again and all systems will be locally mounted. Once a read-write file system has been exported at the file system sysplex server, it cannot be moved within the sysplex until it is unexported. Attempts to v_export a sysplex client file system are rejected with EINVAL/JrCantExpClient, and attempts to chmount (move) an already exported file system are rejected with EINVAL/JRIsExported.

Related services

Characteristics and restrictions

A process must be registered as a file exporter before the v_export service is permitted; see v_reg (BPX1VRG, BPX4VRG) — Register a process as a server.