Providing your own error-handling logic

Frequently, error messages require that you take action to resolve the problem indicated in the message text. To simplify day-to-day synchronization management, you might choose to add your own logic to automatically perform these actions when a particular error message is issued.

Procedure

  1. To define automatic processing of errors: Using a text editor of your choice, open the following file for editing: 
    DSYUserExits.properties
    This file associates a message number with a routine or program that runs when the message number is written to the log. This properties file supports many different parameters. 
    # Formats:
# {DSY message id}={class to execute} {environment parameters}
# {DSY message id}={command to execute} {environment parameters}
#   where
#     {DSY message id}:
#       a DSY* message id that you want to define a user exit for (such as 
#       DSYD000E)
#     {class to execute}:
#       the name the Java .class to execute. This class must implement the
#       com.ibm.mobileservices.DSYUserExitsInterface
#     {command to execute}:
#       the name the command to execute (such as pager.exe)
#     {environment parameters}:
#       a series of parameters to pass in to the class or command to execute
#
#   Optional command tags:
#     <DSYID>            = the message id
#     <DSYIDMSG>         = the message id message text
#     <DSYIDMSG_>        = the message id message text, but all blanks are 
#                          converted to underscores
#     <DSYMSG>           = the message text
#     <DSYMSG_>          = the message text, but all blanks are converted to 
#                          underscores.
#     <SERVER_IPADDRESS> = the server ip address (such as 9.112.19.143)
#     <SERVER_NAME>      = the server name (such as mpauser.stl.ibm.com)
#
# Refer to the messages section for available DSY message ids.
#
# Example 1:
#   If you wanted to have user exists for DSYD000E, you would add a line 
#   similar to the following:
#
# DSYD000E=pager.exe number=5551234 id=<DSYID> msg=<DSYMSG_>
#
# When a DSYD000E message was issued, the pager.exe command would be executed
# with two environment parameters would be set: number=5551234, id=DSYD000E
# and msg=DSY message text, substituting an underscore (_) for blanks.
#
# Example 2:
#   If you wanted to have a class executed when a DSYD020E was encountered,
#   you would add a line similar to the following:
#
# DSYD020E=com.ibm.mobileservices.DSYUserExitsSample.class
#
# When a DSYD020E was issued, the com.ibm.mobileservices.DSYUserExitsSample 
# class would be executed.
  2. At the end of the file, pair a message number with an action to be performed when that message is written to the log. The action can be a command (such as an executable or batch file) or a Java class. Use the following format: 
    message_number=action parameter=value
    where:

    message_number
    The number of the message. See Error messages for message numbers and their associated text.

    action
    The file referencing the command or Java class that is called. The Java class must implement the com.ibm.mobileservices.DSYUserExitsInterface.

    parameter=value
    A series of parameter sets (such as lastname=Doe firstname=John), with each set separated by a space.

    The action to be performed must be a reference to a valid routine or program.

For example, suppose that you want to include a user exit that pages you when message DSYD000E is issued. You could write a program called pager.exe that dials your pager, and includes the pager number as a parameter. The line in the DSYUserExits file might look something like this: 

DSYD000E=pager.exe number=9980674

You can also include the following parameters and variables with the command:

ID
Use this parameter to write the number of the message. For the parameter value, specify the variable DSYID.

MSG
Use this parameter to write the message text. For the parameter value, specify DSYMSG to write the actual message text, or DSYMSG_ to write the message text, but convert all blank spaces in the text to underscore characters.

The following example dials the same pager, but submits both the message number and its text as parameters so they appear in the pager window: 

DSYD000E=pager.exe number=9980674 id=dsyid msg=dsymsg

The Sync Server does not check the validity of your entries in the DSYUserExits properties file, nor does it validate that the action associated with the message has been completed.

Use the DSYUserExitsTest.bat file tool to test a user exit routine. Use the following format to test: 

DSYUserExitsTest.bat dsy_message_id

where dsy_message_id is the message number you want to simulate. If you do not provide a message ID, a list of available message IDs is displayed.

Example command with message id DSYS001I: 

DSYUserExitsTest.bat dsys001i

The DSYS001I message is generated and the user exit defined for this message number is started.

Example command with an invalid message number: 

DSYUserExitsTest.bat zzz

The output from the DSYUserExitsTest tool is: 

DSYUserExitsTest
    DSY message id 'ZZZ' not found. Valid DSY message id's are: 
DSYA000E, DSYA001E, DSYD000E, DSYD002E, DSYD006E, DSYD007E, ...

Related concepts

Related tasks