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

SQL Anywhere 11.0.0 » MobiLink - Server-Initiated Synchronization » Listener utility

 

Listener syntax

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

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-name Specifies 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 string Specifies extra information about the device. By default, this information is the operating system version. Using this option overrides the default value.
-ga

Turns on asynchronous ip tracking.

This option has been deprecated. Asynchronous ip tracking is now implicit.

-gi

Controls the ip tracker polling interval. The default is 60 seconds. This option is ignored if -ga is specified.

This polling mechanism can be used for trouble shooting, however is no longer needed under normal circumstances.

-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.
-ni Stop tracking UDP addresses when -x is used. This is useful when you want device tracking to exclude UDP address updates due to IP address changes.
-np Use to disable persistent connection.
-ns For Windows Mobile 2003 and later 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.
-nu Disables default UDP listening.
-o filename Logs output to a file. If -o is not used, output is logged to the Listener messages 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 message log. 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). See Logging database server messages to a file.

-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:

  • continue=yes   specifies that the Listener should continue after finding the first match. This is useful when you specify multiple -l clauses to cause one message to initiate multiple actions. The default is no.

  • maydial=no   specifies that the action cannot dial the modem. This provides information to the Listener to decide whether to release the modem or not before the action. This option is useful when the action or altaction need exclusive access to the modem used by the Listener. The default is yes.

  • confirm_delivery=no   specifies that this handler should not confirm delivery. A message requires confirmation if the gateway used to send it has its confirm_delivery property set to yes. Delivery can only be confirmed if the message requires confirmation and if the handler accepts the message. The default is yes.

    Normally, you do not need to specify this option. By default the first handler that accepts the message sends delivery confirmation, if required. This option can be used when multiple handlers might accept the same message to give you finer control over which handler should confirm the delivery.

    For information about handling delivery confirmation on the server, see confirmation_handler property.

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.

  • start   spawns a process. When you start a program, the Listener continues listening for more messages.

    When you start a program, the Listener doesn't wait for a return code, so it can only tell that the action has failed if it cannot find or start the program.

    The following example starts dbmlsync with some command line options, parts of which are obtained from the message using the $content action variable.

    "action='start dbmlsync.exe @dbmlsync.txt -n 
      $content -wc dbmlsync_$content -e sch=INFINITE';"

  • run   runs the program and waits for it to finish. The Listener resumes listening after the process is complete.

    When you run a program, the Listener determines that the program has failed if the Listener cannot find or start the program or if it returns a non-zero return code.

    The following example runs dbmlsync with some command line options, parts of which are obtained from the message.

    "action='run dbmlsync.exe @dbmlsync.txt -n $content';"

  • post   posts a Windows message to a window class. This is required by dbmlsync when scheduling is on. Post is also used when signaling applications that use Windows messages.

    You can identify the Windows message by message contents or by the ID of the Windows message, if one exists.

    You can identify the window class by its name or by the title of the window. If you identify the window class by name, you can use the dbmlsync -wc option to specify the window class name. If you identify the window class by its title, only the title of the top level window can be used to identify the window class.

    If there are non-alphanumeric characters such as spaces or punctuation marks in your Windows message or window class name, you can put the message or name in single quotes. In that case, to use a single quote in the string, use two single quotes in a row. For example, to post my'message to my'class, use the following syntax:

    ... -l "action='post my''message to my''class';"

    or

    ... -l "action='post ''my''''message'' to ''my''''class''';"

    The following example posts a Windows message registered as dbas_synchronize to a dbmlsync instance registered with the class name dbmlsync_FullSync.

    "action='post dbas_synchronize to dmblsync_FullSync';"

    See -wc option.

  • socket   notifies an application by making a TCP/IP connection. This is especially useful for passing dynamic information to a running application. It is also useful for integrating with Java and Visual Basic applications, because Java and VB don't support custom window messaging, and eVB doesn't support command line parameters. You can connect to a local socket by specifying just a port, or you can connect to a remote socket by specifying the host along with the port. Using sendText, you can send a string. You can optionally verify that the response is as expected with recvText. When you use recvText, you can also specify a timeout to avoid hanging if the case of application or network problems.

    When you perform a socket action, the Listener determines that the action has failed if it failed to connect, send, or receive expected acknowledgement before timeout.

    The following example forwards the string in $sender=$message to a local application that is listening on port 12345, and expects the application to send back "beeperAck" as an acknowledgement within 5 seconds.

    -l "action='socket port=12345;
       sendText=$sender=$message;
       recvText=beeperAck;
       timeout=5'"

  • DBLSN FULL SHUTDOWN   causes the Listener utility to shut down. After shutdown, the Listener stops handling inbound messages and stops synchronizing device tracking information. The remote user must restart the Listener to continue with server-initiated synchronization. This feature is mostly useful during testing.

    For example, action='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