Function

The vn_cancel operation cancels the wait for an asynchronous operation to complete, or cancels the remaining portion of an operation after the I/O completion has been scheduled.

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.

VnCan_Flags

Supplied parameter

Type:

String

Length:

4 bytes

Control flags for this cancelation. Refer to the vncanflags structure in BPXYPFSI.

• vncanforce: This flag specifies whether a normal or forced cancelation is being requested:
  • 0– Normal Cancel:

    Only the wait for completion is being canceled; otherwise the operation is to proceed normally. If the PFS finds the request on a waiting queue, it is to be removed from the queue and completed with a return code of ECANCELED. That is, osi_sched should be called, and the normal flow for a failed request should be followed. Note that if it is the PFS's custom to handle asynchronous failures in Part 2, it may call osi_sched with success and return ECANCELED from the Part 2 call.

    If the PFS does not find the request on a waiting queue, it should take no action whatsoever. The request is completing, or has completed, normally and should not be interrupted.

  • 1– Forced Cancel and Cleanup:

    Part 2 is not run for this operation, usually because the user's process is terminating. The PFS should remove the request from any waiting queues, and discard all buffers and other resources that were allocated to this request. Regardless of whether the request was found on the waiting queues, the PFS must clean up the request if it is still active.

PFS_AsyTok

Supplied parameter

Type:

String

Length:

8 bytes

A copy of the PFS's Asynchronous I/O Request Token, which identifies the request that is being canceled.

This is the token that was originally passed by the PFS to the LFS via a call to osi_upda during Part 1 of the asynchronous operation. This is also the same token that is passed in osi_asytok on Part 2 of an asynchronous operation to identify the request to the PFS.

LFS_AsyTok

Supplied parameter

Type:

String

Length:

8 bytes

A copy of the LFS's Asynchronous I/O Request Token, which was originally passed to the PFS in the osi_asytok field on Part 1 of the request that is being canceled.

This token has presumably been saved by the PFS in its request structure during Part 1, since it is needed for osi_sched, and can be used to validate the PFS request structure. The PFS's original request structure must be validated on vn_cancel because the original operation might have finished by the time the vn_cancel reaches the PFS, and therefore its request structure might have been already freed or reused for another operation. Once cancel is started for a request, the LFS does not reuse its token until after the cancel has completed.

The PFS may also, of course, perform this validation on its own and ignore the LFS_AsyTok if it is so designed. A request structure could be validated, for instance, with a structure sequence number that is included within the PFS_AsyTok, or by running a chain of active request blocks.

For more information see the processing notes in this topic.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the vn_cancel operation returns the results of the operation, as one of the following:

Return_value

Meaning

0

The request was found.

-1

The request was not found.

Generally, vn_cancel is not called after osi_sched has been called, but there is a race condition between these two acts and so this Return_value is really not very definitive. For more information see the processing notes.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the vn_cancel operation stores the return code. The vn_cancel operation returns Return_code only if Return_value is -1. For a complete list of supported return code values, see z/OS UNIX System Services Messages and Codes.

The vn_cancel operation should support at least the following error value:

Return_code	Explanation
EINVAL	The PFS_AsyTok is not valid.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

A fullword in which the vn_cancel operation stores the reason code. The vn_cancel operation returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. These reason codes are documented by the PFS.

Implementation notes

Overview of vn_cancel processing

Asynchronous I/O processing provides an overview of asynchronous I/O, and discusses the flows that are related to vn_cancel.

Specific processing notes

• Vn_cancel is for one specific request only.
• Only requests that originally had OsiAsy1=ON are potentially cancelable.
• The normal cancel only "pushes through" the original request, and does not attempt to abort it if it is not blocked.
• Vn_cancel is not an asynchronous operation in the sense of the OsiAsy1 and OsiAsy2 bits. It is also not normally a blocking operation. If the original request is found on a waiting queue it may be removed, and osi_sched() called, on another thread while vn_cancel returns to the LFS.
• Vn_cancel must contend with situations in which a thread may be calling osi_sched, or an SRB may be running Part 2 of the original request. This can be a problem in either case, if the PFS is about to free up the structures that are related to the original request and the PFS_AsyTok. Hopefully, the original request structure can be validated or not used directly, in order to avoid introducing additional serialization points into the main line path just to deal with a potential cancel. For instance, for a normal cancel, only requests that are found on a waiting chain need be referenced directly, and for cancel force some cleanup may be able to be deferred to vn_close.

  Technically, though, because of fork() and inherited descriptors, vn_cancel(Force) might not soon be followed by vn_close. However, it would be rather rare for an application in this position to carry on. The results of the application would be unpredictable because of timing; and at a minimum it would have to expect data loss, since the termination could just as easily have occurred on entry to its I/O Completion exit.

  Vn_cancel(Force) is a result of process termination; therefore, any requests that were still in the PFS have gone through recovery and generally have been handled, as they would be for any abnormal end situation.

  • Part 1 requests run on the user's TCB or SRB, and these are abnormally ended before vn_cancel is issued.
  • For process termination in general, new SRBs are not permitted to start Part 2, but old SRBs are allowed to finish. Osi_wait(), though, returns as if interrupted with a signal, in an attempt to keep these SRBs from blocking. If the user address space goes to memterm, nothing is able to run, so Part 2 can be abnormally ended for that reason. If the PFS issues its own MVS™ suspend during Part 2, it can also be abnormally ended by the system.

Serialization provided by the LFS

The vn_cancel operation is invoked with an exclusive vnode latch.

Additional serialization is provided even when the PFS is not using vnode latching.

1. The vn_cancel operation is not invoked while the request it is canceling is still in the PFS during Part 1 of the operation.
2. Vn_close is not invoked while vn_cancel is in progress.
3. If a user process terminates before osi_upda is called, vn_cancel is not called, since the LFS does not have the PFS's token to pass.
4. The LFS serializes vn_cancel with the potentially simultaneously occurring end of Part 2 on the SRB, so the PFS does not have to in any sense "wait" within vn_cancel for Part 2.

Security calls to be made by the PFS

None.