Note on usage
Function: Query status of file transfer request
User group: FT user and FT administrator
Alias names: SHFT / NSTATUS / FTSHWREQ
Functional description
The SHOW-FILE-TRANSFER command allows you to request information about FT requests. As with CANCEL-FILE-TRANSFER, you can specify selection criteria in order to obtain information about specific FT requests.
FT users can only obtain information about the FT requests they own.
The FT administrator can obtain information about the requests of any owner.
The owner of requests issued in the local system is the user ID under which they are submitted. The owner of requests issued in the remote system is the user ID in the local system under which the requests are executed.
The scope of information to be output can be selected. By default the following information is output by the system in response to the SHOW-FILE-TRANSFER command:
the transfer ID of the request,
the initiator of the request (local or remote system),
the operating status of the request (see description of operands for more details),
the partner system,
the transfer direction,
the name of the file (or library member) to be transferred in the local system,
the number of bytes transferred.
By entering INFORMATION=*ALL in the SHOW-FILE-TRANSFER command more information can be obtained. openFT then, in addition to the standard output, outputs the values of further operands of the transfer command that was used to issue the request. Which output parameters are displayed depends on the parameters which were specified for the request.
The complete description of all possible output parameters and values is provided in the section “Description of the long output of SHOW-FILE-TRANSFER”.
The more precise your information request, the fewer irrelevant requests are output.
The specification of INFORMATION=*SUMMARY returns a small table with the number of jobs in the various request states.
Format
SHOW-FILE-TRANSFER / SHFT / NSTATUS / FTSHWREQ |
TRANSFER-ID = *ALL / <integer 1..2147483647> ,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> *ALL(...) PARTNER-STATE = *ALL / *ACTIVE ,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 ,STATE = *ALL / *SUSPEND / *LOCKED / *WAIT / *ACTIVE / *CANCELLED / *FINISHED / *HOLD ,GLOBAL-REQUEST-ID = *ALL / <alphanum-name 1..10> ,INFORMATION = *STD / *ALL / *SUMMARY ,OUTPUT = *SYSOUT (...) / *SYSLST(...) *SYSOUT (...) / *SYSLST(...) LAYOUT = *STD / *CSV |
Operands
TRANSFER-ID =
Transfer ID of the FT request about which information is required.
TRANSFER-ID = *ALL
Supplies information about all the owner’s FT requests.
The FT user can only obtain information about the current requests he/she owns.
The FT administrator can obtain information about all current FT requests that access his/her system.
TRANSFER-ID = <integer 1..2147483647>
Transfer ID assigned to the local system and output as part of the message confirming acceptance of the request.
SELECT =
Contains selection criteria defining the file transfer requests on which inquiries are to be made. Information on a file transfer request is output if the request satisfies all the specified criteria.
SELECT = *OWN
Provides information on all current file transfer requests for which you are designated as the owner.
SELECT = *PARAMETERS(...)
OWNER-IDENTIFICATION =
Owner of the FT requests. Only the FT administrator can make use of this operand unrestricted.
OWNER-IDENTIFICATION = *OWN
Provides information only on the file transfer requests in the user’s own ID.
OWNER-IDENTIFICATION = *ALL
Provides information on FT requests in all user IDs.
OWNER-IDENTIFICATION = <name 1..8>
Specific user ID about whose file transfer requests information is required. The FT user may only enter his/her own user ID. The specification corresponds to *OWN.
INITIATOR =
Initiator of the file transfer requests concerned.
INITIATOR = ( *LOCAL,*REMOTE )
Provides information on file transfer requests issued in the local system and in remote systems.
INITIATOR = *LOCAL
Provides information on file transfer requests issued in the local system.
INITIATOR = *REMOTE
Provides information on file transfer requests issued in the remote systems.
PARTNER =
Selects file transfer requests carried out with a specified remote system.
PARTNER = *ALL (...)
The partner system is not used as a selection criterion to determine the file transfer requests on which information is to be output.
PARTNER-STATE =
The status of the partner system is used as a selection criterion.
PARTNER-STATE = *ALL
The requests are selected independently of the partner system’s status.
PARTNER-STATE = *ACTIVE
Only the requests to and from the active partners are selected.
PARTNER = <text 1..200 with-low>
Name or an address of a partner system. Information is required on the file transfer requests being executed with this system. For more information on address specifications, see section “Specifying partner addresses”
FILE-NAME =
FT requests that access this file, this pubset or this library member in the local system as a send file or receive file. The file name or library member name must be specified exactly as it appears in the FT request. If %UNIQUE was specified, the file name generated by openFT must be entered as the selection criterion here.
FILE-NAME = *ALL
The file name is not used as a selection criterion to define the file transfer requests on which information is to be output.
FILE-NAME = <filename 1..54> / <c-string 1..512 with-low> /
*POSIX(NAME = <posix-pathname 1..510>)
Name of a file. Information is required on the file transfer requests that access this file.
FILE-NAME = *PUBSET(PUBSET = <cat-id 1..4>)
Information on all FT requests that access files on the specified pubset should be displayed.
FILE-NAME = *LIBRARY-ELEMENT(...)
Information is required on file transfer 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 define the file transfer requests on which information is to be output.
LIBRARY = <filename 1..54>
Name of a library. Information is required on the file transfer requests that access this library.
ELEMENT =
Library member. Information is required on all the file transfer requests that access this member.
ELEMENT = *ALL
The name of the library member is not used as a selection criterion to define the file transfer requests.
ELEMENT = <filename 1..64 without-gen-vers>(...) /
<composed-name 1..64 with-under>(...)
Name of a library member. Information is required on the file transfer requests that access this library member.
VERSION =
Version number of the library member.
VERSION = *ALL
Information is required on all file transfer requests that access any version of the library member.
VERSION = <text 1..24>
Information is required on the file transfer requests that access a specific version of the library member.
TYPE =
The type of library member.
TYPE = *ALL
The member type is not used as a selection criterion to define the file transfer requests on which information is to be output.
TYPE = <name 1..8>
Information is required only on those file transfer requests that access library members of this type.
MONJV =
If appropriate, selects the specific file transfer request that is being monitored by this job variable.
MONJV = *NONE
A job variable is not used as a selection criterion to define the file transfer request on which information is to be output.
MONJV = <filename 1..54 without-gen-vers>
Information is required on the file transfer request that is being monitored by this job variable.
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 for the job variable.
JV-PASSWORD = *SECRET
The system requests you to enter the password. This input is not displayed on the screen.
STATE =
Selects those file transfer requests that are in the specified status. The status of a request may change in between entry of the command and information output. This is why the output may include requests that are in a state other than the one selected with STATE.
STATE = *ALL
The status of a request is not used as a selection criterion to define the file transfer requests on which information is to be output.
STATE = *SUSPEND
Requests information on those file transfer requests that are currently in SUSPEND status (= interrupted).
STATE = *LOCKED
Requests information on FT requests that are in the LOCKED operating status (= temporarily locked as a result of a longer term resource bottleneck).
STATE = *WAIT
Requests information on those file transfer requests that are currently in WAIT status (= waiting for resources).
STATE = *ACTIVE
Requests information on those file transfer requests that are currently in ACTIVE status (= being processed).
STATE = *CANCELLED
Requests information on those file transfer requests that were canceled and are waiting for negotiation with the communications partner to be concluded. These requests are visible only to the FT administrator.
STATE = *FINISHED
Requests information on those file transfer requests that are currently in FINISHED status (= terminated or aborted, but where the user has not yet been informed).
STATE = *HOLD
Requests information on those FT requests that are currently in HOLD status (= awaiting the specified start time).
GLOBAL-REQUEST-ID =
Selects the FT requests on the basis of the global request identification.
GLOBAL-REQUEST-ID = *ALL
The global request identification is not a search criterion.
GLOBAL-REQUEST-ID = <alphanum-name 1..10>
Requests information on the FT request with a particular global request identification. The global request identification is relevant only for inbound requests of openFT and FTAM partners. It is assigned by the initiator of the request (transfer ID) and transferred to the local system.
INFORMATION =
Scope of the output.
INFORMATION = *STD
Output is summary form and contains the following information (see Description of the shortoutput of SHOW-FILE-TRANSFER):
Transfer ID,
Initiator,
State of the request,
Partner,
Direction of transfer,
Byte count,
File or library member name in the local system.
INFORMATION = *ALL
Output is in full form. In addition to the summary form data, further information is provided on the operands used in the TRANSFER-FILE command (see Description of the longoutput of SHOW-FILE-TRANSFER).
INFORMATION = *SUMMARY
Output is in the form of a specified sum. By specifying INFORMATION=*SUMMARY, you can restrict the output information to a statistic of the currently existing requests. By doing this, the display is arranged according to the conditions in which the requests find themselves. The displayed sum can, of course, exceed the sum of the individual columns, since all requests, even those that still have no request condition, are counted. Information is output about the number of request in each individual processing status (see Descriptionof the summary output of SHOW-FILE-TRANSFER).
OUTPUT =
Output medium.
OUTPUT = * SYSOUT (...)
Output is sent to SYSOUT.
OUTPUT = *SYSLST(...)
Output is sent to SYSLST.
LAYOUT = *STD
Output is formatted using a standard layout that can be easily read by the user.
LAYOUT = *CSV
Output is supplied in CSV (Character Separated Values) format. This is a widely used tabular format, especially in the PC environment, in which individual fields are separated by a delimiter, which is usually a semicolon “;“ (see section “SHOW-FILE-TRANSFER”).
If selection criteria are specified in the SHOW-FILE-TRANSFER command and no request is found that matches all the specified criteria, the command is acknowledged with the following message:
% FTR0504 No requests available for the selection criteria
In such a case, procedures do not branch to the next SET-JOB-STEP.
Commando return codes
(SC2) | SC1 | Maincode | Meaning |
0 | 0 | CMD0001 | There are no requests that meet the specified selection criteria. |
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. |
88 | 32 | CMD0221 | Error during OPS generation. |
36 | 64 | FTR1036 | User not authorized for other user IDs |
47 | 64 | FTR1047 | The request with the specified transfer ID could not be 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”. | |||
OPS variables
The following table shows the OPS variables for the command SHOW-FILE-TRANSFER with the operand INF=*ALL. The underlined values are valid for the output with the operand INF=*STD. The second table shows the OPS variables for the output with the operand INF=*SUMMARY.
Element | Type | Output |
TRANS-ID | Integer | |
STA | String | *SUSPEND / *LOCK / *WAIT / *ACTIVE / *FINISH / |
BYTE-COUNT | Integer | |
PRIO | String | *NORM / *HIGH / *LOW |
INIT | String | *LOC / *REM |
TRANS-DIRECT | String | *TO-PARTNER / *FROM-PARTNER |
PARTNER-NAME | String | |
COMPRESS | String | *NONE / *BYTE-REPETITION / *ZIP |
DATA-ENC | String | *YES / *NO |
DICHECK | String | *YES / *NO |
WRITE-MODE | String | * REPL-FILE / *NEW-FILE / *EXT-FILE |
FILE-SIZE | String | Value |
REC-SIZE | String | Value |
REC-FORMAT | String | *STD / *VARIABLE / *FIXED /*UNDEFINED |
START | Struct | |
.DATE | String | *SOON / yyyy-mm-dd |
.TIME | String | *SOON / hh:mm:ss |
CANCEL | Struct | |
.DATE | String | *NO / yyyy-mm-dd |
.TIME | String | *NO / hh:mm:ss |
OWNER | String | |
DATA-TYPE | String | *CHAR / *BINARY / *NOT-SPEC |
TRANSP | String | *YES / *NO |
LOC-PAR | Struct | |
.F-TYPE 1 | String | *FILE / *LIB |
.F-NAME | String | |
.LIB | String | |
.ELEM | String | |
.VERSION | String | |
.TYPE | String | |
.TRANS-ADMIS | Struct | |
.USER-ID | String | |
.ACCOUNT | String | |
.PROF-NAME 2 | String | |
.PROCESS-ADMIS | Struct | |
.USER-ID | String | |
.ACCOUNT | String | |
.SUCC-PROCESS | String | *SECRET / success-processing |
.FAIL-PROCESS | String | *SECRET / failure-processing |
.LISTING | String | *NONE / *SYSLST / *LISTFILE / *FAIL-SYSLST / |
.MONJV | String | |
.CCS-NAME | String | *STD / value |
REM-PAR | Struct | |
.F-TYPE 1 | String | *FILE / *LIB |
.F-NAME | String | |
.LIB | String | |
.ELEM | String | |
.VERSION | String | |
.TYPE | String | |
.TRANS-ADMIS | Struct | |
.USER-ID 3 | String | *REM-PROF / user-id |
.ACCOUNT 3 | String | *REM-PROF / account |
.PROCESS-ADMIS | Struct | |
.USER-ID | String | |
.ACCOUNT | String | |
.SUCC-PROCESS | String | *SECRET / success-processing |
.FAIL-PROCESS | String | *SECRET / failure-processing |
.CCS-NAME | String | *STD / value |
TARGET | Struct | |
.FILE-FORMAT | String | *SAME / *BLOCK / *SEQ |
.REC-FORMAT | String | *SAME / *UNDEF |
PROTECTION | String | *STD / *SAME |
GLOBAL-REQ-ID | Integer |
1For F-Type=*FILE, LIB, ELEM, VERSION and TYPE are not displayed.
2USER-ID and ACCOUNT are not assigned if an FTAC profile is specified.
3Since this cannot be output when a remote FTAC transfer admission is specified, USER-ID and ACCOUNT are assigned with *REM-PROFILE in this case.
The following table shows the OPS variables for the output with the operand INF=*SUMMARY.
Element | Type | Output |
NUM-ACTIVE | Integer | |
NUM-WAIT | Integer | |
NUM-LOCK | Integer | |
NUM-SUSPEND | Integer | |
NUM-HOLD | Integer | |
NUM-FINISHED | Integer | |
NUM-SUMM 1 | Integer |