Sybase 12.5.3a et MQ (RTDS, Real Time Data Services)

Logo

Introduction

Sybase offre les Real Time Data Services (RTDS) depuis Sybase Adaptive Server Enterprise 12.5.2. Ces services permettent de faire communiquer Sybase ASE avec des bus de messages. On parle aussi communément de RTMS (Real Time Messaging Services).

Pour la version 12.5.2, TIBCO est supporté par Sybase RTDS.

À partir de la version Sybase ASE 12.5.3a, MQ (IBM MQ Series) est supporté par Sybase RTDS. Cette documentation décrit la configuration nécessaire pour faire communiquer Sybase RTDS avec MQ Series.

Les commandes T-SQL msgsend() et msgrecv() permettent désormais respectivement d’envoyer un message vers MQ ou recevoir un message depuis MQ. L’objectif de cette documentation ne se concentre pas sur comment appeler les commandes msgsend et msgrecv mais sur tous les prérequis nécessaires pour que les RTDS avec MQ fonctionne. Le comportement interne des messages Sybase avec MQ fera l’objet d’une documentation spécifique.

Dans le contexte de cette documentation, $SYBASE est le répertoire /Software/sybase/sybase-12.5.3a.

Licence

Le Real Time Messaging avec Sybase 12.5.3a requiert la licence ASE_MESSAGING.

Pour ajouter la licence, lancer le programme lmgr situé dans le répertoire $SYBASE/SYSAM-1_0/bin (programme pouvant être lancé graphiquement en ayant au préalable exporter la variable DISPLAY : export DISPLAY=<adresse IP>:0.0)

Une fenêtre s’affiche afin de rentrer les informations de licence fournies par Sybase (Order Number, Feature Name, Feature Count, Software Version, Authorization Code). Le programme lmgr enregistre l’information dans le fichier de licence et redémarre automatiquement le license daemon.

32-bits ou 64-bits, variable LD_LIBRARY_PATH

Le user sybase qui démarre le serveur ASE 12.5.3a qui communiquera avec MQ doit savoir où trouver les librairies MQ qui sont installées dans les répertoires ci-dessous en fonction de la plateforme.

Plateforme Variable d’environnement Chemin
Solaris 64-bit $LD_LIBRARY_PATH /opt/mqm/lib64
Solaris 32-bit $LD_LIBRARY_PATH /opt/mqm/lib
Linux 32-bit $LD_LIBRARY_PATH /opt/mqm/lib
HPUX 64-bit $SHLIB /opt/mqm/lib64
AIX 64-bit $LIBPATH /usr/mqm/lib64

Si les librairies MQ sont configurées pour du 64 bits, le serveur ASE 12.5.3a doit également être en 64 bits. Il est important d’être homogène sur le caractère 32 bits ou 64 bits avec Sybase ASE 12.5.3a et MQ.

La commande Unix truss permet de voir rapidement qu’un serveur Sybase 12.5.3a 64 bits recherche quoiqu’il arrive les librairies MQ 64 bits.

En voici un exemple, la commande truss étant lancé sur l’engine Sybase dédié à MQ, dans ce cas de figure MQ est une version 32 bits et Sybase ASE 12.5.3a une version 64 bits :

      /1: stat("/opt/mqm/lib64/libmqmcs.so", 0x10000CCE610) Err#2 ENOENT
       /1: sigprocmask(SIG_SETMASK, 0xFFFFFFFF7F11D4C0, 0x10000CCD2B0) = 0
       /1: sigprocmask(SIG_SETMASK, 0x10000CCD29C, 0x00000000) = 0
       /1: fstat(27, 0x10000CCD240) = 0
       /1: sigprocmask(SIG_SETMASK, 0xFFFFFFFF7F11D4C0, 0x10000CCD2B0) = 0
       /1: sigprocmask(SIG_SETMASK, 0x10000CCD29C, 0x00000000) = 0
       /1: sigprocmask(SIG_SETMASK, 0xFFFFFFFF7F11D4C0, 0x10000CCD390) = 0
       /1: sigprocmask(SIG_SETMASK, 0x10000CCD37C, 0x00000000) = 0
       /1: sigprocmask(SIG_SETMASK, 0xFFFFFFFF7F11D4C0, 0x10000CCD390) = 0
       /1: sigprocmask(SIG_SETMASK, 0x10000CCD37C, 0x00000000) = 0
       /1: write(27, "04\002\0\0\0\0\0FF\0 Q\0".., 512) = 512
       /10: lwp_cond_wait(0xFFFFFFFF7B5A1F70, 0xFFFFFFFF7B5A1F80, 0x00000000) = 0
       /1: lwp_cond_signal(0xFFFFFFFF7B5A1F70) = 0
       /1: poll(0x100000901C8, 2, 0) = 0
       /1: kaio(AIOWAIT, 0xFFFFFFFFFFFFFFFF) Err#22 EINVAL
       /1: poll(0x100000901C8, 2, 0) = 0
       /1: kaio(AIOWAIT, 0xFFFFFFFFFFFFFFFF) Err#22 EINVAL

Une fois que l’on s’est assuré que le caractère 32 bits ou 64 bits est homogène au niveau de Sybase ASE 12.5.3a et MQ, il suffit de référencer les librairies MQ dans le fichier SYBASE.sh (localisé dans le répertoire $SYBASE, /Software/sybase/sybase-12.5.3a dans notre cas pratique), SYBASE.sh étant le shell qui source les variables d’environnement au démarrage du serveur ASE.

La variable qui est mise à jour dans le fichier SYBASE.sh est la variable $LD_LIBRARY_PATH, variable dans laquelle on référence l’accès aux librairies MQ :

Pour une version 32 bits

…
LD_LIBRARY_PATH="/Software/sybase/sybase-12.5.3a/OCS-12_5/lib3p":$LD_LIBRARY_PATH
LD_LIBRARY_PATH="/Software/sybase/sybase-12.5.3a/OCS-12_5/lib3p64":$LD_LIBRARY_PATH
LD_LIBRARY_PATH="/Software/sybase/sybase-12.5.3a/OCS-12_5/lib":$LD_LIBRARY_PATH
LD_LIBRARY_PATH="/opt/mqm/lib":$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
…

Pour une version 64 bits

…
LD_LIBRARY_PATH="/Software/sybase/sybase-12.5.3a/OCS-12_5/lib3p":$LD_LIBRARY_PATH
LD_LIBRARY_PATH="/Software/sybase/sybase-12.5.3a/OCS-12_5/lib3p64":$LD_LIBRARY_PATH
LD_LIBRARY_PATH="/Software/sybase/sybase-12.5.3a/OCS-12_5/lib":$LD_LIBRARY_PATH
LD_LIBRARY_PATH="/opt/mqm/lib64":$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
…

Configuration de RTMS

La configuration RTMS suppose un certain nombre de redémarrage du serveur Sybase ASE.

Script installmsgvss

Pour configurer Sybase 12.5.3a avec du RTDS (Real Time Data Services), les procédures stockées RTMS doivent être installées et des paramètres doivent être appliqués grâce au script insallmsgvss situé dans le répertoire $SYBASE/$SYBASE_ASE/scripts/installmsgvss (/Software/sybase/sybase-12.5.3a/ASE-12_5/scripts dans notre cas pratique) :

isql -i$SYBASE/$SYBASE_ASE/scripts/installmsgsvss

DBA_T2_ASE > isql -Usa -iinstallmsgsvss
00:00000:00012:2005/11/15 17:45:42.95 server Configuration file '/Software/sybase/dba/DBA_T2_ASE/cfg/DBA_T2_ASE.cfg' has been written and the previous version has been renamed to '/Software/sybase/dba/DBA_T2_ASE/cfg/DBA_T2_ASE.003'.
01:00000:00012:2005/11/15 17:45:42.96 server The configuration option 'allow updates to system tables' has been changed by 'sa' from '0' to '1'.

Parameter Name                   Default     Memory Used Config Value
Run Value   Unit                 Type
-------------------------------- ----------- ----------- ------------
----------- -------------------- ----------
allow updates to system tables             0           0            1
          1  switch              dynamic

(1 row affected)
Configuration option changed. The SQL Server need not be rebooted since the
option is dynamic.
Changing the value of 'allow updates to system tables' to '1' increases the
amount of memory ASE uses by 2 K.
(return status = 0)
Installing procedures from rtm_common ...
Installing procedures from rtm_help ...
Installing sp_rtm_help
Installing procedures from rtm_check_extra_args ...
Installing sp_rtm_check_extra_args
Installing procedures from rtm_check_required_arg ...
Installing sp_rtm_check_required_arg
Installing procedures from rtm_helpserver ...
Installing sp_rtm_helpserver
Installing procedures from rtm_helpexternlogin ...
Installing sp_rtm_helpexternlogin
Installing procedures from rtm_default ...
Installing sp_rtm_default
Installing procedures from rtm_list ...
Installing sp_rtm_list
Installing procedures from rtm_register ...
Installing sp_rtm_register
Installing procedures from rtm_remove ...
Installing sp_rtm_remove
Installing procedures from rtm_msgadmin ...
Installing sp_msgadmin

00:00000:00012:2005/11/15 17:46:27.25 server Configuration file '/Software/sybase/dba/DBA_T2_ASE/cfg/DBA_T2_ASE.cfg' has been written and the previous version has been renamed to '/Software/sybase/dba/DBA_T2_ASE/cfg/DBA_T2_ASE.004'.
00:00000:00012:2005/11/15 17:46:27.26 server The configuration option 'allow updates to system tables' has been changed by 'sa' from '1' to '0'.

Parameter Name                   Default     Memory Used Config Value
Run Value   Unit                 Type
-------------------------------- ----------- ----------- ------------
----------- -------------------- ----------
allow updates to system tables             0           0            1
          0  switch              dynamic

Configuration option changed. The SQL Server need not be rebooted since the
option is dynamic.
Changing the value of 'allow updates to system tables' does not increase the
amount of memory Adaptive Server uses.
Loading of Real Time messaging procedures is complete.

Local Server (sp_addserver)

Il faut ajouter le serveur local dans la table sysservers si ce n’est pas encore fait avec la commande sp_addserver :

exec sp_addserver '<ServerName>',local
go

Rôle messaging_role

Le rôle messaging_role est ensuite attribué aux logins autorisés à faire du RTMS (Real Time Messaging Services), seul ce rôle peut faire du RTMS :

grant role messaging_role to <login>

Paramètre serveur 'enable real time messaging'

Le paramètre 'enable real time messaging' active le RTMS au niveau du serveur ASE, ce paramètre est dynamique. C’est au moment de l’activation de ce paramètre que Sybase ASE tente de localiser l’accès aux libraires nécessaires (MQ et/ou TIBCO EMS) et remonte un message d’erreur si la variable $LD_LIBRARY_PATH ne référence pas le bon chemin d’accès aux librairies nécessaires (MQ et / ou TIBCO).

Pour la version initiale 12.5.3a GA (Generally Available), l’activation du paramètre 'enable real time messaging' implique l’activation de la communication avec MQ et TIBCO :

exec sp_configure 'enable real time messaging',1
go

Avec les versions ultérieures de RTDS (12.5.3a ESD#1), il est désormais possible de spécifier directement au niveau du paramètre 'enable real time messaging' si il s’agit des librairies MQ et/ou TIBCO JMS :

Pour n’activer que TIBCO :

exec sp_configure 'enable real time messaging', 1,'tibco_jms'
go

Pour n’activer que MQ Series :

exec sp_configure 'enable real time messaging', 1,'ibm_mq'
go

Lorsque seul MQ est activé avec sp_configure 'enable real time messaging', le paramètre 'enable real time messaging' vaut dans ce cas 4 :

exec sp_configure 'enable real time messaging'
go
          Parameter Name              Default  Memory Used Config Value  Run Value Unit    Type
--------------------------  -------  ----------- ------------  --------- ------- --------
enable real time messaging  0        0           4             4         switch  dynamic

Paramètre serveur 'messaging memory'

Une zone mémoire en pages de 2K est allouée par ASE pour le messaging, celle-ci peut être modifiée et augmentée avec le paramètre serveur dynamique 'messaging memory'. Par défaut cette zone mémoire est fixée à 400 pages de 2K.

exec sp_configure 'messaging memory'
go

Parameter Name     Default   Memory Used Config Value  Run Value Unit              Type
------------------ --------  ----------- ------------  --------- ----------------  -------
messaging memory   400       0           400           400       Memory pages (2K) dynamic

Paramètres serveur engine ('max online Q engines' , 'number of Q engines at startup', 'max native threads per engine')

Les paramètres serveur 'max online Q engines' et 'number of Q engines at startup' permettent de dédier un ou plusieurs engines Sybase pour la communication avec les APIs MQ.

Avec le processus de polling, le ou les engine(s) sont complètement dédiés aux communications avec les APIs MQ.

Avec la première version 12.5.3a GA de Sybase, les numéros de configuration dans la table sysconfigures pour les paramètres 'max online Q engines' et 'number of Q engines at startup' ne sont pas installées correctement.

Pour corriger ce problème , la table sysconfigures dans la base master doit être modifiée manuellement :

use master
go
exec sp_configure 'allow updates', 1
go
update sysconfigures set config=447 where name='max online Q engines'
go
update sysconfigures set config=448 where name='number of Q engines at startup'
go
exec sp_configure 'allow updates', 0
go

Les versions ultérieures de Sybase 12.5.3a (ESD#1, etc.) corrigent ce problème.

max online Q engines : spécifie le nombre maximum de Q engines qui peuvent être « online » pour MQ. Il se peut que le paramètre 'max online engines' nécessite d’être augmenté car les Q engines sont dédiés à MQ uniquement. Ce paramètre est statique et nécessite un redémarrage du serveur ASE.

number of Q engines at startup : spécifie le nombre de Q engines qui sont « online » pour MQ au démarrage du serveur. Ce paramètre est statique et nécessite un redémarrage du serveur ASE. Il se peut que le paramètre 'max online engines/' nécessite d’être augmenté.

Bien entendu, le paramètre 'number of Q engines at startup' doit être inférieur au paramètre 'max online Q engines', de même que le paramètre 'max online Q engines' doit être inférieure au paramètre 'max online engines'. Il ne faut jamais oublier que les Q engines sont uniquement dédiés à MQ.

Dans l’exemple qui suit, on suppose qu’au départ le paramètre 'max online engines' vaut 4 :

use master
go
exec sp_configure 'max online engines', 6
go
exec sp_configure 'max online Q engines', 2
go
exec sp_configure 'number of Q engines at startup', 2
go

Les Q engines sont répertoriés dans la table sysengines et sont identifiés dans cette table grâce à la colonne status :

use master
go
select engine, osprocid, osprocname, status, startime from sysengines
go

engine osprocid    osprocname          status       starttime
------ ----------- ------------------- ------------ -------------------
0      2266        online                         9 Nov 17 2005 6:03PM
1      2269        online_q                       0 Nov 17 2005 6:03PM

Les opérations de messaging échouent si il n’y a pas assez de Q engines et dans ce cas aucune session ne peut être démarrée sur le Q engine.

Les Q engines apparaissent dans la table sysengines avec le suffixe _q et les statuts sont les suivants :

  • online_q : Q engine « online »
  • offline_q : Q engine « offline »
  • dormant_q : Q engine « dormant »

Comme pour les engines classiques de Sybase ASE, sp_engine peut être utilisée pour mettre un Q engine « online ».

max native threads per engine

Un Q engine utilise les threads de l’OS, le paramètre de configuration 'max native threads per engine' contrôle le nombre maximum de threads natifs qu’un Q engine utilise. La valeur par défaut de ce paramètre vaut 50 (la valeur maximale valant quant à elle pour ce paramètre 1000).

Si il y a plus de sessions messaging qu’il n’y a de threads natifs configurés, les opérations de messagins sont bloqués jusqu’à ce qu’un thread soit libéré.

Configuration et autorisations MQ

La configuration de Sybase ASE n’est pas suffisante, des opérations complémentaires doivent être réalisées au sein des queue managers de MQ et notamment au niveau des autorisations.

Commande select msgsend () vers MQ

Pour envoyer un message vers MQ, la commande T-SQL msgsend () est utilisée, la syntaxe générale est la suivante :

select msgsend ('msg', 'ibm_mq:<channel>?qmgr=<queueManagerName>,queue=<queueName>')
  • <channel> : canal à utiliser pour envoyer le message msg
  • <queueManagerName> : Nom du Queue Manager
  • <queueName> : Queue dans laquelle le message doit être envoyé.

Voici un exemple d’appel :

select msgsend('hello world','ibm_mq:EUROPC.CL/tcp/FRAWMQ501(51105)?qmgr=MWMQD02,queue=TESTQ'
               message header 'priority=2')
go

--------------------------------------------------------------------------------------
0x414d51204d574d5144303220202020204376d02120017b03
(1 row affected)

Exemples d’échec

Lorsque le queue manager n’est par exemple pas disponible, le message MQRC_Q_MGR_NOT_AVAILABLE est renvoyé :

select msgsend('hello world','ibm_mq:TO.MWMQD02/tcp/FRAWMQ501(51105)?qmgr=MWMQD02,queue=TESTQ'
                message header 'priority=2')
go
Messaging services API call failed. Operation 'um_get_ep_maxmsglen'.
Error received from the messaging provider. \n\tMQ API call failed with reason
code 'MQRC_Q_MGR_NOT_AVAILABLE' (2059)\nFrom provider
'TO.MWMQD02/tcp/FRAWMQ501(51105)', endpoint 'TESTQ'.

-------------------------------------------------------------------------------------
NULL

Lorsque les droits nécessaires sont insuffisants, le message MQRC_NOT_AUTHORIZED est renvoyé

select msgsend('hello world','ibm_mq:EUROPC.CL/tcp/FRAWMQ501(51105)?qmgr=MWMQD02,queue=TESTQ'
               message header 'priority=2')
go
Messaging services API call failed. Operation 'um_get_ep_maxmsglen'.
Error received from the messaging provider. \n\tMQ API call failed with reason
code 'MQRC_NOT_AUTHORIZED' (2035)\nFrom provider
'EUROPC.CL/tcp/FRAWMQ501(51105)', endpoint 'TESTQ'.

Sécurité MQ (droits insuffisants MQRC_NOT_AUTHORIZED)

Le message MQRC_NOT_AUTHORIZED est retourné au client après la commande select msgsend() lorsque les droits nécessaires dans MQ ne sont pas donnés.

Avec MQ, on ne peut pas spécifier de user et de password dans la commande select msgsend() pour communiquer avec un queue manager comme on peut le faire avec TIBCO.

Après avoir effectué la connexion vers le queue manager MQ, Adaptive Server tente d’ouvrir la queue avec le login ASE qui effectue l’opération.

Pour cette raison :

  • le compte Unix qui démarre Sybase ASE doit avoir les droits de connexion au queue manager + quelques autres droits. Généralement ce compte Unix est sybase.
  • le login ASE qui effectue l’opération doit avoir un compte utilisateur sur la machine hébergeant le queue manager.
  • le login ASE doit être un user MQ
  • le login ASE doit avoir les autorisations nécessaires et listées plus loin dans cette documentation.

Dans la suite de cette section, on suppose qu’il s’agit du login idee_maint qui effectue les opérations de messaging dans le serveur ASE, ce login ASE ayant bien entendu le rôle messaging_role.

Création du user Unix pour le login ASE (useradd)

La commande Unix Solaris useradd en tant que root est utilisée pour créer le compte idee_maint sur la machine hébergeant le queue manager :

root@UNIX > useradd [ -d home_dir ] [ -g initial_group ] [ -s shell ] login

D’autres paramètres de la commande useradd permet aussi de forcer l’id du user si l’environnement est normalisé.

Application : le user unix idee_maint est créé avec pour répertoire par défaut /Software/mqseries, groupe initial mqdec et shell par défaut /bin/ksh.

root@UNIX > useradd -d /Software/mqseries -g mqdec -s /bin/ksh idee_maint

Tableau des autorisations MQ à donner

Le tableau ci-dessous résume les autorisations nécessaires pour réaliser les opérations de messaging :

Compte Autorisation MQ
Compte OS qui exécute le dataserver Sybase (sybase/) connect, altusr,inq,setid sur le queue manager
Compte OS associé au login ASE (idee_maint dans notre exemple) inq, get, read, browse, put

Avec les lignes de commande MQ, si le Queue manager s’appelle QM1 et la queue Q1, les autorisations sont données comme ci-dessous :

Autorisations pour le compte O/S sybase :

% setmqaut -m QM1 -t qmgr -p sybase +connect +altusr +inq +setid

Autorisations pour le compte O/S associé au login ASE login1 (cela serait idee_maint dans notre exemple) :

% setmqaut -m QM1 -t q -n Q1 -p login1 +inq +get +browse +put

Transactions SQL et RTDS

Par défaut, toutes les opérations de messaging (msgsend, msgrecv, etc.) sont annulées si la transaction SQL est annulée. Toutefois une opération de messaging en échec n’affecte pas la transaction SQL parente.

Le comportement transactionnel est contrôlé par la commande T-SQL « set transactionnal messaging ».

set transactional messaging [ none | simple | full ]

Par défaut , le mode est 'simple' dans une session T-SQL. Il s’agit d’une option qui n’existe qu’au niveau de la session et qui n’existe pas au niveau du serveur (option non existante avec sp_configure), par ailleurs il est impossible d’appliquer la commande set transactional messaging au sein d’une transaction.

Le mode 'none'

Dans le mode 'none', les opérations de messaging et bases de données n’intéragissent pas.

set transactional messaging none
begin tran
       select msgsend(…)
       insert (…)

La commande msgsend est exécutée que l’insertion échoue ou pas et vice versa.

Le mode 'simple'

Dans le mode 'simple', mode par défaut dans une session T-SQL, les opérations bases de données affectent les opérations de messaging, mais le contraire n’est pas vrai, les opérations de messaging n’ont aucune influence sur les opérations bases de données.

set transactional messaging simple
begin tran
       select msgsend(…)
       insert (…)

La commande insert n’est pas abandonnée si la commande msgsend échoue en revanche la commande msgsend est annulée si l’insertion échoue.

Le mode 'full'

Dans le mode 'full', les opérations bases de données affectent les opérations de messaging et vice-versa les opérations de messaging affectent les opérations bases de données.

set transactional messaging full
       begin tran
       select msgsend(…)
       insert (…)

La commande insert est abandonnée si la commande msgsend échoue et la commande msgsend est annulée si l’insertion échoue.