Undocumented $QIO interface to WSDRIVER (Version 1.0)

John McMahon
TGV, Incorporated
603 Mission Street
Santa Cruz, CA 95060

E-Mail:  MCMAHON@TGV.COM
Phone:	 408-427-4366

"The display variable device driver (WSDRIVER) is a clone of the null device 
 driver (NLDRIVER).  Oh brother..."

The SET DISPLAY and SHOW DISPLAY command issues $QIOW calls to WSDRIVER to
change/read the display variable information.  This attempts to document those
calls.

Warning: The interfaces to WSDRIVER are not documented, not supported, not
ANYTHING by Digital Equipment Corporation.  It was John McMahon's idea to write
this file.  TGV Incorporated had nothing to do with the production of this and
TGV does not support WSDRIVER either.  Use at your own risk.  Post no bills.

My thanks to Jake, Karen and Nancy who all comment their code pretty well...

SET DISPLAY Commands
====================

	Function			$QIOW function code
	========			===================

	Change Display Variables or	IO$_SETMODE or IO$M_WS_DISPLAY
	Change Device Privileged Channel Number or
	Change Display Mode


	Change Device Permanence	IO$_SETMODE or IO$M_WS_PERM

SHOW DISPLAY Commands
=====================

	Function			$QIOW function code
	========			===================

	Read Display Variables or	IO$_SENSEMODE or IO$M_WS_DISPLAY
	Read Display Mode or
	Reading the Device Privileged Channel Number

Other Commands
==============

	WSDRIVER contains the same I/O functions as NLDRIVER.  As a result you
	can read and write to WS devices.  The results can be found below.

	$QIO Function			Result returned
	=============			===============
        IO$_READLBLK 			SS$_ENDOFFILE
        IO$_READVBLK                    SS$_ENDOFFILE
	(No data is returned from read operations)

	IO$_WRITEOF                     SS$_NORMAL
        IO$_WRITELBLK                   SS$_NORMAL
	IO$_WRITEVBLK                   SS$_NORMAL
	(No data is written in write operations)
	
Display Variables $QIO Parameters
=================================

	The DECwindows display variables consist of the transport to be used
	to get to the server node.  The node the server is on.  Which server 
	on the node to use.  And which screen on the server to use.

	P1:			Character String (Passed by descriptor)
				 For a SETMODE operation, this value will be
				 stored in the WS device.  For a SENSEMODE
				 operation, this variable will be filled 
				 by the value in the WS device.
	P2:			Unsigned Word (Passed by value)
				 Length of the Character String in P1.
	P3:			Unsigned Word (Passed by value)
				 What value to be set/retrieved from 
				 the WS device.

				 DECW$C_WS_DSP_NODE  		(/NODENAME)
				 DECW$C_WS_DSP_TRANSPORT	(/TRANSPORT)
				 DECW$C_WS_DSP_SERVER		(/SERVER)
				 DECW$C_WS_DSP_SCREEN		(/SCREEN)

	Note:  If transport is DECNET, the colons should be stripped off of
	the node name before putting them in the display variable.

Device Privileged Channel Number $QIO Parameters
================================================

	When a WS device is created in supervisor mode, it is deleted when
	the process exits.  This is accomplished by assigning a channel in
	executive mode that holds the device open until the process goes away.
	If the user wishes to destroy this device before logging out, the
	SET DISPLAY routine has to find the executive mode channel and get rid
	of it.  To find that channel, it keeps it stored in the WSDRIVER.

	P1:			Unsigned long (Passed by reference)

	P2:			4 (Passed by Value) The length of
				a longword.

	P3:			Unsigned Word (Passed by value)
				 (EQUAL TO DECW$C_WS_DSP_PRIVCHAN)
				 
Change Device Permanence $QIO Parameters
========================================

	The permanence of the device depends on the privilege mode set 
	(Kernel, Executive, Supervisor, User) in WSDRIVER.  Executive and
	User devices have the permanent flag set by the SET DISPLAY command.
        Supervisor mode devices do not have the permanent flag set.  Kernel
        mode WS devices are not used.

	P1:			Zero (Not Permanent)
				One  (Permanent)
				[Passed By Value]


Change Mode $QIO Parameters
===========================

	The mode of the device.  Valid modes are User (Deleted after one
	execution), Supervisor (Survives for the length of the process),
	and Executive (Lives until reboot or manual deletion).

	P1:			Unsigned long (Passed by reference)
				PSL$C_USER	- User mode
				PSL$C_SUPER	- Supervisor mode
				PSL$C_EXEC	- Executive mode

	P2:			4 (Passed by Value) The length of
				a longword.

	P3:			Unsigned Word (Passed by value)
				 (EQUAL TO DECW$C_WS_DSP_MODE)

	If P1 is PSL$C_EXEC, SYSNAM privilege is required.
				 
Things not covered
==================

There is a flags field stored in the display information.  The function of the
flags field is unknown to me at this time.

Constants
=========

DECW$C_WS_DSP_MODE	(Undocumented)	0x5
DECW$C_WS_DSP_NODE      (Undocumented)  0x1
DECW$C_WS_DSP_PRIVCHAN	(Undocumented)  0x7
DECW$C_WS_DSP_SCREEN    (Undocumented)  0x4
DECW$C_WS_DSP_SERVER    (Undocumented)  0x3
DECW$C_WS_DSP_TRANSPORT (Undocumented)  0x2
IO$_READLBLK		(Documented)	Found in $IODEF
IO$_READVBLK		(Documented)	Found in $IODEF
IO$_SENSEMODE		(Documented)	Found in $IODEF
IO$_SETMODE		(Documented)	Found in $IODEF
IO$_WRITEOF		(Documented)	Found in $IODEF
IO$_WRITELBLK		(Documented)	Found in $IODEF
IO$_WRITEVBLK		(Documented)	Found in $IODEF
IO$M_WS_DISPLAY		(Undocumented)	0x40
IO$M_WS_PERM		(Undocumented)  0x80
PSL$C_EXEC		(Documented)	Found in $PSLDEF
PSL$C_SUPER		(Documented)	Found in $PSLDEF
PSL$C_USER		(Documented)	Found in $PSLDEF
SS$_ENDOFFILE		(Documented)	Found in $SSDEF
SS$_NORMAL		(Documented)	Found in $SSDEF