Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

FTMGET

&pagelevel(3)&pagelevel

Note on usage

Function: Get remote files

User group: FT user

Functional description

FTMGET 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, FTMGET uses the NCOPY (asynchronous) or the FTSCOPY (synchronous) command internally. The transfer mode (synchronous or asynchronous) is controlled via the TRANSFER-MODE operand.

Format

FTMGET

PARTNER = <text 1..200 with-low>

,LOCAL-PARAMETER = *PAR AMETERS (...)

*PARAMETERS (...)

FILE-NAME = *SAME / <text 2..59> / <c-string_1..512_with-low>

,PASSWORD = *NONE / <alphanum-name 1..8>

,TRANSFER-ADMISSION = *SAME / <alphanum-name 8..32> / <x-string 15..64> /

<c-string 8..32 with-low> / *PARAMETERS(...)

*PARAMETERS(...)

USER-IDENTIFICATION = <name 1..8>

,ACCOUNT = *NONE / <alphanum-name 1..40> / c-string 1..40>

,PASSWORD = *NONE / <alphanum-name 1..8>

,CODED-CHARACTER-SET = *STD / <alphanum-name 1..8>

,REMOTE-PARAMETER = *BS2 000(...) / *MSP(...) / *ANY(...)

* BS2 000(...)

FILE-NAME = <filename 1..54> / <c-string 1..512 with-low> / *LIBRARY-ELEMENT(...)

*LIBRARY-ELEMENT(...)

LIBRARY = <filename 1..54>

,ELEMENT = <filename 1..64>(...) / <c-string 1..64 with low>(...)

<filename>(...) / <c-string>(...)

,VERSION = *STD / <text 1..24>

,TYPE = <name 1..8>

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

<integer -2147483648..2147483647>

,TRANSFER-ADMISSION = <alphanum-name 8..32> / <x-string 15..64> /

<c-string 8..32 with-low> / *PARAMETERS(...)

*PARAMETERS(...)

USER-IDENTIFICATION = <alphanum-name 1..8>

,ACCOUNT = *NONE / <alphanum-name 1..8>

,PASSWORD = *NONE / <c-string 1..8> / <c-string 9..32> / <x-string 1..16>

,PROCESSING-ADMISSION = *SAME / *NOT-SPECIFIED / *PARAMETERS(...)

*PARAMETERS(...)

USER-IDENTIFICATION = <alphanum-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>

,CODED-CHARACTER-SET = *STD / <alphanum-name 1..8>

*MSP(...)

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

,PASSWORD = *NONE / <alphanum-name 1..8>

,TRANSFER-ADMISSION = <alphanum-name 8..32>/<x-string 15..64>/<c-string 8..32 with-low> /

*PARAMETERS(...)

*PARAMETERS(...)

USER-IDENTIFICATION = <name1..8>

,ACCOUNT = *NONE / <alphanum-name 1..40> / <c-string 1..40>

,PASSWORD = *NONE / <alphanum-name 1..8>

,PROCESSING-ADMISSION = *SAME / *NOT-SPECIFIED / *PARAMETERS(...)

*PARAMETERS(...)

USER-IDENTIFICATION = <name 1..8>

,ACCOUNT = *NONE / <alphanum-name 1..40> / <c-string 1..40>

,PASSWORD = *NONE / <alphanum-name 1..8>

,SUCCESS-PROCESSING = *NONE /<c-string 1..1000 with-low>

,FAILURE-PROCESSING = *NONE / <c-string 1..1000 with-low>

,CODED-CHARACTER-SET = *STD / <alphanum-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 =<name 1..8>

,PASSWORD = *NONE / <c-string 1..64 with-low> / <x-string 1..128>

,TRANSFER-ADMISSION = *NONE / <alphanum-name 8..32> / <x-string 15..64> /

<c-string 8..32 with-low> / *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>

,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>

,SUCCESS-PROCESSING = *NON E /<c-string 1..1000 with-low>

,FAILURE-PROCESSING = *NONE / <c-string 1..1000 with-low>

,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..40> / c-string 1..40>

,PASSWORD = *NONE / <alphanum-name 1..8>

,SUCCESS-PROCESSING = *NONE /<c-string 1..1000 with-low>

,FAILURE-PROCESSING = *NONE / <c-string 1..1000 with-low>

,LISTING = *STD / *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..32756>

,RECORD-FORMAT = *STD / *FIXED / *VARIABLE / *UNDEFINED

,TABULATOR = *AUTO / *ON / *OFF

,TARGET-FILE-FORMAT = *SAME / *BLOCK-ORIENTED / *SEQUENTIAL(...)

*SEQUENTIAL(...)

RECORD-FORMAT = *SAME / *UNDEFINED

Operands

Only the differences compared with the FTSCOPY command and the NCOPY 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 = <text 2..59> / <c-string_1..512_with-low>
The file names will be prefixed.
The prefix must end with a dot (.), a slash (/) or a backslash (\). The % character is replaced by the last part of the remote file name.

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, FTMGET 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.

REMOTE-PARAMETER = *PARAMETERS(...)

FILE-NAME = <file name with wildcard ...> /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
starts with a * (asterisk), you must double the * (i.e. **) if the searched string
is followed by other characters and if you do not specify any other wildcard.

?

as a wildcard for any single character.

[chars]

as a wildcard for a single character from the set specified by chars. In
chars, you can list individual characters or specify one or more character
ranges in the form a-z. This selects all characters a through z (inclusive).

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
in the specified wildcard pattern.


TRANSFER- MODE =
Specifies the transfer mode.

TRANSFER- MODE = *SYNCHRONOUS
The files are fetched synchronously. To do this openFT starts internally one FTSCOPY request for each file.

TRANSFER- MODE = *ASYNCHRONOUS(...)
The files are fetched asynchronously. To do this openFT starts internally one NCOPY 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.

If you specify REMOTE-PARAMETER=*ANY without specifying a transfer admission with file name prefix in TRANSFER-ADMISSION, the following applies for BS2000 and z/OS partners:
  • BS2000 partners: FTMGET will fetch files or library elements only if file names are given in lower case in FILE-NAME=.

  • z/OS partners: FTMGET 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, FTMGET 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 ( SYSOUT )

Meaning

FTR0707 Invalid parameter

The syntax of the local filename or library or
element or element type is invalid

FTR0865 Not all files transferred successfully

At least one source file could not be transferred to
the local system.

FTR2047 Request rejected by local FTAC

Invalid values in LOCAL-PARAMETER=...

FTR2155 File / directory not found

The path for the filename given in REMOTE-
PARAMETER=... is incorrect

FTR2169 Transfer admission invalid

Request rejected. Remote system: Transfer
admission invalid, i.e. transfer admission incorrect
or insufficient FTAC authorizations.

Example

Fetch synchronously all files from the z/OS system zos1 which start with CFG and store them in the local system with prefix SAV.

FTMGET ZOS1,(SAV.),(C'CFG*',,'TRANSADM')

The same command asynchronously and start of transfer is tomorrow:

FTMGET ZOS1,(SAV.),(C'CFG*',,'TRANSADM'),TRANS-MODE=*A(START=(*TOM))