Note on usage
Function: Get remote files
User group: FT user
Alias name: FTMGET
Functional description
GET-REMOTE-FILES allows you to fetch synchronously or asynchronously multiple files from a remote partner system. You can specify the remote files using wildcards. To do this, GET-REMOTE-FILES uses the TRANSFER-FILE (asynchronous) or the TRANSFER-FILE-SYNCHRONOUS (synchronous) command internally. The transfer mode (synchronous or asynchronous) is controlled via the TRANSFER-MODE operand.
Format
GET-REMOTE-FILES / FTMGET |
PARTNER = <text 1..200 with-low> ,LOCAL-PARAMETER = *PAR AMETERS (...) *PARAMETERS (...) FILE-NAME = *SAME / <partial-filename_2..53> / <c-string_1..512_with-low> / *LIBRARY-ELEMENT(...) / *POSIX(NAME= *SAME / <posix-pathname 1..510>) *LIBRARY-ELEMENT(...) LIBRARY = *SAME / <filename 1..54> ,ELEMENT = *SAME / <partial-filename 2..64>(...) / <c-string 1..64>(...) <partial-filename 2..64>(...) / <c-string 1..64> VERSION = *STD / <text 1..24> ,TYPE = *SAME / <alphanum-name 1..8> ,PASSWORD = *NONE / <c-string 1..4> / <x-string 1..8> / <integer -2147483648..2147483647> / *SECRET ,TRANSFER-ADMISSION = *SAME / <alphanum-name 8..32> / <x-string 15..64> / <c-string 8..32 with-low> / *SECRET / *PARAMETERS(...) *PARAMETERS(...) USER-IDENTIFICATION = <name 1..8> ,ACCOUNT = *NONE / <alphanum-name 1..8> ,PASSWORD = *NONE / <c-string 1..8> / <c-string 9..32> / <x-string 1..16> / *SECRET ,CODED-CHARACTER-SET = *STD / <name 1..8> ,REMOTE-PARAMETER = *BS2 000(...) / *MSP(...) / *ANY(...) * BS2 000(...) FILE-NAME = <file name with wildcard 1..54> / *LIBRARY-ELEMENT(...) / *POSIX(NAME=<posix-pathname 1..510>) *LIBRARY-ELEMENT(...) LIBRARY = <filename 1..54> ,ELEMENT = <filename 1..64 without-gen-vers with wildcard>(...) / <composed-name 1..64 with-underscore with wildcards>(...) <filename>(...) / <omposed-name >(...) ,VERSION = *STD / <text 1..24> ,TYPE = <alphanum-name 1..8> ,PASSWORD = *SAME / *NONE / <c-string 1..4> / <x-string 1..8> / <integer -2147483648..2147483647> / *SECRET ,TRANSFER-ADMISSION = *SAME / <alphanum-name 8..32> / <x-string 15..64> / <c-string 8..32 with-low> / *SECRET/ *PARAMETERS(...) *PARAMETERS(...) USER-IDENTIFICATION = <name 1..8> ,ACCOUNT = *NONE / <alphanum-name 1..8> ,PASSWORD = *NONE / <c-string 1..8> / <c-string 9..32> / <x-string 1..16> / *SECRET ,PROCESSING-ADMISSION = *SAME / *NOT-SPECIFIED / *PARAMETERS(...) *PARAMETERS(...) USER-IDENTIFICATION = <name 1..8> ,ACCOUNT = *NONE / <alphanum-name 1..8> ,PASSWORD = *NONE / <c-string 1..8> / <c-string 9..32> / <x-string 1..16> ,SUCCESS-PROCESSING = *NONE / <c-string 1..1000 with-low> ,FAILURE-PROCESSING = *NONE / <c-string 1..1000 with-low> ,FILE-AVAILABILITY = *BY-RECEIVING-SYSTEM / *IMMEDIATE / *DEFERRED ,STORAGE-ACCOUNT = *NONE / <c-string 1..40 with-low> / <text 1..40> ,ACCESS-MODE = *BY-RECEIVING-SYSTEM / *PARAMETERS(...) *PARAMETERS(...) READ-FILE = *NO / *YES ,INSERT-DATA-UNIT = *NO / *YES ,REPLACE-FILE = *NO / *YES ,EXTEND-FILE = *NO / *YES ,ERASE-DATA-UNIT = *NO / *YES ,READ-ATTRIBUTES = *NO / *YES ,CHANGE-ATTRIBUTES = *NO / *YES ,DELETE-FILE = *NO / *YES ,LEGAL-QUALIFICATION = *NONE / <c-string 1..80 with-low> / <text 1..80> ,CODED-CHARACTER-SET = *STD / <name 1..8> *MSP(...) FILE-NAME = <text 1..80> ,PASSWORD = *NONE / <alphanum-name 1..8> / *SECRET ,TRANSFER-ADMISSION = <alphanum-name 8..32>/<x-string 15..64>/<c-string 8..32 with-low> / / *SECRET / *PARAMETERS(...) *PARAMETERS(...) USER-IDENTIFICATION = <name 1..7> ,ACCOUNT = *NONE / <text 1..43> ,PASSWORD = *NONE / <alphanum-name 1..8>/ *SECRET ,PROCESSING-ADMISSION = *SAME / *NOT-SPECIFIED / *PARAMETERS(...) *PARAMETERS(...) USER-IDENTIFICATION = <name 1..7> ,ACCOUNT = *NONE / <text 1..43> ,PASSWORD = *NONE / <alphanum-name 1..8>/ *SECRET ,SUCCESS-PROCESSING = *NONE /<c-string 1..1000 with-low> ,FAILURE-PROCESSING = *NONE / <c-string 1..1000 with-low> ,CODED-CHARACTER-SET = *STD / <name 1..8> *ANY(...) FILE-NAME = <c-string 1..512 with-low> / *LIBRARY-ELEMENT(...) *LIBRARY-ELEMENT(...) LIBRARY = <c-string 1..63 with-low> ,ELEMENT = <c-string 1..64 with-low>(...) <c-string 1..64 with-low>(...) VERSION = *NONE / *STD / <c-string 1..24 with-low> ,TYPE =<c-string 1..8 with-low> ,PASSWORD = *NONE / <c-string 1..64 with-low> / <x-string 1..128> / *SECRET ,TRANSFER-ADMISSION = *NONE / <alphanum-name 8..32> / <x-string 15..64> / <c-string 8..32 with-low> / *SECRET / *PARAMETERS(...) *PARAMETERS(...) USER-IDENTIFICATION = <c-string 1..67 with-low> ,ACCOUNT = *NONE / <c-string 1..64 with-low> ,PASSWORD = *NONE / <c-string 1..64 with-low> / <x-string 1..128 with-low> / *SECRET ,PROCESSING-ADMISSION = *SAME / *NONE / *PARAMETERS(...) *PARAMETERS(...) USER-IDENTIFICATION = <c-string 1..67 with-low> ,ACCOUNT = *NONE / <c-string 1..64 with-low> ,PASSWORD = *NONE / <c-string 1..64 with-low> / <x-string 1..128 with-low> / *SECRET ,SUCCESS-PROCESSING = *NON E /<c-string 1..1000 with-low> ,FAILURE-PROCESSING = *NONE / <c-string 1..1000 with-low> ,FILE-AVAILABILITY = *BY-RECEIVING-SYSTEM / *IMMEDIATE / *DEFERRED ,STORAGE-ACCOUNT = *NONE / <c-string 1..40 with-low> / <text 1..40> ,ACCESS-MODE = *BY-RECEIVING-SYSTEM / *PARAMETERS(...) *PARAMETERS(...) READ-FILE = *NO / *YES ,INSERT-DATA-UNIT = *NO / *YES ,REPLACE-FILE = *NO / *YES ,EXTEND-FILE = *NO / *YES ,ERASE-DATA-UNIT = *NO / *YES ,READ-ATTRIBUTES = *NO / *YES ,CHANGE-ATTRIBUTES = *NO / *YES ,DELETE-FILE = *NO / *YES ,LEGAL-QUALIFICATION = *NONE / <c-string 1..80 with-low> / <text 1..80> ,CREATE-PASSWORD = *NONE / <c-string 1..64 with-low> / <x-string 1..128> / *SECRET ,CODED-CHARACTER-SET = *STD / <c-string 1..8 with-low> ,TRANSFER- MODE = *SYNCHRONOUS / *ASYNCHRONOUS(...) *ASYNCHRONOUS (...) ,LOCAL-PARAMETER = *PARAMETERS (...) *PARAMETERS (...) ,PROCESSING-ADMISSION = *SAME / *NOT-SPECIFIED / *PARAMETERS(...) *PARAMETERS(...) USER-IDENTIFICATION = <name 1..8> ,ACCOUNT = *NONE / <alphanum-name 1..8> ,PASSWORD = *NONE / <c-string 1..8> / <c-string 9..32> / <x-string 1..16> / *SECRET ,SUCCESS-PROCESSING = *NONE /<c-string 1..1000 with-low> ,FAILURE-PROCESSING = *NONE / <c-string 1..1000 with-low> ,LISTING = *NONE / *SYSLST / *LISTFILE / *PARAMETERS(...) *PARAMETERS(...) OUTPUT = *SYSLST / *LISTFILE ,CONDITION = *ANY / *ON-FAILURE-ONLY ,PRIORITY = *NORMAL / *HIGH / *LOW ,START = * SOON / *EARLIEST(...) *EARLIEST(...) DATE = * TODAY / *TOMORROW / <date 8..10> ,TIME = 00:00 / <time 1..8> ,CANCEL = *N O / *AT(...) *AT(...) DATE = *TODAY / *TOMORROW / <date 8..10> ,TIME = 23:59 / <time 1..8> ,CASE-SENSITIVE = * BY-PARTNER / *NO / *YES ,COMPRESS = *NONE / *BYTE-REPETITION / *ZIP ,WRITE-MODE = *REPLACE -FILE / *NEW-FILE / *EXTEND-FILE ,DATA-TYPE = *NOT-SPECIFIED / *CHARACTER (...) / *BINARY (...) / *USER *CHARACTER(...) TRANSPARENT = *NO / *YES *BINARY(...) TRANSPARENT = *NO / *YES ,DATA-ENCRYPTION = *NO / *YES / *ONLY-DATA-INTEGRITY ,RECORD-SIZE = *NOT-SPECIFIED /<integer 1..32767> ,RECORD-FORMAT = *STD / *FIXED / *VARIABLE / *UNDEFINED ,TARGET-FILE-FORMAT = *SAME / *BLOCK-ORIENTED / *SEQUENTIAL(...) *SEQUENTIAL(...) RECORD-FORMAT = *SAME / *UNDEFINED ,PROTECTION = *STD / *SAME ,LAST-CHANGE-DATE = *STD / *SAME |
Operands
Only the differences compared with the TRANSFER-FILE-SYNCHRONOUS command and the TRANSFER-FILE command are described below.
LOCAL-PARAMETER = *PARAMETERS(...)
FILE-NAME =
Determines the names of the receive files in the local system.
FILE-NAME = *SAME
The file names are taken over unchanged.
FILE-NAME = <partial-filename_2..53> / <c-string_1..512_with-low> / POSIX(NAME=<posix-pathname 1..510>)
The file names will be prefixed.
This prefix must end with a dot (.) in case of format partial-filename or a percent (%) character in case of format c-string or format POSIX(NAME=...). If the prefix ends with a dot then the last part of the name of the remote file is attached. If the prefix ends with a percent (%) then the % is replaced by the last part of the remote file.
The last part of the name starts after the last slash (/) or backslash (\) or a corresponding character in the remote system.
The prefix can also contain the absolute or relative path of a directory that exists on the local computer. If the specified directory does not exist, GET-REMOTE-FILES is not executed.
Please note that the resulting file name must comply with the rules of the local system, otherwise the files will not be transferred.
FILE-NAME = *LIBRARY-ELEMENT(...)
specifies that library members are to be transferred.
The operands in these parentheses can be used as positional operands without their keywords.
LIBRARY =
Name of the library in the local system.
LIBRARY = *SAME
The name is taken over unchanged.
LIBRARY = <filename 1..54>
Specifies the name of the library in the local system.
ELEMENT =
Names of the library elements in the local system.
ELEMENT = *SAME
The names are taken over unchanged.
ELEMENT = <partial-filename 2..64>(...) / <c-string 1..64>(...)
The names will be prefixed. This prefix must end with a dot (.) in case of format partial-filename or a percent (%) character in case of format c-string. If the prefix ends with a dot then the last part of the name of the remote file is attached. If the prefix ends with a percent (%) then the % is replaced by the last part of the name of the remote file.
VERSION =
Version of the elements in the local system.
VERSION = *STD
Highest version of the members.
VERSION = <text 1..24>
Version of the members.
TYPE =
Type of the members in the local system.
TYPE = *SAME
The type is taken over unchanged.
TYPE = <name 1..8>
Type of the elements.
REMOTE-PARAMETER = *PARAMETERS(...)
FILE-NAME = <file name with wildcard ...>/ <c-string with low> /*POSIX(NAME = <posix-pathname 1..510>) /LIBRARY-ELEMENT(ELEMENT=filename 1..64 without-gen-vers with wildcard)
Specifies which files or library elements are to be fetched from the remote system.
You can only use wildcard characters in the final part of the name following the last slash (/ with Unix systems) or backslash (\ with Windows systems). A BS2000 partner is regarded as a POSIX system if the specified file name is a POSIX pathname, i.e. starts with / or ./.
The following characters can be used to define a wildcard pattern:
* | as a wildcard for any string (including an empty string). |
For BS2000 partners, the following applies: If the string to be searched | |
? | as a wildcard for any single character. |
[chars] | as a wildcard for a single character from the set specified by chars. In |
Example: [aeiX-Z] stands for one of the characters a e i X Y Z. | |
\x | x as a wildcard for one only of the following characters: * ? [ ] \ |
The backslash is used to cancel the special meaning of these characters |
TRANSFER- MODE =
Specifies the transfer mode.
TRANSFER- MODE = *SYNCHRONOUS
The files are fetched synchronously. To do this openFT starts internally one TRANSFER-FILE-SYNCHRONOUS request for each file.
TRANSFER- MODE = *ASYNCHRONOUS(...)
The files are fetched asynchronously. To do this openFT starts internally one TRANSFER-FILE request for each file. The further parameters (e.g. for follow-up processing) then apply for all transfer requests.
CASE-SENSITIVE =
Determines whether the search for the files is case sensitive or not.
CASE-SENSITIVE = *BY-PARTNER
The behavior is determined by the partner system:
For Unix and POSIX partners, upper case and lower case is considered.
For other partner systems, upper case and lower case is not considered.
CASE-SENSITIVE = *NO
Upper case and lower case is not considered when searching for the files.
CASE-SENSITIVE = *YES
Upper case and lower case is considered when searching for the files.
BS2000 partners: GET-REMOTE-FILES will fetch files or library elements only if file names are given in lower case in FILE-NAME=.
z/OS partners: GET-REMOTE-FILES will fetch files only if file names are given in upper case in FILE-NAME=.
DATA-ENCRYPTION =
Controls the encryption option for user data and file/directory list attributes. I.e. the specifications also apply to file management requests (unlike file transfer commands).
Result messages and return codes
On success, GET-REMOTE-FILES issues one of the following messages:
FTR0505 Requests carried out; <n> files were transferred (synchronous transfer)
FTR0511 Requests accepted; <n> file transfers initiated (asynchronous transfer)
Where <n> stands for the number of files transferred synchronously or the number of asynchronous file transfer requests initiated. If no files that match the specified pattern were found on the remote system, the following message appears instead:
FTR2174 No files corresponding to specified pattern found
Other messages:
Output ( STDERR ) | Meaning |
FTR0707 Invalid parameter | The syntax of the local filename or library or |
FTR0865 Not all files transferred successfully | At least one source file could not be transferred to |
FTR2047 Request rejected by local FTAC | Invalid values in LOCAL-PARAMETER=... |
FTR2155 File / directory not found | The path for the filename given in REMOTE- |
FTR2169 Transfer admission invalid | Request rejected. Remote system: Transfer |
Example
Fetch synchronously all files from the BS2000 system BS2 which start with CFG and store them in the local system with prefix SAV.
/GET-REMOTE-FILES BS2,(SAV.),(C'CFG*',,'TRANSADM')
The same command asynchronously and start of transfer is tomorrow:
/GET-REMOTE-FILES BS2,(SAV.),(C'CFG*',,'TRANSADM'),TRANS-
MODE=*A(START=(*TOM))