User's Guide

Part III. Using SQL Anywhere

Chapter 28. SQL Remote Administration

You need to define the message types you will use for sending messages before you add remote users to your database.

Supported message types

SQL Remote supports a set of message links. The links currently supported include:

• FILE The FILE link: storage of message files in directories on a shared file system for reading by other databases.
• MAPI Microsoft's messaging API (MAPI) link, used in Microsoft Mail and other electronic mail systems.
• VIM Lotus's Vendor Independent Messaging (VIM), used in Lotus Notes and cc: Mail.
• SMTP Internet Simple Mail Transfer Protocol (SMTP/POP), used in Internet e-mail.

The links are implemented as DLLs on Windows 3.x, Windows 95, Windows NT, and OS/2. The Message Agent for NetWare, DOS and QNX supports the FILE link only, as a compiled library.

Supported message types

This section describes the message types supported by SQL Remote.

The MAPI message system

The Message Application Programming Interface (MAPI) is used in several popular e-mail systems, such as Microsoft Mail. SQL Remote supports the MAPI message system under Windows 3.x, Windows 95, and Windows NT.

To use SQL Remote and a MAPI message system, each database participating in the setup requires a MAPI user ID and address. These are distinct identifiers: the MAPI address is the destination of each message, and the MAPI user ID is the name entered by a user when they connect to their mail box.

Although SQL Remote messages may arrive in the same mail box as e-mail intended for reading, they do not show up in your e-mail inbox. SQL Remote sends application-defined messages, which MAPI identifies and hides when the mailbox is opened. In this way, users can use the same e-mail address and same connection to receive their personal e-mail and their database updates, yet the SQL Remote messages do not interfere with the mail intended for reading.

One exception to this is if a message is routed via the Internet, in which case the special message type information is lost. The message then does show up in the recipient's mailbox.

The FILE message system

SQL Remote can be used even if you do not have a message system in place, by using the FILE message link.

The FILE message link is a file-sharing system. A FILE address for a remote user is a subdirectory into which all their messages are written. To retrieve messages from their "inbox", the user reads the messages from the directory containing their files. Return messages are sent to the address (written to the directory) of the consolidated database.

The FILE link addresses are typically subdirectories of a shared directory that is available to all SQL Remote users, whether by modem or on a local area network. Each user should have a registry entry or SQLREMOTE environment variable pointing to the shared directory.

You can also use the FILE link to put the messages in directories on the consolidated and remote machines. A simple file transfer mechanism can then be used to exchange the files periodically to effect replication.

The VIM message system

The Vendor Independent Messaging system (VIM) is used in Lotus cc: Mail and Lotus Notes.

To use SQL Remote and a VIM message system, each database participating in the setup requires a VIM user ID and address. These are distinct identifiers: the VIM address is the destination of each message, and the VIM user ID is the name entered by a user when they connect to their mail box.

VIM messages do appear in your mailbox along with mail intended for reading.

The SMTP message system

The Simple Mail Transfer Protocol (SMTP) is used in Internet e-mail products.

To use SQL Remote and a SMTP message system, each database participating in the setup requires a SMTP user ID and address. These are distinct identifiers: the SMTP address is the destination of each message, and the SMTP user ID is the name entered by a user when they connect to their mail box.

SMTP messages do appear in your mailbox along with mail intended for reading.

Specifying a message type

To specify a message type for a database, you need to specify a message link, and also an address, under that link, for the publisher user ID of the database.

The publisher address at a consolidated database is used by the database extraction utility as a return address when creating remote databases. It is also used by the Message Agent to identify where to look for incoming messages for the FILE link.

The SQL statement to create a message type has the following syntax:

     CREATE REMOTE MESSAGE TYPElink-name
          ADDRESSaddress-string

where link-name is one of the message links supported by SQL Remote, and address-string is the publisher's address under that message link.

The SQL statement to alter the publisher's address for a message type has the following syntax:

     ALTER REMOTE MESSAGE TYPElink-name
          ADDRESSnew-address-string

The SQL statement to drop a message type has the following syntax:

     DROP REMOTE MESSAGE TYPElink-name

You can create and alter message types in Sybase Central. The Message Type folder is inside the SQL Remote folder.

The address supplied with a message type definition is closely tied to the publisher ID of the database. This is discussed further in the following section.

Message link control parameters

Each message link has several parameters that govern aspects of its behavior. This section documents these parameters.

Where the parameters are held

The message link control parameters are stored in the registry under Windows NT and Windows 95, and in SQLANY.INI under Windows 3.x.

FILE message control parameters

The FILE message system uses the following control parameters:

• Directory This is set to the of the directory under which the messages are stored. The setting is an alternative to the SQLREMOTE environment variable.
• Debug This is set to either YES or NO, with the default being NO. When set to YES, all file system calls made by the FILE link are displayed.

The FILE section of the SQLANY.INI file (Windows 3.x) has the following entries:

     [FILE]
     Directory=path
     Debug=yes | no

On NetWare, you should create a file named DBREMOTE.INI in the SYS:\SYSTEM directory to hold the directory setting.

MAPI message control parameters

The MAPI message system uses the following control parameters:

• IPM_Send This can be set to YES or NO (default NO). If set to YES, the MAPI link sends IPM messages, which are visible in the mailbox. If set to NO, the MAPI link sends IPC messages, which are not visible in the mailbox. This may be useful if your MAPI provider does not support IPC messages.
• IPM_Receive This can be set to YES or NO (default NO). If set to YES, the MAPI link receives IPM messages, which are visible in the mailbox. If set to NO, the MAPI link receives IPC messages, which are not visible in the mailbox. This may be useful if your MAPI provider does not support IPC messages. Also, it may be useful when receiving messages over the Internet. In this case, the sender might not be using MAPI or the IPC attributes are have been lost.
• Force_Download (default YES) controls if the MAPI_FORCE_DOWNLOAD flag is set when calling MapiLogon. This might be useful when using remote mail software that dials when this flag is set.
• Debug When set to YES, displays all MAPI calls and the return codes. This is useful for troubleshooting MAPI support problems. Default is NO.

The MAPI section of the SQLANY.INI file (Windows 3.x) has the following entries:

     [MAPI]
     IPM_Send=yes | no
     IPM_Receive=yes | no
     Force_Download=yes | no
     Debug=yes | no

SMTP message control parameters

The SMTP message system uses the following control parameters:

• smtp_host The name of the computer on which the SMTP Server is running.
• smtp_address The return address if the mail cannot be delivered. If the address of a subscriber database is wrong the mail may be sent but later returned to this address.
• local_host In some environments, the winsock call gethostname cannot return a local host name, yet the local host name is necessary to initiate an SMTP session with an SMTP host. In such environments, you can set local_host, and its value is sent to the SMTP host to identify the local host instead of calling gethostname and gethostbyname.
• pop3_host The name of the computer on which the POP3 host is running. This is generally the same as the SMTP host.
• pop3_userid The user ID for your POP3 account.
• pop3_password The password for your POP3 account.
• Debug When set to YES, displays all SMTP calls and the return codes. This is useful for troubleshooting SMTP support problems. Default is NO.

If all of the fields are set, or if only the Debug field is not set, the login window is not displayed.

The SMTP section of the SQLANY.INI file (Windows 3.x) has the following entries:

     [SMTP]
     smtp_host=smtp_host
     smtp_address=smtp_address
     pop3_host=pop3_host
     pop3_userid=userid
     pop3_password=password
     Debug=yes | no

VIM message control parameters

The VIM message system uses the following control parameters:

• Path This corresponds to the Path field in the cc: Mail login window. It is not applicable to and is ignored under Lotus Notes.
• Userid This corresponds to the User ID field in the cc: Mail login window.
• Password This corresponds to the Password field in the cc: Mail login window. If all of Path, Userid, and Password are set, the login window is not displayed.
• Debug When set to YES, displays all VIM calls and the return codes. This is useful for troubleshooting VIM support problems. Default is NO.
• Receive_All When set to YES, the Message Agent checks all messages to see if they are SQL Remote messages. When set to NO (the defaut), the Message Agent looks only for messages of the application-defined type SQLRemoteData. Setting ReceiveAll to YES is useful in setups where the message type is lost, reset, or never set. This includes setups including cc: Mail messages.
• Send_VIM_Mail When set to YES, the Message Agent sends messages compatible with SQL Anywhere releases before 5.5.01, and compatible with cc: Mail. If this is set to YES, you should ensure that Receive_All is set to YES also.

The VIM section of the SQLANY.INI file (Windows 3.x) has the following entries:

     [VIM]
     Path=path
     Userid=userid
     Password=password
     Debug=yes | no
     Receive_All = yes | no
     Send_VIM_Mail = yes | no