Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

SQL Anywhere 10.0.1 » MobiLink - Server-Initiated Synchronization » Listener Utility

Listener Utility Next Page

Listener syntax


The Listener utility, dblsn, configures and starts the Listener on Windows devices, including Windows CE.

This section is a detailed reference of the Listener utility. For usage information, see Listeners.

For information about Palm devices, see Listeners for Palm Devices.

Syntax

dblsn [ options ] -l message-handler [ -l message-handler... ]

message-handler :
[ filter;... ]action
[ ;continue = yes ]
[ ;maydial = no ]
[ ;confirm_delivery = no ]

filter :
[ subject = string ]
[ content = string ]
[ message = string | message_start = string ]
[ sender = string ]

action :
action = command[;altaction = command ]

command :
start program [ program-arguments ]
| run program [ program-arguments ]
| post window-message to { window-class-name | window-title }
| tcpip-socket-action
| DBLSN FULL SHUTDOWN

tcpip-socket-action :
socket port=app-port
[ ;host=app-host ]
[ ;sendText=text1 ]
[ ;recvText= text2 [ ;timeout=num-sec ] ]

window-message : string | message-id

Parameters

Options    The following options can be used to configure the Listener. They are all optional.

dblsn options

Description

@data

Reads options from the specified environment variable or configuration file. If both exist, the environment variable is used. See Storing Listener options.

-a option

Specifies a Listener DLL option. If you specify multiple -d options, each -a is for the -d option it follows.

To specify multiple options, repeat -a. For example, -a port=2439 -a ShowSenderPort.

To see options for your dll, enter dblsn -d filename.dll -a ? or see Listening libraries.

-d filename

Specifies the Listener dll that you want to use. The default dll is lsn_udp.dll.

For SMTP gateways, there are several dll's that you can specify. For a list, see Listening libraries.

To enable multi-channel listening, specify multiple dlls by repeating -d. After each -d option, specify the -a and -i options that relate to the dll. For example,

dblsn.exe -d lsn_udp.dll -i 10 -d maac750.dll -i 60

-e device-nameSpecifies the device name. By default, the device name is automatically extracted from the system. If you do not use -e, you must ensure that all devices have unique names.
-f stringSpecifies extra information about the device. By default, this information is the operating system version. Using this option overrides the default value.

-i seconds

Sets the polling interval in seconds for SMTP connections. This is the frequency at which the Listener checks for messages. If you use multiple -d options, each -i setting is for the -d it follows. The default for SMTP is 30 seconds. For UDP connections, the Listener attempts to connect immediately.

-m

Turns on message logging. The default is off.

-niStop tracking UDP addresses when -x is used. This is useful when you do not want device tracking but you do want delivery confirmation. See confirmation_handler property.
-nsFor Windows Mobile 2003 and up Phone Edition, the Listener listens for SMS as well as UDP. It uses a filtering mechanism that runs as a system process, so the filtering continues even when the Listener is not running. This option disables this behavior. When you use -ns, the Listener listens by default on UDP only, and you can use SMS listening by specifying a listening library with the -d option.
-nuDisable default UDP listening.

-o filename

Logs output to a file. If -o is not used, output is logged to the console window.

-os bytes

Specifies a maximum size for the log file in bytes. The minimum size is 10000. By default, there is no limit.

-ot filename

Logs output to file, but deletes the contents first.

-p

Allows automatic idle power-off. This option has an effect only on CE devices. Use it to allow the device to shut down when idle. By default, the Listener prevents the device from shutting itself down so that Listening may continue.

-pc {+|-}Use -pc- to disable persistent connections for receiving notification but continue to use short-lived persistent connections for device tracking and confirmation. By default, persistent connections are enabled (-pc+). If a persistent connection is broken, the Listener attempts to reconnect continuously.

-q

Runs in a minimized window.

-r remote-id-file

Identifies a MobiLink remote database that is involved in the responding action of a message handler. When -r is used, the $remote_id variable can be used in message handlers to refer to the remote ID that is contained in remote-id-file. This option can simplify references to remote IDs, which by default are GUIDs.

If you have multiple databases on the device, you can use this option multiple times.

The remote-id-file is the full path/name of a file that contains the remote ID. This file is automatically created by dbmlsync after the first synchronization. It uses the same location and name as the database file, and has the extension .rid. For UltraLite databases, use the UltraLite database name as the remote ID file.

See Filtering by remote ID.

-t {+|-} ml-user-alias

Register remote databases for notification so that you can address the remote database by name when using device tracking. You can also use the $remote_id variable to identify databases.

See Listener options for device tracking and Action variables.

-u Listener-name

Specifies a MobiLink user name. This name is used when the Listener needs to connect to the MobiLink server, which it does for device tracking, confirmations, and persistent connection.

The default MobiLink user name is device-name-dblsn.

MobiLink user names must be registered with the MobiLink server. See Adding MobiLink user names to the consolidated database.

-v [ level ]

Sets the verbosity level for the dblsn log and console. The level can be 0, 1, 2, or 3:

  • 0 - show no informational messages (the default).

  • 1 - show Listener dll messages, basic action tracing steps, and command line options.

  • 2 - show level 1 plus detailed action tracing steps.

  • 3 - show level 2 plus polling and listening states.

To output notification messages, you must also use -m (see above).

-w password

Specifies a password for the Listener-name.

See Listener options for device tracking.

-x {http|https|tcpip} [(keyword=value;...)]

Specifies the network protocol and protocol options for the MobiLink server. For a list of protocol options, see MobiLink Client Network Protocol Options. A connection to the MobiLink server is required for the Listener to send device tracking information and delivery confirmation to the consolidated database, and for the SYNC gateway.

See Listener options for device tracking.

-y new-password

Specifies a new MobiLink password for the Listener name. If your authentication system allows remote devices to change their passwords, this option lets them send up the new password.

See Listener options for device tracking.

Message-handlers    The -l option allows you to specify a message handler, which is a filter-action pair. The filter determines which messages should be handled, and the action is invoked when the filter matches a message.

You can specify multiple instances of -l. Each instance of -l specifies a different message handler for each incoming message. Message handlers are processed in the order they are specified.

You can also specify the following options for message handlers:

Filters    You specify a filter to compare to an incoming message. If the filter matches, the action you specify is invoked.

The filter is optional. If you do not specify a filter, the action is performed when any message is received. This is useful when debugging or when you want a catch-all message handler as the last message handler.

See Using subject and content filters and Using the filters message, message_start, and sender.

Action and altaction    Each filter is associated with an action and, optionally, an alternative action called the altaction. If a message meets the conditions of the filter, the action is invoked. You must specify an action. If you specify an altaction, the altaction is invoked only if the action fails.

For each action and altaction, there can be one command, and it can be one of start, run, post, socket, or DBLSN FULL SHUTDOWN.

You can only specify one action and one altaction in each instance of -l. If you want an action to perform multiple tasks, you can write a cover program or batch file that contains multiple actions, and run it as a single action.

Following is an example of altaction. In this example, $content is the protocol option for connecting to MobiLink. The primary action is to post the dbas_synchronize Windows message to the dbmlsync_FullSync window. The example uses altaction to start (not run) dbmlsync with the window class name dbmlsync_FullSync if the primary action fails. This is the standard way to make the Listener work with dbmlsync scheduling.

-l "subject=sync;
    action='post dbas_synchronize to dbmlsync_FullSync';
    altaction='start dbmlsync.exe 
                      @dbmlsync.txt
         -wc dbmlsync_FullSync
         -e adr=$content;sch=INFINITE'"
See also

Action variables
Listening libraries