Ecriture de programmes d'exit de canal sous z/OS

Vous pouvez utiliser les informations suivantes pour vous aider à écrire et à compiler des programmes d'exit de canal pour z/OS®.

Les exits sont démarrés comme par un z/OS LINK, dans:

Etat du programme d'incident non autorisé
Mode de contrôle de l'espace adresse principal
Mode mémoire-non-croisée
Mode d'enregistrement sans accès
Mode d'adressage 31 bits

Les modules d'édition de liens doivent être placés dans le fichier indiqué par l'instruction de définition de données CSQXLIB de la procédure d'espace adresse de l'initiateur de canal ; les noms des modules de chargement sont indiqués comme noms d'exit dans la définition de canal.

Lors de l'écriture des exits de canal pour z/OS, les règles suivantes s'appliquent:

Les exits doivent être écrits en assembleur ou en C ; si C est utilisé, il doit être conforme à l'environnement de programmation des systèmes C pour les exits système, décrit dans le manuel z/OS C/C++ Programming Guide.
Les exits sont chargés à partir des bibliothèques non autorisées définies par une instruction de définition de données CSQXLIB. Si CSQXLIB est associé à DISP=SHR, les exits peuvent être mis à jour pendant que l'initiateur de canal est en cours d'exécution. La nouvelle version est utilisée lorsque le canal est redémarré.
Les exits doivent être réentrants et capables de s'exécuter n'importe où dans la mémoire virtuelle.
Les exits doivent réinitialiser l'environnement, à leur retour, à celui de l'entrée.
Les exits doivent libérer la mémoire obtenue ou s'assurer qu'elle est libérée par un appel d'exit ultérieur.
Pour le stockage qui doit être conservé entre les appels, utilisez le service z/OS STORAGE ou la fonction de bibliothèque 4kmalc pour la programmation système C.

Pour plus d'informations sur cette fonction, voir 4kmalc() -- Allocation de stockage aligné sur les pages.
Tous les appels IBM® MQ MQI à l'exception de MQCMIT ou CSQBCMT et MQBACK ou CSQBBAK peuvent être utilisés. Ils doivent être contenus après MQCONN (avec un nom de gestionnaire de files d'attente vide). Si ces appels sont utilisés, vous devez éditer les liens de l'exit avec le module de remplacement CSQXSTUB.
L'exception à cette règle est que les exits de canal de sécurité peuvent émettre des appels MQI de validation et d'annulation. Pour émettre de tels appels, codez les verbes CSQXCMT et CSQXBAK à la place de MQCMIT ou CSQBCMT et MQBACK ou CSQBBAK.
Tous les exits qui utilisent le module de remplacement CSQXSTUB de IBM WebSphere® MQ 7.0 ou version ultérieure doivent être édités par des liens dans une bibliothèque de chargement CSQXLIB au format PDS-E.
Les exits ne doivent pas utiliser de services système provoquant une attente, car l'utilisation de ces services affecterait gravement le traitement de certains ou de tous les autres canaux. De nombreux canaux sont exécutés sous un seul bloc de contrôle des tâches. Si vous effectuez une action dans un exit qui provoque une attente et que vous n'utilisez pas MQXWAIT, cela entraîne l'attente de tous ces canaux. La mise en attente des canaux ne génère aucun problème fonctionnel, mais peut avoir un effet négatif sur les performances. La plupart des SVC impliquent des attentes, vous devez donc les éviter, à l'exception des SVC suivants:
- GETMAIN/FREEMAIN/STORAGE
- CHARGER/EFFACER
Par conséquent, en général, évitez les SVC, les PC et les E-S. A la place, utilisez l'appel MQXWAIT.
Les exits n'émettent pas d'ESTAE ou de SPEI, à l'exception des sous-tâches qu'ils connectent, car leur traitement des erreurs peut interférer avec le traitement des erreurs effectué par IBM MQ. Cela signifie que IBM MQ peut ne pas être en mesure de récupérer d'une erreur ou que votre programme d'exit peut ne pas recevoir toutes les informations d'erreur.
L'appel MQXWAIT (voir MQXWAIT ) fournit un service d'attente qui attend les E-S et d'autres événements ; si ce service est utilisé, les exits ne doivent pas utiliser la pile de liaisons.
Pour les fonctions d'E-S et les autres fonctions qui ne fournissent pas de fonctions non bloquantes ou pour lesquelles un ECB doit attendre, une sous-tâche distincte doit être connectée et son achèvement doit être attendu par MQXWAIT ; en raison du traitement auquel cette technique est soumise, cette fonction doit être utilisée uniquement par l'exit de sécurité.
L'appel MQDISC MQI ne provoque pas de validation implicite dans le programme d'exit. Une validation du processus de canal est effectuée uniquement lorsque le protocole de canal l'exige.

Les exemples d'exit suivants sont fournis avec IBM MQ for z/OS:

CSQ4BAX0

Cet exemple est écrit en assembleur et illustre l'utilisation de MQXWAIT.

CSQ4BCX1 et CSQ4BCX2

Ces exemples sont écrits en C et montrent comment accéder aux paramètres.

CSQ4BCX3 et CSQ4BAX3

Ces exemples sont écrits respectivement en C et en assembleur.

L'exemple CSQ4BCX3 (qui est précompilé dans SCSQAUTH LOADLIB) doit fonctionner sans aucune modification nécessaire sur l'exit lui-même. Vous pouvez créer une bibliothèque LOADLIB (par exemple, MY.TEST.LOADLIB) et copiez-y le membre SCSQAUTH (CSQ4BCX3).

Pour configurer un exit de sécurité sur une connexion client, procédez comme suit:

Etablissez un segment OMVS valide pour l'ID utilisateur utilisé par l'initiateur de canal.
Cela permet à l'initiateur de canal IBM MQ for z/OS d'utiliser TCP/IP avec l'interface de socket z/OS UNIX System Services (z/OS UNIX), afin de faciliter le traitement des exits. Notez qu'il n'est pas nécessaire de définir un segment OMVS pour l'ID utilisateur d'un client en cours de connexion.
Assurez-vous que le code d'exit lui-même s'exécute uniquement dans un environnement contrôlé par programme.
Cela signifie que tout ce qui est chargé dans l'espace adresse CHINIT doit être chargé à partir d'une bibliothèque contrôlée par programme (c'est-à-dire toutes les bibliothèques de la bibliothèque STEPLIB), ainsi que toutes les bibliothèques nommées dans CSQXLIB et
```
++hlq++.SCSQANLx 
++hlq++.SCSQMVR1 
++hlq++.SCSQAUTH 
```
Pour définir une bibliothèque de chargement comme étant contrôlée par un programme, utilisez une commande similaire à l'exemple suivant:
```
RALTER PROGRAM * ADDMEM('MY.TEST.LOADLIB'//NOPADCHK) 
```
Vous pouvez ensuite activer ou actualiser l'environnement contrôlé par le programme en exécutant la commande suivante:
```
SETROPTS WHEN(PROGRAM) REFRESH 
```
Ajoutez l'exit LOADLIB à la définition de données CSQXLIB (dans la procédure démarrée CHINIT), en exécutant la commande suivante:
```
ALTER CHANNEL(xxxx) CHLTYPE(SVRCONN)SCYEXIT(CSQ4BCX3)
```
Cela active l'exit pour le canal nommé.
Votre gestionnaire de sécurité externe (ESM) répertorie toutes les autres bibliothèques à contrôler par programme, mais notez qu'aucune des bibliothèques ESM ou C n'a besoin d'être contrôlée par programme.

Pour plus d'informations sur la configuration d'un exit de sécurité à l'aide de l'exemple CSQ4BCX3, voir Canal de connexion serveurIBM MQ for z/OS .

CSQ4BCX4

Cet exemple est écrit en C et illustre l'utilisation des zones RemoteProduct et RemoteVersion dans MQCXP.