Utilisez cette tâche pour créer une interaction entre les API sortantes et l'espace d'adressage externe
ou le sous-système.
Avant de commencer
Etablir une connexion avec un espace d'adressage externe ou
un sous-système, comme décrit dans la rubrique Utilisation des adaptateurs locaux optimisés pour appeler un espace d'adressage externe ou un sous-système à partir d'une application WebSphere Application Server on z/OS.
Procédure
- Facultatif : Démarrez une transaction locale de gestionnaire de ressources
(RMLT) si vous utilisez une tâche de serveur Customer Information Control
System (CICS) prenant en charge
les transactions. Pour utiliser une tâche de serveur CICS prenant en charge les transactions,
le mot clé TXN=Y est utilisé au démarrage de la tâche de serveur. Vous pouvez démarrer
une tâche RMLT pour encapsuler plusieurs interactions dans une unité de travail unique. Votre composant d'application
Java™ Enterprise Edition (Java EE) ne doit
pas être exécuté sur une transaction globale et doit posséder une frontière LocalTransaction paramétrée sur Application
dans son descripteur de déploiement d'application. L'exemple suivant explique comment démarrer une
transaction locale en utilisant l'objet LocalTransaction une fois le descripteur de déploiement changé.
LocalTransaction lt = con.getLocalTransaction();
lt.begin();
Pour plus d'informations sur le changement du paramètre LocalTransaction d'un descripteur de déploiement
d'application, voir la rubrique relative à la configuration des attributs de déploiement transactionnels.
Si votre composant d'application Java EE
est configuré pour utiliser la frontière LocalTransaction,ContainerAtBoundary,
la connexion est automatiquement enregistrée dans un RMLT une fois la connexion
établie. Le travail effectué lors de l'utilisation de cette connexion est automatiquement
effectué lorsque le composant d'application Java EE se termine.
Si votre composant d'application Java EE démarre dans une transaction globale,
le connecteur est automatiquement enregistré dans la transaction globale une fois la connexion établie. Le travail
effectué lors de l'utilisation de cette connexion est automatiquement effectué lorsque le composant d'application
Java EE se termine. L'objet ConnectionFactory utilisé pour établir votre connexion
doit comporter la propriété personnalisée RegisterName paramétrée pour participer à une
transaction globale.
- Créez une interaction à l'aide de l'objet Connexion, par exemple :
Interaction int = con.createInteraction();
- Créez un objet InteractionSpecImpl et définissez le nom de service
dans la spécification de l'interaction. Le nom de service décrit
le nom de la méthode ou de la fonction que vous voulez appeler sur le
système distant. Le nom de service a été fourni lorsque le système distant a appelé l'hôte ou une des API Receive
Request, ou lors de l'utilisation de la tâche serveur CICS (Customer Information
Control System). C'est le nom du programme à démarrer dans CICS, par exemple :
InteractionSpecImpl isi = new InteractionSpecImpl();
isi.setServiceName("MYSERVICE");
Avertissement : Lorsque vous utilisez les adaptateurs locaux optimisés sur OTMA,
le nom de service n'est pas défini et la transaction IMS cible
est spécifiée dans le flux de message. Le nom de service peut être défini, mais il n'est pas
utilisé pour les adaptateurs locaux optimisés sur OTMA. Pour plus d'informations, reportez-vous à la rubrique
Appel de transactions IMS existantes
avec les adaptateurs locaux optimisés sur OTMA.
- Exécutez l'interaction à l'aide de la spécification d'interaction créée,
par exemple :
int.execute(isi, null);
- Si votre application a utilisé un RMLT,
validez ou annulez le travail une fois que vous en avez fini avec votre dernière
interaction. Utilisez les méthodes de validation ou d'annulation de l'objet
LocalTransaction, par exemple :
lt.commit();
Résultats
L'interaction avec l'espace d'adressage externe ou
le sous-système est terminée.
Avertissement : Lors de l'utilisation d'une
transaction RMLT ou globale, si l'application CICS
émet un point de synchronisation au cours de la transaction RMLT ou globale,
la tâche de serveur émet un abandon BBOX pour le point de synchronisation. Ceci entraîne un échec du point de
synchronisation et une génération d'abandon ASPx par CICS. L'application
CICS doit attendre que WebSphere
Application Server émette l'opération du point de synchronisation en appelant la méthode commit ou rollback de l'objet
LocalTransaction ou en laissant le composant de l'application Java EE s'exécuter
jusqu'au bout.
Avertissement : Si
vous souhaitez définir la durée maximale pendant laquelle une transaction CICS peut être exécutée lorsqu'un contexte de transaction
globale ou un RMLT est importé dans CICS à partir de WebSphere, modifiez la valeur du paramètre OTSTIMEOUT
de la définition de transaction utilisée pour démarrer
la tâche de lien du serveur de lien CICS. Par défaut, le nom de transaction est BBO#. Si la durée d'exécution de la transaction CICS est supérieure à la durée indiquée par le paramètre OTSTIMEOUT, la tâche CICS qui exécute la transaction CICS est interrompue, ce qui entraîne l'annulation de toute la
transaction globale ou du RMLT. Pour plus d'informations sur le mode de codage du paramètre OTSTIMEOUT dans la
définition de la transaction, voir le manuel CICS Transaction Server for
z/OS Resource Definition Guide.
Si votre composant d'application
Java EE participe à un RMLT ou une transaction globale et que l'application
communique avec un programme batch ou un serveur de lien CICS démarré avec le
mot clé TXN=N, la connexion de l'adaptateur local optimisé ne peut pas établir de connexion avec le
programme cible. Le programme cible ne peut pas fournir les capacités transactionnelles requises par l'application
Java EE. Une exception s'affiche avec le code mineur 0xC9C24C3B. Ce code indique
que le nom d'enregistrement cible est détecté, mais n'est pas activé pour les
transactions. Seuls les serveurs de lien CICS
activés avec le mot clé TXN=Y peuvent prendre en charge les transactions
de propagation à partir de WebSphere Application
Server for z/OS.
Exemple
La méthode suivante indique comment démarrer une interaction avec des données
d'entrée et de sortie sous la forme d'un tableau d'octets (byte[]) :
public byte[] driveInteraction(javax.resource.cci.ConnectionFactory cf,
javax.resource.cci.Connection con,byte[] inputDataBytes),throws javax.resource.ResourceException
{
// Create an interaction using the optimized local adapter connection
javax.resource.cci.Interaction i = con.createInteraction();
// The InteractionSpec describes the service we want to call
com.ibm.websphere.ola.InteractionSpecImpl isi = new com.ibm.websphere.ola.InteractionSpecImpl();
isi.setServiceName("MYSERVICE");
// The input data is specified using an IndexedRecord. The first
// slot in the indexed record contains the input data bytes.
javax.resource.cci.RecordFactory rf = cf.getRecordFactory();
javax.resource.cci.IndexedRecord ir = rf.createIndexedRecord(null);
ir.add(inputDataBytes);
// The interaction returns another IndexedRecord, whose first
// slot contains the output data bytes.
javax.resource.cci.Record or = i.execute(isi, ir);
byte[] outputDataBytes = null;
if (or != null)
{
outputDataBytes = (byte[])((javax.resource.cci.IndexedRecord)or).get(0);
}
// Return the output data to the caller
return outputDataBytes;
}
La méthode suivante indique comment démarrer une interaction à l'aide d'un objet Record de stockage
généré par Rational Application Developer :
/**
* An example of driving an optimized local adapter interaction, using a Rational
* Application Developer copybook mapping class as input (inputRecord) and receiving
* a Rational Application Developer copybook mapping as output.
*/
public javax.resource.cci.Record driveInteraction(
javax.resource.cci.Connection con,
javax.resource.cci.Record inputRecord)
throws javax.resource.ResourceException
{
// Create an interaction using the OLA connection
javax.resource.cci.Interaction i = con.createInteraction();
// The InteractionSpec describes the service we want to call com.ibm.websphere.ola.InteractionSpecImpl isi =
new com.ibm.websphere.ola.InteractionSpecImpl();
isi.setServiceName("MYSERVICE");
// The Rational Application Developer generated copybook implements
// javax.resource.cci.Record and can be passed directly to the interaction.
// The interaction returns an IndexedRecord, whose first slot contains
// the output data bytes.
javax.resource.cci.Record or = i.execute(isi, inputRecord);
javax.resource.cci.Record outputRecord = null;
if (or != null)
{
// In this example, RADGeneratedOutputType is the name of the Rational Application Developer
// generated copybook mapping class.
outputRecord = new RADGeneratedOutputType();
// The output bytes are stored in the output record returned on the
// interaction, which is an IndexedRecord.
byte[] outputDataBytes =
(byte[])((javax.resource.cci.IndexedRecord)or).get(0);
// To convert the output bytes to another Rational Application Developer generated copybook,
// call the setBytes(byte[]) method of that class. The class will
// implement the com.ibm.etools.marshall.RecordBytes interface.
((com.ibm.etools.marshall.RecordBytes)outputRecord)
.setBytes(outputDataBytes);
}
// Return the output data to the caller
return outputRecord;
}