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, use the following command for an integration node called
integrationNodeName:
mqsisetdbparms integrationNodeName -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 integrationNodeName -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 integrationNodeName -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 node.
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:
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, 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, enter 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 node.
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, FTPS, 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, FTPS, 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.