Partager via

RECEIVE_ALLOCATE_EX

  • Article

Le verbe RECEIVE_ALLOCATE_EX accepte une nouvelle structure VCB pour autoriser l’inscription d’un gestionnaire d’attachement.

Syntaxe

  
typedef struct receive_allocate_ex {  
    unsigned short    opcode;  
        unsigned char     opext;   
        unsigned char     format;  
        unsigned short    primary_rc;  
        unsigned long    secondary_rc;  
       unsigned char     tp_name[64];  
       unsigned char     tp_id[8];  
       unsigned long     conv_id;  
       unsigned char     sync_level;  
        unsigned char    conv_type;  
        unsigned char     user_id[10];  
       unsigned char     lu_alias[8];  
       unsigned char     plu_alias[8];  
       unsigned char     mode_name[8];  
       unsigned char     reserv3[2];  
       unsigned long     conv_group_id;  
       unsigned char     fqplu_name[17];  
       unsigned char     pip_incoming;  
       unsigned long     timeout;  
       unsigned char     password[10];  
       unsigned char     reserv5[2];  
       unsigned char     attach_id[8];  
 }

Membres

opcode
Paramètre fourni : RECEIVE_ALLOCATE_EX

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

format
Paramètre 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.

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.

tp_name
Paramètre fourni. Le tp_name est un paramètre retourné uniquement. Toutefois, l’application doit allouer suffisamment d’espace tampon pour contenir le tp_name (c’est-à-dire 64 caractères) et initialiser le nom en espaces EBCDIC (X'40'hexadécimal)

Le verbe retourné contient le nom TP réel envoyé par le système distant.

tp_id
Paramètre retourné. Identifie le TP local.

conv_id
Paramètre retourné. Fournit l’identificateur de conversation. Il identifie la conversation établie par APPC entre les deux TPs partenaires.

sync_level
Paramètre retourné. Spécifie le niveau de synchronisation de la conversation. Il détermine si les fournisseurs de services peuvent demander la confirmation de la réception des données et confirmer la réception des données.

  • AP_NONE spécifie que le traitement de confirmation ne sera pas utilisé dans cette conversation.

  • AP_CONFIRM_SYNC_LEVEL spécifie que les TPs peuvent utiliser le traitement de confirmation dans cette conversation.

    AP_SYNCPT spécifie que les TPs peuvent utiliser le traitement de confirmation de niveau 2 de synchronisation dans cette conversation.

    conv_type
    Paramètre retourné. Spécifie le type de conversation choisi par le tp partenaire, à l’aide de MC_ALLOCATE ou ALLOCATE. Les valeurs possibles sont les suivantes :

    AP_BASIC_CONVERSATION

    AP_MAPPED_CONVERSATION

    user_id
    Il s’agit du user_id EBCDIC envoyé par le système distant

    lu_alias
    Paramètre fourni. Alias de lu locale. Doit être fourni pour inscrire un gestionnaire d’attachement. Un seul gestionnaire d’attachement peut être inscrit pour un alias de lu locale donné dans le sous-domaine Host Integration Server. Si un autre processus de gestionnaire d’attachement est déjà inscrit pour cette lu_alias, l’erreur suivante est retournée :

    primary_rc = AP_STATE_CHECK (0x0002) secondary_rc = AP_LU_ALREADY_REGISTERED (0x0000050A)

    Cela indique que Host Integration Server n’a pas pu inscrire ce gestionnaire d’attachement.

    plu_alias
    Paramètre retourné. Fournit l’alias par lequel l’unité logique partenaire (qui a lancé l’allocation entrante) est connue du TP local. Il s’agit d’une chaîne de caractères ASCII.

    mode_name
    Paramètre retourné. Fournit le nom de mode spécifié par MC_ALLOCATE ou ALLOCATE dans le tp partenaire. Il s’agit du nom d’un ensemble de caractéristiques réseau définies lors de la configuration. Le mode_name est une chaîne de caractères EBCDIC de type A.

    reserv3
    Paramètre réservé.

    conv_group_id
    Identificateur de groupe de conversation.

    fqplu_name
    Ce paramètre retourné fournit le nom complet de la lu.

    pip_incoming
    Paramètre fourni. Si ce gestionnaire d’attachement accepte les attachements FMH-5 entrants qui incluent des données PIP, définissez-le sur AP_YES. Sinon, définissez cette valeur sur AP_NO.

    Paramètre retourné : si des données PIP sont présentes dans l’attachement entrant, ce paramètre est défini sur AP_YES. Si aucune donnée PIP n’est présente, elle est définie sur AP_NO.

    timeout
    Délai d’expiration, en secondes. La valeur 0xFFFFFFFF peut être utilisée pour attendre indéfiniment.

    password
    Paramètre retourné : il s’agit du mot de passe EBCDIC envoyé par le système distant. Si le système distant prend en charge la « substitution de mot de passe » (chiffrement de mot de passe), le mot de passe chiffré est reçu dans RECEIVE_ALLOCATE_EX. Il n’existe aucune fonctionnalité permettant de déchiffrer ce mot de passe, de sorte que l’application ne pourra pas vérifier les informations d’identification de l’utilisateur.

    reserv5
    Paramètre réservé.

    attach_id
    Paramètre retourné. Toujours défini à 0. Ce champ est défini pour la compatibilité des sources avec les produits SNA non-Microsoft.

Remarques

Host Integration Server prend en charge les RECEIVE_ALLOCATE_EX et RECEIVE_ALLOCATE_EX_END APPC pour simplifier la conception et l’implémentation de certains programmes transactionnels invocables. Cette fonction permet à une application APPC de recevoir toutes les demandes d’attachement FMH-5 entrantes reçues par Host Integration Server sur une lu APPC locale spécifique, ce qui permet à une application d’agir en tant que « gestionnaire d’attachement ». Un gestionnaire d’attachement est un programme qui gère une demande d’attachement FMH-5 entrante pour démarrer une conversation LU6.2. Lorsqu’une application APPC appelle RECEIVE_ALLOCATE (par opposition à RECEIVE_ALLOCATE_EX), Host Integration Server gère la fonctionnalité du gestionnaire d’attachement. Pour implémenter la fonctionnalité de gestionnaire d’attachement dans une application APPC, les opérations suivantes se produisent :

  • L’application fournit un alias de lu APPC local à la fonction RECEIVE_ALLOCATE_EX , avec un tp_name d’espaces EBCDIC (X'40'hexadécimal).

  • Quand Host Integration Server reçoit une demande d’attachement FMH-5 entrante sur une session LU6.2 à l’aide de cette lu APPC locale, Host Integration Server route la demande vers l’application.

  • Une fois la RECEIVE_ALLOCATE_EX terminée, l’application est responsable des éléments suivants :

    1. Acceptation ou rejet de l’attachement FMH-5

    2. Vérification de la sécurité au niveau de la conversation, et

    3. Si vous acceptez la demande d’attachement, gérez complètement la demande dans son contexte de processus Win32.

  • Pour cesser d’écouter les nouvelles demandes d’attachement entrantes, l’application appelle RECEIVE_ALLOCATE_EX_END.

  • Après un problème de processus RECEIVE_ALLOCATE_EX, le processus ne doit pas appeler RECEIVE_ALLOCATE avec un nom TP spécifique. De même, si un processus appelle RECEIVE_ALLOCATE, ce processus ne doit pas appeler ultérieurement RECEIVE_ALLOCATE_EX. En d’autres termes, pendant la durée d’un processus prenant en charge un TP appelant, le processus doit appeler exclusivement RECEIVE_ALLOCATE, ou RECEIVE_ALLOCATE_EX, mais pas les deux.

    Il n’est pas possible pour l’application de distribuer la demande d’attachement entrante à un autre processus, car l’ID de conversation n’est valide que dans son propre contexte d’application.

Notes

: Host Integration Server ne prend pas en charge le démarrage automatique d’une application de gestionnaire d’attachement. En d’autres termes, si une application appelle RECEIVE_ALLOCATE_EX, l’application doit être démarrée avant que toutes les demandes Attach entrantes arrivent sur la lu locale.

La spécification actuelle ne retourne pas l’indicateur de sécurité (octet 4 de l’attachement FMH-5). Par conséquent, l’application doit prendre en charge les demandes d’attachement entrantes qui contiennent les éléments suivants :

  1. Ni user_id ni mot de passe (lorsqu’aucune sécurité n’est envoyée dans l’attachement),

  2. Un user_id uniquement (par exemple pour les pièces jointes « déjà vérifiées ») ou

  3. Un user_id et un mot de passe (si l’autorisation de l’utilisateur est requise).

    Dans la requête BIND LU6.2, Host Integration Server indique la prise en charge des demandes d’attachement FMH-5 entrantes qui contiennent la sécurité utilisateur, déjà vérifiée et la substitution de mot de passe. Host Integration Server ne prend pas en charge les attachements entrants qui demandent une vérification permanente.

    La fonction RECEIVE_ALLOCATE_EX permet à une application de s’inscrire en tant que gestionnaire d’attachement si le tp_name est défini sur tous les espaces EBCDIC (X'40') et qu’un alias de lu locale est fourni dans le champ lu_alias. Lorsqu’il est inscrit en tant que gestionnaire d’attachement pour un lu_alias donné, Host Integration Server route toutes les pièces jointes entrantes reçues au cours de la lu_alias vers l’application. Consultez ci-dessous pour plus d’informations sur la façon dont Host Integration Server route les demandes d’attachement FMH-5 entrantes.

    L’application peut appeler RECEIVE_ALLOCATE_EX plusieurs fois pour s’inscrire en tant que gestionnaire d’attachement pour une ou plusieurs unités lu locales. Toutefois, un seul gestionnaire d’attachement peut être inscrit sur un lu_alias donné dans le sous-domaine SNA (c’est-à-dire sur tous les serveurs d’intégration d’hôte et clients Host Integration Server attachés). L’application ne peut pas fournir un tp_name vide et un lu_alias vide. En d’autres termes, une application ne peut pas s’inscrire en tant que gestionnaire d’attachement par défaut pour recevoir toutes les demandes d’attachement entrantes pour un sous-domaine SNA.

    Une fois RECEIVE_ALLOCATE_EX terminée, l’application est responsable des éléments suivants :

  • Décider si l’attachement sera accepté ou non. Host Integration Server ne fournit aucun mécanisme pour la configuration des programmes transactionnels (TPs). L’application doit avoir ses propres moyens de définir les noms tp qu’elle prendra en charge.

  • Si elle est acceptée, l’application doit vérifier les attributs de sécurité de la conversation (user_id, mot de passe) et pour gérer le traitement de la nouvelle conversation.

  • Les tp_id et les conv_id ne peuvent pas être passés à un processus distinct pour la gestion. Tous les traitements TP doivent être fournis par l’application.

    Si l’application choisit de rejeter la demande d’attachement, [MC_]DEALLOCATE doit être appelé, en spécifiant les conv_id reçus dans le RECEIVE_ALLOCATE_EX terminé, ainsi qu’un code de motif approprié dans le paramètre dealloc_type, à l’aide de ces nouveaux codes étendus :

    #define AP_DEALLOC_SECURITY_NOT_VALID_PASSWORD_EXPIRED 0x10

    #define AP_DEALLOC_SECURITY_NOT_VALID_PASSWORD_INVALID 0x11

    #define AP_DEALLOC_SECURITY_NOT_VALID_USERID_REVOKED 0x12

    #define AP_DEALLOC_SECURITY_NOT_VALID_USERID_INVALID 0x13

    #define AP_DEALLOC_SECURITY_NOT_VALID_USERID_MISSING 0x14

    #define AP_DEALLOC_SECURITY_NOT_VALID_PASSWORD_MISSING 0x15

    #define AP_DEALLOC_SECURITY_NOT_VALID_GROUP_INVALID 0x16

    #define AP_DEALLOC_SECURITY_NOT_VALID_USERID_REVOKED_IN_GROUP 0x17

    #define AP_DEALLOC_SECURITY_NOT_VALID_USERID_NOT_DEFD_TO_GROUP 0x18

    #define AP_DEALLOC_SECURITY_NOT_VALID_NOT_AUTHORIZED_AT_REMOTE_LU 0x19

    #define AP_DEALLOC_SECURITY_NOT_VALID_NOT_AUTHORIZED_FROM_LOCAL_LU 0x1A

    #define AP_DEALLOC_SECURITY_NOT_VALID_NOT_AUTHORIZED_TO_TRANSACTION_PROGRAM 0x1B

    #define AP_DEALLOC_SECURITY_NOT_VALID_INSTALLATION_EXIT_FAILED 0x1C

    #define AP_DEALLOC_SECURITY_NOT_VALID_PROCESSING_FAILURE 0x1D

    #define AP_DEALLOC_SECURITY_NOT_VALID_PROTOCOL_VIOLATION 0x1E

    Lorsque l’application définit les dealloc_type ci-dessus, host Integration Server envoie le code sense correspondant dans l’erreur FMH-7 envoyée au système distant lors du rejet de la demande d’attachement FMH-5 :

    #define AP_SECURITY_NOT_VALID_PASSWORD_EXPIRED APPC_FLIPL(x080fff00)

    #define AP_SECURITY_NOT_VALID_PASSWORD_INVALID APPC_FLIPL(x080fff01)

    #define AP_SECURITY_NOT_VALID_USERID_REVOKED APPC_FLIPL(x080fff02)

    #define AP_SECURITY_NOT_VALID_USERID_INVALID APPC_FLIPL(x080fff03)

    #define AP_SECURITY_NOT_VALID_USERID_MISSING APPC_FLIPL(x080fff04)

    #define AP_SECURITY_NOT_VALID_PASSWORD_MISSING APPC_FLIPL(x080fff05)

    #define AP_SECURITY_NOT_VALID_GROUP_INVALID APPC_FLIPL(x080fff06)

    #define AP_SECURITY_NOT_VALID_USERID_REVOKED_IN_GROUP APPC_FLIPL(x080fff07)

    #define AP_SECURITY_NOT_VALID_USERID_NOT_DEFD_TO_GROUP APPC_FLIPL(x080fff08)

    #define AP_SECURITY_NOT_VALID_NOT_AUTHORIZED_AT_REMOTE_LU APPC_FLIPL(x080fff09)

    #define AP_SECURITY_NOT_VALID_NOT_AUTHORIZED_FROM_LOCAL_LU APPC_FLIPL(x080fff0A)

    #define AP_SECURITY_NOT_VALID_NOT_AUTHORIZED_TO_TRANSACTION_PROGRAM APPC_FLIPL(x080fff0B)

    #define AP_SECURITY_NOT_VALID_INSTALLATION_EXIT_FAILED APPC_FLIPL(x080fff0C)

    #define AP_SECURITY_NOT_VALID_PROCESSING_FAILURE APPC_FLIPL(x080fff0D)

    #define AP_SECURITY_NOT_VALID_PROTOCOL_VIOLATION APPC_FLIPL(x080fff0E)

    Avant d’appeler RECEIVE_ALLOCATE_EX, l’application peut souhaiter vérifier les paramètres de configuration de l’UNITÉ APPC locale afin de déterminer si la lu prend en charge le niveau de synchronisation 2 ou si elle est membre du pool d’unités logiques par défaut. Pour ce faire, utilisez l’API GET_LU_STATUS améliorée.

    Pour annuler l’inscription en tant que gestionnaire d’attachement pour une lu APPC locale donnée, l’application doit appeler RECEIVE_ALLOCATE_EX_END, documenté ci-dessous. Si une application s’est inscrite en tant que gestionnaire d’attachement pour plusieurs lu_alias, RECEIVE_ALLOCATE_EX_END doivent être appelées pour chaque lu_alias.

    L’application doit essayer d’avoir un RECEIVE_ALLOCATE_EX en attente à tout moment, afin de gérer les demandes d’attachement entrantes en temps opportun. Si l’application ne parvient pas à publier de nouvelles RECEIVE_ALLOCATE_EX, Host Integration Server met en file d’attente jusqu’à 2 048 attaches entrantes sur l’application, si l’application s’exécute sur le serveur d’intégration hôte, ou 256 si elle s’exécute sur un client HIS. Si la limite est dépassée, Host Integration Server rejette la demande d’attachement avec le code d’insertion X'084B6031', ou AP_TRANS_PGM_NOT_AVAIL_RETRY.