ALLOCATE

Article
12/15/2023

Le ALLOCATE verbe est émis par le programme de transaction d’appel (TP). Il alloue une session entre l’unité logique locale (LU) et l’unité lu partenaire et (conjointement avec RECEIVE_ALLOCATE) établit une conversation entre le TP appelant et le TP appelé. Une fois ce verbe exécuté avec succès, APPC génère un identificateur de conversation (conv_id). Le conv_id est un paramètre obligatoire pour tous les autres verbes de conversation APPC.

La structure suivante décrit le bloc de contrôle de verbe utilisé par le verbe ALLOCATE .

Syntaxe

  
struct allocate {  
    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    conv_type;  
    unsigned char    synclevel;  
    unsigned char    reserv3[2];  
    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    reserv5[11];  
    unsigned char    pwd[10];  
    unsigned char    user_id[10];  
    unsigned short   pip_dlen;  
    unsigned char FAR * pip_dptr;  
    unsigned char    reserv7;  
    unsigned char    fqplu_name[17];  
    unsigned char    reserv8[8];  
    unsigned long    proxy_user;  
    unsigned long    proxy_domain;  
    unsigned char    reserv9[16];  
};

Membres

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

opext
Paramètre fourni. Spécifie l’extension d’opération de verbe, AP_BASIC_CONVERSATION. Si le bit AP_EXTD_VCB est défini, cela indique qu’une version étendue du bloc de contrôle verbe est utilisée. Dans ce cas, la structure ALLOCATE inclut la prise en charge des points de synchronisation ou la prise en charge des fonctionnalités de proxy privilégiés.

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 TP local. La valeur de ce paramètre a été retournée par TP_STARTED.

conv_id
Paramètre retourné. Identifie la conversation établie entre les deux fournisseurs de services.

conv_type
Paramètre fourni. Utilisé uniquement par ALLOCATE pour spécifier le type de conversation à allouer et est AP_BASIC_CONVERSATION ou AP_MAPPED_CONVERSATION.

Si ALLOCATE établit une conversation mappée, le TP local doit émettre des verbes de conversation de base et fournir sa propre couche de mappage pour convertir les enregistrements de données en enregistrements logiques et les enregistrements logiques en enregistrements de données. Le TP partenaire peut émettre des verbes de conversation de base et fournir la couche de mappage, ou il peut utiliser des verbes de conversation mappés (si le TP partenaire utilise une implémentation d’APPC qui prend en charge les verbes de conversation mappés). Pour plus d’informations, consultez vos manuels IBM SNA.

niveau de synchronisation
Paramètre fourni. Spécifie le niveau de synchronisation de la conversation. Il détermine si les fournisseurs de services peuvent demander une confirmation de 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 fournisseurs de services peuvent utiliser le traitement de confirmation dans cette conversation.
AP_SYNCPT spécifie que les fournisseurs de services peuvent utiliser le traitement de confirmation de niveau de synchronisation 2 dans cette conversation.

reserv3
Un champ réservé.

rtn_ctl
Paramètre fourni. Spécifie quand l’unité lu locale, agissant sur une demande de session du TP local, doit retourner le contrôle au TP local. Pour plus d’informations sur les sessions, consultez À propos des programmes transactionnels.
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 documentées 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.) 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 indiqué 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_ALLOCATED spécifie que l’unité lu ne retourne pas le contrôle tant qu’elle n’a pas alloué une session gagnante de contention ou rencontré l’une des erreurs documentées 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.) Si une session n’est pas disponible, le TP en attend une.
AP_WHEN_CONV_GROUP_ALLOCATED 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’ellerencontre l’une des erreurs documentées dans codes de retour de cette rubrique. Si une session n’est pas disponible, le TP attend qu’elle devienne gratuite.

Notes

AP_IMMEDIATE est la seule valeur pour rtn_ctl qui n’entraîne jamais le démarrage d’une nouvelle session. Pour les valeurs autres que AP_IMMEDIATE, si une session appropriée n’est pas immédiatement disponible, Host Integration Server tente d’en démarrer une. Cela entraîne l’activation de la connexion à la demande.

reserv4
Un champ réservé.

conv_group_id
Paramètre fourni/retourné. Spécifie l’identificateur du groupe de conversations à partir duquel la session doit être allouée. Le conv_group_id n’est requis que si rtn_ctlest défini sur WHEN_CONV_GROUP_ALLOC. Quandrtn_ctl spécifie une valeur différente et que le primary_rc est AP_OK, il s’agit d’une valeur retournée.

sense_data
Paramètre retourné. Indique une erreur d’allocation (nouvelle tentative ou absence de nouvelle tentative) et contient des données de sens.

plu_alias
Paramètre fourni. Spécifie l’alias par lequel l’unité lu partenaire est connue du TP local.

Le plu_alias doit correspondre au nom d’une lu partenaire établie lors de la configuration.

Le paramètre est une chaîne de caractères ASCII de 8 octets. Il peut contenir les caractères ASCII suivants :

Lettres majuscules
Nombres 0 à 9
Espaces
Caractères spéciaux $, #, %, et @

Le premier caractère de cette chaîne ne peut pas être un espace.

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

Si vous souhaitez spécifier l’unité lu partenaire avec le paramètre fqplu_name , remplissez ce paramètre avec des zéros binaires.

Pour un utilisateur ou un groupe utilisant des TPs, des émulateurs 5250 et/ou des applications APPC, l’administrateur système peut affecter des unités de référence locales et distantes par défaut. Dans ce cas, le champ est laissé vide ou null et les unités de référence par défaut sont accessibles lorsque l’utilisateur ou le membre du groupe démarre un programme APPC. Pour plus d’informations sur les unités de référence par défaut, consultez Aide de Microsoft Host Integration Server.

mode_name
Paramètre fourni. Spécifie le nom d’un ensemble de caractéristiques réseau définies lors de la configuration.

La valeur de mode_name 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 :
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.

N’utilisez pas SNASVCMG dans une conversation mappée. SNASVCMG est un mode_name réservé utilisé en interne par APPC. L’utilisation de ce nom 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 qui respecte la casse. Le paramètre tp_name peut se composer des caractères EBCDIC suivants :
Lettres majuscules et minuscules
Nombres 0 à 9
Caractères spéciaux $, #, @ et point (.)

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

La convention SNA est qu’un nom 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 EBCDIC de type AE.

security
Paramètre fourni. Fournit les informations dont l’unité lu partenaire a besoin pour valider l’accès au TP appelé.

En fonction de la sécurité de conversation établie pour le TP appelé pendant la configuration, utilisez l’une des valeurs suivantes :
AP_NONE pour un TP appelé qui n’utilise aucune sécurité de conversation.
AP_PGM pour un TP appelé qui utilise la sécurité de conversation et nécessite donc un identificateur d’utilisateur et un mot de passe. Fournissez ces informations via les paramètres user_id et pwd .
AP_PROXY_PGM pour un TP appelé avec un proxy privilégié qui utilise la sécurité de conversation et nécessite donc un identificateur d’utilisateur et un mot de passe. Les pointeurs doivent être configurés pour que proxy_user et proxy_domain pointent vers des chaînes Unicode contenant le nom d’utilisateur et le nom de domaine de l’utilisateur à emprunter l’identité. L’application n’a pas besoin de définir les champs user_id et pwd .
AP_PROXY_SAME pour un TP qui a été appelé à l’aide d’un proxy privilégié avec un identificateur d’utilisateur et un mot de passe valides fournis par le proxy, qui à son tour appelle un autre TP. Les pointeurs doivent être configurés pour que proxy_user et proxy_domain pointent vers des chaînes Unicode contenant le nom d’utilisateur et le nom de domaine de l’utilisateur à emprunter l’identité. L’application n’a pas besoin de définir les champs user_id et pwd .

Par exemple, supposons que TP A appelle TP B avec un identificateur d’utilisateur et un mot de passe valides fournis par le proxy privilégié, et que TP B appelle à son tour TP C. Si TP B spécifie la valeur AP_PROXY_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é).
AP_PROXY_STRONG pour un TP appelé avec un proxy privilégié qui utilise la sécurité de conversation et nécessite donc un identificateur d’utilisateur et un mot de passe fournis par le mécanisme de proxy privilégié. Les pointeurs doivent être configurés pour que proxy_user et proxy_domain pointent vers des chaînes Unicode contenant le nom d’utilisateur et le nom de domaine de l’utilisateur à emprunter l’identité. L’application n’a pas besoin de définir les champs user_id et pwd . AP_PROXY_STRONG diffère de AP_PROXY_PGM en ce que AP_PROXY_STRONG n’autorise pas les mots de passe en texte clair. Si le système distant ne prend pas en charge les mots de passe chiffrés (sécurité de conversation forte), cet appel échoue.
AP_SAME pour un TP qui a été appelé avec un identificateur d’utilisateur et un mot de passe valides, qui à son tour appelle 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é).

Lorsque AP_SAME est utilisé dans un verbe ALLOCATE , votre application doit toujours fournir des valeurs pour les paramètres user_id et pwd dans le bloc de contrôle verbe. Selon les propriétés négociées entre le serveur SNA et l’unité lu homologue, le verbe ALLOCATE envoie l’un des trois types de messages Attach (FMH-5), dans cet ordre de priorité :

Si les LU ont négocié la sécurité « déjà vérifiée », l’attachement envoyé par le serveur SNA n’inclut pas le contenu du champ de paramètre pwd spécifié dans le VCB.
Si les LU ont négocié la sécurité de « vérification permanente », l’attachement envoyé par le serveur SNA inclut le paramètre pwd spécifié dans le VCB, mais uniquement lorsque l’attachement est le premier pour le paramètre user_id spécifié depuis le début de la session LU-LU et omet le paramètre pwd sur toutes les attaches suivantes (émises par votre application ou toute autre application utilisant ce triplet en mode LU-LU).
Si les LU n’ont pas négocié l’un des éléments ci-dessus, l’attachement envoyé par le serveur SNA omet à la fois les paramètres user_id et pwd sur toutes les attaches.

Votre application ne peut pas dire quel mode de sécurité a été négocié entre les LU, ni si le verbe ALLOCATE qu’elle émet est le premier pour ce triplet en mode LU-LU. Par conséquent, votre application doit toujours définir les champs de paramètres user_id et pwd dans le VCB lorsque la sécurité est définie sur AP_SAME.

Pour plus d’informations sur la vérification persistante et la sécurité déjà vérifiée, consultez le Guide des formats SNA, section « Fm Header 5 : Attach (LU 6.2) ».

AP_STRONG pour un TP appelé qui utilise la sécurité de conversation et nécessite donc un identificateur d’utilisateur et un mot de passe. Fournissez ces informations via les paramètres user_id et pwd . AP_STRONG diffère de AP_PGM en ce que AP_STRONG n’autorise pas les mots de passe en texte clair. Si le système distant ne prend pas en charge les mots de passe chiffrés (sécurité de conversation forte), cet appel échoue.

Si la fonctionnalité d’ouverture de session automatique APPC doit être utilisée, la sécurité doit être définie sur AP_PGM. Pour plus d'informations, consultez la section Notes.

reserv5
Un champ réservé.

pwd
Paramètre fourni. Spécifie le mot de passe associé à user_id.

Le paramètre pwd n’est requis que si la sécurité est définie sur AP_PGM ou AP_SAME. Il doit correspondre au mot de passe de user_id qui a été établi lors de la configuration.

Le paramètre pwd est une chaîne de caractères EBCDIC de 10 octets qui respecte la casse. Il peut se composer des caractères EBCDIC 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.

Si la fonctionnalité d’ouverture de session automatique APPC doit être utilisée, la chaîne de caractères pwd doit être codée en dur sur MS$SAME. Pour plus d'informations, consultez la section Notes.

User_id
Paramètre fourni. Spécifie l’identificateur d’utilisateur requis pour accéder au TP partenaire. Elle n’est requise que si le paramètre de sécurité est défini sur AP_PGM ou AP_SAME.

Le paramètre user_id est une chaîne de caractères EBCDIC de 10 octets qui respecte la casse. Il doit correspondre à l’un des identificateurs d’utilisateur configurés pour le TP partenaire.

Le paramètre peut se composer des caractères EBCDIC suivants :
Lettres majuscules et minuscules
Nombres 0 à 9
Caractères spéciaux $, #, @ et point (.)

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

Si la fonctionnalité d’ouverture de session automatique APPC doit être utilisée, la chaîne de caractères user_id doit être codée en dur sur MS$SAME. Pour plus d'informations, consultez la section Notes.

pip_dlen
Paramètre fourni. Spécifie la longueur des paramètres d’initialisation du programme (PIP) à passer au tp partenaire. La plage 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 de flux de données général (GDS). Pour plus d’informations, consultez Référence SNA LU6.2 : Protocoles homologues publiés par IBM.

Pour 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.

reserv7
Un champ réservé.

fqplu_name
Paramètre fourni. Spécifie le nom complet de l’unité lu partenaire. Cela doit correspondre au nom complet de la lu locale définie dans le nœud distant. Le paramètre se compose de deux chaînes de caractères EBCDIC de type A pour le NETID et le nom lu de l’unité lu partenaire. Les noms sont séparés par une période EBCDIC (.).

Ce nom doit être fourni si aucune plu_alias n’est spécifiée. Il peut se composer des caractères EBCDIC suivants :
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).

reserv8
Un champ réservé.

proxy_user
Paramètre fourni. Spécifie une LPWSTR pointant vers une chaîne Unicode contenant le nom d’utilisateur à emprunter l’identité à l’aide de la fonctionnalité de proxy privilégié. Ce champ ne peut être utilisé que lorsque le bit AP_EXTD_VCB est défini sur le champ opext , ce qui indique un VCB étendu.

proxy_domain
Paramètre fourni. Spécifie une LPWSTR pointant vers une chaîne Unicode contenant le nom de domaine de l’utilisateur à emprunter l’identité à l’aide de la fonctionnalité de proxy privilégié. Ce champ ne peut être utilisé que lorsque le bit AP_EXTD_VCB est défini sur le champ opext , ce qui indique un VCB étendu.

reserv9
Un champ réservé.

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 (AP_IMMEDIATE) du contrôle au TP, 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_SYNC_LEVEL

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

AP_BAD_TP_ID

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

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_BAD_CONV_TYPE (pour une conversation de base)

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

AP_NO_USE_OF_SNASVCMG (pour une conversation mappée)

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 étaient plus longues que le segment de données alloué, ou l’adresse de la mémoire tampon de données PIP é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 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 ; indique qu’il n’a pas été possible de charger un composant requis ou d’y mettre fin 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’est 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 génère ce code de retour pour le système configuré avec plusieurs nœuds à l’aide de Host Integration Server, 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

ALLOCATE peut établir une conversation de base ou mappée.

L’état de la conversation est RESET lorsque le TP émet ce verbe. Une fois l’exécution réussie (primary_rc est AP_OK), l’état devient SEND. Si le verbe ne s’exécute pas, l’état reste inchangé.

Plusieurs paramètres d’ALLOCATE 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.

Pour envoyer immédiatement la demande ALLOCATE , le TP appelant peut émettre flush ou CONFIRM immédiatement après ALLOCATE. Sinon, la requête ALLOCATE s’accumule avec d’autres données dans la mémoire tampon d’envoi de la lu locale jusqu’à ce que la mémoire tampon soit pleine.

En émettant CONFIRM after ALLOCATE, le TP appelant peut déterminer immédiatement si l’allocation a réussi (si le niveau de synchronisation est défini sur AP_CONFIRM_SYNC_LEVEL).

Normalement, la valeur du paramètre mode_name du verbe ALLOCATE doit correspondre au nom d’un mode configuré pour le nœud du TP appelé et associé lors de 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.

Host Integration Server prend en charge une fonctionnalité appelée substitution de mot de passe. Il s’agit d’une fonctionnalité de sécurité prise en charge par le système d’exploitation IBM i qui chiffre tout mot de passe qui circule entre deux nœuds sur un message Attach. Un mot de passe circule sur une attache chaque fois qu’une personne appelle un programme de transaction APPC spécifiant un identificateur d’utilisateur et un mot de passe. Par exemple, cela se produit chaque fois que quelqu’un se connecte à un IBM i.

La prise en charge de la substitution de mot de passe est indiquée en définissant le bit 5 dans l’octet 23 de la demande BIND sur 1 (ce qui indique que la substitution de mot de passe est prise en charge). Si le système distant définit ce bit dans la réponse BIND, le serveur SNA chiffre automatiquement le mot de passe de sécurité de conversation LU 6.2 inclus dans le message d’attachement FMH-5. Les applications APPC utilisant Host Integration Server tirent automatiquement parti de cette fonctionnalité en définissant le champ de sécurité du VCB sur AP_PGM ou AP_STRONG dans la requête ALLOCATE .

Si une application APPC souhaite forcer le flux d’un mot de passe chiffré, l’application peut spécifier AP_STRONG pour le champ de sécurité dans le VCB dans la requête ALLOCATE . Cette option est implémentée comme défini dans IBM i V3R1 et est documentée dans la référence du programmeur IBM i CPI-C sous la forme CM_SECURITY_PROGRAM_STRONG, où le champ LU 6.2 pwd (mot de passe) est chiffré avant qu’il ne circule sur le réseau physique.

Les fonctionnalités de substitution de mot de passe sont actuellement uniquement prises en charge par IBM i V3R1 ou version ultérieure. Si le système distant ne prend pas en charge cette fonctionnalité, le serveur SNA UNBIND la session avec le code sense de 10060006. Les deux nœuds négocient s’ils prennent ou non en charge cette fonctionnalité dans l’échange BIND. Host Integration Server définit un bit dans le bind et ajoute également des données aléatoires sur le BIND pour le chiffrement. Si le nœud distant prend en charge la substitution de mot de passe, il définit le même bit dans la réponse BIND et ajoute des données aléatoires (différentes) pour le déchiffrement.

Host Integration Server prend en charge l’ouverture de session automatique pour les applications APPC. Cette fonctionnalité nécessite une configuration spécifique de la part de l’administrateur réseau : l’application APPC doit être appelée côté RÉSEAU à partir d’un client de Host Integration Server. Le client doit être connecté à un domaine Windows, mais le client peut s’exécuter sur n’importe quel système d’exploitation pris en charge par les API APPC Host Integration Server.

L’application cliente est codée pour utiliser la sécurité au niveau « programme », avec un nom d’utilisateur APPC codé en dur spécial MS$SAME et un mot de passe MS$SAME. Lorsque cette allocation de session passe du client au serveur SNA, le serveur recherche le compte hôte et le mot de passe correspondant au compte Windows sous lequel le client est connecté et remplace les informations du compte hôte dans le message d’attachement APPC qu’il envoie à l’hôte.

Notes

Il est interdit au nœud distant de définir le bit spécifiant la substitution de mot de passe et de ne pas ajouter les données aléatoires.

Selon IBM, il existe des implémentations de la substitution de mot de passe LU 6.2 qui ne prennent pas en charge la substitution de mot de passe, mais qui renvoient le bit de substitution de mot de passe à Host Integration Server, sans spécifier de données aléatoires. Dans ce cas, le serveur SNA unBIND la session avec le code sense 10060006.Ce code de sens est interprété comme suit :

1006 = Champ ou paramètre obligatoire manquant.
0006 = Un sous-champ obligatoire d’un vecteur de contrôle a été omis.

Host Integration Server doit également consigner un événement 17 (échec d’activation de session APPC : réponse négative BIND envoyée).

La solution correcte consiste à corriger l’échec de l’implémentation. Toutefois, comme solution de contournement à court terme, le paramètre de Registre du service Host Integration Server suivant peut être défini :

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\snaservr\parameters\NOPWDSUB : REG_SZ : OUI

Lorsque ce paramètre est spécifié dans le Registre, la prise en charge de la substitution de mot de passe est désactivée.

Plusieurs mises à jour ont été apportées à Host Integration Server pour permettre à une application APPC privilégiée d’ouvrir une conversation APPC à l’aide de la fonctionnalité de Sign-On unique pour le compte d’un utilisateur Windows défini. Il s’agit de la fonctionnalité de proxy privilégié. Une extension a été ajoutée au verbe APPC ALLOCATE pour appeler cette fonctionnalité.

Une application APPC devient privilégiée en étant démarrée dans un compte d’utilisateur Windows membre d’un groupe Windows spécial. Lorsqu’un domaine de sécurité hôte est configuré, SNA Manager définit un deuxième groupe Windows à utiliser avec les fonctionnalités de sécurité de l’hôte de Host Integration Server. Si le compte d’utilisateur sous lequel le client est en cours d’exécution est membre de ce deuxième groupe Windows, le client est privilégié pour lancer une conversation APPC au nom de tout compte d’utilisateur défini dans le cache du compte hôte.

L’exemple suivant illustre le fonctionnement de la fonctionnalité de proxy privilégié :

L’administrateur du serveur d’intégration hôte crée un domaine de sécurité de l’hôte appelé APP. SNA Manager crée désormais deux groupes Windows. Le premier groupe est appelé APP et le second est appelé APP_PROXY pour cet exemple. Les utilisateurs affectés au groupe d’applications sont activés pour l’authentification unique. Les utilisateurs affectés au groupe APP_PROXY sont des proxys privilégiés. L’administrateur ajoute l’utilisateur Windows AppcUser au groupe APP_PROXY à l’aide du bouton Utilisateurs de la boîte de dialogue de la propriété Domaine de sécurité de l’hôte dans le Gestionnaire SNA.

L’administrateur configure ensuite une application APPC sur host Integration Server pour qu’elle s’exécute en tant que service Windows appelé APPCAPP et ce service a été configuré pour fonctionner sous le compte d’utilisateur AppcUser. Quand APPCAPP s’exécute, il ouvre une session APPC via un verbe ALLOCATE au format VCB étendu et spécifie le nom d’utilisateur Windows de l’utilisateur souhaité, UserA (par exemple).

Le service SNA voit la demande de session provenir d’une connexion qui est membre de l’APPLICATION domaine de sécurité hôte. L’interface client/serveur indique au service SNA que le client réel est AppcUser.

Le service SNA vérifie si AppcUser est membre du groupe APP_PROXY. Étant donné qu’AppcUser est membre de APP_PROXY, le service SNA insère le nom d’utilisateur/mot de passe pour UserA dans la commande APPC Attach (FMH-5) et l’envoie au tp partenaire.

Pour prendre en charge la fonctionnalité de proxy privilégié, l’application APPC doit implémenter la logique de programme suivante :

L’application APPC doit déterminer l’ID d’utilisateur Windows et le nom de domaine qu’elle souhaite emprunter l’identité.

L’application APPC doit définir les paramètres suivants avant d’appeler le verbe ALLOCATE :

Activez l’utilisation de la structure de bloc de contrôle de verbes ALLOCATE étendue en définissant l’indicateur AP_EXTD_VCB dans le champ opext .

Définissez sécurité sur AP_PROXY_SAME, AP_PROXY_PGM ou AP_PROXY_STRONG.

Configurez les pointeurs pour proxy_user et proxy_domain afin de pointer vers des chaînes Unicode contenant le nom d’utilisateur et le nom de domaine de l’utilisateur à emprunter l’identité.

Notes

L’application n’a pas besoin de configurer les champs user_id et pwd dans le VCB ALLOCATE .

Lorsque l’application APPC effectue les étapes ci-dessus et émet le verbe ALLOCATE , le serveur Host Integration Server effectue une recherche dans le domaine de sécurité de l’hôte pour l’utilisateur Windows spécifié et définit les champs ID utilisateur et mot de passe dans le message d’attachement FMH-5 envoyé au système distant.

ALLOCATE

Syntaxe

Membres

Codes de retour

Notes

Ressources supplémentaires