v_close (BPX1VCL, BPX4VCL)

Function

The v_close service closes a previous open created by v_open. This frees the open token and removes all state information associated with the v_open.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1VCL):	31-bit
AMODE (BPX4VCL):	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 BPX1VCL,(Vnode_token,
              OSS,
              Open_Token,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4VCL with the same parameters.

Parameters

Vnode_token

Supplied parameter

Type:: Token
Length:: 8 bytes

The name of an 8-byte area that contains a vnode token that represents the file that was previously opened by v_open.

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).

Open_Token

Supplied parameter

Type:: Token
Length:: 8 bytes

The name of an 8-byte area that holds the open token returned by a prior call to v_open.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the v_close 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_close service stores the return code. The v_close service returns Return_code only if the Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The v_open service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	Parameter error; for example, the vnode token has been released or one of the token parameters does not contain a valid token value.
ESTALE	The open token is stale or already closed.
EAGAIN	The open token is currently in use by another thread in this process.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

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

The v_close service frees the open token represented by Open_Token and releases all state information associated with it. This includes share reservations and byte range locks associated with the open instance.
Byte range locks are not associated with open tokens that are created with OPEN_NLM_SHR, so v_close will not release these. They must be explicitly released with the v_lockctl service.
In accordance with POSIX rules, when v_close releases byte range locks on a file, all locks owned by the open owner are also released—even those obtained by this open owner using other open tokens. Also, for any lock owner who is not the open owner but who is specified on a v_lockctl call using this open token, all of the locks on the file that are owned by that lock owner will be released.
When v_close releases pending asynchronous byte range locks, the request completion signal will be sent and the lock request will complete with an ECANCELED error.
Note: There is a race condition with the lock request completing normally just before the v_close is issued and, in this case, the lock request will successfully complete but the lock will have been released. This is similar to the case where one thread obtains a byte range lock on a file and another thread closes that file before the first thread has had a chance to use the lock.
If any other thread is currently issuing a call (such as v_rdwr) using the same open token that v_close is attempting to close, the v_close will fail with an EAGAIN error.
The v_rel service implicitly calls v_close for any open token that is associated with the vnode token that is being released.

Related services

Characteristics and restrictions

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