Programmed Request Description and Examples
Word 4: Device Size
The size of the device (in 256-word blocks) for block-replaceable devices; 0 for sequential-access devices, the smallest-sized volume for variable-sized devices. The last block on the device is the device size -1.
.DSTAT
Notes
The device name can be a user-assigned name. .DSTAT information is extracted from the device handler. Therefore, this request requires the handler for the device to be present on the system device and installed on the system. Refer to RT–11 Device Handlers Manual.
Errors:
Code Explanation
0 Device not found in tables.
Example: See the example under .CSISPC.
.ELAW
EMT 375, Code 36, Subcode 3
The .ELAW request eliminates a virtual address window.
Macro Call:
.ELAW area,addr where:
area is the address of a two-word EMT argument block
addr is the address of the window definition block for the window to be eliminated
Request Format:
R0 area: 36 3
addr
Errors:
Code Explanation
3 An invalid window identifier was specified.
17 Inactive mode or space was specified.
Example:
See .CRAW.
.ELRG
Mapping
EMT 375, Code 36, Subcode 1
The .ELRG request directs the monitor to eliminate a dynamic region in physical memory and return it to the free list where it can be used by other jobs.
When memory is freed after a region is eliminated, the .ELRG programmed request concatenates contiguous areas of memory segmented in the allocation table.
Macro Call:
.ELRG area,addr where:
area is the address of a two-word EMT argument block
addr is the address of the region definition block for the region to be eliminated. Windows mapped to this region are unmapped. The static region cannot be eliminated
Request Format:
R0 area: 36 1
addr
Errors:
Code Explanation
2 An invalid region identifier was specified.
14 Global region in use.
11 Deallocation failure.
Example:
See .CRAW.
.ENTER
EMT 375, Code 2
The .ENTER request allocates space on the specified device and creates a tentative entry in the directory with the name of the specified file. The channel number specified is associated with the file.
Macro Call:
.ENTER area,chan,dblk,len[,seqnum]
where:
area is the address of a four-word EMT argument block chan is a channel number in the range 0-3768
dblk is the address of a Radix–50 descriptor of the file to be created.
If the file name is not provided in dblk, it is a non-file-structured .LOOKUP which connects the channel to the entire device, starting at block 0.
len is the file size specification. If you don’t specify a value for len, the value inareais used to specify the value for len.
For RT–11 structured devices, the value of this argument determines the file length allocation:
0 is either half the largest empty entry or the entire second-largest empty entry. Whichever is larger is compared to MAXBLK (RMON fixed offset 314). The smaller value is selected. Value may be expressed as:
MIN(MAXBLK, MAX(LEMPTY)/2, 2ND LEMPTY).
NOTE
MAXBLK is the maximum size for nonspecific .ENTER requests that are patched in the monitor by changing RMON offset 314.
(See example for .PVAL.)
-1 is the smaller of the largest available empty entry compared to MAXBLK (1777778 blocks.) Value may be expressed as MIN(MAXBLK, LEMPTY).
m is a file ofmblocks. Use this argument to specify the number of blocks needed.
.ENTER
seqnum is a parameter for magtape. Programming for specific devices such as magtape is discussed in detail inRT–11 Device Handlers Manual.
Seqnumdescribes 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:
0 Rewind the magtape and space forward until the file name is found or until logical end-of-tape is detected.
If the file name is found, an error is generated. If the file name is not found, then enter file. If the file name is a null, a non-file-structured lookup is done (tape is rewound)
-1 Space to the logical end-of-tape and enter file
-2 Rewind the magtape and space forward until the file name is found or until logical end-of tape is detected.
A new logical end-of-tape is implied.
n Position magtape at file sequence number n if n is greater than zero and the file name is not null Request Format:
R0 area: 2 chan
dblk len seqnum
On return from this call, R0 contains the size of the area actually allocated for use.
Or zero (0) for a non-RT–11 device or non-file-structured .ENTER.
Notes
Because a file created with an .ENTER request is not permanent until a .CLOSE request is given on that channel, the newly created file is not available to .LOOKUP, and the channel cannot be used by .SAVESTATUS requests. However, it is possible to read data that has just been written into the file by reading the channel number on which the .ENTER was issued. When the .CLOSE to the channel is given, any existing permanent unprotected file of the same name on the same device is deleted and the new file becomes permanent. Although space is allocated to a file during the .ENTER operation, the actual length of the file is determined when .CLOSE is requested. The .CLOSZ request can be used to truncate the file wherever you wish.
Each program can have up to 255 files open on the system at any time. If required, all 255 can be opened for output with the .ENTER function.
.ENTER
When a file-structured .ENTER request is made, the device handler must be in memory. Thus, a .FETCH should normally be executed before an .ENTER can be done.
When using the zero-length feature of .ENTER, keep in mind that the space allocated is less than the largest empty space. This can have an important effect in transferring files between devices, particularly diskettes that have a relatively small capacity. For example, transferring a 200-block file to a diskette, on which the largest available empty space is 300 blocks, does not work with a zero-length .ENTER. Since the .ENTER allocates half the largest space, only 150 blocks are really allocated and an output error occurs during the transfer. When transferring from A to B, with the length of A unknown, do a .LOOKUP first. This request returns the length so that value can be used to do a fixed-length .ENTER. The .ENTER request generates hard errors when problems are encountered during directory operations. These errors can be detected after the operation with the .SERR request. Hard errors are passed to the program when .SERR has been issued prior to .ENTER.
Errors:
Code Explanation
0 Channel is not available.
1 In a fixed-length request, no space greater than or equal to m was found; or the device or the directory was found to be full.
2 Nonshareable device is already in use by another program.
3 A file by that name already exists and is protected. A new file was not opened.
4 File sequence number was not found.
5 File sequence number is invalid or file name is null.
6 Request is issued to a nonexistent or otherwise invalid special-directory device unit. The handler determines the validity of the device unit.
Example:
.TITLE EENTER;2
;+
; .ENTER - This is an example in the use of the .ENTER request.
; The example makes a copy of the file ’PIP.SAV’ on device DK:
;-.MCALL .LOOKUP,.ENTER,.WRITW,.READW,.CLOSE .MCALL .PRINT,.EXIT
$ERRBY =: 52 ;(.SYCDF) EMT error byte
$USRRB =: 53 ;(.SYCDF) user error byte
SUCCS$ =: 001 ;(.UEBDF) success bit
FATAL$ =: 004 ;(.UEBDF) error bit
.ENTER
.ENABL LSB
START: .LOOKUP #AREA,#0,#PIP ;Lookup file SY:PIP.SAV
BCS 4$ ;Branch if not there!
MOV R0,R3 ;Copy size of file to R3
.ENTER #AREA,#1,#TFILE,R3 ;Enter a new file of same size
BCS 5$ ;Branch if failed
CLR BLK ;Initialize block # to zero
1$: .READW #AREA,#0,#BUFFR,#256.,BLK ;Read a block
BCC 2$ ;Branch if successful
TSTB @#$ERRBY ;Was error EOF?
BEQ 3$ ;Branch if yes
MOV #RERR,R0 ;Hard read error message to R0
BR 7$ ;Branch to print message
2$: .WRITW #AREA,#1,#BUFFR,#256.,BLK ;Write a block
INC BLK ;*C*Bump block #
BCC 1$ ;Branch if write was ok
MOV #WERR,R0 ;R0 => Write error message
BR 7$ ;Branch to print message
3$: .CLOSE #1 ;Make new file permanent
MOV #DONE,R0 ;R0 => Done message
BR 6$ ;Branch to print message
4$: MOV #NOFIL,R0 ;R0 => File not found message
BR 7$ ;Branch to print it
5$: MOV #NOENT,R0 ;R0 => Enter Failed message
BR 7$ ;Branch to print message
6$: BISB #SUCCS$,@#$USRRB ;Indicate success
BR 8$
7$: BISB #FATAL$,@#$USRRB ;Indicate error
8$: .PRINT ;Print message on console
; terminal
.EXIT ;the exit program
AREA: .WORD 0 ;EMT Argument block
BLK: .WORD 0,0,0,0 ;
BUFFR: .BLKW 256. ;I/O Buffer
PIP: .RAD50 /SY/ ;File descriptors...
.RAD50 /PIP /
.RAD50 /SAV/
TFILE: .RAD50 /DK/
.RAD50 /PIP /
.RAD50 /TMP/
NOFIL: .ASCIZ /?EENTER-F-File not found/
NOENT: .ASCIZ /?EENTER-F-.ENTER Failed/
WERR: .ASCIZ /?EENTER-F-Write Error/
RERR: .ASCIZ /?EENTER-F-Read Error/
DONE: .ASCIZ /!EENTER-I-PIP Copy Complete/
.END START
.EXIT
EMT 350