SEND_CONVERSATION

Le verbe 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ésaffecte 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 l’appel du TP ou par RECEIVE_ALLOCATE dans le TP appelé.

rtn_ctl
Paramètre fourni. Spécifie la façon dont APPC doit sélectionner une session à allouer pour la conversation et quand la 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 gagnant de contention, si une session 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’alloue pas une session ou rencontre l’une des erreurs décrites dans Les codes de retour dans cette rubrique. Si la limite de session est égale à zéro, la lu retourne immédiatement le contrôle. Notez que si une session n’est pas disponible, le TP attend un.

  • AP_WHEN_SESSION_FREE spécifie que le lu alloue une session de gagnant de contention 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 Les 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 l’unité logique ne retourne pas de contrôle tant qu’elle n’alloue pas une session contention-gagnant ou rencontre l’une des erreurs décrites dans Les codes de retour dans cette rubrique. Si la limite de session est égale à zéro, la lu retourne immédiatement le contrôle. Notez que si une session n’est pas disponible, le TP attend un.

  • AP_WHEN_CONV_GROUP_ALLOC spécifie que l’unité logique ne retourne pas le contrôle au TP tant qu’elle n’alloue pas la session spécifiée par conv_group_id ou rencontre l’une des erreurs décrites dans Les codes de retour dans cette rubrique. Si la session n’est pas disponible, le TP attend qu’il devienne gratuit.

    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 conversation à 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 avec l’assurance que la même session sera réaffectée et donc les conversations effectuées sur la session se produisent 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 aucune nouvelle tentative), un code de sens défini par SNA est retourné.

    plu_alias
    Paramètre fourni. Spécifie l’alias par lequel la lu partenaire est connue du TP local. Ce paramètre doit correspondre au nom d’une lu partenaire établie pendant la configuration. Le paramètre est un jeu de caractères G ASCII de type 8 octets qui inclut :

  • 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 à 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 du 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 à partir du jeu de caractères EBCDIC de type, 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.

    L’utilisation du nom SNASVCMG (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 l’appel du TP 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, sensible à la casse. Ce paramètre peut se composer de caractères à partir du jeu de caractères AE EBCDIC de type. Ces caractères sont les suivants :

  • Lettres majuscules et minuscules

  • Chiffres 0 à 9

  • Caractères spéciaux $, #, @ et point (.)

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

    La convention SNA pour nommer un tp de service est 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 EBCDIC AE.

    security
    Paramètre fourni. Spécifie les informations requises par l’unité d’accès du partenaire 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é des conversations 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 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 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 pendant la configuration.

    Ce paramètre est une chaîne de caractères EBCDIC de 10 octets, sensible à la casse. Il peut se composer de caractères du jeu de caractères AE EBCDIC de type. 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 remplir à 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 AE EBCDIC de type. Ces caractères sont les suivants :

  • Lettres majuscules et minuscules

  • Chiffres 0 à 9

  • Caractères spéciaux $, #, @ et point (.)

    Si l’identificateur de l’utilisateur est inférieur à 10 octets, utilisez des espaces EBCDIC (0x40) pour le remplir à 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 d’installation environnementales requises par un tp partenaire ou un système d’exploitation distant. Les données PIP doivent respecter 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 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 réseau (NETID) et le nom de l’unité logique du partenaire. Les noms sont séparés par un point EBCDIC (.). Le NETID peut être omis et, s’il s’agit du cas, la période doit également être omise.

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

    Les caractères EBCDIC de type sont les suivants :

  • Lettres majuscules

  • Chiffres 0 à 9

  • Caractères spéciaux $, #et @

    Si la valeur de ce paramètre est inférieure à 17 octets, remplissez-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 l’unité logique 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 l’unité logique 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 retour immédiat du contrôle au TP (AP_IMMEDIATE) et l’unité logique locale n’a pas eu 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 a été 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’une défaillance de lien. 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é 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 ALLOCATE, il peut indiquer qu’aucun système de communication n’a pu être trouvé pour prendre en charge l’unité logique 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 est inférieur à 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 satisfaire la requête 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 émise) n’est configurée sur aucun nœud actif. Le problème peut être l’un des suivants :

  • Le nœud avec l’unité logique locale n’est pas démarré.

  • L’unité logique 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 l’appel du TP 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’existe aucune modification d’état.

Plusieurs paramètres de SEND_CONVERSATION sont des chaînes EBCDIC ou ASCII. Un tp peut utiliser 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é 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 lorsqu’aucun nom de mode associé à l’unité logique partenaire ne correspond à la valeur de mode_name.