Function

The osi_getvnode service is used by a PFS to create a vnode or return a vnode that it created but never used.

Requirements

Parameters

Entry_code

Supplied parameter

Type:

Integer

Length:

Fullword

Entry_code specifies the function that is being requested for the osi_getvnode service.

Entry_code	Explanation
OSI_BUILDVNOD	Get a vnode
OSI_BUILDVNODNL	Get a vnode that is never locked by the LFS.
OSI_RTNVNOD	Return an unused vnode.
OSI_BUILDVNODXL	Get a vnode that is always under an exclusive lock.
OSI_PURGELLA	Purge LLA entries for a vnode.
OSI_INACTASAP	Inactivate a vnode as soon as possible.
OSI_MEMCRITICAL	PFS requests memory relief for its file systems.
OSI_STALEVNODE	Indicate that a file is no longer usable.

Token_structure

Supplied parameter

Type:

TOKSTR

Length:

Specified by TOKSTR.ts_hdr_cblen.

This token_structure is the one that was passed to the vnode or VFS operation from which this call is being made. It represents the parent file or file system of the file for which a vnode is being created. This parameter is 0 for OSI_PURGELLA and OSI_INACTASAP.

attribute_structure

Supplied parameter

Type:

Structure

Length:

Specified by the structure's attr.cbhdr.cblen field.

The file attributes of the file for which this vnode is being created. This structure is mapped by typedef ATTR in the BPXYVFSI header file (see Interface structures for C language servers and clients).

PFS_token

Supplied parameter

Type:

Token

Length:

8

The PFS token for the file for which this vnode is being created.

Vnode_token

Returned parameter for entry code OSI_BUILDVNOD, OSI_BUILDVNODXL, and OSI_BUILDVNODNL; supplied parameter for entry code OSI_RTNVNOD, OSI_PURGELLA, and OSI_INACTASAP.

Type:

Token

Length:

8

The vnode token for the file.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the osi_getvnode service returns the results of the operation, as one of the following:

Return_value

Meaning

-1

The operation was not successful.

0

The operation was successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the osi_getvnode service stores the return code. The osi_getvnode service can return one of the following values in the Return_code parameter only if Return_value is -1. Reason_code further qualifies the Return_code value.

Return_code	Explanation
0	Successful completion
Osi_BadParm	Invalid OSI_structure
Osi_Abend	Abend in osi_getvnode

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the osi_getvnode service stores the reason code. The osi_getvnode service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value.

Usage notes

1. For additional information, see Creating, referring to, and inactivating file vnodes.
2. The PFS should use the OSI_RTNVNOD function to return an unused vnode only when it gets a vnode, but decides it does not need it, before returning the vnode token to the LFS.

   The Token_structure, attribute_structure, and PFS_token parameters are not referenced for OSI_RTNVNOD, and the PFS may pass a zero for each parameter.

3. The address of the osi_getvnode routine is passed to the PFS in the OSIT when the PFS is initialized.
4. OSI_BUILDVNODNL is used when the PFS does not need the vnode serialization provided by the LFS. A vnode that is obtained in this way is locked only for vn_open and vn_close.
5. The PFS may pass a minimum File_Attribute_Structure, for performance reasons. This structure must include:

   at_hdr.cbid

   Set to ATT2 to distinguish this subset ATTR

   at_hdr.cblen

   Set to the correct length

   at_mode

   The file type field, at least

   at_ino

   at_major

   at_minor

   at_genvalue

   The LFS bits, at least

   at_fid

6. No Token_structure is required on an OSI_PURGELLA or OSI_INACTASAP request. This parameter may be 0.
7. The PFS can use OSI_STALEVNODE to tell the LFS that a file is no longer usable. After this call, the LFS will not allow new vnode operations. The PFS must continue to handle any operations already in progress at least well enough to fail the operation until the vnode is inactivated.

   For a sysplex-aware PFS, this call must be made to the LFS on all systems in the sysplex. Any future vn_lookup call for the old file name or vfs_vget call for the old FID should return a new vnode. The PFS must also insure that the target vnode cannot be inactivated while processing the OSI_STALEVNODE request. During the time that it is processing an OSI_STALEVNODE request, the PFS must reject any vn_inact calls for that vnode.

Characteristics and restrictions

1. This routine can be called only for a vnode or VFS operation that returns a vnode token on the interface—for example, vn_lookup.
2. This routine must be used only on the task that made the vnode or VFS call, with the exception of the OSI_INACTASAP requests. OSI_INACTASAP requests can be invoked on a physical file system worker task; no serialization is necessary for these operations.
3. OSI_MEMCRITICAL is not a vnode-related function. Only the Token_Structure is used as input. The PFS should first check the PFS initialization block (PFSI) to see if the OSI_MEMCRITICAL function is supported. If it is, the PFS may use it to request memory relief by requesting that LFS clean up the vnode cache quickly. The PFS will also be called to harden its cached data to disk for each of its mounted file systems, using vfs_sync. To indicate the completion of this LFS memory-critical function, LFS will set the ts_sysd1 field to OSI_MEMCRITICAL for the last vfs_sync operation.