fteCreateLogger: create an MFT file or database logger

Use the fteCreateLogger command to create a Managed File Transfer file or database logger.

Important: On IBM MQ for Multiplatforms, only users who are IBM MQ administrators (and members of the mqm group) can run this command. If you try to run this command as a user who is not an IBM MQ administrator, we will receive the error message BFGCL0502E: You are not authorized to perform the requested operation. and the command will not run. On z/OS systems, the user must satisfy (at least) one of these conditions in order to run the migrate command:

Be a member of the mqm group (if the mqm group is defined on the system).
Be a member of the group named in the BFG_GROUP_NAME environment variable (if one is named).
Have no value set in the BFG_GROUP_NAME environment variable when the command is run.

Purpose

The fteCreateLogger command is supported on IBM WebSphere MQ Version 7.5 and later.

The fteCreateLogger command provides you with the MQSC commands that we must run against your logger command queue manager to create the following logger queues:

SYSTEM.FTE.LOG.CMD.logger_name
SYSTEM.FTE.LOG.RJCT.logger_name

These queues are internal system queues that we must not modify, delete, or read messages from unless we are deleting the logger. The MQSC commands to run are also supplied in a file in the following location: MQ_DATA_PATH\mqft\config\coordination_qmgr\loggers\logger_name\logger_name_create.mqsc

If you later want to delete the logger, use the fteDeleteLogger command.

Managed File Transfer provides advanced logger properties that help you configure loggers. See, MFT logger configuration properties

Note: If the logger we are creating is a database logger and it is not connecting to a local Db2 database, we will need to manually create a MQMFTCredentials.xml file. The file contains the user name and password for connecting to the database. We should use the property file, wmqfte.database.credentials, in the logger.properties file to specify the path to the MQMFTCredentials.xml file. A sample of this credentials file is located in MQ_INSTALLATION_PATH/mqft/samples/credentials/.

Special characters

Take care when we use parameter values that contain special characters so that you avoid the command shell interpreting the characters in a way we do not expect. For example, fully qualified file paths and names that contains such characters as space, quotation mark (single or double), forward-slash or back-slash characters, might be interpreted by the command shell rather than being passed through directly to the command itself. To avoid characters being interpreted by the command shell, enclose the entire parameter in double/single quotation marks or escape the special characters by using the escape sequence of the command shell.

Syntax

fteCreateLogger

DATABASE options

FILE options

Windows system options

Parameters for MQ security

Parameters

-loggerType (type)

Required. Specifies where managed file transfer information will be logged. The options for type are either DATABASE, if transfer information will be logged to a database, or FILE, if the information will be logged to a file.

-loggerQMgr (qmgr_name)

Optional. Determines the queue manager to connect to in order to receive messages containing information about managed file transfers. The queue manager must be on the same system as the logger. If we do not specify the -loggerQMgr parameter then the coordination queue manager that is associated with the configuration options set for this logger is used as the default.From IBM MQ Version 9.1, if the coordination queue manager connects using a clients mode connection, the logger uses clients mode. Attention: The loggerQmgrHost, loggerQmgrPort, and loggerQmgrChannel parameters are valid on a File logger only.If you attempt to use any one, or more, of these parameters on a Database logger, you receive the following message:

BFGCL0456E: The parameter '-loggerQMgrHost' is not valid for the fteCreateLogger command.

-dbType (database_type)

Required when -loggerType is DATABASE. Specifies the type of database management system in use for storing managed file transfer information. The options are db2 or oracleNote: We need to create tables by using SQL files. The .sql files are available from MQ_INSTALLATION_PATH_/mqft/sql:

For Db2 databases: ftelog_tables_db2.sql
For Oracle databases: ftelog_tables_oracle.sql

-dbName (database_name)

Required when -loggerType is DATABASE. The name of the database where managed file transfer information is stored. The database must be configured with the Managed File Transfer log tables.

-dbDriver (driver)

Required when -loggerType is DATABASE. The location of the JDBC driver classes for the database. This is typically the path and file name of a JAR file.

-dbLib (path)

Optional when -loggerType is DATABASE. The location of any native libraries needed by your chosen database driver.

-fileLoggerMode (mode)

Required when -loggerType is FILE. Specifies the type of file system in use for storing managed file transfer information. The options are LINEAR or CIRCULAR.

Option LINEAR means the file logger will write information to a file until that file reaches its maximum size as defined by -filesize. When the maximum size is reached the file logger will start a new file. Previously written files will not be deleted which allows them to be kept as a historical record of log messages. Files are not deleted when running in this mode, so the -fileCount will be ignored as there is no upper limit to the number of files that can be created. As there is no upper limit when running in this mode it will be necessary to track the amount of disk space used by the log files in order to avoid running low on disk space.

Option CIRCULAR means the file logger will write information to a file until that file reaches its maximum size as defined by -fileSize. When the maximum size is reached the file logger will start a new file. The maximum number of files written in this mode is controlled by the value defined using the -fileCount. When this maximum number of files is reached the file logger will delete the first file and re-create it for use as the currently active file. If the value defined in the -fileSize is a fixed size byte unit, the upper limit on the disk space used in this mode will equal fileSize x fileCount. If the values defined in -fileSize are a time unit, the maximum size will depend on the throughput of log message in the system over these time periods.

For more information, see MFT logger configuration properties

-fileSize (size)

Required when -loggerType is FILE. The maximum size that a log file is allowed to grow to. The value is a positive integer, greater than zero, followed by one of the following units: KB, MB, GB, m (minutes), h (hours), d (days), w (weeks). For example: -fileSize 5MB (specifies a maximum size of 5MB), -fileSize 2d (specifies a maximum of 2 days worth of data).

-fileCount (number)

Required when -loggerType is FILE and -fileLoggerMode is CIRCULAR. The maximum number of log files to create. When the amount of data exceeds the maximum amount that can be stored in this number of files, the oldest file is deleted so that the number of log files never exceeds the value specified in this parameter.

-loggerQMgrHost

Host name, or IP address, of the machine where the logger queue manager is running.

The default value is None.

If we do not specify the -loggerQMgrHost parameter, the logger is created in bindings mode.

-loggerQMgrPort

Port number where the logger queue manager is listening.

The default value is 1414.

-loggerQMgrChannel

Name of the channel used for connecting to the logger queue manager.

The default value is SYSTEM.DEF.SVRCONN.

-s (service_name)

Optional (Windows systems only). Indicates that the logger is to run as a Windows service. If we do not specify service_name, the service is named mqmftLoggerLOGGERQMGR, where LOGGER is the logger name and QMGR is your logger queue manager name.

The display name for the service, which is shown in the Windows Services window in the Name column, is always Managed File Transfer Logger LOGGER@QMGR.

-su (user_name)

Optional (Windows only). When the logger is to run as a Windows service, this parameter specifies the name of the account under which the service runs. To run the logger using a Windows domain user account specify the value in the form DomainName\UserName. To run the service using an account from the local built-in domain specify the value in the form UserName.

The Windows user account that you specify using the -su parameter must have the Log on as a service right. For information about how to grant this right, see Guidance for running an MFT agent or logger as a Windows service.

Required when -s specified. Equivalent to -serviceUser.

-sp (password)

Optional (Windows only). Password for the user account set by -su or -serviceUser parameter.

This parameter is only valid when -s is specified. Equivalent to -servicePassword. If we do not specify this parameter when you specify the -s parameter, a warning message is produced. This message warns you that you must set the password using the Windows Services tool before the service starts successfully.

-sj (options)

Optional (Windows only). When the logger is started as a Windows service, defines a list of options in the form of -D or -X that are passed to the JVM. The options are separated using a number sign (#) or semicolon (;) character. If we must embed any (#) or semicolon (;) characters, put them inside single quotation marks.

This parameter is only valid when -s is specified. Equivalent to -serviceJVMOptions.

-sl (options)

Optional (Windows only). Sets the Windows service log level. Valid options are: error, info, warn, debug. The default is info. This option can be useful if we are having problems with the Windows service. Setting it to debug gives more detailed information in the service log file.

This parameter is only valid when -s is specified. Equivalent to -serviceLogLevel.

-p (configuration options)

Optional. Specifies the set of configuration options that is used to create the logger. By convention, this value is the name of a coordination queue manager. If we do not specify this parameter, the default set of configuration options is used.

-f

Optional. Forces the command to overwrite the existing configuration.

(logger_name)

Required. Name of the logger to create. This is incorporated into Managed File Transfer queue names, and so must contain only letters, numbers, and the periods (.) and underscore characters (_). It is also limited to a maximum length of 28 characters.

-credentialsFile (filePath)

Optional. The full file path of an existing or new credentials file, to which the IBM MQauthentication details are added.

This command supports the addition of a set of IBM MQ authentication details, to a named Managed File Transfer credentials file. Use this command when IBM MQ connection authentication has been enabled. If you update the existing details, we must use the -f force parameter.

-userid (username)

Optional. The user ID used to associate the credential details. If we do not specify a user ID, the credential details will apply to all users. We must also specify the -credentialsFile parameter.

-? or -h

Optional. Displays command syntax.

Examples

In this example, a circular file logger is created called filelogger1. The file logger will create a maximum of 10 files, each file being 10MB in size, using a maximum of 100MB of disk space in total:

fteCreateLogger -loggerType FILE -fileLoggerMode CIRCULAR -fileSize 10MB -fileCount 10 filelogger1

In this example, a database logger is created called dblogger1. The database logger connects to a Db2 database called FTEDB:

fteCreateLogger -loggerType DATABASE -dbName FTEDB -dbType DB2 
    -dbDriver "C:\Program Files (x86)\IBM\SQLLIB\java\db2jcc4.jar" dblogger1

In this example, a database logger is created called dblogger1. The database logger connects to a an Oracle database called FTEDB:

fteCreateLogger -loggerType DATABASE -dbName FTEDB -dbType oracle 
    -dbDriver "C:\app\oracle\product\12.1.0\dbhome_2\jdbc\lib\ojdbc7.jar" dblogger1

In this example, a client mode file logger is created, using the host name and default port and channel:

fteCreateLogger -loggerType FILE -loggerQMgr CORDQM -loggerQMgrHost cordqm.ibm.com 
-fileLoggerMode CIRCULAR -fileSize 10MB -fileCount 10 FL1

In this example, a client mode file logger is created, using the host name, port, and channel:

fteCreateLogger -loggerType FILE -loggerQMgr CORDQM -loggerQMgrHost cordqm.ibm.com 
-loggerQMgrPort 4444 -loggerQMgrChannel LOGGER_CHANNEL -fileLoggerMode CIRCULAR -fileSize 10MB 
-fileCount 10 FL1