Pascal Library Routines for RSTS

For use with Oregon Software's Pascal-2

Written and submitted to the DECUS RSTS SIG Tape Copy by
       Edward F. Moran
       Horace Mann - Barnard School
       231 West 246th St.
       Bronx, N.Y.  10471
       212-548-4000

Programs and documentation copyright (c) 1988 by Edward F. Moran.
These routines are being made available to the DECUS library for 
non-commercial use only, etc. etc.  We take no responsibility for their
correctness, completeness, etc., etc. 


     On our system we have set up an account with the logical name PLIB: to 
contain procedures and functions which are meant to be used by a Pascal
program through the "%Include" directive.  These routines were written
primarily to provide access to the type of RSTS monitor calls which a BASIC 
program can access through SYS calls, though some non-SYS call routines have 
been included.   Most of the routines were meant to be used by our students,
so some of them provide only the non-privileged options for monitor calls 
which actually have both privileged and non-privileged uses - some routines
force certain parameters to their non-priv values, and others might actually
print an error message if an attempt is made to use them to affect someone
else's job or terminal.  A few of the routines were intended primarily to be
for my own use - I keep them on PLIB: but with a <60> protection code instead
of the <40> used on the rest. 

     Some files may contain things which are specific to our site, and so may 
need to be edited for your use.  Two that come to mind are SPOOL, which you 
will have to edit to put in the names of the print queues in use on your 
system, and TERMNL, which must be edited to match any custom terminal types
(as in SET TERMINAL/DEVICE=<termtype>) you have defined in $TERMAC.SYS.

     I rarely use Oregon Software's string package when I program, so some
routines which have strings as parameters may require normal [1..n] strings,
not the string package's [0..n] strings.  Most routines use conformant arrays
and so accept both versions, however. 

     These routines have been written over a period of years, during which we 
have upgraded both RSTS and Pascal a number of times.  Many of the routines 
are in frequent use, but there may be some out there which have not been 
tested with the most recent versions of RSTS and Pascal.  We currently are 
using V9.5 of RSTS and V2.1E of Oregon Software's Pascal.  Since many of the 
routines are old, you should have no trouble using them on older versions of 
RSTS and Pascal.  Some, however, will work only on V9.0 or later of RSTS, and
several require the conformant arrays that were introduced in, I believe,
V2.1A of Pascal. 

     I have included a couple of things which are not really part of our PLIB: 
library, but which you might find interesting.  
- The files SHWATR.PAS (show attributes) and SHWACT.PAS (show account) contain
procedures that look up the kind of information about an account you get when
you type SHOW ACCOUNT/FULL.  They show how to read RSTS's account attribute
blockettes, including user-defined ones (which we use to hold info such as a
code for which course a student is taking).  SHWACT is the latest version. 
(The routines in SHWACT assume that student accounts are set up by projects by
year of graduation - for the 1987-88 school year,the projects are 188 for
seniors, 189 for juniors, etc.  The program which uses the routines must have
set MAXSTUPRJ and MINSTUPRJ to be the highst and lowest project numbers used
for student accounts.) 
- ATTRR.PAS and ATTRW.PAS are complete programs that show how to read and
write the attribute blockettes. 
- SYS.PAS is a procedure to execute a BASIC-Plus SYS call, and SYSTST.PAS is a
complete program that uses SYS.PAS.  I wrote this more out of curiosity than
anything else.  Recently a student claimed that it no longer worked, but in
such cases I usually assume until proven otherwise that the student has made
some mistake. 


     The following is from our online documentation for the library.



                       PLIB: Pascal Library Routines

     To use a routine in your program, add a line at the beginning (after the
program header) of the form   %INCLUDE 'PLIB:FILE';  where "FILE" is the name
of the file containing the routine, as listed below.  Many of the routines
contain instructions, so if their purpose or usage is not clear from the table
below, check the file for more information.  To look at a routine, use the
command TYPE PLIB:FILE.PAS.  Some routines are very short, and so could be
copied (by hand or through EDT) into your source file - this would reduce your
compilation time.  Some routines require that some other library file appear
in your program before the desired routine can be included.  An example is the
CHAIN routine, which calls the FSS routine.  Such requirements are indicated
in the table.  The required types of parameters, if not indicated, usually are
obvious from the context (most are integer or string) or can be determined by
examining the file.  Most of the routines are procedures, some are functions
(which are which can be seen from the usage column), and a few, as noted
below, are neither. 




File	Contents	Purpose				Usage
------------------------------------------------------------------------------
SLEEP	sleep		sleep for n seconds		sleep(n)
POWER	power		raise base to exponent		x := power(base,exp)
RAD50	rad50		convert rad50 integer to	str := rad50(n)
			  string
ECHO	echooff		turn off terminal echo		echooff
	echoon		turn echo back on		echoon
SINGLE	singleon	enable single character input	singleon
	singleoff	return to regular input mode	singleoff
GREATR	greater		True if string1 > string2	TorF:=greater(str1,str2)
CCTRAP	cctrap		enable CTRL/C trapping		cctrap
	cctrapcount	enable CTRL/C trapping		cctrapcount(count)
			  with counter
	nocctrap	disable CTRL/C trapping		nocctrap
XTYPE	xtype		cancel typeahead		xtype
XCTRLO	xctrlo		cancel CTRL/O			xctrlo
TAB	tab		tab to column n (1st is 0)	writeln(a:1,tab(n),b:1)
	hpos		get horizontal position		p := hpos
			  of cursor
JOBINF	usernum		get user number			usernum(prjct,prgrmmr)
	kbnum		get keyboard number		n := kbnum
	jobnum		get job number			n := jobnum
ENTRY	entry		get entry point after		n := entry
			  CHAIN or CCL
CORCMN	   -		get/put core common		(see file)
MSG	removereceiver	message send/receive	removereceiver(error)
	declarereceiver	  routines (require	declarereceiver(receivername,
			  ZEROFX) (see file	   msgmax,error)
	sendmsg		  for more info)	sendmsg(receivername,msgstring,
						   error)
	receivemsg				receivemsg(sleepseconds,
						   msgstring,error)
	getmsginfo				getmsginfo(jobnum,proj,prog,
						   kbnum,bytesxfrd,bytesnotxfrd,
						   parametrstring)
DETJOB	create		create detached job running	create(prgrm,line,job)
			  program at given line number
			  and return the job number
			     (requires FSS)
	attach		attach to a detached job	attach(jobnum)
			  (must be same user number)
	swapconsole	attached and detached jobs	swapconsole(jobnum)
			  swap places (same user #)
CCL	ccl		execute a CCL command		ccl(cmnd)
CHAIN	chain		chain to program 		chain(prog,entrypoint)
			  (requires FSS)
EXIT	exit		stop program, exit to		exit
			  current KBM
	exitd		stop program, exit to		exitd
			  default KBM
LOGOUT	logout		sign off			logout
SYS	sys		BASIC SYS calls			(see file)
SYSTST		(program using SYS - see file)
FSS	fss		do filename string scan 	fss(string,error)
DUMP	dump		octal dump of memory range	dump(start,finish)
			 (requires TYPE word = 0..65535)
ZEROFX	zerofirqb	zero the FIRQB			zerofirqb
	zeroxrb		zero the XRB			zeroxrb
	zerofx		zero the FIRQB and the XRB	zerofx
DATTIM	date		return current date or convert	str := date(0)
			internal format date to std
	time		return current time or convert	str := time(0)
			internal format time to std
RANDM2	random		pick random real number 0<=x<1	x := random
	randomi		pick random integer a<=i<=b	i := randomi(a,b)
	randomr		pick random real number a<=x<b	x := randomr(a,b)
	randominit	initialize random number 	randominit
			  generator
TRIG	tan		trig functions, angles		x := tan(angle)
	sinh		  in radians and < pi/4		x := sinh(angle)
	cosh		  (see file)			x := cosh(angle)
	tanh						x := tanh(angle)
TERMNL	terminaltype	return terminal type code	i := terminaltype(0)
	terminalclass	return terminal class code	i := terminalclass(0)
			  (see file for explanation)
SPOOL	spool		spool a file to PBS (see file)	spool(file/opt,que,err)
ERRMSG	errmsg		print msg for error number n	errmsg(n)
ERROR	sayerr		print msg for RSTS error n	sayerr(n)
PASERR	pascalerror	print msg for Pascal error n	pascalerror(n)
LOCATE	locate		return location (DSK:[PPN]) of	str := locate
			  last opened file (see file)
TTYSET	ttyset		set terminal characteristics	(see file)
LOGICL	logical		translate logical name		logical(str,err)
			  (requires FSS)
STR	initstring	string routines			initstring(string)
	fillinstring				fillinstring(outstring,startpos,
						   instring)
	integerto6charstring			str := integerto6charstring(n)
	stringtointeger				i := stringtointeger(string)
The following work only in privileged programs:
PRIV	droppriv	drop temporary privileges	droppriv
	regainpriv	regain temporary privileges	regainpriv
PEEK	peek		peek at one memory location	x := peek(addr)
FORCE	force		force string to KB		force(kb,string)
SEND	send		send (broadcast) string to KB	send(kb,string)
SHWATR	showattributes	show attributes (see file)	showattributes(prj,prg)
	dateconvert	internal format to dd-mmm-yy	str := dateconvert(n)
	timeconvert	internal format to hh:mm xM	str := timeconvert(n)
SHWACT		(show account - fancier version of SHWATR - see file)
ATTRR		(program to read attribute blockettes - see file)
ATTRW		(program to write attribute blockettes - see file)



     As an example of how a library routine might be used, consider the
echooff routine.  The list above shows that it is in the file echo and
requires no parameters.  Your program might look like this:

                 PROGRAM Test1;
                 %INCLUDE 'PLIB:ECHO';
                 VAR
                    ---
                    ---
                 BEGIN { main }
                    ---
                    ---
                   echooff;
                    ---
                    ---
                 END. { main }


     The swapconsole routine is in the file detach, and requires that a single 
value (the job number) be passed to it.  A program to swap with job number 31 
might look like this:

                 PROGRAM Test2;
                 %INCLUDE 'PLIB:DETACH';
                 VAR
                   job : INTEGER;
                    ---
                 BEGIN { main }
                    ---
                    ---
                   job := 31;
                   swapconsole(job);  { swapconsole(31) also could be used }
                    ---
                    ---
                 END. { main }