MC_SEND_CONVERSATION

Article
10/14/2023

Le verbe MC_SEND_CONVERSATION alloue une session entre l’unité logique locale (LU) et l’unité logique partenaire, envoie des données sur la session, puis désalloue la session.

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

Syntaxe

  
struct mc_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_M_SEND_CONVERSATION.

opext
Paramètre fourni. Spécifie l’extension d’opération de verbe, AP_MAPPED_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 MC_ALLOCATE dans le tp d’appel 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é logique 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 contention-winner, si elle est immédiatement disponible, et retourne le contrôle au TP.
AP_WHEN_SESSION_ALLOCATED spécifie que l’unité logique 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 dans cette rubrique. Si la limite de session est égale à zéro, l’unité logique 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 contention-winner ou 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 est retourné immédiatement avec l’erreur dans les champs primary_rc et secondary_rc .
AP_WHEN_CONWINNER_ALLOC spécifie que l’unité logique ne retourne pas le contrôle tant qu’elle n’a pas alloué une session de contention gagnante ou rencontré l’une des erreurs décrites dans Codes de retour dans cette rubrique. Si la limite de session est égale à zéro, l’unité logique 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 l’unité logique ne retourne pas le contrôle au TP tant qu’elle n’a pas alloué la session spécifiée par conv_group_id ou rencontré l’une des erreurs décrites dans codes de retour dans 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. Lorsque 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, 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 absence de nouvelle tentative), un code de détection défini par SNA est retourné.

plu_alias
Paramètre fourni. Spécifie l’alias par lequel l’unité logique 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 type G de 8 octets qui comprend :
Lettres majuscules
Chiffres 0 à 9
Espaces
Caractères spéciaux $, #, %, et @

Si la valeur de ce paramètre est inférieure à huit octets, placez-la sur la 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 pendant la configuration. Ce paramètre doit correspondre au nom d’un mode associé à la 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
Chiffres 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.

Dans une conversation mappée, le nom ne peut pas être SNASVCMG (un nom de mode réservé utilisé en interne par APPC).

tp_name
Paramètre fourni. Spécifie le nom du TP appelé. La valeur de tp_name spécifiée par MC_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 être constitué de caractères du jeu de caractères EBCDIC de type AE. Ces caractères sont les suivants :
Lettres majuscules et minuscules
Chiffres 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 sur la droite.

La convention SNA est que le nom d’un tp de service peut comporter 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é logique 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 à l’unité logique pour TP C l’identificateur utilisateur 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 est obligatoire uniquement si le paramètre de sécurité est défini sur AP_PGM et doit correspondre au mot de passe de user_id qui a été établi lors de la configuration.

Ce paramètre est une chaîne de caractères EBCDIC de 10 octets, respectant la casse. Il peut être constitué de caractères du jeu de caractères EBCDIC de type AE. Ces caractères sont les suivants :
Lettres majuscules et minuscules
Chiffres 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 sur la 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
Chiffres 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 être constituées de paramètres d’initialisation ou d’informations de configuration environnementales 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 votre ou 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 l’unité logique locale. Ce paramètre doit correspondre au nom complet de l’unité logique locale définie dans le nœud distant. Le paramètre est constitué de deux chaînes de caractères EBCDIC de type A (chacune d’un maximum de huit caractères), qui sont le nom de réseau (NETID) et le nom lu de l’unité logique partenaire. Les noms sont séparés par un point 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.

Type Un caractère EBCDIC contient :
Lettres majuscules
Chiffres 0 à 9
Caractères spéciaux $, #, et @

Si la valeur de ce paramètre est inférieure à 17 octets, placez-la 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 tenir entièrement dans 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 contention-gagnant 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 correspond 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_NO_USE_OF_SNASVCMG

Code de retour secondaire ; SNASVCMG n’est pas une valeur valide pour mode_name.

AP_INVALID_DATA_SEGMENT

Code de retour secondaire ; les données PIP ou les données d’application étaient plus longues que le segment de données alloué, ou l’adresse d’une mémoire tampon de données était incorrecte.

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 MC_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 terminé lors du 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 MC_ALLOCATE, cela peut indiquer qu’aucun système de communication n’est trouvé pour prendre en charge l’unité 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 n’est disponible pour répondre à la demande MC_ALLOCATE .

Lorsque MC_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 la lu locale (quand TP_STARTED est émis) n’est configurée sur aucun nœud actif. Le problème peut être l’un des suivants :
Le nœud avec l’unité lu 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 à 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 du 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 MC_SEND_CONVERSATION sont des chaînes EBCDIC ou ASCII. Un TP peut utiliser le verbe de service commun (CSV) CONVERT 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é lu partenaire. Si l’un des modes associés à l’unité lu partenaire sur le nœud du TP appelé est un mode implicite, la session établie entre les deux unités de gestion sera du mode implicite lorsqu’aucun nom de mode associé à l’unité lu partenaire ne correspond à la valeur de mode_name.

MC_SEND_CONVERSATION

Syntaxe

Membres

Codes de retour

Notes

Ressources supplémentaires