Programmed Request Description and Examples
.UNLOCK Notes
• The number of .UNLOCK requests must at least match the number of .LOCK requests that were issued. If more .LOCK requests are done, the USR remains locked in memory. Extra .UNLOCK requests in your program do no harm since they are ignored.
• With two jobs running, use .LOCK/.UNLOCK pairs only where absolutely necessary. When a one job locks the USR, the other job cannot use it until it is unlocked, which can degrade performance in some cases.
• Calling the CSI, with input coming from the terminal, results in an implicit (though temporary) .UNLOCK.
• Make sure that the .UNLOCK request is not in the same area that the USR swaps into; otherwise, the request can never be executed.
Errors:
None.
Example:
.TITLE ELOCK.MAC
;+
; .LOCK / .UNLOCK - This is an example in the use of the .LOCK and .UNLOCK
; requests. This example tries to obtain as much memory as possible (using
; the .SETTOP request), which will force the USR into a swapping mode. The
; .LOCK request will bring the USR into memory (over the high 2k of our little
; program !) and force it to remain there until an .UNLOCK is issued.
;-.MCALL .LOCK,.UNLOCK,.LOOKUP .MCALL .SETTOP,.PRINT,.EXIT
$USRRB =: 53 ;(.SYCDF) User error byte SUCCS$ =: 001 ;(.UEBDF) Success code ERROR$ =: 004 ;(.UEBDF) Error code FATAL$ =: 010 ;(.UEBDF) Fatal code
$SYSPTR =: 54 ;(.SYCDF) Pointer to beginning of RMON
.LOCK/.UNLOCK
START: .SETTOP @#$SYSPTR ;Try to allocate all of memory (up to
;RMON)
.LOCK ;bring USR into memory
.LOOKUP #AREA,#0,#FILE1 ;LOOKUP a file on channel 0
BCC 1$ ;Branch if successful
2$: .PRINT #LMSG ;Print Error Message BISB #FATAL$,@#$USRRB ;Flag error
.EXIT ;then exit program
1$: .PRINT #F1FND ;Announce our success MOV #AREA,R0 ;R0 => EMT Argument Block
INC @R0 ;Increment low byte of 1st arg (chan #) MOV #FILE2,2(R0) ;Fill in pointer to new filespec
.LOOKUP ;Do the .LOOKUP from filled in arg block
;pointed to by R0.
BCS 2$ ;Branch on error
.PRINT #F2FND ;Say we found it
.UNLOCK ;now release the USR
BISB #SUCCS$,@#$USRRB ;Flag success
.EXIT ;and exit program
AREA: .BLKW 3 ;EMT Argument Block
FILE1: .RAD50 /SY/ ;A File we’re sure to find .RAD50 /SWAP /
.RAD50 /SYS/
FILE2: .RAD50 /SY/ ;Another file we might find .RAD50 /PIP /
.RAD50 /SAV/
LMSG: .ASCIZ /?ELOCK-F-Error on .LOOKUP/ ;Error message F1FND: .ASCIZ /!ELOCK-I-Found SWAP.SYS/
F2FND: .ASCIZ /!ELOCK-I-Found PIP.SAV/
.EVEN
.END START
.LOOKUP
EMT 375, Code 1
A .LOOKUP request can be used in two different ways:
• As a standard .LOOKUP file under all monitors.
• As an MQ job .LOOKUP under system job monitors.
Standard Lookup
The .LOOKUP request associates a specified channel with a device and existing file for the purpose of performing I/O operations. The channel used is then busy until one of the following requests is executed:
.CLOSE .CLOSZ
.SAVESTATUS .SRESET .HRESET .PURGE
.CSIGEN (if the channel is in the range 0-10 8) Notes
If the program is overlaid, channel 178 is used by the overlay handler and should not be modified.
If the first word of the file name (the second word of dblk) is 0 and the device is a file-structured device, absolute block 0 of the device is designated as the beginning of the file. This technique is called a non-file-structured .LOOKUP and allows I/O operations to access any physical block on the device. If a file name is specified for a device that is not file structured (such as LP:FILE.TYP), the name is ignored.
The handler for the selected device must be in memory for a .LOOKUP.
Be careful doing a non-file-structured .LOOKUP on a file-structured device. If your program writes data, corruption of the device directory can occur and effectively destroy the disk’s contents. The RT–11 directory starts in absolute block 6.
In particular, avoid doing a .LOOKUP or .ENTER with a file specification where the file value is missing. Unless you know you want to open an entire device, always supply a dummy file name when issuing a .LOOKUP or .ENTER.
Macro Call:
.LOOKUP area,chan,dblk[,seqnum]
where:
.LOOKUP
area is the address of a three-word EMT argument block chan is a channel number in the range 0-3768
dblk is the address of a four-word Radix–50 descriptor of the file or device to be operated upon
seqnum is a file number for magtape.
If this argument is blank, a value of 0 is assumed.
For magtape, it describes a file sequence number. The action taken depends on whether the file name is given or is null. The sequence number can have the following values:
-1 Means suppress rewind and search for a file name from the current tape position. If a file name is given, a file-structured lookup is performed (do not rewind).
It is important that only -1 be specified and not any other negative number. If the file name is null, a non-file-structured lookup is done (tape is not moved).
0 Means rewind to the beginning of the tape and do a non-file-structured lookup.
n Where n is any positive number. Position the tape at file sequence numbern and check that the file names match. If the file names do not match, an error is generated. If the file name is null, a file-structured lookup is done on the file designated byseqnum.
On return from the .LOOKUP, R0 contains the length in blocks of the file just opened.
On a return from a .LOOKUP for a non-directory, file-structured device (typically magtape), R0 contains 0 to indicate the unknown length.
Request Format:
R0 area: 1 chan
dblk seqnum
Errors:
Code Explanation
0 Channel already open.
1 File indicated was not found on the device.
.LOOKUP 2 File already open on a nonshareable device; for example,
magtape.
5 Argument is invalid; for example, magtape file sequence number.
6 Error code is returned in $ERRBY if the request is issued to a nonexistent or otherwise invalid special-directory device unit.
The handler determines the validity of the device unit.
Example:
.TITLE ELOOKU.MAC
;+
; .LOOKUP - This is an example in the use of the .LOOKUP request.
; This example determines whether or not the RT-11 SWAP.SYS
; Workfile exists on device SY: and if so, prints its size in
; blocks on the console terminal.
;-.MCALL .LOOKUP,.PRINT,.EXIT
$USRRB =: 53 ;(.SYCDF) User error byte SUCCS$ =: 001 ;(.UEBDF) Success code ERROR$ =: 004 ;(.UEBDF) Error code FATAL$ =: 010 ;(.UEBDF) Fatal code
START: .LOOKUP #AREA,#0,#SPEC ;See if there’s a SY:SWAP.SYS
BCC 1$ ;Branch if there is
.PRINT #NOFIL ;Print ’File Not Found’ message BISB #FATAL$,@#$USRRB ;indicate error
.EXIT ;then exit program
1$: MOV #SIZE,R1 ;R1 => where to put ASCII size CALL CNV10 ;Convert size (in R0) to ASCII .PRINT #BUFF ;Print size of QUFILE.TMP on console BISB #SUCCS$,@#$USRRB ;indicate success
.EXIT ;then exit program
CNV10: MOV R0,-(SP) ;Subroutine to convert Binary # in R0 CLR R0 ;to Decimal ASCII by repetitive 1$: INC R0 ;subtraction. The remainder for each
SUB #10.,@SP ;radix is made into ASCII and pushed BGE 1$ ;on the stack, then the routine calls ADD #72,@SP ;itself. The code at 2$ pops the ASCII DEC R0 ;digits off the stack and into the out-BEQ 2$ ;put buffer, eventually returning to CALL CNV10 ;the calling program. This is a VERY 2$: MOVB (SP)+,(R1)+ ;useful routine, is short and is
RETURN ;memory efficient.
AREA: .BLKW 3 ;EMT Argument Block
SPEC: .RAD50 /SY SWAP SYS/
BUFF: .ASCII /!ELOOKU-I-SY:SWAP.SYS = / SIZE: .ASCIZ / Blocks/
NOFIL: .ASCIZ /?ELOOKU-F-File Not Found SY:SWAP.SYS/
.EVEN
.END START System Job Lookup
The foreground and background jobs can send messages to each other via the existing .SDAT/.RCVD/.MWAIT facility. A more general message facility is available to all
.LOOKUP
jobs through the message queue (MQ) handler. By turning message handling into a formal "device" handler, and treating messages as I/O to jobs, the existing .READ /.WRITE/.WAIT mechanism can be used to transmit messages. A channel is opened to a job via a .LOOKUP request, after which standard I/O requests are issued to that channel.
Macro Call:
.LOOKUP area,chan,jobdes where:
area is the address of a two-word EMT argument block chan is the number of the channel to open
jobdes is the address of a four-word descriptor of the job to which messages will be sent or received:
jobdes: .RAD50 /MQ/ ;use MQ device
.BYTE 0,0,0,0,0,0 ;insure null padding 10$: .=.-6
.ASCII /NAME/ ;Logical job name .=10$
where logical-job-name can be from one to six characters long. It must be padded with nulls if less than six characters long. If logical-job-nameis all nulls, the channel will be opened for .READ requests only and will accept messages from any job
Request Format:
R0 area: 1 chan
jobdes
The .LOOKUP request associates a channel with a specified job for the purposes of sending inter-task messages. R0 is undefined on return from the .LOOKUP.
Errors:
Code Explanation
0 Channel not available.
1 No such job.