Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

;TITLE	USRDSP FOR LIBOL
SUBTTL	ROUTINE FOR ADDING USER ROUTINES TO LIBOL /ACK



;THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY ONLY BE USED
;  OR COPIED IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE.
;
;COPYRIGHT (C) 1974, 1981 BY DIGITAL EQUIPMENT CORPORATION

COMMENT	\

OVERVIEW:

	THE PURPOSE OF THIS ROUTINE IS TO ALLOW INSTALLATIONS TO ADD THEIR OWN
MACRO SUBROUTINES TO LIBOL AND ENTER THEM FROM COBOL PROGRAMS.
NOTE THAT THIS MUST BE DONE ON A INSTALLATION AS OPPOSED TO AN
INDIVIDUAL USER BASIS.


	THIS ROUTINE ACTUALLY CONSISTS OF TWO PARTS:  A LOW SEGMENT
DISPATCH ROUTINE, WHICH WILL BE LOADED WITH THE USER'S PROGRAM UNLESS
HE GIVES "/R" IN HIS COMMAND STRING, AND A DISPATCH TABLE WHICH RESIDES
IN LIBOL.SHR.

	IF THE USER SPECIFIES "/R" IN HIS COMMAND STRING THE DISPATCH
ROUTINE WILL NOT BE LOADED, INSTEAD THE USERS ROUTINES WILL BE LOADED
AND RESOLVED INTO DIRECT REFERNCES BY THE LOADER.

	ONE OF THE LOCATIONS IN LIBOL'S DISPATCH TABLE WILL CONTAIN
THE FOLLOWING:

	JRST	1,@USRTB.(15)

WHERE "USRTB." IS THE NAME OF THE USER DISPATCH TABLE IN LIBOL.SHR.
"USRTB." IS ALSO THE NAME OF THE LIBOL DISPATCH TABLE ENTRY FOR
THOSE OUTSIDE OF LIBOL.SHR.

	THE FORMAT OF A USER DISPATCH TABLE ENTRY IN THE LIBOL HIGH SEGMENT
IS AS FOLLOWS:

	EXTERNAL	ROUTINE
	XWD	0,ROUTINE

	THE DISPATCH ROUTINE IN THE LOW SEGMENT DETERMINES THE OFFSET
INTO THE DISPATCH TABLE, PLACES THAT IN AC 15 AND THEN EXECUTES
	JRST	USRTB.##

AFTER CONTROL HAS BEEN TRANSFERED REGISTER 15 IS AVAILABLE TO THE
USER ROUTINE.

INSTALLATION INSTRUCTIONS:

	FIRST COMLETE ANY OTHER REQUIRED SYSTEM REBUILDING AS
INSTRUCTED IN THE INSTALLATION GUIDE (COBOL.INS).

	TO PLACE A ROUTINE IN LIBOL CALLABLE FROM A COBOL PROGRAM
SIMPLY LIST THE ROUTINE ENTRY POINT NAMES IN THE DISPATCH TABLE
SKELETON AT THE END OF THIS TEXT.

THEN COMPILE THIS ROUTINE WITH THE FOLLOWING COMMANDS:

R MACRO
USRDSL=USRDSP
USRDSH=TTY:,DSK:USRDSP
SHR==1
<CONTROL Z>
<CONTROL Z>

THEN REPLACE THE OLD USRDSL.REL AND USRDSH.REL IN LIBOL.REL BY THE NEW
ONES USING FUDGE2 AND THEN ADD THE USER ROUTINES TO LIBOL.REL.  THE
SEQUENCE OF THE REL FILES IN LIBOL IS VERY IMPORTANT AND MUST BE:

	LILOWS.REL
	.
	.
	.
	USRDSL.REL
	USRDSH.REL
	RTN1.REL
	RTN2.REL
	.
	.
	.
	RTNN.REL

AFTER THIS REBUILD LIBO10.SHR AS FOLLOWS:

.R LINK
*LIBSHR,LIBOL/SEARCH/GO
.SAVE LIBO10

INSTALL THE SYSTEM AS INSTRUCTED IN THE INSTALLATION GUIDE.

USER ROUTINE LOW SEGMENTS:

	FOR CURRENT AND FUTURE COMPATABILITY REASONS USER ROUTINES
ARE NOT PROVIDED WITH A STATIC LOW SEGMENT AREA.  INSTEAD A
DYNAMIC (INDEXED) LOW SEGMENT FACILITY IS PROVIDED.

A.	CHOOSE A REGISTER TO CONTAIN THE LOW SEGMENT BASE ADDRESS
	TO BE USED BY ALL ROUTINES FOR LOW SEGMENT REFERENCE.

B.	CREATE A SINGLE MACRO PROGRAM TO DEFINE THE LOW SEGMENT
	FOR ALL USER ROUTINES.  THE LOW SEGMENT IS DEFINED IN TERMS OF
	INTERNAL SYMBOLS AND STANDARD BLOCK DEFINITIONS (NO PRESET
	VALUES), BEGINNING WITH A "LOC 0".

C.	A SINGLE STATIC LOW SEGMENT VARIABLE "USRLO.", PRESET TO ZERO,
	IS PROVIDED TO STORE THE LOW SEGMENT BASE ADDRESS ACROSS
	ROUTINE CALLS.  THE FIRST TWO INSTRUCTIONS OF ROUTINES
	USING A LOW SEGMENT SHOULD BE:

		SKIPN	IDX,USRLO.##	;GET LOW SEGMENT BASE
		PUSHJ	17,GETLO	;SET IT UP IF NOT PREVIOUSLY DONE

	IF CORE HAS BEEN OBTAINED FOR THE USER LOW SEGMENT, IE.
	"USRLO." IS NON-ZERO, THE ROUTINE WILL PROCEED.   ALL LOW
	SEGMENT REFERENCES ARE MADE AS A FUNCTION OF IDX, FOR EXAMPLE:

		MOVE	T1,LOVAR##(IDX)	;OBTAIN CONTENTS OF LOSEG VARIABLE

	IF CORE HAS NOT BEEN OBTAINED CONTROL IS TRANSFERED TO A USER
	PROVIDED ROUTINE WHICH DETERMINES HOW MUCH CORE IS REQUIRED
	FOR THE ENTIRE LOW SEGMENT, OBTAINS IT VIA A CALL TO ROUTINE
	"FUNCT.", AND STORES THE RESULTANT BASE ADDRESS IN "USRLO.".

WHY IT WORKS:

CASE 1 (NO "/R" IN THE COMMAND STRING):

	THE COMPILER WILL GENERATE AN EXTERNAL, "LILO.",
WHICH WILL CAUSE LILOWS.REL TO BE LOADED WHICH IN TURN WILL 
GENERATE AN EXTERNAL REFERENCE "USRTB%" WHICH WILL CAUSE
USRDSL.REL TO BE LOADED.  IN USRDSL.REL ALL OF THE USER LIBOL ROUTINE ENTRY NAMES
ARE DECLARED AS INTERNAL, THUS SATISFYING ALL REFERENCES TO ROUTINES
WHICH ARE IN LIBOL.SHR.

	THE LIBOL.SHR DISPATCH TABLE REFERENCES THE USER DISPATCH
TABLE , CAUSING IT TO BE LOADED, WHICH IN TURN CAUSES THE ACTUAL 
ROUTINES TO BE LOADED.

CASE 2 ("/R" IN THE COMMAND STRING):

	THE COMPILER WILL NOT GENERATE AN EXTERNAL "LILO.".
SINCE THE ENTRY POINTS INTO THE USER'S ROUTINES IN USRDSL.REL
ARE DECLARED AS INTERNAL, USRDSL.REL WILL NOT BE LOADED.  THUS
THE REFERENCES TO THE USER'S ROUTINES ARE SATISFIED BY ACTUAL
LOADING FROM LIBOL.REL.

\

SUBTTL DEFINITIONS

IFNDEF SHR,<SHR==0>	;0 ==> GENERATE LOW SEGMENT CODE TO DISPATCH
			; TO "LOC".
			;1 ==> GENERATE HIGH SEGMENT CODE TO DISPATCH
			; TO USER'S ROUTINE FROM "LOC".

	IFE	SHR,<TITLE	USRDSL FOR LIBOL>
	IFN	SHR,<TITLE	USRDSH FOR LIBOL>


IFE SHR,<
	ENTRY	USRTB%	;THE LILOWS WILL GENERATE 
USRTB%:	BLOCK 0		;	EXTERNAL USRTB%
			; IF "/R" IS NOT SPECIFIED TO FORCE THIS
			; ROUTINE TO BE LOADED.

;MACRO TO GENERATE TABLE ENTRIES FOR DISPATCHING TO "LOC".

	DEFINE	$X(A)
<
	INTERNAL	A
A':	JSP	15,DSPTCH
	IDX==IDX+1
>
	IDX==0
>

IFN	SHR,<
	ENTRY	USRTB.	;SO LIBOL.SHR WILL HAVE THE TABLE IN IT.
			; WHICH WILL FORCE ALL THE USER'S ROUTINES TO
			; BE LOADED.

;MACRO TO GENERATE THE TABLE FOR DISPATCHING TO THE PARTICULAR ROUTINE

	DEFINE $X(A)
<
	EXTERNAL	A
	XWD	0,A
>
	HISEG
>

SUBTTL	THE DISPATCH TABLE.


	SALL

IFN SHR,<
USRTB.:
>
IFE SHR,<
TABST.:
>
; ******* PLACE LIST OF ROUTINES HERE *****
;USING THE MACRO "$X" IN THE FOLLOWING  FASHION:
;	$X	RTN1
;	$X	RTN2
;	  ...



;THE DISPATCH ROUTINE.

IFE SHR,<
IFN IDX,<
DSPTCH:	SUBI	15,TABST.+1	;COMPUTE THE TABLE OFFSET.
	JRST	USRTB.##		;DISPATCH
>>

	END