Manual de programación de OS/2/Llamadas DOSxxx para gestión de sesiones

DosSelectSession

DosSelectSession permite a una sesión padre conmutar a uno de sus hijos a primer plano. El Shell de OS/2, por ser padre de todas las sesiones que se abran, puede conmutar a cualquiera de ellas. Para devolver a éste al primer plano está la conbinación CTRL+ESC.

#define INCL_BASE
#include <os2.h>

ULONG ulSessID;
APIRET rc; /* Codigo de error */

rc = DosSelectSession(ulSessID); ==

Parámetros ==
ulSessID	El identificador de la sesión que se debe conmutar a primer plano. El valor especificado debe haber sido retornado por una llamada previa a DosStartSession, excepto cuando el valor es cero, en cuyo caso se pasa la propia sesión que hace la llamada.

==

Codigos de error ==
0	Sin error
224	No existe tal ventana (la sesión no se puede traer a primer plano)
369	Identificador de sesión no válido
418	Llamada no válida
459	Reserva no válida
460	La sesión no es hija de la actual
463	Reintentar el Sub Alloc

DosStartSession

DosStartSession crea una nueva sesión e inicia en ella la ejecución de un nuevo programa.

#define INCL_BASE
#include <os2.h>

PSTARTDATA pStartData;
PULONG pSessID;
PPID ppidPID;
APIRET rc; /* Codigo de error */

rc = DosStartSession(pStartData, pSessID, ppidPID); ==

Parámetros ==
pStartData	Puntero a una estructura de sesión con estos datos:
	Tamaño Nombre Descripción Word Length longitud de la estructura en bytes, incluyendo el propio campo de longitud. Puede ser 24, 30, 32, 50 o 60 bytes. No se debe especificar una longitud mayor de 32 para programas en modo texto, pues OS/2 no los cargará si el Presentation Manager no está presente.Cuando se especifica 24 o 30 bytes, OS/2 rellena el resto con ceros. Word Related indica la relación entre la nueva sesión y el padre. Si es cero (SSF_RELATED_INDEPENDENT), la nueva sesión es independiente, y no puede ser tratada con DosSelectSession ni DosStopSession. Si es uno (SSF_RELATED_CHILD) la nueva sesión es hija de la que hizo la llamada, y se devuelven los valores de SessID y PID. Word FgBg si vale cero (SSF_FGBG_FORE), la nueva sesión se arrancará en primer plano (si es ventana, obtendrá el foco); si vale uno (SSF_FGBG_BACK), se iniciará en background. Word TraceOpt indica si se trazará la ejecución del nuevo programa. Si vale cero (SSF_TRACEOPT_NONE), no se traza; si vale 1 (SSF_TRACEOPT_TRACE) traza solo la sesión actual, sin incluir a los descendientes; si vale dos (SSF_TRACEOPT_TRACEALL) traza también todos los descendientes. DWord PgmTitle un puntero a una cadena ASCIIZ que contiene el título del programa, tal y como se mostrará en el título de la ventana y en la lista de tareas. Puede medir hasta 61 bytes de longitud, incluyendo el byte final de cero. DWord PgmName un puntero a una cadena ASCIIZ que contiene la unidad, path y nombre del ejecutable a cargar en la nueva sesión. DWord PgmInputs puede ser cero, o bien un puntero a una cadena ASCIIZ que contiene los argumentos que deben ser pasados al programa. DWord TermQ puede ser cero, o bien un puntero a una cadena ASCIIZ que contiene el path completo y el nombre de una cola de sistema (ver DosCreateQueue). Esta cola es usada para devolver al proceso padre mensajes de terminación de las sesiones hijo. Cada mensaje está formado por dos WORD; la primera contiene el Session ID, y la segunda el resultado. DWord Environment puede ser cero, o bien un puntero a una cadena de entorno que debe ser pasada al programa iniciado en la nueva sesión. Si es cero, el entorno que tome dependerá del InheritOpt. En las sesiones DOS, este campo está reservado, y debe ser cero. Word InheritOpt indica si el programa iniciado en la nueva sesión hereda el entorno del padre y sus ficheros abiertos. Si vale cero (SSF_INHERTOPT_SHELL), hereda el entorno del Shell del sistema. Si vale uno (SSF_INHERTOPT_PARENT), hereda el entorno del programa que hace la llamada. Word Session Type define el tipo de sesión que será creado. Si vale cero (SSF_TYPE_DEFAULT), se usa la información de PgmHandle, o se permite al shell establecer el tipo. Si vale 1 (SSF_TYPE_FULLSCREEN) inicia el programa en una sesión a pantalla completa. Si vale 2 (SSF_TYPE_WINDOWABLEVIO) inicia una sesión de modo texto en ventana. Si vale 3 (SSF_TYPE_PM) inicia una sesión de ventana para programa que usen el Presentation Manager (incluyendo llamadas AVIO). Si vale 4 (SSF_TYPE_VDM) inicia una sesión DOS a pantalla completa. Si vale 7 (SSF_TYPE_WINDOWEDVDM) inicia una sesión DOS en ventana. DWord IconFile puede valer cero o ser un puntero a una cadena ASCIIZ que contiene la unidad, el path completo y el nombre de un fichero de icono. Si no se encuentra un icono o no se especifica, pone un icono por defecto. DWord PgmHandle puede valer cero o el handle retornado por WinAddProgram o WinQueryProgramHandle. Word PgmControl un campo de bits que especifican el estado inicial de una sesión en ventana. Se ignora en aplicaciones a pantalla completa. El valor de cada bit representa lo siguiente: Bit Valor Nombre Estado inicial 0 0x0000 SSF_CONTROL_VISIBLE Visible 0 0x0001 SSF_CONTROL_INVISIBLE Invisible 1 0x0002 SSF_CONTROL_MAXIMIZE Maximizada 2 0x0004 SSF_CONTROL_MINIMIZE Minimizada 3 0x0008 SSF_CONTROL_NOAUTOCLOSE No se cierra automáticamente al terminar la aplicación (solo sesiones VIO en ventana). 4-14 Reservados 15 0x8000 SSF_CONTROL_SETPOS Usa la posición y tamaño especificados Word InitXPos contiene la coordenada X inicial, en pixels, para la ventana. (0,0) es la esquina inferior izquierda de la pantalla. Se ignora en sesiones a pantalla completa. Word InitYPos contiene la coordenada Y inicial, en pixels, para la ventana. (0,0) es la esquina inferior izquierda de la pantalla. Se ignora en sesiones a pantalla completa. Word InitXSize contiene el ancho, en pixels, para la ventana. Se ignora en sesiones a pantalla completa. Word InitYSize contiene el alto, en pixels, para la ventana. Se ignora en sesiones a pantalla completa. Word Reservado se debe rellenar con ceros. Para futuros usos. DWord ObjectBuffer puntero a un buffer donde se devuelve el nombre del objeto que ha hecho fallar la llamada. DWord ObjectBuffLen es la longitud, en bytes, del buffer apuntado por ObjectBuffer.
pSessID	Puntero a una doble palabra donde se almacena el identificador de la nueva sesión creada. Es retornado solo cuando el valor especificado en related es 1. Se necesita para las llamadas a DosSelectSession y DosStopSession.
ppidPID	Puntero a una doble palabra donde se almacena el identificador del proceso creado en la nueva sesión. El PID devuelto puede no ser válido para algunas llamadas (por ejemplo, DosSetPriority)) que necesitan una relación padre/hijo.

==

Codigos de error ==
0	Sin error
369	Identificador de sesión no válido
418	Llamada no válida
460	La sesión no es hija de la actual
463	Reintentar el Sub Alloc

DosStopSession

DosStopSesion finaliza una sesión.

#define INCL_BASE
#include <os2.h>

ULONG ulTargetOption;
ULONG ulSessID;
APIRET rc; /* Codigo de error */

rc = DosStopSession(ulTargetOption, ulSessID); ==

Parámetros ==
ulTargetOption	Si vale cero (STOP_SESSION_SPECIFIED) finaliza sóolo la sesión indicada por SessID. Si vale 1 (STOP_SESSION_ALL) finaliza todas las sesiones.
ulSessID	El identificador de la sesión a finalizar. El valor es el devuelto por una llamada a DosStartSession. Este parámetro se ignora si TargetOption vale uno.

==

Codigos de error ==
0	Sin error
369	Identificador de sesión no válido
418	Llamada no válida
458	Opción de STOP no válida
459	Reserva no válida
460	La sesión no es hija de la actual
463	Reintentar el Sub Alloc