.page size 58,75
.flags substitute
.figure 5
.center;Forrest A. Kenney
.center;1600 S. Eads ST. Apt. 425 N
.center;Arlington, Va 22202
.center;Days 301-731-4100 
.center;Home 703-979-6676
.center;$$date
.blank 3
.fill
.justify
.paragraph;This directory contains a number of simple routines that provide
an example of how to get UNIX CBREAK or RAW I/O using the VMS terminal driver
without having to have the line set to PASTHRU all of the time. What are CBREAK
and RAW I/O?  Interpreting from the ULTRIX-32 manuals I have come up with the
following descriptions of these terminal driver modes.  In RAW mode I/O all
characters are passed directly through the terminal driver to the reading
process without interpretation.  In CBREAK mode, the terminal driver interprets
only flow control characters; typically CTRL/S and CTRL/Q.  All other
characters are passed directly to to the reading process as in RAW mode.  These
two modes conveniently map into setting for the VMS terminal driver.  These
setting are TT2_$M__PASTHRU, and TT2_$M__PASTHRU with TT_$M__TTSYNC disabled. 
.paragraph;The programs make a few assumptions.  First the device that the 
input and output going to is the terminal line associated with the logical name
SYS_$INPUT:.  The second assumption is that the input and output will be
occurring at a relatively slow sustained rate, less than 120 characters a
second.  If the I/O device is not SYS_$INPUT: you will need to change the setup
routine and replace SYS_$INPUT: with the device name or a logical name pointing
to it.  If you are going to be getting data at a higher rate you will want to
change the input and output routines to buffer data by performing reads and
writes for larger amounts of data. 
.paragraph;If the device supplying data understands XON/XOFF for flow
control then you should use the routines in CBREAK mode this will prevent the
loss of data.  These routines are not the only way to provide RAW and CBREAK
I/O but are a way that I have used successfully.  Be advised that CTRL/Y and
CTRL/C keys will be disabled.  That is assuming you are reading from
SYS_$INPUT:. This is because the routines prevent the VMS terminal driver from
interpreting these keys as interrupt signals. 
.paragraph;Finally I plan at a later date to write a article for the 
pageswapper that presents a more detailed discussion of CBREAK and RAW I/O as
well as performance issues.  If you use these routines or have written routines
of your own to get CBREAK or RAW I/O I would like to hear from you.  Also if
you use these routines and have problems getting them to work please let me
know.  The routines were written in an evening and have not rigorously tested.
But the code is simple enough that I have reasonable confidence that they will
work.  Below is a list of the routines and brief description of its function. 
.blank 3
.left margin +22
.indent -19;CC__RAWIO__EXIT.C####This routine will reset the terminal line when
the program performs an exit.  If for some reason the program is terminated
abnormally the routine may not be invoked.  To insure that it is the program
will need to be installed with some privilege.  To do this run the VMS install
utility.  Any privilege will do so give it TMPMBX as everybody gets this by
default.
.blank 1
.indent -19;CC__RAWIO__SETUP.C###This routine makes sure that the device being
addressed is a terminal and sets the line characteristics for RAW or CBREAK
I/O it also will turn off echo.
.blank 1
.indent -19;CC__RGETC.C#########This routine will read one character at a
time synchronously from the terminal device.
.blank 1
.indent -19;CC__RPUTC.C#########This routine will write one character at
a time synchronously to the terminal device.  This routine is only provided
for completeness.
.blank 1
.indent -19;RAWIO__TEST.C#######A simple sample program to show how to use
these routines.  The main thing to note is the main is the declaration of
the control block for the exit handler.  Programs that use these routines
should do the same thing.
.blank 1
.indent -19;CC__RAWIO.H#########Include file contains the necessary global 
variable declarations.
.left margin -22
.blank 2
RESTRICTIONS:
.paragraph;The code was written using VAX-11 C version 2.0 and include a
number of VMS specific definition files.  Most of theses files can be easliy
reproduced by extracting their VAX-11 MACRO versions from SYS_$LIBRARY:
STARLET.MLB and LIB.MLB and converting them to C definition files.  The
only problem you should encounter is the _$DESCRIPTOR macro definition which
is defined in descrip.h.  For those who do not have VAX-11 C the code for
the _$DESCRIPTOR macro is show below:
.blank 1
.literal
/*
 *	Scalar or string descriptor:
 */
struct	dsc$descriptor_s
	{
	unsigned short	dsc$w_length;	/* length of data item in bytes,
					     or if dsc$b_dtype is 
					     DSC$K_DTYPE_V, bits,
					     or if dsc$b_dtype is 
					     DSC$K_DTYPE_P, digits 
					     (4 bits each) */
	unsigned char	dsc$b_dtype;	/* data type code */
	unsigned char	dsc$b_class;	/* descriptor class code = 
					     DSC$K_CLASS_S */
	char		*dsc$a_pointer;	/* address of first byte of data 
					     storage */
	};
/*
 *	Define just the class and data type values we need.
 */

#define DSC$K_DTYPE_T	14		/* character-coded text;  a single 
					     character or a string */
#define DSC$K_CLASS_S	1		/* scalar or string descriptor */

/*
 *	A simple macro to construct a string descriptor:
 */
#define $DESCRIPTOR(name,string) 
	struct dsc$descriptor_s name = {sizeof(string)-1, DSC$K_DTYPE_T, 
					DSC$K_CLASS_S, string }
.end literal