Configuring RTDS for Adaptive Server

Before you begin configuring RTDS, set your Adaptive Server environment settings by sourcing:

On Unix – SYBASE.sh or SYBASE.csh
On Windows – SYBASE.bat

In addition, if you are configuring Real-Time Data Services 4.5 to work specifically with Adaptive Server version 15.0.2 ESD #1 or later:

JRE – set the SYBASE_JRE_RTDS environment variable so that it points to a valid JRE location.
MQ – set the RTDS_MQCLIENT_VERSION environment variable as the current MQ client version. If the MQ client is:
- Version 6.0 or later – set the varaible as 6.0
- Version 5.3 – set the variable as 5.3.

Real-Time Data Services, as a messaging services feature, uses these Adaptive Server sp_configure configuration parameters, which you set when you configure Adaptive Server:

'enable real time messaging' – configures Adaptive Server to use Real-Time Data Services. Its default value is 0. To turn this parameter on, enter:

sp_configure 'enable real time messaging', 1

Table 3 describes the settings that must be correct for sp_configure 'enable real time messaging', 1 to succeed.

Table 3: Settings for **sp_configure 'enable real time messaging', 1**
Configuration	Description
LD_LIBRARY_PATH	Located in SYBASE.sh on IBM AIX – the second line is for MQ only: set LIBPATH $SYBASE/$SYBASE_ASE/lib set LIBPATH /usr/mqm/lib64 Located in SYBASE.sh on Linux, Solaris, and HP-UX: set LD_LIBRARY_PATH $SYBASE/$SYBASE_ASE/lib Located in SYBASE.bat on Windows – the last line is for MQ only: set PATH %SYBASE%/%SYBASE_ASE%/bin set PATH c:\Program files\IBM\WebSphere MQ\bin
SYBASE_JRE	Located in SYBASE.sh on UNIX: set SYBASE_JRE $SYBASE/shared/jre142 Located in SYBASE.bat on Windows: set SYBASE_JRE %SYBASE%/shared/sun/jre142 SYBASE_JRE is not a valid environment variable for RTDS 4.5 working with Adaptive Server 15.0.2 ESD #1 or higher.
SYBASE_JRE_RTDS	Required for all platforms if you are running RTDS 4.5 with Adaptive Server 15.0.2 ESD #1 or higher. You must manually set this environment variable and point it to a valid JRE location. On Windows 64-bit, RTDS 4.5 sets SYBASE_JRE_RTDS automatically.
RTDS_MQCLIENT_VERSION	Sets the current MQ client version. If the MQ client is: Version 6.0 or later, set the varaible as 6.0 Version 5.3, set teh variable as 5.3. Set this environment variable manually.
The provider JAR libraries	Located in rtms.properties: easclient.jar – EAServer 5 eas-client-14.jar – EAServer 6.0.2 for RTDS 4.5 working with Adaptive Server 15.0.2 ESD #1. The jar file is used while $SYBASE_JRE_RTDS points to jre1.4. eas-client-15.jar – EAServer 6.0.2 for RTDS 4.5 working with Adaptive Server 15.0.2esd1. The jar file is used while $SYBASE_JRE_RTDS points to jre1.5. TIBCO – tibjms.jar The files are provided by these applications.
SYBASE messaging licenses	Located in the license file under $SYBASE/SYSAM-2_0/licenses (%SYBASE%\SYSAM-2_0\licenses in Windows): EAServer JMS – ASE_MESSAGING_EASJMS TIBCO EMS – ASE_MESSAGING_TIBJMS IBM WebSphere MQ – ASE_MESSAGING_IBMMQ
The SYBASE interface libraries from the CD	Located in: UNIX – $SYBASE/$SYBASE_ASE/lib Windows – %SYBASE%\%SYBASE_ASE%\bin
MQCCSID	If the CCSID of the connected queue manager is not compatible with the locale of the RTDS 4.5 environment, set the “MQCCSID” environment variable accordingly. For example, when the connected queue manager’s CCSID is 819 and the Adaptive Server RTDS 4.5 is running on a Windows 2000 Simplified Chinese Version (CCSID 936), set $MQCCSID as 819 before you start Adaptive Server and RTDS 4.5.

WARNING! Linux users RTDS can hang on some Linux machines if your $SYBASE_JRE or $SYBASE_JRE_RTDS points to JRE 1.4. This is a known JRE issue. To avoid this, use JRE 1.5. For more information about this issue, see the Sun known bugs Web page

Omitting alter_user=yes When you send a message to the remote cluster queue without using alter_user=yes, MQ might not check the authentication of the Adaptive Server login, but instead check the authentication of the user who started Adaptive Server. This is a known issue with IBM (PMR #31913,756), and is expected to be fixed in MQ version 6.0.2.2.

See the Messaging Services Users Guide for Adaptive Server Enterprise for detailed instructions.

'messaging memory' – specifies the number of memory pages set for messaging. Its default value is 400 2K pages, and its minimum value is 60 2K pages. For example, to set this parameter to 800, enter:
```
sp_configure 'messaging memory', 800
```
'max online Q engines' – required for MQ. Specifies the maximum number of Q engines you can have online. You may need to increase 'max online engines' to accommodate the number of 'max online Q engines'. Restart Adaptive Server for 'max online Q engines' to take effect.
'number of Q engines at startup' – required for MQ. Specifies the number of Q engines that are online when the server starts. You may need to increase 'max online engines' to accommodate the number of 'max online Q engines'. You must restart Adaptive Server for 'number of Q engines at startup' to take effect.

This example assumes that current 'max online engines' is 4.

-- Add 2 more to 'max online engines'.
sp_configure 'max online engines', 6
go
sp_configure 'max online Q engines', 2
go
sp_configure 'number of Q engines at startup, 2
go

MQ only – set the path for the MQ client shared libraries to the dynamic linker’s search path using the information in Table 4 for your platform.

**Table 4: MQ client shared libraries and their paths**
Platform	Path
Solaris 64-bit	/opt/mqm/lib64
Solaris 32-bit	/opt/mqm/lib
Solaris AMD 64-bit	/opt/mqm/lib64
Linux 32-bit	/opt/mqm/lib
HPUX 64-bit	/opt/mqm/lib64
AIX 64-bit	/usr/mqm/lib64
Windows	c:\Program files\IBM\WebSphere MQ\bin
HPIA 64-bit	/opt/mqm/lib64
Linux AMD 64-bit	/opt/mqm/lib64

On UNIX platforms, your MQ client shared library path must be correct before you start Adaptive Server. Windows sets the PATH automatically when you install IBM MQ even if you install the client shared libraries in other locations.

Configuring your installation

Install system stored procedures for real-time messaging services:

isql -Usa -Psa_password -Sserver_name
    -i$SYBASE/$SYBASE_ASE/scripts/installmsgsvss
    -ooutput_file

Add your local server:
```
sp_addserver, <local server name>
```
Shut down your server.
Set the SYBASE_JRE variable to point to $SYBASE/shared/jre142 (%SYBASE%\Shared\Sun\jre142 on Windows), so that the JVM can start when you enable real-time messaging:
```
SYBASE_JRE = $SYBASE/shared/jrel42
```
If you are running RTDS 4.5 with Adaptive Server 15.0.2 ESD #1 or later, the environment variable is SYBASE_JRE_RTDS. Do not use SYBASE_JRE.
Restart your server.

Adaptive Server version 15.0.2 or later only – when you install Real-Time Data Services, the properties file is copied into the Adaptive Server shared libraries directory.

After you have installed RTDS, verify that the properties file is its default location:
- On UNIX – in the shared libraries directory in $SYBASE/$SYBASE_ASE/lib/rtms.properties.
- On Windows – in the binary directory in %SYBASE%\%SYBASE_ASE%\lib\rtms.properties.
To save the properties file to other locations, specify the new location with the sp_msgadmin 'config', 'jvmpropertyfile', 'new location of rtms.properties' stored procedure. See the reference pages for sp_msgadmin in the Messaging Services Users Guide for Adaptive Server Enterprise for details.

Before you run RTDS, modify its contents so that the rtms.properties file points to the correct location of the messaging provider’s client JAR file. The contents of rtms.properties should look similar to:

TIBCOQUEUEMETHOD = 
    createQueueConnection(java.lang.String,java.lang.String)
TIBCOTOPICMETHOD = 
    createTopicConnection(java.lang.String,java.lang.String)
TIBCOTFACTORY = com.tibco.tibjms.TibjmsTopicConnectionFactory
TIBCOQFACTORY = com.tibco.tibjms.TibjmsQueueConnectionFactory
TIBCOJAR = $SYBASE/$SYBASE_ASE/lib/tibjms.jar
EASQUEUEMETHOD = com.sybase.jms.InitialContextFactory
EASTOPICMETHOD = com.sybase.jms.InitialContextFactory
EASTFACTORY = javax.jms.TopicConnectionFactory
EASQFACTORY = javax.jms.QueueConnectionFactory
EASJAR = $SYBASE/$SYBASE_ASE/lib/easclient.jar

Adjust the values in your rtms.properties file based on Table 5.

**Table 5: Values in the *rtms.properties* file based on product**
Application	Property type	Value
EAServer 5.x and earlier	EASQUEUEMETHOD	com.sybase.jms.InitialContextFactory
	EASTOPICMETHOD	com.sybase.jms.InitialContextFactory
	EASJAR	The pathname to the easclient.jar file, such as $SYBASE/$SYBASE_ASE/lib/easclient.jar (%SYBASE%\%SYBASE_ASE%\lib\easclient.jar on Windows)
EA Server version 6.0.2 and later working with Adaptive Server version 15.0.2 ESD #1 or later	EASQUEUEMETHOD	com.sybase.jms.client.InitialContextFactory
	EASTOPICMETHOD	com.sybase.jms.client.InitialContextFactory
	EASJAR	The pathname to either the eas-client-14.jar or eas-client-15.jar file, such as $SYBASE/$SYBASE_ASE/lib/eas-client-14.jar (%SYBASE%/%SYBASE_ASE%/lib/eas-client-14.jar on Windows)
	EASHOME	Any directory you specify, as long as the user who starts Adaptive Server has write permission to access it.
TIBCO	TIBCOJAR	Change the value of $SYBASE/$SYBASE_ASE/lib/tibjms.jar (%SYBASE%\%SYBASE_ASE%\lib\tibjms.jar on Windows) to the location where you installed tibjms.jar.

Messaging operations such as msgsend and msgrecv fail if Adaptive Server cannot access the JAR file.

For the new configuration to take effect, restart the Java Real-Time Data Services JVM server by disabling real-time messaging:
```
sp_configure 'enable real time messaging',0
```

Reenable real-time messaging:

sp_configure 'enable real time messaging',1

Assign messaging_role permissions to users:
```
grant role messaging_role to <login>
```

Setting up MQ

Create and start a queue manager. In this example, the queue manager is called QM1:

% crtmqm QM1

WebSphere MQ queue manager created.
Creating or replacing default objects for QM1.
Default objects statistics : 31 created. 0 replaced. 
0 failed.
Completing setup.
Setup completed.

% strmqm QM1

WebSphere MQ queue manager 'QM1' started.

Use the MQSC tool to create a queue. This example creates a queue called Q1 on the QM1 queue manager:

% runmqsc QM1

5724-B41 (C) Copyright IBM Corp. 1994, 2002. ALL RIGHTS RESERVED.
Starting WebSphere MQ script Commands.
define qlocal(Q1)
       1 : define qlocal(Q1)
AMQ8006: WebSphere MQ queue created.
end
       2 : end
No MQSC commands read.
No commands have a syntax error.
All valid MQSC commands were processed.

Use the MQSC tool to define a server channel in the queue manager. This example defines a channel called CH1 on QM1:

% runmqsc QM1

5724-B41 (C) Copyright IBM Corp. 1994, 2002. ALL RIGHTS RESERVED.
Starting WebSphere MQ script Commands.
define channel(CH1) chltype(SVRCONN)
       1 : define channel(CH1) chltype(SVRCONN)
AMQ8014: WebSphere MQ channel created.
end
       2 : end
No MQSC commands read.
No commands have a syntax error.
All valid MQSC commands were processed.

Add authorizations for the SYBASE user login and ASE logins. In this example, Adaptive Server runs as user “sybase,” the Adaptive Server messaging user is “login1”, and the queue is “Q1”:
```
% setmqaut -m QM1 -t qmgr -p sybase +connect +altusr +inq +setid
% setmqaut -m QM1 -t q -n Q1 -p login1 +inq +get +browse +put
```
Start an MQ listener. This example starts a listener on port 8765:
```
% runmqlsr -t tcp -p 8765 -m QM1 &
```

The following shows the endpoint URL for the objects created in these examples, with “myhost” as the host name:

ibm_mq:CH1/tcp/myhost(8765)?qmgr=QM1,queue=Q1