RUI_READ
Le verbe RUI_READ reçoit des réponses, des commandes SNA et des données dans une mémoire tampon d’applications d’application d’unité logique (LUA) Microsoft® Windows®.
La structure suivante décrit le membre LUA_COMMON du bloc de contrôle verbe (VCB) utilisé par RUI_READ.
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_READ.
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 de la lu locale utilisée par la session Windows LUA.
RUI_READ requiert ce paramètre uniquement si lua_sid est égal à zéro.
Ce paramètre est de huit octets, rempli à 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 Microsoft® Host Integration Server et doit être égal à zéro.
lua_sid
Paramètre fourni et retourné. Spécifie l’identificateur de session et est retourné par SLI_OPEN et RUI_INIT. D’autres verbes utilisent ce paramètre pour identifier la session utilisée pour la commande . Si d’autres verbes utilisent le paramètre lua_luname pour identifier les sessions, définissez le paramètre lua_sid sur zéro.
lua_max_length
Spécifie la longueur de la mémoire tampon reçue pour RUI_READ et SLI_RECEIVE. Non utilisé par d’autres verbes RUI et SLI et doit être défini sur zéro.
lua_data_length
Paramètre retourné. Spécifie la longueur des données retournées dans lua_peek_data pour le verbe RUI_BID .
lua_data_ptr
Pointeur vers la mémoire tampon fournie par l’application qui doit recevoir les données d’un verbe RUI_READ . Les commandes et les données SNA sont placées dans cette mémoire tampon, et elles peuvent être au format EBCDIC.
Lorsque RUI_READ est émis, ce paramètre pointe vers l’emplacement où recevoir les données de l’hôte.
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
Paramètre retourné. Contient l’en-tête de transmission SNA (TH) du message envoyé ou reçu. Différents sous-paramètres sont définis pour les fonctions d’écriture et retournés pour les fonctions de lecture et d’enchère. Ses sous-paramètres sont les suivants :
lua_th.flags_fid
Format d’identification type 2, quatre bits.
lua_th.flags_mpf
Champ de mappage de segmentage, deux bits. Définit le type de segment de données. Les valeurs suivantes sont valides :
0x00 Segment du milieu0x04 Dernier segment0x08 Premier segment0x0C segment uniquement
lua_th.flags_odai
Indicateur de l’assigneur champ d’adresse d’origine-champ d’adresse de destination (OAF–DAF), un bit.
lua_th.flags_efi
Indicateur de flux accéléré, un bit.
lua_th.daf
Champ d’adresse de destination (DAF), char non signé.
lua_th.oaf
Champ d’adresse d’origine (OAF), char non signé.
lua_th.snf
Champ numéro de séquence, char non signé[2].
lua_rh
Paramètre retourné. Contient l’en-tête de requête/réponse SNA (RH) du message envoyé ou reçu. Elle est définie pour la fonction d’écriture et retournée par les fonctions de lecture et d’enchère. Ses sous-paramètres sont les suivants :
lua_rh.rri
Indicateur requête-réponse, un bit.
lua_rh.ruc
Catégorie de RU, deux bits. Les valeurs suivantes sont valides :
LUA_RH_FMD (0x00) segment de données FMLUA_RH_NC (0x20) Contrôle réseauLUA_RH_DFC (0x40) Contrôle de fluxde données LUA_RH_SC (0x60) Contrôle de session
lua_rh.fi
Indicateur de format, un bit.
lua_rh.sdi
Détecter l’indicateur des données incluses, un bit.
lua_rh.bci
Indicateur de chaîne de début, un bit.
lua_rh.eci
Indicateur de chaîne de fin, un bit.
lua_rh.dr1i
Réponse définie 1 indicateur, un bit.
lua_rh.dr2i
Réponse définie 2 indicateur, un bit.
lua_rh.ri
Indicateur de réponse d’exception (pour une demande) ou indicateur de type de réponse (pour une réponse), un bit.
lua_rh.qri
Indicateur de réponse mis en file d’attente, un bit.
lua_rh.pi
Indicateur de rythme, un bit.
lua_rh.bbi
Commencez l’indicateur de crochets, un bit.
lua_rh.ebi
Indicateur de crochet de fin, un bit.
lua_rh.cdi
Changer l’indicateur de direction, un bit.
lua_rh.csi
Indicateur de sélection de code, un bit.
lua_rh.edi
Indicateur de données enchiffré, un bit.
lua_rh.pdi
Indicateur de données rembourrées, un bit.
lua_flag1
Paramètre fourni. Contient une structure de données contenant des indicateurs pour les messages fournis par l’application. Ses sous-paramètres sont les suivants :
lua_flag1.bid_enable
Indicateur d’activation de l’enchère, un bit.
lua_flag1.close_abend
Fermez l’indicateur immédiat, un bit.
lua_flag1.nowait
Pas d’attente pour l’indicateur de données, un bit.
lua_flag1.sscp_exp
Flux accéléré SSCP, un bit.
lua_flag1.sscp_norm
Flux normal SSCP, un bit.
lua_flag1.lu_exp
Flux accéléré lu, un bit.
lua_flag1.lu_norm
Flux normal lu, un bit.
Définissez lua_flag1.nowait sur 1 pour indiquer que vous souhaitez que RUI_READ retourne immédiatement si les données sont disponibles ou non à lire, ou définissez-les sur zéro si vous souhaitez que le verbe attende les données avant de les renvoyer.
Définissez lua_flag1.bid_enable sur 1 pour réactiver les RUI_BID les plus récents (ce qui revient à émettre à nouveau RUI_BID avec exactement les mêmes paramètres qu’auparavant), ou définissez-le sur zéro si vous ne souhaitez pas réactiver RUI_BID.
La réactivation de l’RUI_BID précédente réutilise le VCB initialement alloué pour lui, de sorte que ce VCB ne doit pas avoir été libéré ou modifié.
Définissez un ou plusieurs des indicateurs suivants sur 1 pour indiquer à partir de quel flux de message lire les données :
lua_flag1.sscp_exp
lua_flag1.lu_exp
lua_flag1.sscp_norm
lua_flag1.lu_norm
Si plusieurs indicateurs sont définis, les données de priorité la plus élevée disponibles sont retournées. L’ordre des priorités (le plus élevé en premier) est : SSCP accéléré, LU accéléré, SSCP normal, LU normal. L’indicateur équivalent dans le groupe lua_flag2 est défini pour indiquer à partir du flux à partir duquel les données ont été lues.
lua_message_type
Spécifie le type des commandes et données SNA entrantes ou sortantes. Paramètre retourné. Spécifie le type de message SNA indiqué à RUI_READ. Les valeurs possibles sont les suivantes :
LUA_MESSAGE_TYPE_LU_DATA
LUA_MESSAGE_TYPE_SSCP_DATA
LUA_MESSAGE_TYPE_RQR
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_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
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. Ses sous-paramètres sont les suivants :
lua_flag2.bid_enable
Indique que RUI_BID a été correctement réactivé s’il est défini sur 1.
lua_flag2.async
Indique que le verbe d’interface LUA s’est terminé de manière asynchrone s’il est défini sur 1.
lua_flag2.sscp_exp
Indique le flux accéléré SSCP s’il est défini sur 1.
lua_flag2.sscp_norm
Indique le flux normal SSCP s’il est défini sur 1.
lua_flag2.lu_exp
Indique le flux accéléré lu s’il est défini sur 1.
lua_flag2.lu_norm
Indique le flux normal lu si défini sur 1.
lua_resv56
Réservé et doit être défini sur zéro.
lua_encr_decr_option
Réservé et doit être défini sur zéro.
Codes de retour
LUA_OK
Code de retour principal ; indique que le verbe s’est exécuté correctement.
LUA_DATA_INCOMPLETE
Code de retour secondaire ; RUI_READ n’a pas pu retourner toutes les données reçues, car la mémoire tampon de données de l’application (indiquée par lua_max_length) n’était pas assez grande. Les demandes de RUI_READ suivantes peuvent être émises pour récupérer les données RUI restantes.
Il ne s’agit pas du comportement par défaut pour RUI_READ et n’est activé que lorsque lua_resv56[3] est défini sur une valeur différente de zéro dans le bloc de contrôle verbe lors de l’appel de RUI_INIT pendant l’établissement de la session. Pour plus d’informations, consultez Remarques.
LUA_CANCELED
Code de retour principal ; le verbe ne s’est pas terminé correctement, car il a été annulé par un autre verbe ou par une erreur interne.
LUA_PURGED
Code de retour secondaire ; RUI_READ a été annulé par RUI_PURGE.
LUA_TERMINATED
Code de retour secondaire ; RUI_TERM a été émis alors que RUI_READ était en attente.
LUA_PARAMETER_CHECK
Code de retour principal ; le verbe n’a pas été exécuté en raison d’une erreur de paramètre.
LUA_BAD_DATA_PTR
Code de retour secondaire ; le paramètre lua_data_ptr contenait une valeur non valide.
LUA_BAD_SESSION_ID
Code de retour secondaire ; une valeur non valide pour lua_sid a été spécifiée dans le VCB.
LUA_BID_ALREADY_ENABLED
Code de retour secondaire ; lua_flag1.bid_enable a été défini pour réactiver RUI_BID , mais le RUI_BID précédent était toujours en cours.
LUA_DUPLICATE_READ_FLOW
Code de retour secondaire ; les indicateurs de flux du groupe lua_flag1 spécifiaient un ou plusieurs flux de session pour lesquels RUI_READ était déjà en attente. Une seule RUI_READ à la fois peut attendre chaque flux de session.
LUA_INVALID_FLOW
Code de retour secondaire ; aucun des indicateurs de flux lua_flag1 n’a été défini. Au moins l’un de ces indicateurs doit avoir la valeur 1 pour indiquer à partir de quel flux ou flux lire.
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_NO_PREVIOUS_BID_ENABLED
Code de retour secondaire ; lua_flag1.bid_enable a été défini pour réactiver RUI_BID, mais aucune RUI_BID précédente ne pouvait être activée. (Pour plus d’informations, consultez la section Notes.)
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_NO_RUI_SESSION
Code de retour secondaire ; RUI_INIT n’a pas encore réussi pour le nom lu spécifié sur RUI_READ.
LUA_NEGATIVE_RSP
Code de retour principal ; indique l’un des deux cas suivants, qui peuvent être distingués par le code de retour secondaire :
LUA a détecté une erreur dans les données reçues de l’hôte. Au lieu de transmettre le message reçu à l’application sur RUI_READ, LUA ignore le message (et le reste de la chaîne s’il se trouve dans une chaîne) et envoie une réponse négative à l’hôte. LUA informe la demande d’une RUI_READ ou d’un RUI_BID ultérieur qu’une réponse négative a été envoyée.
L’application LUA a précédemment envoyé une réponse négative à un message au milieu d’une chaîne. LUA a vidé les messages suivants dans cette chaîne et signale désormais à l’application que tous les messages de la chaîne ont été reçus et vidés.
LUA_SEC_RC
Code de retour secondaire ; ce paramètre est un code de retour secondaire différent de zéro contenant le code sense envoyé à l’hôte sur la réponse négative. Cela indique que LUA a détecté une erreur dans les données de l’hôte et envoyé une réponse négative à l’hôte. Pour plus d’informations sur l’interprétation des valeurs de code de sens qui peuvent être retournées, consultez Considérations relatives au SNA à l’aide de LUA.
Un code de retour secondaire de zéro indique que, suite à une RUI_WRITE précédente d’une réponse négative à un message au milieu d’une chaîne, LUA a maintenant reçu et ignoré tous les messages de cette chaîne.
LUA_UNSUCCESSFUL
Code de retour principal ; l’enregistrement du verbe fourni était valide, mais le verbe ne s’est pas terminé correctement.LUA_DATA_TRUNCATED
Code de retour secondaire ; le paramètre lua_data_length était inférieur à la longueur réelle des données reçues sur le message. Seuls lua_data_length octets de données ont été retournés au verbe ; les données restantes ont été ignorées. Des paramètres supplémentaires sont également retournés si ce code de retour secondaire est obtenu.
LUA_NO_DATA
Code de retour secondaire ; lua_flag1.nowait a été défini pour indiquer un retour immédiat sans attendre les données, et aucune donnée n’était actuellement disponible sur le flux ou les flux de session spécifiés.
LUA_INVALID_PROCESS
Code de retour secondaire ; le processus OS/2 qui a émis ce verbe n’était pas le même processus que celui qui a émis RUI_INIT pour cette session. Seul le processus qui a démarré une session peut émettre des verbes sur cette session.
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é interrompue (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_RUI_LOGIC_ERROR
Code de retour secondaire ; une erreur interne a été détectée dans LUA. Cette erreur ne doit pas se produire pendant une opération normale.
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
RUI_INIT devez avoir terminé correctement avant l’émission de RUI_READ .
Lorsqu’un RUI_READ existant est en attente, vous pouvez émettre un autre RUI_READ uniquement s’il spécifie un autre flux de session ou s’il s’exécute à partir de verbes RUI_READ en attente. Vous ne pouvez pas avoir plusieurs RUI_READ en attente pour le même flux de session.
Vous pouvez spécifier un flux de message particulier (LU normal, LU accéléré, SSCP normal ou SSCP accéléré) à partir duquel lire des données, ou vous pouvez spécifier plusieurs flux de messages. Vous pouvez avoir plusieurs verbes RUI_READ en suspens, à condition qu’aucun d’entre eux ne spécifie le même flux.
Les données sont reçues par l’application sur l’un des quatre flux de session. Les quatre flux de session, de la priorité la plus élevée à la priorité la plus faible sont les suivants :
SSCP accéléré
LU accélérée
SSCP normal
LU normal
Le type de flux de données que RUI_READ doit traiter est spécifié dans le paramètre lua_flag1 . L’application peut également spécifier si elle souhaite examiner plusieurs types de flux de données. Lorsque plusieurs bits de flux sont définis, la priorité la plus élevée est reçue en premier. Lorsque RUI_READ termine le traitement, lua_flag2 indique le type spécifique de flux pour lequel les données ont été reçues par l’application Windows LUA.
Si RUI_BID se termine correctement avant l’émission d’un RUI_READ , l’interface Windows LUA peut être chargée de réutiliser le dernier RUI_BID verbes VCB. Pour ce faire, émettez le RUI_READ avec lua_flag1.bid_enable défini.
Le paramètre lua_flag1.bid_enable ne peut être utilisé que si les éléments suivants sont true :
RUI_BID a déjà été émis avec succès et s’est terminé.
Le stockage alloué pour RUI_BID n’a pas été libéré ou modifié.
Aucune autre RUI_BID n’est en attente.
Lorsque vous utilisez lua_flag1.bid_enable, le stockage RUI_BID ne doit pas être libéré, car le dernier RUI_BID verbes VCB est utilisé. En outre, lors de l’utilisation de lua_flag1.bid_enable, la réussite de RUI_BID est publiée.
Si RUI_READ est émis avec lua_flag1.nowait quand aucune donnée n’est disponible à recevoir, LUA_NO_DATA sera le code de retour secondaire défini par l’interface Windows LUA.
Si les données reçues sont plus longues que lua_max_length, elles sont tronquées. Seuls lua_max_length octets de données sont retournés. Le code de retour principal LUA_UNSUCCESSFUL et le code de retour secondaire LUA_DATA_TRUNCATED sont également retournés. La bibliothèque RUI retourne autant de données que possible dans la mémoire tampon de données de l’application, mais les données restantes du RUI sont ignorées et ne peuvent pas être extraites lors des demandes de RUI_READ suivantes. Cela force l’application RUI à allouer une mémoire tampon de données RUI_READ suffisamment grande pour gérer la taille complète de la RU.
Ce comportement par défaut peut être modifié en définissant la valeur de lua_resv56[3] sur une valeur différente de zéro dans le bloc de contrôle verbe lors de l’appel de RUI_INIT pendant l’établissement de la session. Dans ce cas, si les données reçues sont plus longues que lua_max_length, une demande de RUI_READ retourne un code de retour principal de LUA_OK et un code de retour secondaire de LUA_DATA_INCOMPLETE. Une application RUI peut ensuite émettre de nouveaux appels RUI_READ et recevoir le reste des données.
Cette amélioration n’a pas été adoptée dans le cadre de la norme d’API LUA de Microsoft Windows Open Services Architecture (WOSA) et diffère de l’implémentation de RUI par IBM.
Une fois qu’un message a été lu à l’aide de RUI_READ, il est supprimé de la file d’attente des messages entrants et n’est plus accessible. (RUI_BID peut être utilisé comme lecture non destructrice. L’application peut l’utiliser pour case activée le type de données disponibles, mais les données restent dans la file d’attente entrante et n’ont pas besoin d’être utilisées immédiatement.)
Le rythme peut être utilisé sur la demi-session primaire-secondaire (spécifiée dans la configuration de l’hôte), pour protéger l’application LUA contre l’inondation de messages. Si l’application LUA est lente à lire les messages, Host Integration Server retarde l’envoi de réponses de rythme à l’hôte pour le ralentir.
Voir aussi
RUI_BID
RUI_INIT
RUI_TERM
RUI_WRITE
SLI_OPEN
SLI_PURGE
SLI_RECEIVE
SLI_SEND