Parameters 

Options    The following options can be used to configure the Listener. If you are creating a configuration file for a Palm device, you must use -n. The rest are optional.

-l message-handler    -l allows you to specify a message handler, which is a filter-action pair. The filter determines which message 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.

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

There are three types of filter you can specify:

The filter is optional. If you do not specify a filter, the action is performed when any message is received.

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. Palm devices do not recognize altaction.

The action and altaction are specified as { action | altaction }= command. 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.

  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 
    $message_end -wc dbmlsync_$message_end -e sch=INFINITE"

• run    runs the program and waits for it to finish. The Listener resumes listening after the process is complete. You cannot use run on Palm devices.

  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 $message_end"

• post    posts a message to a window class. This is required by dbmlsync when scheduling is on. Use the dbmlsync -wc option to specify the window class name. Post is also used when signaling applications that use Windows messages. You cannot use post on Palm devices.

  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

• socket    notifies an application by making a TCP/IP connection. This is especially useful for Java and eMbedded Visual Basic applications, because Java and eVB 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.

  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.

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

• DBLSN FULL SHUTDOWN    After shutdown, the Listener stops handling inbound messages. The remote user must restart the Listener in order to continue with server-initiated synchronization. This feature is mostly useful during development.

  For example, action='DBLSN FULL SHUTDOWN'

You can also specify the following action options:

• continue {yes|no}    specifies whether 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. This option is not recognized by Palm devices. The default is no.

• maydial {yes|no}    specifies whether the action can 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. This option is not recognized by Palm devices. The default is yes.

The escape character for action and altaction is a dollar sign ($), so to specify a single dollar sign as plain text, type $$.

The Listener determines that an action has failed (and then invokes the altaction) in the following ways:

• When you run a program, the Listener determines that the program has failed if the program doesn't exist or if it returns a non-zero return code.

• 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 the program does not exist.

• When you post to a window class, the Listener determines that the action has failed if no window class has been registered with the given name or the operating system has reported that the post failed.

• 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.

You can only specify one action and one altaction in each instance of -l. You can also write a cover program or batch file that contains multiple actions, and run it as the action.

Following is an example of the specification of altaction. In this example, the $message_end that matches the filter is the stream parameter 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 "message_start=[sync];
    action='post dbas_synchronize to dbmlsync_FullSync';
    altaction='start dbmlsync.exe 
                        @dbmlsync.txt
                 -wc dbmlsync_FullSync
                 -e adr=$message_end;sch=INFINITE'"

Action variables 

The following Listener action variables can be used anywhere in the action or altaction.

An action variable is replaced just before the action or altaction is performed.

Listener action variables start with a dollar sign ($). The escape character is also a dollar sign, so to specify a dollar sign as plain text, type $$. For example, type $$message_start when you don't want $message_start to be substituted.