RUI_READ

  • Artículo

El verbo RUI_READ recibe respuestas, comandos SNA y datos en un búfer de aplicaciones de aplicación de unidad lógica (LUA) de Microsoft® Windows®.

En la estructura siguiente se describe el miembro LUA_COMMON del bloque de control de verbos (VCB) usado por RUI_READ.

Sintaxis

  
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;  
};

Members

lua_verb
Parámetro proporcionado. Contiene el código de verbo, LUA_VERB_RUI para verbos de interfaz de unidad de solicitud (RUI).

lua_verb_length
Parámetro proporcionado. Especifica la longitud en bytes del VCB lua. Debe contener la longitud del registro de verbo que se va a emitir.

lua_prim_rc
Código de retorno principal establecido por LUA al finalizar el verbo. Los códigos de retorno válidos varían según el verbo LUA emitido.

lua_sec_rc
Código de retorno secundario establecido por LUA al finalizar el verbo. Los códigos de retorno válidos varían según el verbo LUA emitido.

lua_opcode
Parámetro proporcionado. Contiene el código de comando LUA (código de operación de verbo) para el verbo que se va a emitir, LUA_OPCODE_RUI_READ.

lua_correlator
Parámetro proporcionado. Contiene un valor proporcionado por el usuario que vincula el verbo con otra información proporcionada por el usuario. LUA no usa ni cambia esta información. Este parámetro es opcional.

lua_luname
Parámetro proporcionado. Especifica el nombre ASCII de la LU local usada por la sesión de LUA de Windows.

RUI_READ solo requiere este parámetro si lua_sid es cero.

Este parámetro tiene ocho bytes de longitud, rellenado a la derecha con espacios (0x20) si el nombre tiene menos de ocho caracteres.

lua_extension_list_offset
No se usa por RUI en Host Integration Server y debe establecerse en cero.

lua_cobol_offset
LuA no se usa en Microsoft® Host Integration Server y debe ser cero.

lua_sid
Parámetro proporcionado y devuelto. Especifica el identificador de sesión y lo devuelven SLI_OPEN y RUI_INIT. Otros verbos usan este parámetro para identificar la sesión usada para el comando. Si otros verbos usan el parámetro lua_luname para identificar sesiones, establezca el parámetro lua_sid en cero.

lua_max_length
Especifica la longitud del búfer recibido para RUI_READ y SLI_RECEIVE. No se usa en otros verbos RUI y SLI y debe establecerse en cero.

lua_data_length
Parámetro devuelto. Especifica la longitud de los datos devueltos en lua_peek_data para el verbo RUI_BID .

lua_data_ptr
Puntero al búfer proporcionado por la aplicación que va a recibir los datos de un verbo RUI_READ . Tanto los comandos SNA como los datos se colocan en este búfer y pueden estar en formato EBCDIC.

Cuando se emite RUI_READ , este parámetro apunta a la ubicación para recibir los datos del host.

lua_post_handle
Parámetro proporcionado. Se usa en Microsoft Windows Server si los eventos deben realizar notificaciones asincrónicas. Esta variable contiene el identificador del evento que se va a indicar o un identificador de ventana.

lua_th
Parámetro devuelto. Contiene el encabezado de transmisión SNA (TH) del mensaje enviado o recibido. Se establecen varios subparámetros para las funciones de escritura y se devuelven para las funciones de lectura y puja. Sus subparámetros son los siguientes:

lua_th.flags_fid

Formato tipo de identificación 2, cuatro bits.

lua_th.flags_mpf

Campo de asignación de segmentación, dos bits. Define el tipo de segmento de datos. Valores válidos son:

segmento 0x00 medio0x04 último segmento0x08 primer segmento0x0C solo segmento

lua_th.flags_odai

Indicador del asignador de campo de dirección de origen:campo de destino (OAF–DAF), un bit.

lua_th.flags_efi

Indicador de flujo acelerado, un bit.

lua_th.daf

Campo de dirección de destino (DAF), un carácter sin signo.

lua_th.oaf

Campo de dirección de origen (OAF), un carácter sin signo.

lua_th.snf

Campo número de secuencia, un carácter sin signo[2].

lua_rh
Parámetro devuelto. Contiene el encabezado de solicitud/respuesta de SNA (RH) del mensaje enviado o recibido. Se establece para la función de escritura y la devuelven las funciones de lectura y puja. Sus subparámetros son los siguientes:

lua_rh.rri

Indicador de solicitud-respuesta, un bit.

lua_rh.ruc

Categoría de RU, dos bits. Valores válidos son:

LUA_RH_FMD (0x00) control de flujo de datos fmLUA_RH_NC (0x20) Control de red LUA_RH_DFC (0x40) Control de flujo de datosLUA_RH_SC (0x60) Control de sesión

lua_rh.fi

Indicador de formato, un bit.

lua_rh.sdi

Los datos de detección incluyen un indicador, un bit.

lua_rh.bci

Indicador de cadena inicial, un bit.

lua_rh.eci

Indicador de cadena final, un bit.

lua_rh.dr1i

Indicador de respuesta definitiva 1, un bit.

lua_rh.dr2i

Indicador de respuesta 2 definitiva, un bit.

lua_rh.ri

Indicador de respuesta de excepción (para una solicitud) o indicador de tipo de respuesta (para una respuesta), un bit.

lua_rh.qri

Indicador de respuesta en cola, un bit.

lua_rh.pi

Indicador de velocidad, un poco.

lua_rh.bbi

Indicador de corchete inicial, un bit.

lua_rh.ebi

Indicador de corchete final, un bit.

lua_rh.cdi

Indicador de dirección de cambio, un bit.

lua_rh.csi

Indicador de selección de código, un bit.

lua_rh.edi

Indicador de datos cifrado, un bit.

lua_rh.pdi

Indicador de datos rellenado, un bit.

lua_flag1
Parámetro proporcionado. Contiene una estructura de datos que contiene marcas para los mensajes proporcionados por la aplicación. Sus subparámetros son los siguientes:

lua_flag1.bid_enable

Indicador de habilitación de puja, un bit.

lua_flag1.close_abend

Cierre el indicador inmediato, un bit.

lua_flag1.nowait

No hay ninguna marca de datos de espera, un bit.

lua_flag1.sscp_exp

Flujo acelerado de SSCP, un bit.

lua_flag1.sscp_norm

Flujo normal de SSCP, un bit.

lua_flag1.lu_exp

Flujo acelerado de LU, un bit.

lua_flag1.lu_norm

Flujo normal de LU, un poco.

Establezca lua_flag1.nowait en 1 para indicar que desea que RUI_READ devuelva inmediatamente si los datos están disponibles para ser leídos o no, o si desea que el verbo espere datos antes de devolverlos.

Establezca lua_flag1.bid_enable en 1 para volver a habilitar el RUI_BID más reciente (equivalente a emitir RUI_BID de nuevo con exactamente los mismos parámetros que antes) o establézcalo en cero si no desea volver a habilitar RUI_BID.

Al volver a habilitar el RUI_BID anterior, se reutiliza el VCB asignado originalmente para él, por lo que este VCB no se debe haber liberado ni modificado.

Establezca una o varias de las marcas siguientes en 1 para indicar desde qué flujo de mensajes se van a leer los datos:

lua_flag1.sscp_exp

lua_flag1.lu_exp

lua_flag1.sscp_norm

lua_flag1.lu_norm

Si se establece más de una marca, se devuelven los datos de prioridad más alta disponibles. El orden de las prioridades (primero más alto) es: SSCP acelerado, LU acelerado, SSCP normal, LU normal. La marca equivalente del grupo lua_flag2 se establece para indicar desde qué flujo se leyeron los datos.

lua_message_type
Especifica el tipo de los comandos y datos de SNA entrantes o salientes. Parámetro devuelto. Especifica el tipo de mensaje SNA indicado para RUI_READ. Los valores posibles son:

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 y SSCP_DATA no son comandos SNA.

lua_flag2
Parámetro devuelto. Contiene marcas para los mensajes devueltos por LUA. Sus subparámetros son los siguientes:

lua_flag2.bid_enable

Indica que RUI_BID se ha vuelto a habilitar correctamente si se ha establecido en 1.

lua_flag2.async

Indica que el verbo de la interfaz LUA se completó de forma asincrónica si se establece en 1.

lua_flag2.sscp_exp

Indica el flujo acelerado de SSCP si se establece en 1.

lua_flag2.sscp_norm

Indica el flujo normal de SSCP si se establece en 1.

lua_flag2.lu_exp

Indica el flujo acelerado de LU si se establece en 1.

lua_flag2.lu_norm

Indica el flujo normal de LU si se establece en 1.

lua_resv56
Reservado y debe establecerse en cero.

lua_encr_decr_option
Reservado y debe establecerse en cero.

Códigos de retorno

LUA_OK
Código de retorno principal; el verbo se ha ejecutado correctamente.

LUA_DATA_INCOMPLETE

Código de retorno secundario; RUI_READ no pudo devolver todos los datos recibidos porque el búfer de datos de la aplicación (indicado por lua_max_length) no era lo suficientemente grande. Las solicitudes de RUI_READ posteriores se pueden emitir para recuperar los datos rui restantes.

Este no es el comportamiento predeterminado de RUI_READ y solo se habilita cuando lua_resv56[3] se establece en un valor distinto de cero en el bloque de control de verbos al llamar a RUI_INIT durante el establecimiento de la sesión. Para obtener más información, consulte Comentarios.

LUA_CANCELED
Código de retorno principal; el verbo no se completó correctamente porque fue cancelado por otro verbo o por un error interno.

LUA_PURGED

Código de retorno secundario; RUI_READ ha sido cancelado por RUI_PURGE.

LUA_TERMINATED

Código de retorno secundario; RUI_TERM se emitió mientras RUI_READ estaba pendiente.

LUA_PARAMETER_CHECK
Código de retorno principal; el verbo no se ha ejecutado debido a un error en un parámetro.

LUA_BAD_DATA_PTR

Código de retorno secundario; el parámetro lua_data_ptr contenía un valor no válido.

LUA_BAD_SESSION_ID

Código de retorno secundario; se especificó un valor no válido para lua_sid en el VCB.

LUA_BID_ALREADY_ENABLED

Código de retorno secundario; lua_flag1.bid_enable se estableció para volver a habilitar RUI_BID , pero el RUI_BID anterior todavía estaba en curso.

LUA_DUPLICATE_READ_FLOW

Código de retorno secundario; las marcas de flujo del grupo lua_flag1 especificaron uno o varios flujos de sesión para los que RUI_READ ya estaba pendiente. Solo una RUI_READ cada vez puede estar esperando en cada flujo de sesión.

LUA_INVALID_FLOW

Código de retorno secundario; no se estableció ninguna de las marcas de flujo de lua_flag1 . Al menos una de estas marcas debe establecerse en 1, para indicar desde qué flujo o flujos se van a leer.

LUA_INVALID_POST_HANDLE

Código de retorno secundario; para un sistema operativo Windows que usa eventos como método de contabilización asincrónica, el VCB de LUA de Windows no contiene un identificador de eventos válido.

LUA_NO_PREVIOUS_BID_ENABLED

Código de retorno secundario; lua_flag1.bid_enable se estableció para volver a habilitar RUI_BID, pero no había ninguna RUI_BID anterior que se pudiera habilitar. (Para más información, vea la sección Comentarios.)

LUA_RESERVED_FIELD_NOT_ZERO

Código de retorno secundario; un campo reservado en el registro de verbo o un parámetro no utilizado por este verbo se estableció en un valor distinto de cero.

LUA_VERB_LENGTH_INVALID

Código de retorno secundario; Un verbo LUA se emitió con el valor de lua_verb_length inesperado por LUA.

LUA_STATE_CHECK
Código de retorno principal; el verbo no se ejecutó porque se emitió en un estado no válido.

LUA_NO_RUI_SESSION

Código de retorno secundario; RUI_INIT aún no se ha completado correctamente para el nombre de LU especificado en RUI_READ.

LUA_NEGATIVE_RSP
Código de retorno principal; indica uno de los dos casos siguientes, que se pueden distinguir mediante el código de retorno secundario:

  • LUA detectó un error en los datos recibidos del host. En lugar de pasar el mensaje recibido a la aplicación en RUI_READ, LUA descarta el mensaje (y el resto de la cadena si está en una cadena) y envía una respuesta negativa al host. LUA informa a la aplicación en un RUI_READ posterior o RUI_BID que se envió una respuesta negativa.

  • La aplicación LUA envió previamente una respuesta negativa a un mensaje en medio de una cadena. LUA ha purgado los mensajes posteriores de esta cadena y ahora informa a la aplicación de que todos los mensajes de la cadena se han recibido y purgado.

    LUA_SEC_RC

    Código de retorno secundario; este parámetro es un código de retorno secundario distinto de cero que contiene el código de detección enviado al host en la respuesta negativa. Esto indica que LUA detectó un error en los datos del host y envió una respuesta negativa al host. Para obtener información sobre cómo interpretar los valores de código de sentido que se pueden devolver, vea Consideraciones de SNA con LUA.

    Un código de retorno secundario de cero indica que, después de un RUI_WRITE anterior de una respuesta negativa a un mensaje en medio de una cadena, LUA ha recibido y descartado ahora todos los mensajes de esta cadena.

    LUA_UNSUCCESSFUL
    Código de retorno principal; el registro de verbo proporcionado era válido, pero el verbo no se completó correctamente.

    LUA_DATA_TRUNCATED

    Código de retorno secundario; el parámetro lua_data_length era menor que la longitud real de los datos recibidos en el mensaje. Solo lua_data_length bytes de datos se devolvieron al verbo; se descartaron los datos restantes. También se devuelven parámetros adicionales si se obtiene este código de retorno secundario.

    LUA_NO_DATA

    Código de retorno secundario; lua_flag1.nowait se estableció para indicar el retorno inmediato sin esperar datos y no había datos disponibles actualmente en el flujo de sesión o flujos especificados.

    LUA_INVALID_PROCESS

    Código de retorno secundario; el proceso OS/2 que emitió este verbo no era el mismo proceso que emitió RUI_INIT para esta sesión. Solo el proceso que inició una sesión puede emitir verbos en esa sesión.

    LUA_COMM_SUBSYSTEM_ABENDED
    Código de retorno principal; indica una de las condiciones siguientes:

  • El nodo utilizado por esta conversación encontró una anulación.

  • La conexión entre el programa de transacción (TP) y el nodo 2.1 de la unidad física (PU) se interrumpió (un error laN).

  • SnaBase en el equipo TPs encontró un ABEND.

    LUA_SESSION_FAILURE
    Código de retorno principal; Se ha finalizado un componente de Host Integration Server necesario.

    LUA_LU_COMPONENT_DISCONNECTED

    Código de retorno secundario; indica que se produjo un error en la sesión de LUA debido a un problema con el servicio de vínculo o con la LU del host.

    LUA_RUI_LOGIC_ERROR

    Código de retorno secundario; se detectó un error interno en LUA. Este error no debe producirse durante el funcionamiento normal.

    LUA_INVALID_VERB
    Código de retorno principal; El código de verbo o el código de operación, o ambos, no son válidos. El verbo no se ejecutó.

    LUA_STACK_TOO_SMALL
    Código de retorno principal; el tamaño de la pila de la aplicación es demasiado pequeño para ejecutar el verbo. Aumente el tamaño de pila de la aplicación.

    LUA_COMM_SUBSYSTEM_NOT_LOADED
    Código de retorno principal; no se pudo cargar un componente necesario o se ha terminado mientras se procesa el verbo. Por tanto, no se pudo establecer la comunicación. Consulte al administrador del sistema para aplicar una acción correctiva.

    LUA_UNEXPECTED_DOS_ERROR
    Código de retorno principal; después de emitir una llamada del sistema operativo, se recibió un código de retorno inesperado del sistema operativo y se especifica en el código de retorno secundario.

Comentarios

RUI_INIT debe haberse completado correctamente antes de que se emita RUI_READ .

Aunque hay una RUI_READ existente pendiente, puede emitir otro RUI_READ solo si especifica un flujo de sesión diferente o flujos de verbos RUI_READ pendientes. No puede tener más de un RUI_READ pendiente para el mismo flujo de sesión.

Puede especificar un flujo de mensajes determinado (LU normal, LU acelerado, SSCP normal o SSCP acelerado) desde el que leer datos, o puede especificar más de un flujo de mensajes. Puede tener varios verbos de RUI_READ pendientes, siempre que no dos de ellos especifiquen el mismo flujo.

La aplicación recibe los datos en uno de los cuatro flujos de sesión. Los cuatro flujos de sesión, de mayor a menor prioridad son:

  • SSCP acelerado

  • LU acelerada

  • SSCP normal

  • LU normal

    El tipo de flujo de datos que RUI_READ se va a procesar se especifica en el parámetro lua_flag1 . La aplicación también puede especificar si desea examinar más de un tipo de flujo de datos. Cuando se establecen varios bits de flujo, primero se recibe la prioridad más alta. Cuando RUI_READ finaliza el procesamiento, lua_flag2 indica el tipo específico de flujo para el que la aplicación LUA de Windows ha recibido los datos.

    Si RUI_BID se completa correctamente antes de que se emita un RUI_READ , se puede indicar a la interfaz LUA de Windows que reutilice los últimos verbos RUI_BID VCB. Para ello, emita el RUI_READ con lua_flag1.bid_enable establecido.

    El parámetro lua_flag1.bid_enable solo se puede usar si se cumple lo siguiente:

  • RUI_BID ya se ha emitido correctamente y se ha completado.

  • El almacenamiento asignado para RUI_BID no se ha liberado ni modificado.

  • No hay ningún otro RUI_BID pendiente.

    Al usar lua_flag1.bid_enable, no se debe liberar el almacenamiento de RUI_BID porque se usa el último verbo RUI_BID VCB. Además, al usar lua_flag1.bid_enable, se publicará la finalización correcta de RUI_BID .

    Si RUI_READ se emite con lua_flag1.nowait cuando no hay datos disponibles para recibir, LUA_NO_DATA será el código de retorno secundario establecido por la interfaz LUA de Windows.

    Si los datos recibidos son más largos que lua_max_length, se truncan. Solo se devuelven lua_max_length bytes de datos. También se devuelven el código de retorno principal LUA_UNSUCCESSFUL y el código de retorno secundario LUA_DATA_TRUNCATED. La biblioteca RUI devuelve tantos datos como sea posible al búfer de datos de la aplicación, pero los datos restantes del RUI se descartan y no se pueden extraer en las solicitudes de RUI_READ posteriores. Esto obliga a la aplicación RUI a asignar un búfer de datos RUI_READ lo suficientemente grande como para controlar el tamaño de RU completo.

    Este comportamiento predeterminado se puede cambiar estableciendo el valor de lua_resv56[3] en un valor distinto de cero en el bloque de control de verbos al llamar a RUI_INIT durante el establecimiento de la sesión. En este caso, si los datos recibidos son más largos que lua_max_length, una solicitud de RUI_READ devolverá un código de retorno principal de LUA_OK y un código de retorno secundario de LUA_DATA_INCOMPLETE. Después, una aplicación RUI puede emitir nuevas llamadas RUI_READ y recibir el resto de los datos.

    Esta mejora no se ha adoptado como parte del estándar de LA API de LUA de Microsoft Windows Open Services (WOSA) y difiere de la implementación de RUI por IBM.

    Una vez leído un mensaje mediante RUI_READ, se quita de la cola de mensajes entrantes y no se puede acceder de nuevo. (RUI_BID se puede usar como lectura no destructiva. La aplicación puede usarla para comprobar el tipo de datos disponibles, pero los datos permanecen en la cola entrante y no es necesario usarlos inmediatamente).

    El ritmo se puede usar en la sesión media principal a secundaria (especificada en la configuración del host) para proteger la aplicación LUA de estar inundada con mensajes. Si la aplicación LUA es lenta para leer mensajes, Host Integration Server retrasa el envío de respuestas de velocidad al host para ralentizarlo.

Consulte también

RUI_BID
RUI_INIT
RUI_TERM
RUI_WRITE
SLI_OPEN
SLI_PURGE
SLI_RECEIVE
SLI_SEND