NCANCEL

Note on usage

Function: Cancel file transfer requests

User group: FT user and FT administrator

Alias name: FTCANREQ

Functional description

The NCANCEL command can be used to cancel a file transfer request or to abort the file transfer. The FT system deletes from the request queue the file transfer request that corresponds to the specified selection criteria and, if necessary, aborts the associated file transfer.

The following features apply to this command:

• FT requests submitted either in the local or the remote system can be canceled.

• A single command can be used to cancel several FT requests simultaneously.

• The FT requests to be canceled can be selected using different selection criteria.

• The FT user can only cancel file transfer requests, whose "owner" he/she is.

  The owner of an FT request submitted in the local system is the user ID under which the request was issued.
  The owner of an FT request submitted in the remote system is the user ID that is accessed in the local system for the request.

• As FT administrator you can cancel requests from any user.

• As FT administrator you can also fully and unconditionally cancel a selected request and remove it from the request file. “Unconditional” means that, if necessary, the request can be cancelled without any negotiation with the corresponding partner system. In this way, you can clear the request file of requests which are no longer recognized in the partner system or for which there is no longer any connection to the partner system.

  WARNING!

  If not used carefully, this function can result in inconsistencies in the request files of the corresponding partner systems. Under certain circumstances these inconsistencies may cause baffling error messages (SYSTEM ERROR) and “dead requests” in the partner system request files. It should therefore only be used in exceptional circumstances and after a suitable period has elapsed.

After the FT request is canceled, openFT initiates a follow-up processing in the event of failure (FAILURE-PROCESSING) which was previously specified in the NCOPY command. The following points apply:

• If you cancel a request issued in the local system, local FAILURE-PROCESSING will be initiated in any case; FAILURE-PROCESSING will be initiated in the remote system only if the data transfer process had already begun.

• If you cancel a request issued in a partner system, FAILURE-PROCESSING will be initiated both in the local and the remote system, respectively.

Note

• The user who issued the file transfer request in the local system is informed that the request has been aborted, provided that the FAILURE-PROCESSING operand was used in the original transfer request to specify user-generated result information for the local system, or if the default result list is to be supplied.

• The user in the remote system is only informed that the file transfer request has been aborted if file transfer has already been started and if the FAILURE-PROCESSING operand has been used to request user-generated result information for the remote system.

• The file transfer requests aborted with NCANCEL remain in the request queue until both systems involved have informed each other of the abort action.

• Requests for which the file transfer proper has already been completed but where the decision to end the request has not yet been reached with the partner can no longer be canceled.

• If a request is canceled while preprocessing or postprocessing is running in z/OS, openFT starts a separate "Cancel-Job" to terminate the processing job. openFT constructs the cancel job with the TSOJOB job envelope from the openFT parameter library PARM. This job envelope is also required for follow-up processing (see the manual "openFT (z/OS) - Installation and Operation"). This Cancel-Job is assigned a "Z" as the last letter in the job name in order to give it a higher priority than the processing jobs that are currently running.

Format

NCANCEL / FTCANREQ

TRANSFER-ID = *ALL / <integer 1..2147483647> (FORCE-CANCELLATION = *NO / *YES)

,SELECT = *OWN / *PARAMETERS(...)

*PARAMETERS(...)

OWNER-IDENTIFICATION = *OWN / *ALL / <name 1..8>

,INITIATOR = ( *LOC AL, *REMOTE ) / list-poss(2): *LOCAL / *REMOTE

,PARTNER = *ALL / <text 1..200 with-low>

,FILE-NAME = *ALL / <filename 1..59> / <c-string 1..512 with-low>

You cannot issue an NCANCEL command without specifying any operands. In order to cancel or withdraw all your FT requests you may enter, for example:

NCANCEL *ALL

This is intended to prevent you unintentionally canceling all your FT requests by accidentally issuing an NCANCEL command without specifying any operands.

Operands

TRANSFER-ID =

Transfer ID of the FT request to be canceled.

TRANSFER-ID = *ALL
Deletes all FT requests if no further selection criteria are specified with SELECT. FT users can only delete FT requests of their own ID using this entry. FT administrators can delete all current FT requests that access the system.

TRANSFER-ID = <integer 1..2147483647>
Request identification which was communicated to the local system in the FT request confirmation. The associated FORCE-CANCELLATION parameter is available only to the FT administrator. It is used for an unconditional request cancellation.

TRANSFER-ID = <integer 1..2147483647>(FORCE-CANCELLATION = *NO)
NO is the default value. The request is removed from the request file following negotiation with the partner system.

TRANSFER-ID = <integer 1..2147483647>(FORCE-CANCELLATION = *YES)
The request is removed from the request file without negotiation with the partner system. This specification is only possible for an FT administrator who has previously attempted to cancel the request with NCANCEL <transfer-id> (FORCE-CAN=*NO).

SELECT =

Contains selection criteria for FT requests to be canceled. A request is canceled if it satisfies all the specified criteria.

SELECT = *OWN
Cancels all FT requests associated with the own user ID and the specified TRANSFER-ID.

SELECT = *PARAMETERS(...)

OWNER-IDENTIFICATION =

Designates the owner of the FT requests. As an FT user you can omit this parameter, because you can only delete requests of your own ID.

OWNER-IDENTIFICATION = *OWN
Cancels only the FT requests under the user’s own ID.

OWNER-IDENTIFICATION = *ALL
Cancels FT requests under all user IDs. Only the administrator can use this entry.

OWNER-IDENTIFICATION = <name 1..8>
Specifies a particular user ID whose FT requests are to be canceled. As FT user you can only specify your own ID.

INITIATOR =
Initiator of the FT requests to be canceled.

INITIATOR = ( *LOCAL,*REMOTE )
Cancels FT requests in the local system and in remote systems.

INITIATOR = *LOCAL
Cancels FT requests issued in the local system.

INITIATOR = *REMOTE
Cancels FT requests issued in remote systems.

PARTNER =
Cancels FT requests that were to be executed with a specific partner system.

PARTNER = *ALL
The name of the partner system is not used as a selection criterion to determine the FT requests to be canceled.

PARTNER = <text 1..200 with-low>
The FT requests that were to be executed with this partner are to be canceled.
The name must be specified in the same form in which it is output using NSTATUS.

FILE-NAME =
Cancels all FT requests in the local system that access this file or this library element whether as a send file or receive file. The file name or library member name must be specified exactly as it appears in the file transfer request.

FILE-NAME = *ALL

The file name is not used as a selection criterion to determine the FT requests to be canceled.

FILE-NAME = <filename 1..59> / <c-string 1..512 with-low>
Cancels FT requests in the local system that access this file.

If multiple selection criteria are specified in the NCANCEL command, then each one of these must be valid for the requests that are to be canceled. Otherwise the NCANCEL command is acknowledged with the following message:

FTR0504 OPENFT: No requests available for the selection criteria.

Examples

1. An FT user wants to cancel all FT requests which carry his/her own ID. In order to do this, it is sufficient to issue the command only with the operand *ALL:

   NCANCEL *ALL

   If only one job was existent, openFT acknowledges the request with the following message:

   FTR2072 Request 12334456 has been canceled

   If several jobs were existent, all requests are deleted with no prompt for confirmation and cancellation is acknowledged by messages:

   FTR2072 Request 12334558 has been canceled

   FTR2072 Request 12334739 has been canceled

   FTR2072 Request 12339336 has been canceled

2. The FT request with the transfer ID 194578 is to be deleted. If the

   NCANCEL command is to be issued under the same ID as that under which the FT request was also submitted, the following command is sufficient:

   NCANCEL TRANSFER-ID=194578

   The recommended short form of this command is as follows:

   NCANCEL 194578

3. As an FT administrator, you want to cancel the request with the transfer ID 194578; you know that the user ID USER1 is the owner of this FT request. You issue the following command:

   NCANCEL TRANSFER-ID=194578,SELECT=(OWNER=USER1)

   A possible short form of this command is as follows:

   NCAN 194578,(USER1)

   openFT acknowledges the request with the following message:

   FTR2072 OPENFT: Request 194578 has been canceled

4. An FT user wishes to cancel all file transfer requests from remote system VAR001 that access his/her file DATA. This can be achieved with the following command:

   NCANCEL TRANSDER-ID=*ALL,SELECT=(INITIATOR=*REMOTE,PARTNER=VAR001,

   FILE-NAME=DATA)

   The recommended short form of this command is as follows:

   NCANCEL *ALL,SEL=(INIT=*REMOTE,PARTNER=VAR001,FILE=DATA)

5. As an FT administrator, you want to cancel the request with the transfer ID 655423; you do not know who is the owner of this FT request. You issue the following command:

   NCANCEL TRANSFER-ID=655423,SELECT=(OWNER=*ALL)

   A possible short form of this command is as follows:

   NCAN 655423,(*ALL)

6. As an FT administrator, you want to cancel all FT requests involving your FT system. You issue the following command:

   NCANCEL TRANSFER-ID=*ALL,SELECT=(OWNER=*ALL)

   A possible short form of this command is as follows:

   NCAN *ALL,(*ALL)