Writing a file to a remote FTP, FTPS, or SFTP server

Use a FileOutput node to write a file to a directory on a remote FTP, FTPS, or SFTP server.

Before you begin

This example shows you how one combination of values in the Record definition, Delimiter, and Delimiter type properties result in the creation of a file from multiple messages. The example is an extension of the example described in Writing a file to your local file system, and describes the use of a FileOutput node in a message flow.

These instructions assume that you are using a Windows system, and that you have already created a message flow containing a FileOutput node. You also require the following resources:

An FTP or SFTP server. Ensure that an FTP or SFTP server exists with the following settings, so that you can follow this example scenario:

Server

ftpserver.hursley.abc.com

Port

21 (for FTP or FTPS) or 22 (for SFTP)

Working directory

/ftpfileoutput

User ID

myuserid

Password

mypassword

These values are for the purposes of this example only. If you use other values, record them so that you can set the appropriate values when you follow the instructions in this task.
A security identity. Use the mqsisetdbparms command to define a security identity called myidentity for your user and password details.
If you want to connect to an FTP or FTPS server, the security identity must have an ftp:: prefix, to enable the file nodes to find the identity definition. For example:
```
    mqsisetdbparms -w workDir -n ftp::myidentity -u myuserid -p mypassword
```
If you want to connect to an SFTP server, the security identity must have an sftp:: prefix, as shown in the following example:
```
    mqsisetdbparms -w workDir -n sftp::myidentity -u myuserid -p mypassword
```
You can also configure a connection to an SFTP server to use Public Key authentication, by specifying an SSH identity file and pass phrase, instead of a password. For example:
```
    mqsisetdbparms -w workDir -n sftp::myidentity -u myuserid -i identity_file -r passphrase
```
To check what security credentials are already set, use the mqsireportdbparms command; see Checking the password for a resource that is used by an integration server.

For more information about configuring connections to an SFTP server, see Transferring files securely by using SFTP.
The following messages, which must be produced by the message flow preceding the FileOutput node:
- Three input messages. These messages are sent, in this order, to the In terminal of the FileOutput node:
  - Message 1:
```
<Message>test1</Message>
```
  - Message 2:
```
<Message>testtwo</Message>
```
  - Message 3:
```
<Message>testthree</Message>
```
  These messages can be produced, for example, by the XMLNSC domain with a message set that recognizes XML, in the following form:
```
<Message>...</Message>
```
- A final message sent to the Finish File terminal of the FileOutput node after the first three messages have been sent:
```
<thiscanbe>anything</thiscanbe>
```

Complete the following steps:

Procedure

Set the required node properties on the FileOutput node.

The following table summarizes the FileOutput node properties that you must set, the tabs on which they are displayed, and the values that are used in this example:

Tab	Property	Value
Basic	Directory	C:\FileOutput\TestDir
	File name or pattern	test_output1.xml
	Mode for writing to file	Stage in transit directory and move to output directory on Finish File
	Action if file exists	Time Stamp, Archive and Replace Existing File
	Replace duplicate archive files	Selected
Records and Elements	Record definition	Record is Delimited Data
	Delimiter	Broker System Line End
	Delimiter type	Postfix
FTP	Remote transfer	Selected
	Transfer protocol	FTP, or SFTP, or FTPS
	Remote server and port	ftpserver.hursley.abc.com
	Security identity	myidentity
	Server directory	/ftpfileoutput
	Transfer mode	ASCII (for FTP only)
	Action if remote file exists	Replace Existing File or Append to Existing File
	Retain local file after transfer	Selected

If you used other values for your FTP, FTPS, or SFTP server resource, use those values. The settings used here are identical to those settings used in the example in Writing a file to your local file system except that the Remote transfer property has been selected and there are now properties on the FTP tab. If you clear the Remote transfer property, the node operates as it does in the example in Writing a file to your local file system; the properties on the FTP tab remain set but are ignored.

You can override the Remote server and port property on the node by setting a value in the local environment. For more information, see Local environment overrides for the remote server on the FileOutput node.

Deploy the message flow to the integration server. See Deploying integration solutions.
Send the first three messages to the In terminal of the FileOutput node.
Send the final message to the Finish File terminal of the FileOutput node.
If the remote file exists, the mode for writing to remote file is used to specify if the file transferred replaces an existing file or appends data to the existing file. The transfer happens on the Finish File action. To support the use of Append you might have to update your FTP server configuration.

Results

The following actions occur when you perform these steps:

The file is processed. The FileOutput node generates one record per message with a local file system line terminator after each one. The file contains the following data, with each line terminated by a carriage return (X'0D') and line feed (X'0A') pair of characters (on a Windows system):
```
<Message>test1</Message>
<Message>testtwo</Message>
<Message>testthree</Message>
```
Records are accumulated in file test_output1.xml in the C:\FileOutput\TestDir\mqsitransit directory. When the final message is sent to the Finish File terminal, the file is moved to the remote FTP or SFTP server directory (because the Remote transfer property is selected). As a result, the file /ftpfileoutput/test_output1.xml is created.
If a file with the same name exists in the remote FTP or SFTP server directory, the existing file is overwritten.
If the remote FTP or FTPS server is not running on a Windows system and the Transfer mode property is set to ASCII, the character encoding and line terminator characters might be modified after transfer. For example, on a z/OS® FTP server, the ASCII text is typically converted to EBCDIC, and the line terminator character pairs are replaced by EBCDIC new line characters (X'15'). Other FTP or FTPS servers might treat ASCII transfers differently. If you are using SFTP, the Transfer mode property is ignored and files are sent as Binary files.
Because the Retain local file after transfer property is selected, the local file is not deleted but is moved from the mqsitransit subdirectory to the output directory, C:\FileOutput\TestDir. If a file with the same name exists in the output directory, the existing file is renamed and moved to the mqsiarchive directory. For example, the following file might be created:
C:\FileOutput\TestDir\mqsiarchive\20081124_155346_312030_test_output1.xml
However, if a file with this name exists in this archive directory, it is overwritten according to the value of the Replace duplicate archive files property set on the FileOutput node.

What to do next

For more information, see Setting the Record definition property for the FileOutput and FTEOutput nodes, which shows the results of running this task with different values set in the Record definition, Delimiter, and Delimiter type properties of the FileOutput node.