ft_mget

Note on usage

Function: Fetching multiple files

User group: FT user

Functional description

ft_mget allows you to fetch synchronously or asynchronously multiple files from a remote partner computer. You specify the files using wildcards. To do this, ft_mget uses the ncopy (synchronous) or the ft (asynchronous) command internally. The transfer mode (synchronous or asynchronous) is controlled via the -async option.

Format

ft_mget -h |

[ -async ]
[ -case=y | -case=n ]
[ -t | -u | -b ][ -x ]
[ -o | -e | -n ]
[ -k | -z ][ -c ][ -S | -s ][ -m=n | -m=f | -m=a ] *)
<partner 1..200>!<file name with wildcard 1..512>
<prefix 0..511>%s
<transfer admission 8..67> | @n |

<user ID 1..67>[,[<account 1..64>][,<password 1..64>] ]

[ -p=[<password 1..64>] ][ -di ]
[ -lc=<CCS name 1..8> ][ -rc=<CCS name 1..8> ]
[ -ls=<follow-up proc 1..1000> ][ -lf=<follow-up proc 1..1000> ]
[ -rs=<follow-up proc 1..1000> ][ -rf=<follow-up proc 1..1000> ]
[ -r=v[<1..65535>] | -r=f[<1..65535>] | -r=u[<1..65535>] |
-r=<1..65535> ]
[ -tff=b | -tff=s ][ -trf=u ]
[ -av=i | -av=d ] [ -ac=<new account number 1..64> ]
[ -am=[r][i][p][x][e][a][c][d] | -am=@rw | -am=@ro ]
[ -lq=<legal qualification 1..80> ]
[ -pr=n | -pr=l ]
[ -sd=yyyymmdd | +<start date 0..ddddd> ]
[ -st=[+]<start time hhmm> ]
[ -cd=yyyymmdd | +<cancel date 0..ddddd> ]
[ -ct=[+]<cancel time hhmm> ]
[ -md ]

*) The option -m is only available on Unix systems

Description

Only the differences compared with the ncopy and ft command are described below. The other parameters have the same meanings as in the ncopy command and the ft command.

Note that the same conditions apply to the -c option (encryption of user data) as for the ft or ncopy command, i.e. openFT-CR must be installed and the partner system must support encryption.

-async

The files are fetched asynchronously. In this event, you must not specify the -s option. All other parameters are permitted.

In the case of asynchronous transfer, the number of transfer requests that can be processed simultaneously is limited by the size of the request queue. If you wish to fetch a large number of files asynchronously using ft_mget, the FT administrator may have to increase the maximum size of the request queue. For further details, refer to the manual "openFT (Unix and Windows systems) - Installation and Operation".

-async not specified

If you omit -async, the files are fetched synchronously. In this event, you must not specify the following options:

• -ls and -lf (local follow-up processing)

• -pr (priority)

• -sd and -st (start date and time)

• -cd and -ct (deletion date and time)

All other parameters are permitted.

-case=y | -case=n

The option -case sets the consideration or non-consideration of upper case / lower case in the file name pattern. It does not influence the determination of the directory name.

y

The file name pattern specified for the source file is compared with the file names received from the remote system with due regard to upper case / lower case.

n

The file name pattern specified for the source file is compared with the file names received from the remote system without regard to upper case / lower case.

-case not specified

If -case is not specified, then the following is valid: file names are case-sensitive with Unix and POSIX systems. Other partner systems are not case-sensitive.

-c

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).

transfer-admission | @n | userid[,[account][,password]]

Specification of the transfer admission is mandatory. Blanking of your entry is not supported. You are therefore not permitted to specify either the value @d or a user ID without password in the form userid,[account].

filename with wildcard

Specifies which files 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 (/) or backslash (\), not in the directory name. A BS2000 partner is regarded as a POSIX system if the specified file name is a POSIX pathname, i.e. starts with / or ./.

If the -async option has not been specified then all files that match the pattern specified under file name with wildcard are transferred to the local computer synchronously by ft_mget in a loop of ncopy commands. Otherwise asynchronous transfer requests are issued in the loop by means of ft commands.

The following characters can be used to define a wildcard pattern:

*

as a wildcard for any string (including an empty string).

?

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

On Unix systems, steps must be taken to ensure that wildcard characters and the exclamation mark (!) are not interpreted or resolved by the local shell. For this reason, we strongly recommend that you enclose the expression <partner 1..200>!<file name with wildcard 1..512> in single quotes, i.e. enter it in the form'<partner 1..200>!<file name with wildcard 1..512>', e.g. ft_mget 'server01!*.pdf' ....

prefix%

Determines the names of the receive files in the local system.

You can specify %, %BASENAME, prefix%, or prefix%BASENAME:

% or %BASENAME

Each of these are replaced by the last part of the name 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.

prefix% or prefix%BASENAME

You can also specify an optional prefix, e.g. saved.%BASENAME.
This prefix must end with a dot (.), a slash (/) or a backslash (\). 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, ft_mget is not executed.

Note that the resulting file name must comply with the rules of the local system, otherwise the files will not be transferred.

If, for instance, the last part of the name of a file that matches the search pattern contains double quotes (") when fetching files from a Unix system to a Windows system, transfer of this file fails, because, unlike Unix systems, Windows systems do not permit quotes in file names.

Result messages and return codes

On success, ft_mget issues one of the following messages:

<n> files successfully transferred (synchronous transfer)

Transfer of <n> files successfully 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:

No files corresponding to specified pattern found

ft_mget normally terminates with the return code 0. If an error occurs during execution, the command terminates and returns one of the following return codes (RC):

RC	Output to stderr	Meaning
1	Invalid source parameter '<par>'. Source expected as <partner 1..200>!<file name with wildcard 1..512>.	The specification of the parameter used to specify the files to be transferred does not match the required format.
1	ft_mget syntax help	One of the mandatory parameters for ft_mget was not specified.
1	Invalid transfer admission specified.	@d or userid,[account], was specified in place of a transfer admission.
1	Parameter(s) '<par>' only allowed together with '-async'	The parameters <par> are only allowed for asynchronous file transfer.
1	Parameter(s) '<par>' must not be specified together with '-async'	The parameters <par> are not allowed for asynchronous file transfer.
2	Given target directory '<dir>' does not exist.	The target directory specified does not exist on the local system.
3	Given target path must contain %, %BASENAME, or %FILENAME.	The parameter specified for the target of ft_mget does not end with one of the specified placeholders.
4	openFtCmd <ftshw> failed	The openFT command ftshw for determining the files in the specified remote directory failed.
5	ft::isAbort after openFtCmd <ftshw>	The openFT command ftshw for determining the files in the specified remote directory failed.
6	Remote directory <dir> on host <partner> could not be accessed (return code= '<rc>', exit code='<code>').	It is not possible to access the specified directory on the remote partner system.
6	Reading content of remote directory <dir> on host <partner> failed (return code='<rc>', exit code='<code>').	It was not possible to read the specified directory on the remote partner system.
7	Not all files successfully transferred	At least one source file could not be transferred to the local system. The previous message(s) indicate(s) the file(s) concerned: Transfer of file '<file>' failed. Reason: '<rc>'

Example

You want to fetch synchronously all files on the remote computer located in a specific subdirectory and whose names start with cfg onto the local computer and store them there in the config subdirectory of the current directory. mytad001 is a valid FTAC transfer admission for the remote computer.

• The local system and the remote system MCH0001X are Unix systems.

  If the files are located in the tmp/config directory, the command is as follows:

  ft_mget

  'MCH0001X!/tmp/config/cfg*' config/copy.%BASENAME mytad001

  If, for instance, the source directory contains the files cfg001, cfg002 and cfg003, ft_mget creates the local receive files config/copy.cfg001, config/copy.cfg002 and
  config/copy.cfg003.

• The local system and the remote system MCH0001W are Windows systems.

  If the files are located in the D:\tmp\config directory, the command is as follows:

  ft_mget

  MCH0001W!D:\tmp\config\cfg* config\copy.%BASENAME mytad001

  If, for instance, the source directory contains the files cfg001, cfg002 and cfg003, ft_mget creates the local receive files config\copy.cfg001, config\copy.cfg002 and
  config\copy.cfg003.