SEND_CONVERSATION

Article
07/21/2023

Le verbe SEND_CONVERSATION alloue une session entre l’unité logique locale (LU) et l’unité lu partenaire, envoie des données sur la session, puis libère la session.

La structure suivante décrit le bloc de contrôle de verbe (VCB) utilisé par le verbe SEND_CONVERSATION .

Syntaxe

  
struct send_conversation {  
    unsigned short      opcode;  
    unsigned char       opext;  
    unsigned char       reserv2;  
    unsigned short      primary_rc;  
    unsigned long       secondary_rc;  
    unsigned char       tp_id[8];  
    unsigned long       conv_id;  
       unsigned char       reserv3[8];  
    unsigned char       rtn_ctl;  
    unsigned char       reserv4;  
    unsigned long       conv_group_id;  
    unsigned long       sense_data;  
    unsigned char       plu_alias[8];  
    unsigned char       mode_name[8];  
    unsigned char       tp_name[64];  
    unsigned char       security;  
    unsigned char       reserv6[11];  
    unsigned char       pwd[10];  
    unsigned char       user_id[10];  
    unsigned short      pip_dlen;  
    unsigned char FAR * pip_dptr;  
    unsigned char       reserv6;  
    unsigned char       fqplu_name[17];  
    unsigned char       reserv7[8];  
    unsigned short      dlen;  
    unsigned char FAR * dptr;  
};

Membres

opcode
Paramètre fourni. Spécifie le code d’opération de verbe, AP_B_SEND_CONVERSATION.

opext
Paramètre fourni. Spécifie l’extension d’opération de verbe, AP_BASIC_CONVERSATION.

reserv2
Champ réservé.

primary_rc
Paramètre retourné. Spécifie le code de retour principal défini par APPC à l’achèvement du verbe. Les codes de retour valides dépendent du verbe APPC émis. Pour connaître les codes d’erreur valides de ce verbe, consultez Codes de retour.

secondary_rc
Paramètre retourné. Spécifie le code de retour secondaire défini par APPC à l’achèvement du verbe. Les codes de retour valides dépendent du verbe APPC émis. Pour connaître les codes d’erreur valides de ce verbe, consultez Codes de retour.

tp_id
Paramètre fourni. Identifie le programme de transaction local (TP). La valeur de ce paramètre a été retournée par TP_STARTED.

conv_id
Paramètre fourni. Fournit l’identificateur de conversation.

La valeur de ce paramètre est retournée par ALLOCATE dans le TP appelant ou par RECEIVE_ALLOCATE dans le TP appelé.

rtn_ctl
Paramètre fourni. Spécifie comment APPC doit sélectionner une session à allouer pour la conversation et quand l’unité lu locale doit retourner le contrôle au TP local. Les valeurs autorisées sont les suivantes :

AP_IMMEDIATE spécifie que la lu alloue une session de contention-gagnant, si celle-ci est immédiatement disponible, et retourne le contrôle au TP.
AP_WHEN_SESSION_ALLOCATED spécifie que l’unité lu ne retourne pas le contrôle au TP tant qu’elle n’a pas alloué une session ou rencontré l’une des erreurs décrites dans Codes de retour de cette rubrique. Si la limite de session est égale à zéro, l’unité lu retourne immédiatement le contrôle. Notez que si une session n’est pas disponible, le TP en attend une.
AP_WHEN_SESSION_FREE spécifie que la lu alloue une session de contention-winner ou de contention-loser, si une session est disponible ou peut être activée, et retourne le contrôle au TP. Si une erreur se produit (comme décrit dans Codes de retour dans cette rubrique), l’appel retourne immédiatement avec l’erreur dans les champs primary_rc et secondary_rc .
AP_WHEN_CONWINNER_ALLOC spécifie que la lu ne retourne pas le contrôle tant qu’elle n’a pas alloué une session gagnante ou rencontré l’une des erreurs décrites dans Codes de retour de cette rubrique. Si la limite de session est égale à zéro, l’unité lu retourne immédiatement le contrôle. Notez que si une session n’est pas disponible, le TP en attend une.
AP_WHEN_CONV_GROUP_ALLOC spécifie que la lu ne retourne pas le contrôle au TP tant qu’elle n’alloue pas la session spécifiée par conv_group_id ou qu’elle rencontre l’une des erreurs décrites dans codes de retour de cette rubrique. Si la session n’est pas disponible, le TP attend qu’elle devienne gratuite.

conv_group_id
Paramètre fourni/retourné. Utilisé comme paramètre fourni lorsque rtn_ctl est WHEN_CONV_GROUP_ALLOC pour spécifier l’identité du groupe de conversations à partir duquel la session doit être allouée. Quand rtn_ctl spécifie une valeur différente et que le primary_rc est AP_OK, il s’agit d’une valeur retournée. L’objectif de ce paramètre est de fournir à un TP l’assurance que la même session sera réaffectée et que, par conséquent, les conversations effectuées sur la session se dérouleront dans la même séquence qu’elles ont été lancées.

sense_data
Paramètre retourné. Si les codes de retour principal et secondaire indiquent une erreur d’allocation (nouvelle tentative ou non), un code de sens défini par SNA est retourné.

plu_alias
Paramètre fourni. Spécifie l’alias par lequel l’unité lu partenaire est connue du TP local. Ce paramètre doit correspondre au nom d’une lu partenaire établie lors de la configuration. Le paramètre est un jeu de caractères ASCII de 8 octets de type G qui comprend :
Lettres majuscules
Nombres 0 à 9
Espaces
Caractères spéciaux $, #, %, et @

Si la valeur de ce paramètre est inférieure à huit octets, placez-le à droite avec des espaces ASCII (0x20).

mode_name
Paramètre fourni. Spécifie le nom d’un ensemble de caractéristiques réseau définies lors de la configuration. Ce paramètre doit correspondre au nom d’un mode associé à l’unité lu partenaire pendant la configuration.

Le paramètre est une chaîne de caractères EBCDIC de 8 octets. Il peut se composer de caractères du jeu de caractères EBCDIC de type A, y compris tous les espaces EBCDIC. Ces caractères sont les suivants :
Lettres majuscules
Nombres 0 à 9
Caractères spéciaux $, #et @

Le premier caractère de la chaîne doit être une lettre majuscule ou un caractère spécial.

L’utilisation du nom SNASVCMG (un nom de mode réservé utilisé en interne par APPC) dans une conversation de base n’est pas recommandée.

tp_name
Paramètre fourni. Spécifie le nom du TP appelé. La valeur de tp_name spécifiée par ALLOCATE dans le TP appelant doit correspondre à la valeur de tp_name spécifiée par RECEIVE_ALLOCATE dans le TP appelé.

Le paramètre est une chaîne de caractères EBCDIC de 64 octets, respectant la casse. Ce paramètre peut se composer de caractères du jeu de caractères EBCDIC de type AE. Ces caractères sont les suivants :
Lettres majuscules et minuscules
Nombres 0 à 9
Caractères spéciaux $, #, @ et point (.)

Si le nom TP est inférieur à 64 octets, utilisez des espaces EBCDIC (0x40) pour le placer à droite.

La convention SNA pour nommer un tp de service comprend jusqu’à quatre caractères. Le premier caractère est un octet hexadécimal compris entre 0x00 et 0x3F. Les autres caractères proviennent du jeu de caractères AE EBCDIC.

security
Paramètre fourni. Spécifie les informations dont l’unité lu partenaire a besoin pour valider l’accès au TP appelé.
AP_NONE spécifie que le TP appelé n’utilise aucune sécurité de conversation.
AP_PGM spécifie que le TP appelé utilise la sécurité de conversation et nécessite un identificateur d’utilisateur et un mot de passe. Utilisez user_id et pwd pour fournir ces informations.
AP_SAME spécifie que le TP appelé, appelé avec un identificateur d’utilisateur et un mot de passe valides, appelle à son tour un autre TP.

Par exemple, supposons que TP A appelle TP B avec un identificateur d’utilisateur et un mot de passe valides, et que TP B appelle à son tour TP C. Si TP B spécifie la valeur AP_SAME, APPC envoie à la LU pour TP C l’identificateur utilisateur à partir de TP A et un indicateur déjà vérifié. Cet indicateur indique à TP C de ne pas exiger le mot de passe (si TP C est configuré pour accepter un indicateur déjà vérifié).

pwd
Paramètre fourni. Spécifie le mot de passe associé à user_id. Ce paramètre n’est requis que si le paramètre de sécurité est défini sur AP_PGM et doit correspondre au mot de passe pour user_id qui a été établi pendant la configuration.

Ce paramètre est une chaîne de caractères EBCDIC de 10 octets, respectant la casse. Il peut se composer de caractères du jeu de caractères EBCDIC de type AE. Ces caractères sont les suivants :
Lettres majuscules et minuscules
Nombres 0 à 9
Caractères spéciaux $, #, @ et point (.)

Si le mot de passe est inférieur à 10 octets, utilisez des espaces EBCDIC (0x40) pour le placer à droite.

User_id
Paramètre fourni. Spécifie l’identificateur d’utilisateur requis pour accéder au TP partenaire. Ce paramètre n’est requis que si le paramètre de sécurité est défini sur AP_PGM et doit correspondre à l’un des identificateurs utilisateur configurés pour le TP partenaire.

Le paramètre peut se composer de caractères du jeu de caractères EBCDIC de type AE. Ces caractères sont les suivants :
Lettres majuscules et minuscules
Nombres 0 à 9
Caractères spéciaux $, #, @ et point (.)

Si l’identificateur utilisateur est inférieur à 10 octets, utilisez des espaces EBCDIC (0x40) pour le placer sur la droite.

pip_dlen
Paramètre fourni. Spécifie la longueur du PIP à passer au TP partenaire. La plage de ce paramètre est comprise entre 0 et 32767.

pip_dptr
Paramètre fourni. Spécifie l’adresse de la mémoire tampon contenant des données PIP. Utilisez ce paramètre uniquement si pip_dlen est supérieur à zéro.

Les données PIP peuvent se composer de paramètres d’initialisation ou d’informations de configuration environnementale requises par un tp partenaire ou un système d’exploitation distant. Les données PIP doivent suivre le format GDS. Pour plus d’informations, consultez vos manuels IBM SNA.

Pour le système d’exploitation Microsoft Windows, la mémoire tampon de données peut résider dans une zone de données statique ou dans une zone allouée globalement.

fqplu_name
Paramètre fourni. Spécifie le nom complet de la lu locale. Ce paramètre doit correspondre au nom complet de l’unité lu locale définie dans le nœud distant. Le paramètre est composé de deux chaînes de caractères EBCDIC de type A (chacune de huit caractères maximum), qui sont le nom de réseau (NETID) et le nom lu de l’unité utilisateur partenaire. Les noms sont séparés par une période EBCDIC (.). Le NETID peut être omis, et si c’est le cas, le point doit également être omis.

Ce nom doit être fourni si aucune plu_alias n’est fournie.

Les caractères EBCDIC de type A contiennent :
Lettres majuscules
Nombres 0 à 9
Caractères spéciaux $, #et @

Si la valeur de ce paramètre est inférieure à 17 octets, placez-le sur la droite avec des espaces EBCDIC (0x40).

dlen
Paramètre fourni. Spécifie le nombre d’octets de données à placer dans la mémoire tampon d’envoi de la lu locale. La plage de ce paramètre est comprise entre 0 et 65535.

Dpt
Paramètre fourni. Spécifie l’adresse de la mémoire tampon contenant les données à placer dans la mémoire tampon d’envoi de la lu locale.

Pour le système d’exploitation Windows, la mémoire tampon de données peut résider dans une zone de données statique ou dans une zone allouée globalement. La mémoire tampon de données doit s’adapter entièrement à cette zone.

Codes de retour

AP_OK
Code de retour principal ; indique que le verbe s’est exécuté correctement.

AP_UNSUCCESSFUL
Code de retour principal ; le paramètre fourni rtn_ctl spécifié le retour immédiat du contrôle au TP (AP_IMMEDIATE), et la lu locale n’avait pas de session de gagnant de contention disponible.

AP_PARAMETER_CHECK
Code de retour principal ; le verbe n’a pas été exécuté en raison d’une erreur de paramètre.

AP_BAD_RETURN_CONTROL

Code de retour secondaire ; la valeur spécifiée pour rtn_ctl n’était pas valide.

AP_BAD_SECURITY

Code de retour secondaire ; la valeur spécifiée pour la sécurité n’était pas valide.

AP_BAD_TP_ID

Code de retour secondaire ; la valeur de tp_id ne correspondait pas à un identificateur TP attribué par APPC.

AP_PIP_LEN_INCORRECT

Code de retour secondaire ; la valeur de pip_dlen était supérieure à 32767.

AP_UNKNOWN_PARTNER_MODE

Code de retour secondaire ; la valeur spécifiée pour mode_name n’était pas valide.

AP_BAD_PARTNER_LU_ALIAS

Code de retour secondaire ; APPC n’a pas reconnu le partner_lu_alias fourni.

AP_ALLOCATION_ERROR
Code de retour principal ; APPC n’a pas pu allouer une conversation. L’état de la conversation est défini sur RESET.

Ce code peut être retourné par le biais d’un verbe émis après ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Code de retour secondaire ; la conversation ne peut pas être allouée en raison d’une condition permanente, telle qu’une erreur de configuration ou une erreur de protocole de session. Pour déterminer l’erreur, l’administrateur système doit examiner le fichier journal des erreurs. Ne réessayez pas l’allocation tant que l’erreur n’a pas été corrigée.

AP_ALLOCATION_FAILURE_RETRY

Code de retour secondaire ; la conversation n’a pas pu être allouée en raison d’une condition temporaire, telle qu’un échec de liaison. La raison de l’échec est consignée dans le journal des erreurs système. Réessayez l’allocation.

AP_COMM_SUBSYSTEM_ABENDED
Code de retour principal ; indique l’une des situations suivantes :

Le nœud utilisé par cette conversation a rencontré un abandon (ABEND).
La connexion a été interrompue entre le programme transactionnel et le nœud PU 2.1 (erreur LAN).
Le processus SnaBase qui se déroule sur l’ordinateur du programme transactionnel a rencontré un abandon (ABEND).

L’administrateur système doit examiner le journal des erreurs pour déterminer la raison de l’abandon.

AP_COMM_SUBSYSTEM_NOT_LOADED
Code de retour principal ; un composant requis n’a pas pu être chargé ou s’est arrêté pendant le traitement du verbe. Par conséquent, la communication n’a pas pu être établie. Contactez l’administrateur système pour mettre en place une action corrective.

Lorsque ce code de retour est utilisé avec ALLOCATE, cela peut indiquer qu’aucun système de communication n’a pu être trouvé pour prendre en charge la lu locale. (Par exemple, l’alias lu local spécifié avec TP_STARTED est incorrect ou n’a pas été configuré.) Notez que si lu_alias ou mode_name contient moins de huit caractères, vous devez vous assurer que ces champs sont remplis d’espaces à droite. Cette erreur est retournée si ces paramètres ne sont pas remplis d’espaces, car aucun nœud disponible ne peut répondre à la demande ALLOCATE .

Lorsque ALLOCATE produit ce code de retour pour un système client Host Integration Server configuré avec plusieurs nœuds, il existe deux codes de retour secondaires comme suit :

0xF0000001

Code de retour secondaire ; aucun nœud n’a été démarré.

0xF0000002

Code de retour secondaire ; au moins un nœud a été démarré, mais l’unité logique locale (lorsque TP_STARTED est émis) n’est pas configurée sur les nœuds actifs. Le problème peut être l’un des suivants :
Le nœud avec l’unité logique locale n’est pas démarré.
La lu locale n’est pas configurée.

AP_INVALID_VERB_SEGMENT
Code de retour principal ; indique que le bloc de contrôle de verbe s’étend au-delà de la fin du segment de données.

AP_STACK_TOO_SMALL
Code de retour principal ; indique que la taille de la pile de l’application est trop petite pour exécuter le verbe. Augmentez la taille de pile de votre application.

AP_CONV_BUSY
Code de retour principal ; il ne peut y avoir qu’un seul verbe de conversation en suspens à la fois sur n’importe quelle conversation. Cela peut se produire si le tp local a plusieurs threads et que plusieurs threads émettent des appels APPC à l’aide du même conv_id.

AP_THREAD_BLOCKING
Code de retour principal ; indique que le thread appelant se trouve déjà dans un appel de blocage.

AP_UNEXPECTED_DOS_ERROR
Code de retour principal ; indique que le système d’exploitation a retourné une erreur à APPC lors du traitement d’un appel APPC à partir du programme transactionnel local. Le code de retour du système d’exploitation a été retourné via secondary_rc. Il apparaît dans l’ordre Intel avec permutation d’octets. Si le problème persiste, consultez l’administrateur système.

Notes

Ce verbe est émis par le TP appelant pour mener une conversation entière avec le TP distant. Si le TP distant rejette l’initiation de la conversation ou les données, le TP appelant ne reçoit pas de notification de rejet.

L’état de la conversation est RESET lorsque le TP émet ce verbe. Il n’y a aucun changement d’état.

Plusieurs paramètres de SEND_CONVERSATION sont des chaînes EBCDIC ou ASCII. Un TP peut utiliser la conversion CSV pour traduire une chaîne d’un jeu de caractères à l’autre.

Normalement, la valeur de mode_name doit correspondre au nom d’un mode configuré pour le nœud du TP appelé et associé pendant la configuration à l’unité logique partenaire. Si l’un des modes associés à l’unité logique partenaire sur le nœud du TP appelé est un mode implicite, la session établie entre les deux unités logiques est du mode implicite quand aucun nom de mode associé à l’unité logique partenaire ne correspond à la valeur de mode_name.

SEND_CONVERSATION

Syntaxe

Membres

Codes de retour

Notes

Ressources supplémentaires