RUI_INIT
El RUI_INIT verbo transfiere el control de la unidad lógica (LU) especificada a la aplicación de aplicación de unidad lógica (LUA) de Microsoft® Windows®. RUI_INIT establece una sesión entre el punto de control de servicios del sistema (SSCP) y la LU especificada.
Nota
Para los usuarios del emulador de 3270, se ha agregado una extensión de Microsoft Host Integration Server que le permite usar 3270 RU en lugar de las LUA. Para obtener más información, vea Comentarios en este tema.
En la estructura siguiente se describe el miembro LUA_COMMON del bloque de control de verbos (VCB) usado por RUI_INIT.
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 en función del 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 en función del 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_INIT.
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_INIT requiere este parámetro.
Este parámetro tiene ocho bytes de longitud, rellenado a la derecha con espacios (0x20) si el nombre tiene más 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 Host Integration Server y debe ser cero.
lua_sid
Parámetro devuelto. Especifica el identificador de sesión.
lua_max_length
No se usa en RUI_INIT y debe establecerse en cero.
lua_data_length
No se usa en RUI_INIT y debe establecerse en cero.
lua_data_ptr
No se usa en RUI_INIT y debe establecerse en cero.
lua_post_handle
Parámetro proporcionado. Se usa en Microsoft® Windows Server si los eventos van a realizar notificaciones asincrónicas. Esta variable contiene el identificador del evento que se va a indicar o un identificador de ventana.
lua_th
No se usa en RUI_INIT y debe establecerse en cero.
lua_rh
No se usa en RUI_INIT y debe establecerse en cero.
lua_flag1
No se usa en RUI_INIT y debe establecerse en cero.
lua_message_type
Especifica el tipo de los comandos y datos de SNA entrantes o salientes. Se trata de un parámetro devuelto para RUI_INIT. Los valores posibles son:
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
La interfaz de nivel de sesión (SLI) recibe y responde a las solicitudes BIND, CRV y STSN a través de las rutinas de extensión de interfaz LUA.
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.
lua_flag2.async
Indica que el verbo de interfaz LUA se completó de forma asincrónica si se establece en 1.
RUI_INIT siempre se completa de forma asincrónica a menos que devuelva un error como LUA_PARAMETER_CHECK).
lua_resv56
Parámetro proporcionado. Campo reservado usado por RUI_INIT y SLI_OPEN. Todos los demás campos reservados de la matriz deben dejarse en blanco. Para obtener más información, vea la explicación de estas extensiones de Host Integration Server en la sección Comentarios.
lua_resv56[1]
Parámetro proporcionado. Indica si una aplicación RUI puede acceder a las LU configuradas como 3270 LU, además de LUA. Si este parámetro es distinto de cero, se puede acceder a 3270 LU.
lua_resv56[2]
Parámetro proporcionado. Indica si la biblioteca RUI liberará la LU cuando la sesión de LU-SSCP o la conexión desaparezcan. Si este parámetro es distinto de cero, la LU no se liberará.
lua_resv56[3]
Parámetro proporcionado. Indica si se admiten lecturas incompletas. Si este parámetro se establece en un valor distinto de cero, se admiten lecturas incompletas o truncadas. Para obtener más información, consulte los comentarios de RUI_READ.
lua_resv56[4]
Parámetro proporcionado. Indica si la biblioteca RUI permitirá que la aplicación mantenga la suspensión de la LU si se recicla en el host. Si este parámetro es distinto de cero, la aplicación puede mantener la suspensión de la LU.
lua_encr_decr_option
Campo para opciones de criptografía. En RUI_INIT, solo se admiten los siguientes elementos:
lua_encr_decr_option = 0
lua_encr_decr_option = 128
No se admiten valores comprendidos entre 1 y 127.
Códigos de retorno
LUA_OK
Código de retorno principal; el verbo se ha ejecutado correctamente.
LUA_CANCELED
Código de retorno principal; el verbo no se completó correctamente porque otro verbo lo canceló.
LUA_TERMINATED
Código de retorno secundario; RUI_TERM se emitió antes de RUI_INIT completado.
LUA_PARAMETER_CHECK
Código de retorno principal; el verbo no se ha ejecutado debido a un error en un parámetro.
LUA_INVALID_LUNAME
Código de retorno secundario; el parámetro lua_luname no coincidía con ningún nombre de LUA o nombre del grupo de LU en el archivo de configuración.
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_RESERVED_FIELD_NOT_ZERO
Código de retorno secundario; un campo reservado en el registro de verbos, 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_DUPLICATE_RUI_INIT
Código de retorno secundario; el parámetro lua_luname especificó un nombre de LU o un nombre de grupo de LU que ya está en uso por esta aplicación (o para el que esta aplicación ya tiene RUI_INIT en curso).
LUA_UNSUCCESSFUL
Código de retorno principal; el registro de verbo proporcionado era válido, pero el verbo no se completó correctamente.
LUA_COMMAND_COUNT_ERROR
Código de retorno secundario, que indica uno de los siguientes errores:
No se pudo emitir el verbo porque la aplicación ya había alcanzado su número máximo de sesiones activas. En Windows, una aplicación puede tener hasta 15 000 sesiones activas en cualquier momento.
El verbo especificó el nombre de un grupo de LU o el nombre de una LU en un grupo, pero todas las LU del grupo están en uso.
LUA_ENCR_DECR_LOAD_ERROR
Código de retorno secundario; el verbo especificó un valor para lua_encr_decr_option distinto de 0 o 128.
LUA_INVALID_PROCESS
Código de retorno secundario; la LU especificada por lua_luname está en uso por otro proceso.
LUA_LINK_NOT_STARTED
Código de retorno secundario; no se ha iniciado la conexión con el host; ninguno de los servicios de vínculo que podría usar está activo.
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 ha interrumpido (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_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
Este verbo debe ser el primer verbo LUA emitido para la sesión. Hasta que este verbo se haya completado correctamente, el único verbo LUA que se puede emitir para esta sesión es RUI_TERM (que finaliza un RUI_INIT pendiente).
Todos los demás verbos emitidos en esta sesión deben identificar la sesión mediante uno de los parámetros siguientes de este verbo:
Identificador de sesión, devuelto a la aplicación en lua_sid.
El nombre de LU o el nombre del grupo de LU, proporcionado por la aplicación en el parámetro lua_luname .
RUI_INIT finaliza después de recibir un mensaje ACTLU del host. Si es necesario, el verbo espera indefinidamente. Si ya se ha recibido una ACTLU antes de RUI_INIT, LUA envía una notificación al host para informarle de que la LU está lista para su uso.
Ni ACTLU ni NOTIFY son visibles para la aplicación LUA.
Una vez que RUI_INIT se ha completado correctamente, esta sesión usa la LU para la que se inició la sesión. Ninguna otra sesión de LUA (de esta o cualquier otra aplicación) puede usar la LU hasta que se emita RUI_TERM , o hasta que se reciba un código de retorno principal LUA_SESSION_FAILURE.
Uso de 3270 LU
Para proporcionar a los usuarios del emulador 3270 la capacidad de usar la llamada de configuración de especificación de interfaz del emulador (EIS) con la API de RUI, se ha agregado una extensión de Host Integration Server a la RUI. Esta extensión permite usar 3270 LU en lugar de LUA. Si una aplicación establece lua_resv56[1] en un valor distinto de cero en la llamada RUI_INIT , se pueden usar 3270 LU.
No liberar la LU
Si una aplicación establece lua_resv56[2] en un valor distinto de cero en la llamada a RUI_INIT , la biblioteca RUI no liberará la LU cuando la sesión o la conexión de LU-SSCP desaparezcan. Cuando esta extensión de Host Integration Server está habilitada, la aplicación no tiene que emitir un nuevo RUI_INIT después de un error de sesión o un error de conexión. Cuando se realiza la copia de seguridad de la sesión de LU-SSCP (la aplicación puede usar WinRUIGetLastInitStatus para detectar esto), la aplicación puede empezar a usarla de nuevo.
Compatibilidad con la fragmentación en esta sesión
Si una aplicación establece lua_resv56[3] en un valor distinto de cero en el establecimiento de sesión de RUI_INIT , esto habilita una extensión de Host Integration Server que puede cambiar el comportamiento de RUI_READ. El comportamiento predeterminado de una llamada de RUI_READ consiste en truncar los datos (descartar los datos restantes) si el búfer de datos de la aplicación no es lo suficientemente grande como para recibir todos los datos de la RU y devolver un código de error. Cuando lua_resv56[3] se establece en un valor distinto de cero en la llamada RUI_INIT , se emite un RUI_READ en el que el búfer de datos de la aplicación no es lo suficientemente grande como para que no se descarten los datos de RU. El verbo RUI_READ devolverá éxito (LUA_OK) para el código de retorno principal y LUA_DATA_INCOMPLETE para el código de retorno secundario. Las solicitudes de RUI_READ posteriores se pueden emitir para recuperar los datos que superaron el búfer de datos de la aplicación.
Omitir DACTLUs
Si una aplicación establece lua_resv56[4] en un valor distinto de cero en el establecimiento de sesión de RUI_INIT , esto habilita una extensión de Host Integration Server y la biblioteca RUI permitirá a la aplicación mantener la lu si se recicla en el host (es decir, desactivada y reactivada).
Nota
Todos los demás campos reservados deben dejarse en blanco.
Para obtener más información, consulte la descripción de la función sepdcrec en la sección de la Ayuda del Kit de desarrollo de software (SDK) en la especificación de la interfaz del emulador 3270.
Cifrado
La criptografía de nivel de sesión se implementa a través de solicitudes de verificación de criptografía (CRV). Las aplicaciones RUI deben realizar todo el procesamiento necesario de estas solicitudes. Para todas las interfaces distintas de RUI, las solicitudes de CRV se rechazan con una respuesta negativa de Host Integration Server.
Para RUI_INIT, se admiten las siguientes opciones:
lua_encr_decr_option = 0
lua_encr_decr_option = 128
No se admiten valores de 1 a 127 (rutinas ACSRENCR y ACSROECR).
La aplicación de envío es responsable de rellenar los datos en un múltiplo de ocho bytes y de establecer el bit de indicador de datos rellenado en rh, así como para el cifrado. La aplicación receptora es responsable de quitar el relleno después del descifrado.