Function

The vn_recovery operation permits a PFS to recover resources when an abnormal end occurs while a request to that PFS is active.

Environment on entry and exit

See Environment for PFS operations.

Parameters

Token_structure

Supplied parameter

Type:

TOKSTR

Length:

Specified by TOKSTR.ts_hdr.cblen.

The Token_structure represents the file (vnode) that is being operated on. It contains the PFS's initialization token, mount token, and the file token. Refer to LFS/PFS control block structure for a discussion of this structure, and to the TOKSTR typedef in BPXYPFSI in Interface structures for C language servers and clients for its mapping.

OSI_structure

Supplied and returned parameter

Type:

OSI

Length:

Specified by OSI.osi_hdr.cblen.

The OSI_structure contains information that is used by the OSI operations that may be called by the PFS. See OSI services for more information.

It also contains MVS-specific information that needs to be passed to the PFS, including SMF accounting fields, a work area, a recovery area, and an optional pointer to an output ATTR structure. For more details on the OSI structure, see The OSI structure.

This area is mapped by the OSI typedef in BPXYPFSI in Interface structures for C language servers and clients.

Audit_structure

Supplied parameter

Type:

CRED

Length:

Specified by CRED.cred_hdr.cblen.

The Audit_structure contains information that is used by the security product for access checks and auditing. It is passed to most SAF routines that are invoked by the PFS.

Refer to Security responsibilities and considerations for a discussion of security processing, and to the CRED typedef in BPXYPFSI in Interface structures for C language servers and clients for the mapping of this structure.

Recovery_area

Supplied parameter

Type:

String

Length:

8 bytes

A copy of the Recovery_area that was filled in by the PFS during the operation that was interrupted. This area is mapped by OSIRTOKEN (see Interface structures for C language servers and clients).

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the vn_recovery operation returns control information to direct the outcome of the recovery processing, as follows:

Return_value

Meaning

VNR_NODUMP

Suppress the system dump that is normally taken.

VNR_RETSUCCESS

Report success to the user. In this case, the value in the Return_Code parameter is passed back to the user as the return value of the original function.

VNR_RETERRNO

Report failure to the user. In this case, the values in the Return_Code and Reason_Code parameters are passed back to the user as the return and reason codes for the original function. The return value that is passed back for the original function is -1.

Dump suppression may be requested with either success or failure reports; that is, with values of VNR_NODUMP+VNR_RETSUCCESS or VNR_NODUMP+VNR_RETERRNO, respectively.

If a Return_value is not returned by the PFS, a system dump is attempted and the original function fails with generic return and reason codes. The Return_values listed in this topic are defined in BPXYPFSI (see Interface structures for C language servers and clients.)

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the vn_recovery operation stores the return code. The vn_recovery operation returns Return_code with the Return_value that was returned, as explained in this topic.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the vn_recovery operation stores the reason code. The vn_recovery operation returns Reason_code with the Return_value that was returned, as explained in this topic.

Implementation notes

Overview of vn_recovery processing

Recovery considerations provides an overview of recovery processing, and discusses the flow for vn_recovery in particular.

When an active request to the PFS is interrupted by an abnormal end, the PFS may have resources, such as storage and locks, that are left in a state that will cause problems for other users. This operation is defined to give the PFS a chance to clean up these resources if an abnormal end should occur.

This operation is designed for a PFS that does not have its own ESTAE or FRR protection. When a PFS has its own recovery, it normally handle abnormal ends before returning or percolating back to the LFS.

Specific processing notes

• An 8-byte Recovery_area is passed on every VFS and vnode operation, through the osi_rtokptr pointer in the OSI_structure, in which the PFS can record its resources or store a pointer to a recovery block. Any information that is stored in this area by the PFS during an operation is passed back to the PFS via the Recovery_area parameter of vn_recovery if the operation is interrupted by an abnormal end.

  The SDWA address is also passed to the PFS, for diagnostic purposes. This address is stored 16 bytes after the 8-byte Recovery_area. (Refer to the osirtokenx structure in Interface structures for C language servers and clients.) The PFS must test this address for zero before using it, because the system is not always able to obtain an SDWA during recovery.

• The OSI work area and the preinitialized C Environment Stack (if used) are still addressable, and left as they were at the time of the abnormal end. These areas can be used to hold a recovery block whose address is placed in the Recovery_area. Vn_recovery is invoked with its own separate areas.
• The PFS is not called if the Recovery_area that is pointed to by osi_rtokptr is zero at the time of the abnormal end.
• The PFS is not called if the file system has been unmounted. A file system can be unmounted between the original vnode operation and vn_recovery in the following scenario:
  1. An operation goes into a signal enabled wait.
  2. The file system is unmounted with the IMMEDIATE operand.
  3. The waiting user is canceled.

  The PFS is expected to have cleaned up all its file-system-related resources during vfs_umount.

• This Recovery_area is the same one that is used by the vfs_recovery operation for user EOM recovery. The difference between these operations is that if the LFS's ESTAE runs, it calls the PFS with vn_recovery from the same home address space and task that the original operation was invoked from. If the LFS's ESTAE is bypassed by MVS™, the LFS's user address space EOM resource manager calls the PFS with vfs_recovery. This call is from a different task and home address space than the original call, and the original home address space no longer exists.
• Vfs_recovery is not called after vn_recovery has been called, unless vn_recovery is interrupted by a sudden end-of-memory condition for the user's address space. An example of this would be a program check in the PFS that was followed almost immediately by an operator force of the user. Another example would be if the PFS's vn_recovery routine were to get into a deadlock or extended wait, and the operator had to force the user off.
• Special care must be taken with vn_recovery, because the Token_structure may not always contain a file-level token. This is because vn_recovery is used for abend recovery of all the VFS and vnode operations. If a VFS operation is interrupted, the Token_structure on the vn_recovery call does not contain a file token; and if vfs_pfsctl is interrupted, the Token_structure contains only the PFS's initialization token.
• No recovery of any type is supplied for the vn_recovery operation itself. The operation is invoked with Osi_rtokptr pointing to a new recovery area, but this is only to allow the PFS to use common entry code that may depend on having a valid address in this field.

  See the OSI and osirtoken structures in Interface structures for C language servers and clients.

• The state of any file system and file objects that may have been involved with the interrupted operation is the same as at the time of the interruption.

Serialization provided by the LFS

The vn_recovery operation is invoked with the same serialization that was held at the time of the abnormal end.

Security calls to be made by the PFS

None.