MobiLink Server-Initiated Synchronization User's Guide

The Listener

The Listener utility

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.

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 will send 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.

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.

For information about using the subject or content filters, see Using subject and content filters.

For information about using the message, message_start, or sender filters, see 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.

  "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 window 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 window message by message contents or by the ID of the window 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 window 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';"

  For more information, 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 in order 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 

Listeners

Action variables
Listening libraries

SQL Anywhere Studio 9.0.2
Copyright © 1989–2004 Sybase, Inc. Portions copyright © 2001–2004 iAnywhere Solutions, Inc. All rights reserved.