CANCEL-FILE-TRANSFER

Note on usage

Function: Cancel file transfer requests

User group: FT user and FT administrator

Alias names: CNFT / NCANCEL / FTCANREQ

Functional description

The CANCEL-FILE-TRANSFER 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.

When a request is canceled, it is only deleted completely from the request file after it has been deleted from the request file in the remote system.

Format

CANCEL-FILE-TRANSFER / CNFT / 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..54> / <c-string 1..512 with-low> /

*LIBRARY-ELEMENT(...) / *POSIX(NAME = <posix-pathname 1..510>) /

*PUBSET(PUBSET = <cat-id 1..4>)

*LIBRARY-ELEMENT(...)

LIBRARY = *ALL / <filename 1..54>

,ELEMENT = *ALL / <filename 1..64 without-gen-vers>(...) /

<composed-name 1..64 with-under>(...)

<filename>(...) / <composed-name>(...)

VERSION = *ALL / <text 1..24>

,TYPE = *ALL / <name 1..8>

,MONJV = *NONE / <filename 1..54 without-gen-vers>

,JV-PASSWORD = *NONE / <c-string 1..4> / <x-string 1..8> /

<integer -2147483648..2147483647> / *SECRET

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 CANCEL-FILE-TRANSFER <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. You can specify either the name of the partner system from the partner list or the address of the partner system, see section “Specifying partner addresses”.

FILE-NAME =
Cancels all FT requests in the local system that access this file, this pubset 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..54> / <c-string 1..512 with-low> /
*POSIX(NAME = <posix-pathname 1..510>)
Cancels FT requests in the local system that access this file.

FILE-NAME = *PUBSET(PUBSET = <cat-id 1..4>)
Deletes all FT requests that have locked files on the specified pubset. Only the FT administrator can use this specification.

FILE-NAME = *LIBRARY-ELEMENT(...)
Cancels FT requests that access library members in the local system.

LIBRARY =
Selects the library concerned.

LIBRARY = *ALL
The library name is not used as a selection criterion to determine the FT requests to be canceled.

LIBRARY = <filename 1..54>
FT requests that access this library are to be canceled.

ELEMENT =
Selects the library concerned.

ELEMENT = *ALL
The name of the library member is not a selection criterion to determine the FT requests to be canceled.

ELEMENT = <filename 1..64 without-gen-vers>(...) /
<composed-name 1..64 with-under>(...)
Name of the library member concerned.

VERSION =
Version of the library member.

VERSION = *ALL

The version of the library member is not a selection criterion for the FT requests to be canceled.

VERSION = <text 1..24>
Only FT requests that access this version of the library member are to be canceled.

TYPE =
Type of the library member concerned.

TYPE = *ALL
The type of library member is not used as a selection criterion to determine the FT requests to be canceled.

TYPE = <name 1..8>
Only FT requests that access library members of this type are to be canceled.

MONJV =
If appropriate, selects the specific FT request that is being monitored by this job variable.

MONJV = *NONE
A job variable is not selected as a selection criterion to cancel the file transfer.

MONJV = <filename 1..54 without-gen-vers>
The FT monitored by this job variable is to be canceled.

JV-PASSWORD =
If required, specifies the password needed to access the job variable.
If you have already notified the system of the password with the BS2000 command ADD-PASSWORD, you do not have to specify JV-PASSWORD.

JV-PASSWORD = *NONE
The job variable is not password-protected.

JV-PASSWORD = <c-string 1..4> / <x-string 1..8> /
<integer -2147483648..2147483647>
This password is required to access the job variable.

JV-PASSWORD = *SECRET
The system issues the request to enter the password. However, input is not displayed on the screen.

The specification of more than one selection criteria in the CANCEL-FILE-TRANSFER command may result in a file transfer request being “overdefined” (e.g. by entries for TRANSFER-ID and MONJV). If all selection criteria for a request apply, the job is canceled.

If not all selection criteria for a request apply, it is not canceled.
If the specified criteria conflict, the CANCEL-FILE-TRANSFER command is acknowledged with the following message:

% FTR0504 No requests available for the selection criteria

In such a case there is no jump to the next SET-JOB-STEP in procedures as no error has occurred.

Command return codes

(SC2)	SC1	Maincode	Meaning
0	0	CMD0001	There are no requests that meet the specified selection criteria.
32	32	CMD0221	Request rejected. Internal error. Job variable not accessible.
33	32	CMD0221	Request rejected. Internal error.
36	32	CMD0221	Request rejected. Request data inconsistent.
82	32	CMD0221	Internal error. Job variable not accessible.
83	32	CMD0221	Internal error.
36	64	FTR1036	User not authorized for other user IDs.
38	64	FTR1038	Request is in the termination phase and can no longer be cancelled.
47	64	FTR1047	Request not found.
226	64	FTR2226	Job variable contents inconsistent.
227	64	FTR2227	Job variable not in use by openFT.
228	64	FTR2228	Job variable not found.
SC1/2 = Subcode 1/2 in decimal notation For additional information, see section “Command return codes”.

Examples

1. An openFT user wants to cancel all FT requests with his/her user ID. It is enough simply to issue the

   /CANCEL-FILE-TRANSFER

   command without specifying any further operands. If only one request is present, openFT acknowledges the request with the following message:

   % FTR2072 Request 229583776 has been canceled

   If there is more than one request, the following prompt appears first:

   % FTR0560 Cancel all specified requests? Reply (y=yes; n=no)

   After the FT user entered a Y, the following messages appear:

   %    FTR2072 Request 23958376 has been canceled

   %    FTR2072 Request 23958461 has been canceled

   %    FTR2072 Request 23958507 has been canceled

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

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

   /CANCEL-FILE-TRANSFER TRANSFER-ID=194578

   The recommended short form of this command is as follows:

   /CNFT 194578

3. 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:

   /CANCEL-FILE-TRANSFER                                                -

   /         SELECT=(INITIATOR=*REMOTE,                                   -
/         PARTNER=VAR001,                                              -

   /         FILE-NAME=DATA)

   The recommended short form of this command is as follows:

   /CNFT SEL=(INIT=*REM,PART-NAME=VAR001,FILE=DATA)

   or

   /NCAN SEL=(INIT=*REM,PART-NAME=VAR001,FILE=DATA).

4. If more than one request has been deleted by a CANCEL-FILE-TRANSFER command, the following prompt appears:

   % FTR0560 Cancel all specified requests? Reply (y=yes; n=no)

   With N the deletion request can be cancelled.