Skip to end of metadata
Go to start of metadata

Purpose

The purpose of this page is to describe how to use the mlfiletransfer utility. Another possible alternative for file transfer that uses the MobiLink Agent, which is part of the central administration of remote databases feature is also discussed.

Overview

The MobiLink file transfer utility (mlfiletransfer) is used to upload or download files through MobiLink. It is particularly useful when remote devices are first created or when software updates are required on the remote devices.

This document assumes there is already a working MobiLink environment set up for synchronization. Tutorials about how to set up a MobiLink synchronization environment can be found in the Related Documents section.

Using the MobiLink File Transfer Utility

Configuring the MobiLink Server

To use the mltransfer utility, the MobiLink server must be configured with options that specify root directories for the files to be transferred.

If the utility is to be used to download files, then the MobiLink server must be started with the -ftr option. If the utility is to be used to upload files, then the MobiLink server must be started with the -ftru option. The MobiLink server can be started with one of the options individually or with both options applied.

-ftr mlsrv16 option

This option specifies a location for files to be downloaded by the mlfiletransfer utility by setting the root directory. Within the root directory, the files to be downloaded can be placed directly in the root or within a subdirectory of the username of the specific client. MobiLink first looks in this subdirectory for the matching client username and if the file cannot be found there, then it searches the main root directory for the file. This behavior can be overridden using the authenticate_file_transfer connection event to implement a custom subdirectory or a custom file name within the root directory. More information about this connection event can be found in the Related Documents section.

mlsrv16 -c "connection-string" -ftr "path"

-ftru mlsrv16 option

This option specifies a location for files uploaded by the mlfiletrasfer utility by setting the root directory. Within the root directory, the files to be uploaded can only be placed directly in the root or within its immediate subdirectories. These subdirectories match the username of the remote user from which the file was uploaded and are created automatically by the utility. This behavior can be overridden using the authenticate_file_upload connection event to implement a custom subdirectory or a custom file name within the root directory. More information about this connection event can be found in the Related Documents section.

mlsrv16 -c "connection-string" -ftru "path"

Note that the directory specified by the -ftr and -ftru options must already be created before attempting to start the MobiLink server. The following error appears if the specified directory is not there:

Using the mlfiletransfer Utility

The mlfiletransfer utility is operated directly from the console of the remote devices. Basic syntax follows the following format:

mlfiletransfer [optionsfile

For standard operation of the utility, three options are required for it to work properly. The required options are the following:

OptionDescription

-u
Username

MobiLink username. This option is required. Usually a password is also required to be specified for a given username and this can be added using the -p option followed by the password. However, this is not required.

-v
 Version

The script version. This option is required. If you are unsure of the script version, check the ml_script_version table at the consolidated database.

-x
Protocol

The protocol can be one of tcpip, tls, http or https. This option is also required. A list of protocol options can be found in the Related Documents section.

Use the -s option to upload a file to MobiLink. The download option is the default and does not require an extra option to be used. After specifying the options for mlfiletransfer, specify the name of the file you want to download/ upload. A full list of options for the mlfiletransfer utility can be found in the Related Documents section.

Examples

Downloading a File to a Remote Device

  1. Create a text file called testfile.txt to download and place it in the root directory that you will specify using the -ftr option in Step 2.
  2. Use the -ftr option when starting the MobiLink server to specify a root directory.
         mlsrv16 -c "DSN=cons_sqla16" -ftr "c:\filesynch\download"
  3. At the remote device, start the mlfiletransfer utility using the proper options as specified above. (The user may require a password (-p), script version (-v) and you can use the -g option to monitor transfer progress.)
         mlfiletransfer -g -u "rem1" -p "sql" -v "v1" -x tcpip testfile.txt
  4. The utility then looks in the root directory specified by the -ftr option on the MobiLink server in a subdirectory named rem1 watching the remote username, and downloads the file to the remote device.

Uploading a File from a Remote Device

  1. Create a text file called testfile.txt to upload and place it in the root directory that you will specify using the -ftru option in Step 2.
  2. Use the -ftru option when starting the MobiLink server to specify an upload directory.
         mlsrv16 -c "DSN=cons_sqla16" -ftru "c:\filesynch\upload"
  3. At the remote device, start the mltransfer utility using the proper options as specified above. Note that for upload the -s option must be used.
         mlfiletransfer -s -g -u "rem1" -p "sql" -v "v1" -x tcpip testfile.txt
  4. The utility looks for the file at the remote and uploads it to the directory specified by the -ftru option on the MobiLink server in a subdirectory named rem1, matching the username of the remote from which the file was uploaded.

Downloading or Uploading an Existing File

If an attempt is made to upload or download a file that already exists, it is overwritten with the newest version of the file without prompting, and the file transfer proceeds reguarly, as above.

If the file has not changed since the last upload or download, the following message is displayed:

Using the MobiLink Agent

The MobiLink Agent can be used as an alternative to the mlfiletransfer utility. The Mobilink Agent is used as a part of a new central administration of remote databases feature that provides a means to centrally manage the entire life cycle of a remote database. While this does include the upload and download of files, this is a small part of what this feature provides. other uses of the central administration of remote databases feature are:

  • Database initialization
  • Schema upgrades
  • Synchronization times
  • Diagnosing and troubleshooting issues
  • Executing SQL
  • Running programs
  • Copying, creating, or deleting files
  • Dropping databases

More information regarding the central administration of remote databases can be found in the Related Documents section.

This section outlines the basic methods of using the MobiLink Agent to transfer files. It does not go into too many details about central administration and assumes a general understanding of these central administration topics.

Configuring the MobiLink Server

The MobiLink server is configured in the same way as it is for using the mlfiletransfer utility. The -ftr and -ftru options must be specified so that the MobiLink Agent knows where to look for files when executing downloads as part of a remote task, and where to upload files when executing uploads.

Configuring the MobiLink Agent

The MobiLink Agent manages remote tasks on a remote device. It synchronizes tasks to be executed from the consolidated database and stores them in the agent database at the remote device. For an overview of the communication between the consolidated database, MobiLink server, agent database, MobiLink Agent, and remote database, go to the Related Documents section.

The Agent is started at the remote using the mlagent command. The Agent must first be configured using the -c option (this boots up the Agent, configures it, then shuts it down) along with the specific options that need to be configured. Then the Agent can be started once again. For a detailed list of mlagent options, see the Related Documents section. 

Configuring the mlagent

mlagent -c -a AID_rem1 -x tcpip{host=localhost;port=xxxx}

Running the mlagent

mlagent -u rem1 -p rem1 -o file.txt

Here is a brief overview of the command line options used above:

OptionDescription
-cRuns the Agent in configuration mode.
-a agentidSpecifies the ID of this Agent.
-x protocol (options)Specifies the MobiLink stream parameters. The protocol can be one of tcpip, tls, http or https. This option is required.
 -u user Specifies the MobiLink user name used to synchronize the agent database.
 -p password Specifies the MobiLink password used to synchronize the agent database.
 -o file Specifies an output log file.

Creating the Download Remote Task

In Sybase Central, under the MobiLink Project in the MobiLink 16 plug-in, right-click Remote Tasks and choose New > Remote Task.

This opens the Create Remote Task Wizard. Work through the wizard, specifying the following:

  • The remote task name
  • Trigger task when it is received by the agent
  • Other settings are optional

Set Download file as the command type for the task. The server file name identifies the name of the file on the server to download to the remote device that has been placed in the root directory specified on the MobiLink server startup by the -ftr option. For server file name, it is possible to specify a single subdirectory (subdir|testfile.txt), as well as to use a variable ({ml_username}|testfile.txt). The remote file name specifies the location on the remote device where the file is to be stored.

After filling in this information, right-click the task and then click Deploy.

This opens the Deploy Remote Task Wizard. Work through the wizard, specifying the following:

  • The consolidated database
  • The agents that will receive this remote task
  • When the task should be sent to the agents
  • Choose your preferred method of reporting the results and status of the task

The next time the corresponding Agents attempt to synchronize with the consolidated, they will synchronize this task into their agent database and execute the task, depending on the specific options used to creat ethe task.

To upload a file from the remote device, follow the same procedure, setting Upload file as the command type for the task. Using a variable in the server file name filed for upload tasks is especially useful because it allows multiple remotes to utilize the same task, uploading their files into different directories. If the directory was hard-coded in this case, the file would simply get overwritten every time a new remote executed the task.

A Brief Comparison

While both methods of file transfer provide the same end results with regard to the upload and download of files through MobiLink, they offer very different possibilities to the user.

The MobiLink Agent allows for the deployment of files to a large number of remote devices from the consolidated, while only one remote task needs to be created. Direct access to the remote devices is not required. Using the mlfiletransfer utility, you must have specific access to the remote console and can only upload or download files at one remote device at a time, since each mlfiletransfer command must be run individually at the remote.

In terms of setup, the MobiLink Agent requires a much more in-depth implementation to be completed for the remote tasks to run properly, the main thing being the proper setup of remote Agents and remote schema names. The mlfiletransfer utility provides a quick way to transfer files without much added configuration.

In the end, if all that is needed is simple file transfer to a small number of remote devices, then the mlfiletransfer utility is most likely your best option. However, if a greater range of remote administration would be beneficial or direct access to the remote devices is not possible, then the central administration of remote databases feature can provide a solution along with a large array of other possibilities.

Related Content

Related Documents

MobiLink tutorials

MobiLink File Transfer utility (mlfiletransfer)

authenticate_file_transfer connection event

authenticate_file_upload connection event

MobiLink client network protocol options

Central administration of remote databases

MobiLink Agents

mlagent command

WIKI: Centralizing Your Remotes for Synchronization

Related SAP Notes/KBAs

 

  • No labels