RUI_INIT
Le verbe RUI_INIT transfère le contrôle de l’unité logique (LU) spécifiée à l’application LUA (Application d’unité logique Microsoft® Windows®). RUI_INIT établit une session entre le point de contrôle des services système (SSCP) et la lu spécifiée.
Notes
Pour les utilisateurs de l’émulateur 3270, une extension Microsoft Host Integration Server a été ajoutée qui vous permet d’utiliser 3270 unités de référence plutôt que les unités LUA. Pour plus d’informations, consultez Remarques dans cette rubrique.
La structure suivante décrit le membre LUA_COMMON du bloc de contrôle de verbe (VCB) utilisé par RUI_INIT.
Syntaxe
struct LUA_COMMON {
unsigned short lua_verb;
unsigned short lua_verb_length;
unsigned short lua_prim_rc;
unsigned long lua_sec_rc;
unsigned short lua_opcode;
unsigned long lua_correlator;
unsigned char lua_luname[8];
unsigned short lua_extension_list_offset;
unsigned short lua_cobol_offset;
unsigned long lua_sid;
unsigned short lua_max_length;
unsigned short lua_data_length;
char FAR * lua_data_ptr;
unsigned long lua_post_handle;
struct LUA_TH lua_th;
struct LUA_RH lua_rh;
struct LUA_FLAG1 lua_flag1;
unsigned char lua_message_type;
struct LUA_FLAG2 lua_flag2;
unsigned char lua_resv56[7];
unsigned char lua_encr_decr_option;
};
Membres
lua_verb
Paramètre fourni. Contient le code verbe, LUA_VERB_RUI pour les verbes RUI (Request Unit Interface).
lua_verb_length
Paramètre fourni. Spécifie la longueur en octets du VCB LUA. Il doit contenir la longueur de l’enregistrement de verbe émis.
lua_prim_rc
Code de retour principal défini par LUA à la fin du verbe. Les codes de retour valides varient en fonction du verbe LUA émis.
lua_sec_rc
Code de retour secondaire défini par LUA à la fin du verbe. Les codes de retour valides varient en fonction du verbe LUA émis.
lua_opcode
Paramètre fourni. Contient le code de commande LUA (code d’opération de verbe) pour le verbe à émettre, LUA_OPCODE_RUI_INIT.
lua_correlator
Paramètre fourni. Contient une valeur fournie par l’utilisateur qui lie le verbe à d’autres informations fournies par l’utilisateur. LUA n’utilise ni ne modifie ces informations. Ce paramètre est facultatif.
lua_luname
Paramètre fourni. Spécifie le nom ASCII de la lu locale utilisée par la session Windows LUA.
RUI_INIT nécessite ce paramètre.
Ce paramètre a une longueur de huit octets, rembourré à droite avec des espaces (0x20) si le nom est inférieur à huit caractères.
lua_extension_list_offset
Non utilisé par RUI dans Host Integration Server et doit être défini sur zéro.
lua_cobol_offset
Non utilisé par LUA dans Host Integration Server et doit être égal à zéro.
lua_sid
Paramètre retourné. Spécifie l’identificateur de session.
lua_max_length
Non utilisé par RUI_INIT et doit être défini sur zéro.
lua_data_length
Non utilisé par RUI_INIT et doit être défini sur zéro.
lua_data_ptr
Non utilisé par RUI_INIT et doit être défini sur zéro.
lua_post_handle
Paramètre fourni. Utilisé sous Microsoft® Windows Server si la notification asynchrone doit être effectuée par des événements. Cette variable contient le handle de l’événement à signaler ou un handle de fenêtre.
lua_th
Non utilisé par RUI_INIT et doit être défini sur zéro.
lua_rh
Non utilisé par RUI_INIT et doit être défini sur zéro.
lua_flag1
Non utilisé par RUI_INIT et doit être défini sur zéro.
lua_message_type
Spécifie le type des commandes et données SNA entrantes ou sortantes. Il s’agit d’un paramètre retourné pour RUI_INIT. Les valeurs possibles sont les suivantes :
LUA_MESSAGE_TYPE_LU_DATA
LUA_MESSAGE_TYPE_SSCP_DATA
LUA_MESSAGE_TYPE_BID
LUA_MESSAGE_TYPE_BIND
LUA_MESSAGE_TYPE_BIS
LUA_MESSAGE_TYPE_CANCEL
LUA_MESSAGE_TYPE_CHASE
LUA_MESSAGE_TYPE_CLEAR
LUA_MESSAGE_TYPE_CRV
LUA_MESSAGE_TYPE_LUSTAT_LU
LUA_MESSAGE_TYPE_LUSTAT_SSCP
LUA_MESSAGE_TYPE_QC
LUA_MESSAGE_TYPE_QEC
LUA_MESSAGE_TYPE_RELQ
LUA_MESSAGE_TYPE_RQR
LUA_MESSAGE_TYPE_RTR
LUA_MESSAGE_TYPE_SBI
LUA_MESSAGE_TYPE_SHUTD
LUA_MESSAGE_TYPE_SIGNAL
LUA_MESSAGE_TYPE_SDT
LUA_MESSAGE_TYPE_STSN
LUA_MESSAGE_TYPE_UNBIND
L’interface de niveau session (SLI) reçoit et répond aux requêtes BIND, CRV et STSN via les routines d’extension d’interface LUA.
LU_DATA, LUSTAT_LU, LUSTAT_SSCP et SSCP_DATA ne sont pas des commandes SNA.
lua_flag2
Paramètre retourné. Contient des indicateurs pour les messages retournés par LUA.
lua_flag2.async
Indique que le verbe d’interface LUA s’est terminé de manière asynchrone s’il est défini sur 1.
RUI_INIT se termine toujours de manière asynchrone, sauf s’il retourne une erreur telle que LUA_PARAMETER_CHECK).
lua_resv56
Paramètre fourni. Champ réservé utilisé par RUI_INIT et SLI_OPEN. Tous les autres champs réservés du tableau doivent être laissés vides. Pour plus d’informations, consultez la discussion sur ces extensions Host Integration Server dans la section Remarques.
lua_resv56[1]
Paramètre fourni. Indique si une application RUI peut accéder aux unités LU configurées en tant que 3270 unités de référence, en plus des unités LUA. Si ce paramètre n’est pas nul, 3270 unités de référence sont accessibles.
lua_resv56[2]
Paramètre fourni. Indique si la bibliothèque RUI libère l’unité lu lorsque la session lu-SSCP ou la connexion disparaît. Si ce paramètre n’est pas nul, l’unité lu n’est pas publiée.
lua_resv56[3]
Paramètre fourni. Indique si les lectures incomplètes sont prises en charge. Si ce paramètre est défini sur une valeur différente de zéro, les lectures incomplètes ou tronquées sont prises en charge. Pour plus d’informations, consultez les remarques relatives à RUI_READ.
lua_resv56[4]
Paramètre fourni. Indique si la bibliothèque RUI permet à l’application de conserver l’unité lu si elle est recyclée sur l’hôte. Si ce paramètre n’est pas nul, l’application peut conserver la lu.
lua_encr_decr_option
Champ pour les options de chiffrement. Sur RUI_INIT, seuls les éléments suivants sont pris en charge :
lua_encr_decr_option = 0
lua_encr_decr_option = 128
Les valeurs comprises entre 1 et 127 ne sont pas prises en charge.
Codes de retour
LUA_OK
Code de retour principal ; indique que le verbe s’est exécuté correctement.
LUA_CANCELED
Code de retour principal ; le verbe ne s’est pas terminé correctement, car il a été annulé par un autre verbe.
LUA_TERMINATED
Code de retour secondaire ; RUI_TERM a été émis avant RUI_INIT terminé.
LUA_PARAMETER_CHECK
Code de retour principal ; le verbe n’a pas été exécuté en raison d’une erreur de paramètre.
LUA_INVALID_LUNAME
Code de retour secondaire ; le paramètre lua_luname ne correspondait à aucun nom lu LUA ou nom du pool LU dans le fichier de configuration.
LUA_INVALID_POST_HANDLE
Code de retour secondaire ; pour un système d’exploitation Windows utilisant des événements comme méthode de publication asynchrone, le VCB Windows LUA ne contient pas de handle d’événement valide.
LUA_RESERVED_FIELD_NOT_ZERO
Code de retour secondaire ; un champ réservé dans l’enregistrement de verbe, ou un paramètre non utilisé par ce verbe, a été défini sur une valeur différente de zéro.
LUA_VERB_LENGTH_INVALID
Code de retour secondaire ; un verbe LUA a été émis avec la valeur de lua_verb_length inattendu par LUA.
LUA_STATE_CHECK
Code de retour principal ; le verbe n’a pas été exécuté, car il a été émis dans un état non valide.
LUA_DUPLICATE_RUI_INIT
Code de retour secondaire ; le paramètre lua_luname a spécifié un nom lu ou un nom de pool LU déjà utilisé par cette application (ou pour lequel cette application a déjà RUI_INIT en cours).
LUA_UNSUCCESSFUL
Code de retour principal ; l’enregistrement du verbe fourni était valide, mais le verbe ne s’est pas terminé correctement.
LUA_COMMAND_COUNT_ERROR
Code de retour secondaire, qui indique que l’une des erreurs suivantes s’est produite :
Le verbe n’a pas pu être émis, car l’application avait déjà atteint son nombre maximal de sessions actives. Sur Windows, une application peut avoir 15 000 sessions actives à tout moment.
Le verbe a spécifié le nom d’un pool lu ou le nom d’une unité lu dans un pool, mais toutes les unités de référence du pool sont en cours d’utilisation.
LUA_ENCR_DECR_LOAD_ERROR
Code de retour secondaire ; le verbe a spécifié une valeur pour lua_encr_decr_option autre que 0 ou 128.
LUA_INVALID_PROCESS
Code de retour secondaire ; l’unité lu spécifiée par lua_luname est en cours d’utilisation par un autre processus.
LUA_LINK_NOT_STARTED
Code de retour secondaire ; la connexion à l’hôte n’a pas été démarrée ; aucun des services de liaison qu’il peut utiliser n’est actif.
LUA_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 entre le programme de transaction (TP) et le nœud d’unité physique (PU) 2.1 a été rompue (erreur LAN).
Le SnaBase sur l’ordinateur des fournisseurs de services a rencontré un ABEND.
LUA_SESSION_FAILURE
Code de retour principal ; un composant Host Integration Server requis s’est arrêté.LUA_LU_COMPONENT_DISCONNECTED
Code de retour secondaire ; indique que la session LUA a échoué en raison d’un problème avec le service de liaison ou avec l’unité lu hôte.
LUA_INVALID_VERB
Code de retour principal ; le code du verbe ou le code d’opération, ou les deux, n’est pas valide. Le verbe n’a pas été exécuté.LUA_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.LUA_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.LUA_UNEXPECTED_DOS_ERROR
Code de retour principal ; après l’émission d’un appel de système d’exploitation, un code de retour inattendu du système d’exploitation a été reçu et est spécifié dans le code de retour secondaire.
Remarques
Ce verbe doit être le premier verbe LUA émis pour la session. Tant que ce verbe n’est pas terminé, le seul autre verbe LUA qui peut être émis pour cette session est RUI_TERM (ce qui met fin à un RUI_INIT en attente).
Tous les autres verbes émis sur cette session doivent identifier la session à l’aide de l’un des paramètres suivants de ce verbe :
Identificateur de session retourné à l’application dans lua_sid.
Nom lu ou nom du pool LU, fourni par l’application dans le paramètre lua_luname .
RUI_INIT se termine une fois qu’un message ACTLU est reçu de l’hôte. Si nécessaire, le verbe attend indéfiniment. Si un ACTLU a déjà été reçu avant RUI_INIT, LUA envoie une notification NOTIFY à l’hôte pour l’informer que la lu est prête à être utilisée.
Ni ACTLU ni NOTIFY ne sont visibles par l’application LUA.
Une fois RUI_INIT terminée, cette session utilise la lu pour laquelle la session a été démarrée. Aucune autre session LUA (de cette application ou de toute autre application) ne peut utiliser la lu tant qu’RUI_TERM n’a pas été émise ou jusqu’à ce qu’un code de retour principal LUA_SESSION_FAILURE soit reçu.
Utilisation de 3270 unités de référence
Pour permettre aux utilisateurs de l’émulateur 3270 d’utiliser l’appel de configuration EIS (Emulator Interface Specification) avec l’API RUI, une extension Host Integration Server a été ajoutée au RUI. Cette extension vous permet d’utiliser 3270 unités de référence plutôt que des unités LUA. Si une application définit lua_resv56[1] sur une valeur différente de zéro sur l’appel de RUI_INIT , 3270 unités de référence peuvent être utilisées.
Ne pas libérer l’unité lu
Si une application définit lua_resv56[2] sur une valeur différente de zéro sur l’appel RUI_INIT , la bibliothèque RUI ne libère pas la lu lorsque la session LU-SSCP ou la connexion disparaît. Lorsque cette extension Host Integration Server est activée, l’application n’a pas besoin d’émettre une nouvelle RUI_INIT après un échec de session ou un échec de connexion. Lorsque la session LU-SSCP est rétablie (l’application peut utiliser WinRUIGetLastInitStatus pour détecter cela), l’application peut recommencer à l’utiliser.
Prise en charge de la segmentation sur cette session
Si une application définit lua_resv56[3] sur une valeur différente de zéro sur l’établissement de session RUI_INIT , cela active une extension Host Integration Server qui peut modifier le comportement de RUI_READ. Le comportement par défaut d’un appel de RUI_READ consiste à tronquer les données (en ignorant toutes les données restantes) si la mémoire tampon de données de l’application n’est pas assez grande pour recevoir toutes les données dans la RU, ce qui renvoie un code d’erreur. Lorsque lua_resv56[3] est défini sur une valeur différente de zéro lors de l’appel de RUI_INIT , une RUI_READ émise lorsque la mémoire tampon de données de l’application n’est pas suffisamment grande n’entraîne pas l’abandon des données ru. Le verbe RUI_READ retourne success (LUA_OK) pour le code de retour principal et LUA_DATA_INCOMPLETE pour le code de retour secondaire. Les demandes de RUI_READ suivantes peuvent ensuite être émises pour récupérer les données qui ont dépassé la mémoire tampon de données de l’application.
Ignorer les DACTLUs
Si une application définit lua_resv56[4] sur une valeur différente de zéro sur l’établissement de session RUI_INIT , cela active une extension Host Integration Server, et la bibliothèque RUI permet à l’application de conserver l’unité logique si elle est recyclée sur l’hôte (c’est-à-dire désactivée et réactivée).
Notes
Tous les autres champs réservés doivent être laissés vides.
Pour plus d’informations, consultez la description de la fonction sepdcrec dans la section de l’aide du Kit de développement logiciel (SDK) sur la spécification de l’interface de l’émulateur 3270.
Chiffrement
Le chiffrement au niveau de la session est implémenté par le biais de requêtes de vérification de chiffrement (CRV). Les applications RUI doivent effectuer tous les traitements nécessaires de ces demandes. Pour toutes les interfaces autres que RUI, les demandes CRV sont rejetées avec une réponse négative par Host Integration Server.
Pour RUI_INIT, les options suivantes sont prises en charge :
lua_encr_decr_option = 0
lua_encr_decr_option = 128
Les valeurs comprises entre 1 et 127 (routines ACSRENCR et ACSROECR) ne sont pas prises en charge.
L’application d’envoi est responsable du remplissage des données sur un multiple de huit octets et de la définition du bit d’indicateur de données rembourré dans l’rh, ainsi que du chiffrement. L’application réceptrice est responsable de la suppression du remplissage après le déchiffrement.