
 CONVERGENT TECHNOLOGIES

RELEASE NOTICE
for 
2.1 Mouse Services

Revised April 27, 1987


SECTION  TITLE	PAGE
	1.0	Description of Programs	  2
	2.0	Changes from Prior Version	  3
		2.1  Problems Closed in this Release	  3
	3.0	Contents of Distribution Diskette	  4
	4.0	Installation Procedures	  5
		4.1  StandAlone Hard Disk Systems	  5
		4.2  Master Hard Disk Systems	  6
		4.3  SRP (MegaFrame) Systems	  7
		4.4  StandAlone Floppy Disk Systems	  7
		4.5  Using the Mouse Services	 7
	5.0	Required Files	  8
	6.0	System Software Compatibility	  9
		6.1  Workstation Environment	  9
		6.2  SRP (MegaFrame) Environment	  9
	7.0	Hardware Information	 10
		7.1  Hardware Configurations
		     Supported	 10
		7.2  Special Hardware Requirements	 10
	8.0	Resource RequirementsUtilization	 11
		8.1  Memory RequirementsUtilization	 11
		8.2  Disk RequirementsUtilization	 11
	9.0	Certification Information	 12
	10.0	Restrictions	 13
	11.0	Documentation Updates	 14
		11.1  Standard Documentation	 14
		11.2  Changes to Documentation	 14
	12.0	Error Codes	 21
	13.0	Known Errors and Omissions	 22
1.0	Description of Programs
This Release Notice describes Mouse Services version 2.0.  This section and the sections that follow provide a description of the product, contents of the Distribution Diskette, installation procedures, and other information pertinent to this release of the Mouse.
The Mouse Services product provides support for a pointing device connected to the keyboard.  The product consists of 3 parts; a system service that controls the pointing device, a library containing an application interface for applications that wish to take advantage of the pointing device, and a program to set mouse controls.  The pointing device supported by this version is the Convergent Mouse PD001.

2.0	Changes from Prior Version
The most significant changes in 2.1 Mouse Services is the ability to run in protected mode with CTOSVM 2.0.
2.1	Problems Closed in this Release
o	Fixed bug that would result in erc 212 when reading an icon larger than a sector using PDReadIconFile.
o	Fixed a bug in PdTranslateNscToVc on bitmapped workstations, which is also called from ReadInputEvent.  This occurs only if PDSetCharMapVirtualCoordinates had been previously called.  The values returned for the Y coordinate from ReadInputEvent when the mouse cursor is placed at the top few pixels of the screen will be non zero (often 25).  Since PDTranslateNscToVc is an object module procedure, applications will need to relink that have this problem.
3.0	Contents of Distribution Diskette
The Mouse Services Distribution Diskette is your master copy, and has been shipped writeprotected.  It should not be writeenabled, nor should it be used as a working copy.
The Mouse Services requires Standard Software version 10.2 or greater and CTOS version  9.5 or greater.
The Distribution Diskette contains the following files in the <CT> directory:
	Mouse.run	SetMouse.run
	MouseCH.run	MouseBM.run
	MouseMsg.bin	MouseForm.lib
	720x348_PntSys.icon	1024x768_PntSys.icon
	Request.1.sys
The Distribution Diskette contains the following files in the <Dev> directory:
	Mouse.Lib
The Distribution Diskette contains the following files in the <ReleaseNote> directory:
	ReleaseNotice
The Distribution Diskette contains the following files in the <Natl> directory.  These files are used to nationalize the product.  Refer to NatlMouseInstr.doc for directions.
	NatlMouseInstr.doc	MouseMsg.txt
	SetMouseFrm.form 	
In addition to various standard system files, the Distribution Diskette contains the following files in the <Sys> directory:
	HdInstall.sub
4.0	Installation Procedures
The Mouse Server should only be used on Convergent Information Processing Systems which are equipped with hard disk, or in clusters where the master is equipped with hard disk.
Use the installation procedures described below (after updating the Standard Software revision level, if required).  Characters that you must type are shown in boldface.  Special keys, such as RETURN and GO, are shown in upper case.
4.1	StandAlone Hard Disk Systems
A.	Sign on and set path at the standalone workstation.  If the Signon form is displayed, fill it in and press GO.  Set the path as follows:
Command   Path		RETURN
Path
  [Volume]	Sys	RETURN
  [Directory]	Sys	RETURN
  [Default file prefix]		RETURN
  [Password]	(if any)	GO
  [Node]
	If your hard disk has a volume password on [Sys], fill this password into the [Password] field before pressing GO.
B.	Insert the Mouse Services Distribution Diskette in drive [f0] and submit HdInstall.sub as follows:
Command   Submit		RETURN
Submit
  File list	[f0]<Sys>HdInstall.sub	GO
  [Parameters]	
  [...]
  [...]
C.	Remove the Mouse Services distribution diskette from drive [f0] and save it as an archive.
NOTE:  Refer to the Mouse Services Manual for the application interface if you wish to write applications using the mouse.
4.2	Master Hard Disk Systems
A.	Sign on and set path at the master workstation.  If the Signon form is displayed, fill it in and press GO.  Set the path as follows:
Command   Path		RETURN
Path
  [Volume]	Sys	RETURN
  [Directory]	Sys	RETURN
  [Default file prefix]	RETURN
  [Password]	(if any)  GO
  [Node]
	If your hard disk has a volume password on [Sys], fill this password into the [Password] field before pressing GO.
B.	Disable the Cluster workstations as follows:
Command   Disable Cluster		GO
Disable Cluster
  [Time Interval (seconds)]
{C.	Insert the Mouse Services Distribution Diskette in drive [f0] and submit HdInstall.sub as follows:}
{Command   Submit		RETURN
Submit
  File list	[f0]<Sys>HdInstall.sub	GO
  [Parameters]	
  [...]
  [...]}
{D.	Resume Cluster operations at the workstations as follows:
Command   Resume Cluster		GO}
{E.	Remove the Mouse Services distribution diskette from drive [f0] and save it as an archive.}
NOTE:  Refer to the Mouse Services Manual for the application interface if you wish to write applications which take advantage of the PD001.
{4.3	SRP (MegaFrame) Systems
The Mouse Services is not supported on SRP systems.}
{4.4	StandAlone Floppy Disk Systems
The Mouse Services is not supported on standalone floppy disk systems.}
{4.5	Using the Mouse Services
After the software has been copied to the hard disk and the workstation rebooted, the Mouse Server must be installed in memory.}
Commands to do this may be invoked either from the Executive before running the Context Manager, or may be added to a [Sys]<Sys>SysInit.jcl file so that installation occurs automatically whenever the system is rebooted. 
From the Executive, issue the following command:
Command   Install Mouse  Server		GO
To install as part of the system initialization, the file [Sys]<Sys>SysInit.jcl (workstations which boot from their own hard disk) or [Sys]<Sys>WsNNN>SysInit.jcl (workstations which boot from a master workstation, where NNN is the workstation type code) is used.  Add the following line to the appropriate SysInit.jcl;
$RUN [Sys]<Sys>Mouse.run
If you do not have a previously created SysInit.jcl file, create one with the following;
$JOB Sysinit
$RUN [Sys]<Sys>Mouse.run
$END
To deinstall the Mouse Server from the Executive, issue the following command:
Command   DeInstall Mouse	 Server	GO
See the Mouse Services Manual for use of the Set Mouse Controls command.
5.0	Required Files
After successful installation of Mouse Services, the following files from [f0]<CT> of the installation diskette will reside on your hard disk on [Sys]<Sys>.
	Mouse.run	SetMouse.run
	MouseCH.run	MouseBM.run
	MouseForm.lib	MouseMsg.bin
	720x348_PntSys.icon	1024x768_PntSys.icon
	Request.1.sys
If you are a systems developer, you will want to copy [f0]<Dev>Mouse.lib to your hard disk as well.
6.0	System Software Compatibility
The Mouse Services requires Standard Software version 10.2 or greater.
6.1	Workstation Environment
The Mouse Services requires Standard Software version 10.2 or greater and CTOS version 9.5 or greater.
If you are a Context Manager user and are using CTOS verison 9.5 or greater, Context Manager 2.2 or greater is required.  If you are are using CTOS VM version 1.0, Context Manager VM version 1.0 or greater is required.
6.2	SRP (MegaFrame) Environment
The Mouse Services is not supported on SRP systems.
7.0	Hardware Information
7.1	Hardware Configurations Supported
The Mouse Services requires an NGEN graphics workstation.
7.2	Special Hardware Requirements
The Mouse Services requires the PD001 pointing device connected to the keyboard.
8.0	Resource RequirementsUtilization
8.1	Memory RequirementsUtilization
The Mouse Server (MouseCh.run, MouseBm.run) requires 15K of memory.  The Set Mouse Controls program requires 73K of memory.
8.2	Disk RequirementsUtilization
The Mouse Server run file (MouseCh.run, MouseBm.run) is approximately 40 sectors of disk space.  The Mouse.Lib is approximately 16 sectors and contains the object module procedures and requests to support applications.  The Set Mouse Controls run file is approximately 154 sectors of disk space.
The Mouse Server installer, mouse.run is 68 sectors.  There are also two graphic cursor icon files 720x348PntSys.icon and 1024x768PntSys.icon that are each 1 sector.
9.0	Certification Information
Certification is not required for Mouse Services.
10.0	Restrictions
The Mouse Services is not supported on standalone dual floppy disk systems, AWS's, IWS's, SRP (MegaFrame) masters or versions of CTOS earlier than 9.5.
11.0	Documentation Updates
11.1	Standard Documentation
The Mouse Services functions are described in the Mouse Services Manual.
NOTE:  This manual serves application and system programmers as well as users of application packages that use the mouse.  
11.2	Changes to Documentation
The following are updates to the preliminary version of the Mouse Services Manual.
The graphic pointing cursor default shape is now configurable.  Mouse system service looks for either of the following icon files depending on the resolution of the monitor.  This allows users to create their own system pointing icon using Icon Designer.  If these are not present, it will use the built in default thin arrow.
[sys]<sys>720x348_PntSys.icon 
[sys]<sys>1024x768_PntSys.icon
PDLoadSystemCursor
Description
The PDLoadSystemCursor procedure loads the default pointing device cursor bitmap.  If graphics tracking has been selected by using PDSetCursorType but no graphics cursor is loaded, the default cursor bitmap loaded by this call will be used.
Procedural Interface
PDLoadSystemCursor 
 (pCursorShape,sCursorShape, bType): ErcType
where
pCursorShape	is the memory address for an icon structure which defines the cursor shape.  
sCursorShape	is the size of the structure which defines the cursor bitmap.
bType	is the type of cursor 

bType = 1 Mask Overlayed 
          (AndOr)
      = 2 Single Overlayed 
          (Or)
      = 3 is an XOR cursor *

(* implemented)
Icon structure (see PDLoadCursor)
Request Block

Offset    Field        Size    Contents

  0       sCntlInfo      1        6
  1       rtInfo         1        0
  2       nReqPbCb       1        1
  3       nRespPbCb      1        0
  4       userNum        2
  6       exchRet        2
  8       ercRet         2
 10       rqCode         2        80B6h
 12       bType          2
 14       reserved       2
 16       reserved       2
 18       pCursorShape   4
 22       sCursorShape   2
PDQueryControls
Description
The PDQueryControls procedure allows an application to query various pointing device controls.  
Procedural Interface
PDQueryControls (pStruct, sStruct): ErcType
where
pStruct	is the memory address for the control structure.  
sStruct	is the size of the control structure.

Control structure
                 Size
Offset  Field   (bytes)  Description      
  0     bXGear    1      Speed gear for X
  1     bYGear    1      Speed gear for Y

  The speed gear is a value from 1 to 10 
  where 10 is the fastest speed for the 
  mouse cursor.


Request Block

Offset    Field        Size    Contents

  0       sCntlInfo      1         6
  1       rtInfo         1         0
  2       nReqPbCb       1         1
  3       nRespPbCb      1         0
  4       userNum        2
  6       exchRet        2
  8       ercRet         2
 10       rqCode         2         80B7h
 12       reserved       2         
 14       reserved       2         
 16       reserved       2         
 18       pStruct        4         
 22       sStruct        2
PDQuerySystemControls
Description
The PDQuerySystemControls procedure allows an application to query various pointing device system wide controls.  
Procedural Interface
PDQueryControls (pStruct, sStruct): ErcType
where
pStruct	is the memory address for the control structure.  
sStruct	is the size of the control structure.

Control structure
Offset  Field         Size  Description
  0     bDefaultXGear  1    Default X 
                            speed gear 
  1     bDefaultYGear  1    Default Y
                            speed gear 


Request Block

Offset    Field        Size    Contents

  0       sCntlInfo      1        6
  1       rtInfo         1        0
  2       nReqPbCb       1        1
  3       nRespPbCb      1        0
  4       userNum        2
  6       exchRet        2
  8       ercRet         2
 10       rqCode         2        80B8h
 12       reserved       2        
 14       reserved       2        
 16       reserved       2        
 18       pStruct        4        
 22       sStruct        2
PDSetCharMapVirtualCoordinates
Description
The PDSetCharMapVirtualCoordinates procedure defines a virtual coordinate space over the current character map window normalized coordinate space.  This procedure differs from PDSetVirtualCoordinates in that it compensates for systems that have the character map offset from the graphics bitmap, such as GC003 systems.
If you wish to use the mouse in a character map application use this call instead of PDSetVirtualCoordinates.
Procedural Interface
PDSetVirtualCoordinates (wXMin, wYMin,
            wXMax, wYMax):
            ErcType
where
wXMin
wYMin	specify the minimum value for the virtual screen coordinates.
wXMax
wYMax	specify the maximum value for the virtual screen coordinates.


Request Block
PDSetCharMapVirtualCoordinates is an object module procedure
PDSetWindow
Description
The PDSetWindow procedure sets the rectangle position and size for the current window in normalized screen coordinates.  This call is intended for INTERNAL USE by the Window Manager (Context Manager VM) to communicate current window frame of reference on the screen.
Procedural Interface
PDSetWindow (wNormMinX, wNormMinY, 
     wNormMaxX, wNormMaxY, userNum, wWinId): 
	    ErcType
where
wNormMinX
wNormMinY	specify the top left corner of the window on the screen in normalized screen coordinates.
wNormMaxX
wNormMaxY	specify the bottom right left corner of the window on the screen in normalized screen coordinates.

userNum	user number that owns the window.

wWinId	window id of the window.
Request Block

Offset    Field        Size    Contents

  0       sCntlInfo      1       12
  1       rtInfo         1        0
  2       nReqPbCb       1        0
  3       nRespPbCb      1        0
  4       userNum        2
  6       exchRet        2
  8       ercRet         2
 10       rqCode         2        801Bh
 12       wNormMinX      2
 14       wNormMinY      2
 16       wNormMaxX      2
 18       wNormMaxY      2
 20       userNum        2
 22       wWinId         2

12.0	Error Codes
Section 4, Troubleshooting of the Mouse Services manual contains a list of the error codes generated by the Mouse Server and library.
13.0	Known Errors and Omissions
The MouseIbus device is not always recognized on power up of the workstation, i.e., the procedure GetIbusDevInfo will return an Id of 0.  Most applications will not be concerned with this as it does not prevent mouse data from being read via ReadInputEvent etc..  If the mouse is plugged in after reboot or unplugged and plugged in during a session the mouse will be recognized and GetIbusDevInfo will return the correct Id.