RUI_INIT

le verbe RUI_INIT transfère le contrôle de l’unité logique spécifiée (LU) à l’application Microsoft® Windows® application d’unité logique (LUA). RUI_INIT établit une session entre le point de contrôle des services système (SSCP) et le lu spécifié.

Notes

pour les utilisateurs de l’émulateur 3270, une extension de Host Integration Server Microsoft a été ajoutée, qui vous permet d’utiliser 3270 lus plutôt que les lu LUA. Pour plus d’informations, consultez la section Notes de cette rubrique.

La structure suivante décrit le LUA_COMMON membre 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 de verbe, LUA_VERB_RUI pour les verbes RUI (Request Unit interface).

lua_verb_length
Paramètre fourni. Spécifie la longueur, en octets, du LUA VCB. 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) du 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 pas ou ne modifie pas ces informations. Ce paramètre est facultatif.

lua_luname
Paramètre fourni. spécifie le nom ASCII du LU local utilisé par la session LUA Windows.

RUI_INIT requiert ce paramètre.

Ce paramètre a une longueur de huit octets, complété à droite par 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 à 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 à zéro.

lua_data_length
Non utilisé par RUI_INIT et doit être défini à zéro.

lua_data_ptr
Non utilisé par RUI_INIT et doit être défini à 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 à zéro.

lua_rh
Non utilisé par RUI_INIT et doit être défini à zéro.

lua_flag1
Non utilisé par RUI_INIT et doit être défini à zéro.

lua_message_type
Spécifie le type des commandes et des 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 demandes 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 exécuté de façon asynchrone si la valeur est égale à 1.

RUI_INIT se termine toujours de façon asynchrone, sauf si elle 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 dans le tableau doivent être vides. pour plus d’informations, consultez la description de ces Host Integration Server extensions dans la section notes.

lua_resv56 [1]

Paramètre fourni. Indique si une application RUI peut accéder aux lu configurés en tant que lu 3270, en plus des lu LUA. Si ce paramètre est différent de zéro, 3270 lu est accessible.

lua_resv56 [2]

Paramètre fourni. Indique si la bibliothèque RUI libère le LU lorsque la session ou la connexion LU-SSCP est supprimée. Si ce paramètre est différent de zéro, le LU n’est pas libéré.

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 notes relatives à RUI_READ.

lua_resv56 [4]

Paramètre fourni. Indique si la bibliothèque RUI permettra à l’application de conserver le LU si elle est recyclée sur l’hôte. Si ce paramètre est différent de zéro, l’application peut maintenir la suspension de l’unité logique.

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 la fin de RUI_INIT .

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 correspond à aucun nom de lu Lua ou nom de pool de lu dans le fichier de configuration.

LUA_INVALID_POST_HANDLE

Code de retour secondaire ; dans le cas d’un système d’exploitation Windows utilisant des événements comme méthode de publication asynchrone, le Windows le format d’événement 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 qui n’est pas 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 inattendue 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 d’unité logique ou un nom de pool lu déjà utilisé par cette application (ou pour lesquels cette application a déjà RUI_INIT en cours).

LUA_UNSUCCESSFUL
Code de retour principal ; l’enregistrement de verbe fourni était valide, mais le verbe ne s’est pas terminé correctement.

LUA_COMMAND_COUNT_ERROR

Le code de retour secondaire, qui indique l’une des erreurs suivantes s’est produite :

Le verbe n’a pas pu être émis, car l’application a déjà atteint le nombre maximal de sessions actives. sur Windows, une application peut avoir jusqu’à 15 000 sessions actives à tout moment.

Le verbe a spécifié le nom d’un pool de LU ou le nom d’un LU dans un pool, mais tous les LUs 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 ; le LU spécifié par lua_luname est utilisé 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 pourrait 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 de l’unité physique (PU) 2,1 a été interrompue (erreur LAN).

  • Le SnaBase sur l’ordinateur TPs 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 au niveau du service de liaison ou de l’unité logique hôte.

    LUA_INVALID_VERB
    Code de retour principal ; le code du verbe ou le code d’opération, ou les deux, ne sont pas valides. 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 a été 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.

    LUA_UNEXPECTED_DOS_ERROR
    Code de retour principal ; après l’émission d’un appel de système d’exploitation, un code de retour de système d’exploitation inattendu 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 ne s’est pas terminé correctement, le seul autre verbe LUA qui peut être émis pour cette session est RUI_TERM (qui termine un RUI_INITen 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 de l’unité logique ou nom du pool LU, fourni par l’application dans le paramètre lua_luname .

    RUI_INIT se termine après la réception d’un message ACTLU 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 à l’hôte pour lui indiquer que le lu est prêt à être utilisé.

    Ni ACTLU ni NOTIFY ne sont visibles par l’application LUA.

    Une fois RUI_INIT terminée, cette session utilise le lu pour lequel la session a été démarrée. Aucune autre session LUA (à partir de cette application ou de toute autre application) ne peut utiliser l’unité logique tant que RUI_TERM n’est pas émise, ou jusqu’à ce qu’un code de retour LUA_SESSION_FAILURE principal soit reçu.

Utilisation d’unités logiques 3270

pour fournir aux utilisateurs de l’émulateur 3270 la possibilité d’utiliser l’appel de configuration EIS (Emulator Interface Specification) avec l’API RUI, une extension de Host Integration Server a été ajoutée au RUI. Cette extension vous permet d’utiliser des lu 3270 plutôt que des lu LUA. Si une application définit lua_resv56 [1] à une valeur différente de zéro lors de l’appel de RUI_INIT , les lu 3270 peuvent être utilisés.

Ne pas libérer le LU

Si une application définit lua_resv56 [2] sur une valeur différente de zéro lors de l’appel de RUI_INIT , la bibliothèque Rui ne libère pas le lu lorsque la session ou la connexion lu-SSCP est supprimée. lorsque cette extension de Host Integration Server est activée, l’application n’a pas besoin d’émettre une nouvelle RUI_INIT après une défaillance de session ou un échec de connexion. Lorsque la session LU-SSCP est rétablie (l’application peut utiliser WinRUIGetLastInitStatus pour la détecter), l’application peut recommencer à l’utiliser.

Prendre en charge la segmentation de cette session

si une application définit lua_resv56 [3] à une valeur différente de zéro dans l’établissement de la session RUI_INIT , cela active une extension de 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 des données de l’application n’est pas suffisamment grande pour recevoir toutes les données du RU, en renvoyant un code d’erreur. Lorsque lua_resv56 [3] est défini sur une valeur différente de zéro pour l’appel de RUI_INIT , un RUI_READ émis lorsque la mémoire tampon de données de l’application n’est pas assez grande n’entraîne pas la suppression des données du RU. Le verbe RUI_READ retourne la réussite (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 DACTLUs

si une application définit lua_resv56 [4] sur une valeur différente de zéro dans l’établissement de la session RUI_INIT , cela active une extension de Host Integration Server, et la bibliothèque RUI permet à l’application de maintenir le LU si elle est recyclée sur l’hôte (autrement dit, désactivée et réactivée).

Notes

Tous les autres champs réservés doivent être 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 3270 Emulator.

Chiffrement

La cryptographie au niveau de la session est implémentée via des demandes de vérification de chiffrement (CRV). Les applications RUI doivent effectuer tout le traitement nécessaire de ces requêtes. 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 émettrice est chargée de remplir les données à un multiple de huit octets et de définir le bit de l’indicateur de données rembourrées dans les RH, ainsi que pour le chiffrement. L’application réceptrice est chargée de supprimer le remplissage après le déchiffrement.

Voir aussi

RUI_TERM
SLI_OPEN