(RT--11 Monitorssingle-job unmapped monitors) (RT--11 MonitorsSee also SB monitor) There are three single-job unmapped RT--11 monitors: (UNNUMBERED) SB replaces the single job (SJ) monitor, and supports most programmed requests. SB supports program requests that manipulate files, perform input and output, set timer routines, check system resources and status, and terminate program operations. MT is used only with MDUPs. AI is used only with automatic installation. (Single-job Mapped Monitors)

Two single-job mapped RT--11 monitors, XB and ZB, (RT--11 Monitorssingle-job mapped monitors) (RT--11 MonitorsSee also XB and ZB monitors) provide programmed requests and features in addition to those provided by the FB monitor: (UNNUMBERED) XB is a single-mapped monitor that supports User and Kernel modes. ZB is a fully-mapped monitor that supports I and D space for User, Supervisor, and Kernel modes. (Multijob Unmapped Monitors)

FB is the unmapped multijob monitor. Multijob monitors support program (RT--11 Monitorsmulti-job unmapped monitors) (RT--11 MonitorsSee also FB monitor) requests in addition to those supported for the single-job monitor. Some programmed requests are provided for the multijob monitor only. Multijob monitors enable a program to set timer routines, suspend and resume jobs, and send messages and data between foreground and background jobs. (Multijob Mapped Monitors)

Mapped monitors extend RT--11's memory support capability beyond the (RT--11 Monitorsmulti-job mapped monitors) (RT--11 MonitorsSee also XM and XB monitors) 28K-word (plus I/O page) restriction imposed by the 16-bit address size. Mapped monitors program requests extend a program's effective logical addressing space (See (FB_XM_PRS)). (ORIGN TABLE_1-5, now in APPENDIX A)

There are two multijob mapped monitors: (UNNUMBERED) XM is a single-mapped monitor that supports User and Kernel modes. ZM is a fully-mapped monitor that supports I and D space for User, Supervisor, and Kernel modes. (System Job Environment)

Programmed requests in the system job environment enable programs to: (UNNUMBERED) (System job environmentprogram requests in) Copy channels from other jobs Obtain job status information about jobs Send messages and data between jobs

Programmed requests perform most system resource control and interrogation functions; however, some communication is accomplished by directly accessing two memory areas: (UNNUMBERED) System communication area Monitor fixed-offset area

Of all the distributed RT--11 monitors, only XM and ZM let you run programs in the system job environment. This system job support enables you to run up to eight user programs in single- or fully-mapped memory environment. RT--11 is distributed with the following programs that can be run as system jobs: (UNNUMBERED) Error logger (ERRLOG) Device queue program (QUEUE) Transparent spooler package (SPOOL) Communication package (VTCOM) Keypad editor (KEX) Virtual index (INDEXX) Resident monitor (RTMON) (Multiterminal Operation)

The multiterminal feature of RT-11 enables your program to perform (Multiterminal operation) character input/output on up to 17 terminals. Programmed requests are available to perform input/output, attach and detach a terminal for your program, set terminal and line characteristics, and return system status information. (System Communication Areas) (System Area)

The system communication area resides in locations 40 to 57(8) and (System communication areas) contains parameters that describe and control execution of the current job. This area holds information such as the Job Status Word, job starting address, User Service Routine (USR) swapping address, and the resident monitor's start address. Your program provides some of this information, but other data provided by the monitor may not be changed. (Fixed Offset Area)

The second memory communication area, the fixed-offset area, is (Fixed-offset areaaccessing) (Fixed-offset areaSee also .GVAL, .PVAL, .PEEK, .POKE) accessed by a fixed-address offset from the start of the resident monitor. This area contains system values that control monitor operation. Your program can examine or modify these values to determine the condition of the operating environment while a job is running. Digital recommends this area be accessed, using only .GVAL, .PVAL, .PEEK, .POKE. The (SIM_BOOK) contains details about the system communication area and the fixed-offset area.

This manual describes programmed requests specifically for RT-11 Version 5. For information about programmed requests for earlier versions of RT-11 and guidelines for their conversion, refer to Appendix A. (Programmed Request Implementation\prog_req_impl) (EMT Instructions)

A programmed request is a macro call (Programmed requestsimplementation) (Programmed requestsEMT instructions) followed by the necessary number of arguments. The macro definition corresponding to the macro call of a programmed request is (expanded\ITALIC) by the MACRO assembler whenever the programmed request appears in your program. The expansion arranges the arguments of the programmed request for the monitor and generates the hardware (emulator trap) instruction. However, some macros like .DRxxxx do not generate EMTs. EMT instructions should never appear in your programs, except through programmed requests.

When an EMT instruction is executed, control passes to the monitor. The low-order byte of the EMT code provides the monitor with the information that tells it what monitor service is being requested. The execution of the EMT generates a trap through vector location 30, which is loaded at boot time with the address of the EMT processor in the monitor.

Table (EMT\VALUE) lists codes that may appear in the low-order byte of an EMT instruction and gives the monitor's interpretation of these codes. (EMT Codes\EMT) (KEEP) (2\15) (Low-Order Byte\Interpretation) (Use GOLD T For table rows) (377\Reserved; RT-11 ignores this EMT by returning control to the user program immediately.) (376\Reserved; used internally by the RT-11 monitor. Your programs should not use this EMT since its use would lead to unpredictable results.) (375\Programmed request with several arguments; R0 points to a block of arguments that supports the user request.) (374\Programmed request with one argument; R0 contains a function code in the high-order byte and a channel code in the low-order byte.) (373\Program request to call Kernel routines.) (360-372\Reserved; used internally by the RT-11 monitor; your programs should never use these EMT codes since their use would lead to unpredictable results.) (340-357\Programmed requests with the arguments on the stack and/or in R0.) (0-337\RT--11 version 1 programmed requests with arguments both on the stack and in R0. They are supported only for binary compatibility with Version 1 programs.) (System Control Path Flow)

(FIG1_2) shows system flow when a programmed request in (System controlpath flow) an application (or system utility) program is implemented with an EMT instruction. When your program is executed, the following occurs: (NUMBERED) The EMT instruction transfers control to the EMT processor code in the monitor. The user program counter (PC) and processor status word (PS) are pushed onto the stack, and the contents of location 30 are placed in the program counter. Location 30 points to the EMT processor code in the monitor. Location 32 contains the PSW for the EMT trap. The monitor loads byte 52 of the system communication area with an error code if the monitor detects any errors during EMT processing. The EMT processor uses R0 to pass back information to the program. All other registers are preserved. Unlike other EMTs, .CSIGEN and .CSISPC return information on the stack, thereby modifying the stack pointer. Request blocks passed to EMTs are accessed, but not modified by the monitors. Parameters pushed onto the stack by standard macro definitions are popped from the stack by the monitor through standard EMT processing.

The monitor either processes a programmed request entirely when it is issued or performs partial processing and queues the request for further processing. For information about requests that perform I/O operations, see Section (IO_OPNS\VALUE). When a request results in an error prior to its being queued, the completion routine is not entered, and the monitor returns to the user program with the carry bit set. If the request is queued, the completion routine is entered upon completion of further processing, regardless of the outcome.

(System Flow During Programmed Request Execution\FIG1_2) (postscript\FIG1_2.eps\29) (System Conventions\sys_conv)

This section describes system conventions that must be followed to ensure correct operation of programmed requests. (Program Request Format)

To issue programmed requests (System ConventionsProgram request format) from assembly language programs, you must set up the arguments in correct order and issue the appropriate EMT instruction. Macros have been created to help you do this. They are contained in the system macro library named SYSMAC.SML. Their use is recommended for maintaining program compatibility with future releases of RT-11 and for program readability. Most names for definitions in SYSMAC.SML, except SOB, start with a period (.) to distinguish them from symbols and macros you define.

Most arguments provided to a programmed request must be valid assembler expressions because the arguments are used as source fields in the instructions (such as a MOV instruction) when macros are expanded at assembly time. Each programmed request in your program must appear in a .MCALL directive to make the macro definition available from system macro library, SYSMAC.SML. Alternatively, you can enable the automatic .MCALL feature of MACRO by using the .ENABL MCL directive. (However, you cannot use .ENABL MCL to automatically .MCALL .PRINT.)

Because there are various ways to set up the argument block and specify arguments to a programmed request, you should read the sections on programmed request format and on blank arguments to be sure you understand programmed request operation. Program requests have two acceptable formats: (FORMAT 1)

The first format specifies the programmed request, followed by the arguments required by the request.

Form: (indent\1\smallskip)(.PRGREQ arg1,arg2,...,argn)

where:

(KEEP) (3\3\15) (\(.PRGREQ)\ is the name of the programmed request) (\(arg1,arg2...,argn)\are arguments used with the request.)

Programmed requests using this format generate either an EMT 374 instruction or EMT 340 through 357 instructions.

Programmed requests that use an EMT 374 instruction set up R0 with the channel number in the even (low-order) byte and the function code in the odd (high-order) byte, as shown in (FIG1_3).

(EMT 374 Argument\FIG1_3) (KEEP) (POSTSCRIPT\FIG1_3.EPS\5)

For example, the programmed request .DATE generates an EMT 374. The macro for this programmed request appears in the system macro library as: (keep) .TITLE EXDATE.MAC .MACRO .DATE MOV #10.*^o400,R0 EMT ^o374 .ENDM

The (function code\ITALIC), in this case 10(10), is placed in the high-order byte of R0. A 0 is placed in the low-order byte since .DATE does not reference a channel.

Any arguments for EMT 340 through 357 would be placed either on the stack, in R0, or in R0 and on the stack.

.CSIGEN is an example of a programmed request that generates an EMT 344. A simplified macro expansion of this programmed request is: .TITLE EXCSIG.MAC .MACRO .CSIGEN DEVSPC,DEFEXT,CSTRNG,LINBUF .IF NB LINBUF MOV LINBUF,-(SP) .ENDC MOV DEVSPC,-(SP) .IF NB LINBUF INC @SP .ENDC MOV DEFEXT,-(SP) .IF B CSTRNG CLR -(SP) .IFF .IF IDN CSTRNG,#0 CLR -(SP) .IFF MOV CSTRNG,-(SP) .ENDC .ENDC EMT ^o344 .ENDM

When this programmed request is executed, all the specified arguments are placed on the User stack. The EMT processor then uses these arguments in performing the function of the programmed request .CSIGEN. See (FIG1_4).

(Stack Set by .CSIGEN Programmed Request\FIG1_4) (KEEP) (POSTSCRIPT\FIG1_4.EPS\9) (FORMAT 2)

The second format specifies the programmed request, the address of the argument block, and the arguments that will be contained in the argument block.

Form: (indent\1\smallskip)(.PRGREQ area,arg1,arg2,...,argn)

where:

(KEEP) (3\3\15) (\(.PRGREQ)\is the name of the programmed request) (\(area)\is the address of an argument block) (\(arg1,arg2,...,argn)\are arguments that will be contained in the argument block.)

This format generates an EMT 375 instruction. Programmed requests that call the monitor, via an EMT 375, use R0 as a pointer to an argument block. See (FIG1_5).

(EMT 375 Argument Block\FIG1_5) (KEEP) (POSTSCRIPT\FIG1_5.EPS\13)

The programmed request format uses (area) as a pointer to the argument block containing the arguments (arg1\ITALIC) through (argn\ITALIC).

Form: (indent\1\smallskip)(.PRGREQ area,arg1,...,argn)

Blank fields are permitted; however, if the (area\ITALIC) argument is empty, the macro assumes that R0 points to a valid argument block. If any of the fields (arg1\ITALIC) to (argn\ITALIC) are empty, the corresponding entries in the argument list are left untouched. For example, (indent\1\smallskip)(.PRGREQ area,arg1,arg2)

points R0 to the argument block at (area\ITALIC), fills in the first word (function code and channel number) and fills in the first and second arguments, while (indent\1\smallskip)(.PRGREQ area)

points R0 to the block and fills in the first word (function code and channel number) without filling in any other arguments. Arguments left blank are discussed in the next section. (Blank Arguments)

Any programmed request that uses an (System Conventionsblank arguments) argument block assumes that any argument left blank has been previously loaded by your program into the appropriate memory location (exceptions to this are the .CHCOPY and .GTJB requests). For example, when the programmed request (indent\1\smallskip)(.PRGREQ area, arg1, arg2)

is assembled, R0 will point to the first word of the argument block. The first word has the function code in the high-order byte and the channel number in the low-order byte. (arg1\ITALIC) is in the second word of the argument block (that is, pointed to by the contents of address R0 plus 2), while (arg2\ITALIC) is in R0 plus 4.

There are two ways to account for arguments: (UNNUMBERED) Let the MACRO assembler generate the instructions needed to fill up the argument block at run time. Write these instructions in your program, leaving the arguments in the programmed request blank for those that you have written in.

Digital recommends that you let SYSMAC.SML macro definitions generate the instructions, both for program clarity and for reduced chance of programming error.

The next three examples are all equivalent because the arguments have been accounted for either in the program instructions or in the programmed request. The second example sets up all the arguments for the programmed request, prior to executing the programmed request: .TITLE EXPRGA.MAC MOV #ARG1,AREA+2 MOV #ARG2,AREA+4 .PRGREQ #AREA .TITLE EXPRGB.MAC MOV #AREA,R0 .PRGREQ ,,#ARG1,#ARG2 .TITLE EXPRGC.MAC MOV #AREA,R0 MOV #CODE*400!CHANNEL,@R0 MOV #ARG1,2(R0) MOV #ARG2,4(R0) .PRGREQ

The next example demonstrates how arguments are specified to the .TWAIT programmed request: .TITLE EXWAIT.MAC .MCALL .PRINT,.TWAIT START: WAIT: .TWAIT #AREA,#TIME .PRINT #MSG BR WAIT AREA: .BLKW 2 TIME: .WORD 0,10.*60. MSG: .ASCIZ /Print this every 10 seconds/ .END START

The .TWAIT programmed request suspends a program and requires two arguments: (UNNUMBERED) The first argument, (area\ITALIC), is replaced by the address of a two-word EMT argument block. The second argument, (time\ITALIC), is replaced by two words of time -- high-order first, low-order second, expressed in ticks.

In the example, AREA is specified as an argument with the programmed request that points to the address of the EMT argument block. The first word of the argument block has a zero stored in the low-order byte representing the channel number and a function code of 24 stored in the high-order byte. The second word contains a pointer to the location (the second argument), which specifies the amount of time that the program will be suspended. It is defined as two words and, in this example, represents a 10-second interval. When run, the example program prints its message every ten seconds. (Addressing Modes)

You must make certain that the arguments specified are valid source fields and (System Conventionsaddressing modes) that the address accurately represents the value desired. If the value is a constant or symbolic constant, use the immediate addressing mode (#), but if the value is in a register, use the register symbol (Rn). If the value is in memory, use the label of the location whose value is the argument.

A common error is to use (n\ITALIC) rather than (#n\ITALIC) for numeric arguments. When a direct numerical argument is required, the immediate mode causes the correct value to be put in the argument block; for example, .TITLE EXPRGD.MAC .PRGREQ #AREA,,#4

is correct, while: .TITLE EXPRGE.MAC .PRGREQ #AREA,,4

is not correct, because the contents of location 4, instead of the desired value 4, are placed into the argument block. However, the form in the next example is correct, because the contents of (list\ITALIC) is the argument block pointer and the contents of (number\ITALIC) is the data value: .TITLE EXPRGF.MAC .PRGREQ LIST,,NUMBER ... .PSECT DATA LIST: .WORD AREA NUMBER: .WORD 4

All registers, except R0, are preserved across a programmed request. In certain cases, R0 contains information passed back by the monitor; however, unless the description of a request indicates that a specific value is returned in R0, the contents of R0 are unpredictable upon return from the request. Also, with the exception of calls to the Command String Interpreter (.CSIGEN/.CSISPC), the position of the stack pointer is preserved across a programmed request.

Be sure that addressing mode provided to the macro generates the correct value as a (source operand) in a MOV instruction. Check the programmed request macro in the Macro Library (SYSMAC.SML) and manually expand the programmed request or use the macro assembler (by using the .LIST MEB directive) to be sure of correct results. (Keyword Macro Arguments)

The RT-11 MACRO assembler supports keyword macro arguments. (System Conventionskeyword macro arguments) All the arguments used in programmed request calls can be encoded in their keyword form. See the (MAC_BOOK) for details.

In EMT 375 programmed requests, the high byte of the first word of the area (pointed to by R0) contains an identifying code for the request. Normally, this byte is set if the macro invocation of the programmed request specifies the area argument, and it remains unaffected if the programmed request omits the area argument. If the macro invocation contains CODE=SET, the high byte of the first word of the area is always set to the appropriate code, whether or not (area\ITALIC) is specified.

If CODE=NOSET is in the macro invocation, the high byte of the first word of area remains unaffected. This is true whether or not (area\ITALIC) is specified. This enables you to avoid setting the code when the programmed request is being set up. This might be done because it is known to be set correctly from an earlier invocation of the request using the same area, or because the code was statically set during the assembly process. (Channels and Channel Numbers)

A channel is a data structure that is a logical connection between your program and a file on a mass storage (System ConventionsChannels and channel numbers) device or on a serial device such as the line printer or terminal. The system provides 16(10) channels by default. When a file is opened on a particular device, a channel number is assigned to that file. The channel number can have an octal value from 0 to 376 (0 to 254 decimal). Your program first opens a channel through a programmed request by specifying the device and/or file name, file type, and a channel number to the monitor, then refers to that file or device in all subsequent I/O operations by the assigned channel number. You can specify a device (non-file-structured) or a device and file name (file-structured).

Channel 255(10) is reserved for system use. Channel 15(10) is used by the system's overlay handler (if the program is overlaid). (Device Blocks) A device block is a four-word block of Radix-50 (System Conventionsdevice blocks) information that you set up to specify a physical or logical device name, file name, and file type for use with a programmed request. When your program opens a file, this information is passed to the monitor which uses the information to locate the referenced device and the file name in the corresponding directory. For example, a device block representing the file FILE.TYP on device DK might be written as: .TITLE EDBLK1.MAC ; 123456 .RAD50 /DK / ;device .RAD50 /FILE / ;name .RAD50 /TYP/ ;type

The first word contains the (device name\ITALIC), the second and third words contain the (file name\ITALIC), and the fourth word contains the (file type\ITALIC). Device, file name, and file type must each be left-justified in the appropriate field. This string could also have been written as: .TITLE EDBLK2.MAC ; 123456789ABC .RAD50 /DK FILE TYP/ ;complete DBLK

Spaces must fill out each field. Also, the colon and period separators must not appear in the string since they are only used by the Command String Interpreter to delimit the various fields.

If the first word of a device block is the name of a mass-storage device such as a disk and the second word of the block is 0, the device block refers to an entire volume of the mass storage device in a non-file-structured manner. (Programmed Request Errors)

Programmed requests use three methods (System Conventionsprogrammed request errors) of reporting errors detected by the monitor: (UNNUMBERED) Setting the carry bit of the processor status word (PSW) Reporting the error code in byte 52 of the system communications area Generating a monitor error message

If a programmed request has been executed unsuccessfully, the monitor returns to your program with the carry bit set. The carry bit is returned clear after the normal termination of a programmed request. Almost all requests should be followed by a Branch Carry Set (BCS) or Branch Carry Clear (BCC) instruction to detect a possible error.

Because some programmed requests have several error codes, byte 52 in the system communications area is used to receive the error code. Therefore, when the carry bit is set, check byte 52 to identify the kind of error that occurred in the programmed request. The meanings of values in the error byte are described individually for each request. The error byte is always zero when the carry bit is clear. Your program should reference byte 52 with absolute addressing. Always address location 52 as a byte, (never as a word\italic), because byte 53 has a different use. The following example shows how byte 52 can be tested for the error code: .TITLE ERRBYT.MAC $ERRBY =: 52 ;(.SYCDF) error byte .PRGREQ #AREA,ARG1,...,ARGN BCS ERROR ... ERROR: TSTB @#$ERRBY ... .END

Error messages generated by the monitor are caused by fatal errors, which cause your program to terminate immediately. Some fatal errors can be intercepted and have their values returned in byte 52 (See the .HERR/.SERR programmed requests). (User Service Routine (USR) Requirement)

The USR is always resident in mapped monitors; therefore, the (System Conventionsuser service routine requirements) (USRswapping) (USRbackground job) (USRvalue of location 46) (USRmonitor offset 374) (USRprotecting program areas) following discussion of programmed request requirements for the USR is applicable only to unmapped monitors. Programmed requests that require USR to be in memory require a fresh copy of the USR to be read in because the code to execute them resides in the USR buffer area. Since the buffer area gets overlaid by data used to perform other system functions, the USR must be read in from the system device even if there is a copy of the USR presently in memory. In mapped monitors, USR is always in memory. The SB monitor will verify the swap address is even and within the job. (PREQ_USR) lists programmed requests that require the USR and notes any exceptions to the requirement.

(Programmed Requests Requiring the USR\PREQ_USR) (TAB1-2) (KEEP) (3\20\20) (1\Special directory operations always require the USR. Or, if the channel has been opened with a non-file-structured open, the USR is not required.) (2\If the channel has not been opened on a special directory device, the USR is not required.) (3\Requires a fresh copy of the USR to be read into memory.) (4\If the job FETCHed a handler which specified a (RELEASE=routine\ITALIC) in .DRPTR or any handler currently in memory requested notification of job exit.) (5\Ensures the USR is in memory.) (.CHAIN(4) \.FPROT \.RELEASE) (.CLOSE(1) \.GFDATE(1) \.RENAME(1)) (.CLOSZ(1) \.GFINFO(1) \.SFDATE(1)) (.CSIGEN \.GFSTAT(1) \.SFINFO(1)) (.CSISPC \.GTLIN \.SFSTAT(1)) (.DELETE(1) \.HRESET(4) \.SRESET(4)) (.DSTATUS \.LOCK(5) \.TLOCK(5)) (.ENTER(1) \.LOOKUP(1) \) (.EXIT(4) \.PURGE(1\2) \) (.FETCH \.QSET(3) \)

USR requirements for programmed requests differ among the monitors as shown in the table. The .CLOSE programmed request on non-file-structured devices, such as a line printer or terminal, does not require the USR under any monitor.

Because USR is not reentrant, only one job at a time can use the USR. This is particularly important for concurrent jobs when a magnetic tape device is active. For example, file operations on tape devices require a sequential search of the tape. When you issue a USR file operation from a background program to a magtape, USR locks out the foreground job until the background job is complete. Special function request SF.USR provided in file structured magtape handlers can be used to perform asynchronous directory operations on tape.

In multijob environments, jobs can use the .TLOCK request to check USR availability. If the USR is not available, control returns immediately with the C bit set, indicating that the .LOCK request (that attempts to gain ownership of USR) has failed. In this way a job can perform critical tasks before losing control by being queued up for USR availability.

Any request that requires the USR to be in memory can also require that a portion of your program be saved temporarily in the system device swap file; that is, a portion of your job can be "swapped out" and stored in file SWAP.SYS to provide room for the USR. Then the USR is then read into memory. Although swapping is invisible in normal operation, you must consider it in your programming. For example, the argument block being passed to the USR must not be in the area that is swapped over. You can save time by optimizing your programs so that they require little or no swapping.

Consider the following items if a swap operation is necessary: (UNNUMBERED) (Background Job\BOLD)

If a .SETTOP request in a background job specifies an address beyond the point at which the USR normally resides, a swap is required when the USR is called (not encountered in mapped monitors because the USR is always resident). (Value of Location 46\BOLD)

If you assemble an address into word 46 or move a value there while the program is running, RT-11 uses the contents of that word as an alternate place to swap the USR. If location 46 is zero, the USR will be at its normal location in high memory. If the USR does not require swapping, this value is ignored.

A foreground job must always have a value in location 46 unless it is certain that the USR will never be swapped. If the foreground job does not allow space for the USR and a swap is required, a fatal error will occur. The SET USR NOSWAP command makes the USR permanently resident.

If you specify an alternate address in location 46, the SB monitor will verify the validity of the USR swap address. In previous versions of RT--11 the SJ monitor did not validate the address. (Monitor Offset 374\BOLD)

The contents of monitor offset 374 indicates the size of the USR in bytes.

Programs should use this information to dynamically determine the size of the region needed to swap the USR. (Protecting Program Areas\BOLD)

Make sure the following areas of your program do not get overlaid when you swap in the USR: (UNNUMBERED\--) Program stack Any parameter block for calls to the USR EMT instruction that invoked the USR I/O buffers Device handlers Interrupt service routines Queue elements Defined channels Completion routines in use when USR is called

The (SIM_BOOK) provides additional information on the USR. (Using Programmed Requests\USING_PRS)

This section describes how to implement programmed requests to (Using programmed requests) access the various monitor services. (Initialization and Control)

Typically, you use several programmed (Using programmed requestsinitialization and control) requests to control the operating environment in which your program is running. These requests can include control of: (UNNUMBERED) Memory allocation I/O access Devices Error processing (Memory Allocation)

When loaded, a program occupies the memory specified by its image (Programmed requestsmemory allocation) created at link time. A program's memory requirements are specified to the monitor by the .SETTOP request. To obtain more memory, execute a .SETTOP request with R0 containing the highest address desired. The monitor: (UNNUMBERED) Determines whether the address is valid. Returns the highest address available. Determines whether it is necessary to swap the USR.

Resident handlers or foreground jobs can restrict the amount of memory available to meet the amount requested for the program. The monitor retains the USR in memory, if possible, thereby reducing the amount of swapping. When this is not possible, the monitor will automatically remove the USR from memory and swap part of the user program to swap file (SWAP.SYS) on the system device whenever the USR must be reloaded to process a request. The .SETTOP request determines how much memory is available and controls monitor swapping characteristics. (See the .SETTOP programmed request in (PROG_REQ_CHAPT) for special optional features provided in an extended memory environment. Additional information on the .SETTOP request is also given in the (SIM_BOOK).)

If a program needs so much memory that the USR must swap, swapping will automatically occur whenever a USR call is made, but when a program knows file operations are necessary so it can consolidate and perform these operations individually, system efficiency can be enhanced as follows: (UNNUMBERED) Request the USR to be swapped in. Have it remain resident while a series of consecutive USR operations is performed. Swap the USR out when the sequence of operations is completed.

Three programmed requests control USR swapping. The request .LOCK causes the USR to be made resident for a series of file operations: (UNNUMBERED) Requiring a portion of your program to be written to the swap blocks prior to reading in the USR. Requiring the USR to be read in, if it finds the USR is overwritten.

The request .UNLOCK swaps your program back in if it was swapped out, and the USR is overwritten; otherwise, no swapping occurs. The request .TLOCK makes the USR resident in multijob monitors only if the USR is not currently servicing another job's file requests at the time the .TLOCK request is issued. This check prevents a job from becoming blocked while the USR is processing another job's request. When a .TLOCK succeeds, the USR is ready to perform an operation immediately. In a single-job environment, the .TLOCK request performs exactly like the .LOCK request.

RT-11 provides 16(10) channels as part of the job's impure area; that is, 16 files can be allocated at one time. Up to 255(10) channels can be allocated with the .CDFN request. This request sets aside memory inside the job area to provide the storage required for the status information on the additional channels. Once the .CDFN request has been executed, as many channels as specified can be active simultaneously. Use the .CDFN request during the initialization phase of your program. The keyboard monitor command CLOSE does not work if you define new channels with the .CDFN programmed request.

The .CNTXSW request lets the job add memory locations to the list of items to be context-switched. The request itself does not cause a context switch to occur. (Input/Output Access)

Each pending I/O, message, or timer request must be placed into one of the (Programmed requestsinput/output access) monitor queues. These are then processed by the monitor on a first-in first-out basis, by job priority, or by time of expiration. In RT-11, all I/O transfers are queued to allow asynchronous processing of the request. A queue is a list of elements, each element being seven words long in unmapped monitors, and ten decimal words long when using mapped monitors. When your program issues a data transfer programmed request, the information specifying the transfer is stored by the monitor in a queue element. This information is passed to the device handler, which then processes the I/O transfer.

Each job, whether background or foreground, initially has only a single queue element available. Additional queue elements may be set aside with a .QSET request. The .QSET request declares where in memory the additional queue elements will go and how many elements there will be. If you do not include a .QSET request in your program, the monitor uses the queue element set aside in the job's impure area. In this case, since only one element is available for each job, all operations would be synchronous. That is, any request issued when the available queue element list is empty has to wait for that element to become free. The number of queue elements necessary equals the number of asynchronous operations pending at any time. (Devices)

The .DEVICE request turns off any special devices that are being used by (Programmed requestsdevices) the running program upon program termination. This request lets you specify a set of device control register addresses and a value to be set in each register on job exit. When a job is terminated -- either normally, by an error condition, or by a CTRL/C -- the specified values are set in the specified locations.

(Don Bridgeman) Loading a background job with a GET, R, or RUN command, or loading a foreground or system job with a FRUN and SRUN command, respectively, alters most locations in the vector area 0 to 476. Virtual jobs do not load over the vector area. RT-11 automatically prevents alteration of locations used by the system, such as the clock, the console terminal, and all vectors used by handlers that are loaded. If a foreground job in a foreground/background environment accesses a device directly through an in-line interrupt service routine, the foreground job must notify the monitor that it must have exclusive use of the vectors. Using the .PROTECT programmed request lets the foreground job gain exclusive use of a vector. The .PROTECT request can also be used by either the foreground or background job, prior to setting the contents of a vector, to test whether the vectors are already controlled by a job. This serves as further protection against jobs interfering with each other. An .UNPROTECT programmed request relinquishes control of a vector, making the vector available to both the background and foreground jobs.

Special function requests (See listing in (DEV_BOOK)) are used for performing special functions on devices such as magnetic tape. .SPFUN requests are used for such functions as rewind or space-forward operations. (Error Processing)

During the course of program execution, errors can occur that cause the (Programmed requestserror processing) monitor to stop the program and print a (MON-F\ITALIC) error message, such as directory I/O errors, monitor I/O errors on the system device, or I/O requests to nonexistent devices. Some programs cannot let the monitor abort the job because of these errors. For example, in the case of RT-11 multi-user DIBOL, a directory I/O error affecting only one of the users should not cause the whole program to abort. For such applications, a pair of requests is provided -- .HERR and .SERR: (UNNUMBERED) .HERR request (normal default) indicates that the monitor will handle severe errors and stop the job. .SERR request causes the monitor to return most errors to your program for appropriate action, setting an error code in byte 52.

In addition to processing I/O errors through .HERR and .SERR requests, you can also use the .TRPSET or .SFPA requests to handle certain fatal errors. Use these requests to prevent your program from aborting due to a trap to location 4 or 10(8) or to the exception traps of the Floating Point Processor (FPP) or Floating Point Instruction Set (FIS). A .TRPSET request specifies the address of a routine that the monitor enters when a trap to location 4 or 10 occurs. A .SFPA request specifies the address of a floating-point exception routine called whenever an exception trap occurs. (Examining System Information and Reporting Status)

Several programmed requests interrogate the system for specific details (System informationexamining and reporting status) about a device or file that your program may be using: (#)

(MULTIPAGE) (2\12) (Request\#############Description) (##.CSTAT\Status information on a file: starting block, length, device location) (##.DATE\ Obtains the system date, which then can be printed on a report or entered as a data record in a file.) (##.DSTAT\Status information on a device: block length, controller-assignment number) (##.GTIM\Obtains the time-of-day and is used in the same way as .DATE.) (##.GTJB\Obtains job information: (UNNUMBERED) Foreground or background information Memory limits Virtual high limit for a job created with the linker /V option (mapped monitors only) Unit number of the job's console terminal (if you are using the multiterminal feature) Address of the job's channel area Address of the job's impure area Logical job name (if you are using a monitor with the system job feature) ) ((STACKED\BRACES) .MTGET .MTSTAT \Multiterminal status information when using multiterminal feature) ((STACKED\BRACES) .MFPS .MTPS \Read the priority bits and set the priority and T-bits in the processor status word (PS); let a program run without change on all processors, including those that support 177776 as PS.) (##.SDTTM\Sets the system date and/or time. Changing the date or time has no effect on any outstanding mark time or timed wait requests.) (Command Interpretation)

Two of the most useful programmed (Programmed requestscommand interpretation) requests are .CSIGEN and .CSISPC. These requests call the Command String Interpreter (CSI), which is part of the USR. They are used to process standard RT-11 command strings:

Form: (indent\1\smallskip)(*Dev:Output[,size]/Option=Dev:Input/Option)

The monitor prints the asterisk on the terminal. The RT-11 system programs use the same command string. See the (SUM_BOOK) for more detailed information.

The .CSIGEN request analyzes the string for correct syntax, automatically loads the required device handlers into memory, opens the files specified in the command, and returns to your program with option information. So, with one request, a language processor such as the FORTRAN compiler is ready to input from the source files and output the listing and binary files. You can specify options in the command string to control the operation of the language processor. The .CSIGEN request uses channels 0 through 2 to accommodate three output file specifications and channels 3 through 10(8) to accommodate six input file specifications. (DON BRIDGEMAN SAYS IT'S RIGHT AS IS)

The .CSISPC request gets you the services of the command processor, but lets you do your own device file manipulation. When you use .CSISPC, the CSI: (NUMBERED) Obtains a command string Analyzes it syntactically Places the results in a table Passes the table to your program for appropriate action

The .GTLIN request obtains one line of input at a time instead of one character at a time. These three requests support the indirect file function and let your program obtain one line at a time from an indirect file. Therefore, if your program were started through an indirect file, the line would be taken from the indirect file and not from the terminal. The .GTLIN request has an optional argument which forces input to come from the terminal, a useful feature if your program requires information only available from the terminal. (File Operations)

A device handler is the normal RT-11 interface (File operationsfile handlers) (File operationsSee also .FETCH, .LOAD) (File operations.SAVESTATUS) (File operations.REOPEN) between the monitor and the peripheral device on which file operations are performed. The console terminal handlers and the interjob message handlers are part of the resident monitor and require no attention on your part. All other device handlers are loaded into memory with either a .FETCH request from the program or a LOAD command from the keyboard, before any other request can access that device. (See Input/Output Operations section that describes the use of programmed requests for performing I/O operations. The (SIM_BOOK) describes how to write device handlers for RT-11.

Once the handler is in memory, a .LOOKUP request can locate existing files and open them for access. New files are created with an .ENTER request. Space for the file can be defined and allocated as: (UNNUMBERED) One-half the size of the largest unused space or all of the second largest space, whichever is larger (the default) A space of a specific size As much space as possible

The parameter you specify as the file size argument of the .ENTER request or as specified in a .CSIGEN command string affects the way the system allocates space.

When file operations are completed, issuing a .CLOSE request makes the new file permanent in the directory. Issuing a .CLOSZ request accomplishes the same thing, but it lets you specify the file length. A .PURGE request can free the channel without making the file permanent in the directory. Existing permanent files can be renamed with a .RENAME request or deleted with a .DELETE request.

Two other requests, .SAVESTATUS and .REOPEN, add to the flexibility of file operations: (UNNUMBERED) .SAVESTATUS stores the current status of a file that has been opened with a .LOOKUP request and makes the file temporarily inactive, thus freeing the channel for use by another file. .REOPEN causes the inactive file to be reactivated on the specified channel, and I/O continues on that channel. (You can open more files than there are channels.)

If you also lock the USR in memory, you can open all the files your program needs, while maintaining system swapping efficiency, by: (UNNUMBERED) Locking the USR in memory, and opening the files that are needed. Issuing the .SAVESTATUS request. Releasing the USR. Issuing a .REOPEN request each time a file is needed. Locking USR, and using the .CLOSE request to make the files permanent.

Because a .REOPEN request does not require any I/O, all USR swapping and directory motion can be isolated in the initialization code for an application, thereby improving program efficiency.

The following requests are useful for obtaining or modifying file information: (UNNUMBERED) .GFDAT provides file's creation date for file's directory entry. .GFINF provides word content of directory offset specified from file's directory entry. .GFSTA provides file status information from the file's directory entry. .SFDAT lets you change the date that appears in a file's directory entry listing. You may want to do this for a file that you update in place, for example, or if the original creation date was in error. .SFINF lets you change the contents of the directory entry offset specified in file's directory entry. .SFSTA lets you change the status information in a file's directory entry. .FPROT protects a file against deletion or removes protection so that a file can be deleted by a .DELETE, .ENTER or .RENAME request. The contents of a protected file are not protected against modification. (Input/Output Operations\IO_OPNS)

You can perform I/O in three different modes that optimize the overlap of CPU and I/O processing: (File operationsinput/output) (Input/output operationssynchronous I/O) (Input/output operationsasynchronous I/O) (Input/output operationsevent-driven I/O) (UNNUMBERED) Synchronous I/O Asynchronous I/O Event-driven I/O (Synchronous I/O)

The programmed requests .READW and .WRITW perform (synchronous\ITALIC) I/O; that is, the instruction following the request is not executed until the I/O transfer is completely finished; in this way the program and the I/O process are synchronized. (Asynchronous I/O)

The program requests .READ, .WRITE, and .WAIT perform (asynchronous\ITALIC) I/O; that is, the .READ or .WRITE request adds the transfer request to the queue for the device: (UNNUMBERED) If the device is inactive, the request is placed at the beginning of the queue; the transfer begins; control returns to the user program before the transfer is completed. If the device is active, the request is queued; control returns to user before transfer is complete.

The .WAIT programmed request, however, blocks the program until the transfer is completed, enabling the I/O operation to be completed before any further processing is done. Asynchronous I/O is most commonly used for double buffering. (Event-Driven I/O)

Program requests, such as .READC and .WRITC, perform (event-driven\ITALIC) I/O; that is, they initiate a completion routine when the transfer is finished. Event-driven I/O is practical for conditions where system throughput is important, where jobs are divided into overlapping processes, or where processing timings are random. The last condition is the most attractive case for using event-driven I/O because processor timing may range up to infinity in a process that is never completed.

Because completion routines are essential to event-driven I/O, the next section presents general guidelines for writing completion routines. (Completion Routines)

Completion routines are part of your program that execute following the (Input/output operationscompletion routines) completion of some external operation, interrupting the normal program flow. On entry to an I/O completion routine, R0 contains the contents of the Channel Status Word and R1 contains the channel number for the operation. The carry bit is not significant.

Completion routines are serialized (within a job's context, not between jobs) and run at priority 0. Completion routines do not interrupt one another but are queued; the next completion routine is not entered until the first is completed.

If the foreground job is running and a foreground I/O transfer completes and wants a completion routine, that routine is entered immediately if the foreground job is not already executing a completion routine. If it is executing a completion routine, that routine continues to termination, at which point other completion routines are entered in a first-in first-out order. If the background job is running (even in a completion routine) and a foreground I/O transfer completes with a specified completion routine, execution of the background job is suspended and the foreground routine is entered immediately.

Also, it is possible to request a completion routine from an in-line interrupt service routine through a .SYNCH programmed request. This enables the interrupt service routine to issue other programmed requests to the monitor.

You must observe the following restrictions when writing completion routines: (UNNUMBERED) Completion routines should never reside in memory space that is used for the USR, since the USR can be interrupted when I/O terminates and the completion routine is entered. If the USR has overlaid the routine, control passes to a random place in the USR, with a HALT or error trap being the likely result. Registers other than R0 and R1 must be saved upon entry to completion routines and restored upon exiting. Registers cannot transfer data between the mainline program and the completion routine. Under mapped monitors, completion routines must remain mapped while the request is active and the routine can be called. The completion routine must exit with an RETURN instruction because the routine was called from the monitor with a CALL ADDR, where ADDR is the user-supplied entry point address. If you exit completion routines with an .EXIT request, your job will abort.

However, if you generate the special .SPCPS support, you can exit from a completion routine by using an .SPCPS request to change the main line PC so it points to .EXIT in the main program. When all completion routines are done, the .EXIT will be executed.

With the exception of the .SYNCH request, completion routines are normally run in User mapping in the mapped monitor context.

Frequently, a program's completion routine needs to change the flow of control of the mainline code. For example, you may wish to establish a schedule among the various tasks of an application program after a certain time has elapsed or after an I/O operation is complete. Such an application needs to redirect the mainline code to a scheduling subroutine when the application's timer or read/write completion routine runs. An .SPCPS programmed request saves the mainline code program counter and processor status word, and changes the mainline code program counter to a new value. If the mainline code is performing a monitor request, that request finishes before derailing can occur. (Terminal Input/Output)

Several programmed requests are available to provide an I/O capability with the terminal: (Input/output operationsterminal input/output) (UNNUMBERED) .TTYIN request obtains a character from the console .TTYOUT request prints a character at the terminal

Programs can issue .TTINR and .TTOUTR requests, which indicate that a character is not available or that the output buffer is full. The program can then resume operation and try again at a later time.

The .PRINT request prints multiple characters and can print multiple lines.

A .RCTRLO request forces the terminal output to be reactivated after a CTRL/O has been typed to suppress it, so that urgent messages will be printed. (Multiterminal Requests) (CHARLIE'S BOOK HAS INFO; CHARLIE WILL PROVIDE.)

The RT-11 multiterminal feature enables your program to perform (Input/output operationsmultiterminal requests) input/output on up to 17 terminals. There are several programmed requests you can use to perform I/O on these terminals. Before issuing any of these programmed requests to a terminal, you must issue the .MTATCH request, which reserves the specified terminal for exclusive use by your program. The terminal cannot then be used by any other job until you issue the .MTDTCH request to detach the terminal.

Multiterminal requests .MTPRNT and .MTRCT0 have the same functionality as .PRINT and .RCTRLO, except that .MTPRNT specifies which terminal to print on. Unlike TTYIN and TTYOUT, the .MTIN request can transfer one or more characters to the program; .MTOUT can print one or more characters at the terminal.

By setting terminal and line characteristics with the .MTSET request, you provide a four-word status block that contains the terminal status word, the character of the terminal requiring fillers and the number of fillers required for this character, the width of the carriage (80 characters by default), and system terminal status. The status of a terminal can be obtained by issuing the .MTGET request.

The .MTSTAT program provides information about the entire multiterminal system, not about an individual terminal in the system. (Foreground/Background Communications)

Communication between (Communicationsforeground/background) (CommunicationsSee also .SDAT and .RCVD) foreground and background jobs is accomplished through programmed requests .SDAT and .RCVD. These requests also have three modes (synchronous, asynchronous, and event-driven) that enable buffer transfer between the two jobs as if I/O were being done. The sending job treats a .SDAT request as a write, and the receiving job treats .RCVD as a read. In the case of .RCVD requests, the receiving buffer must be one word longer than the number of words expected. When the data transfer is completed, the first word of the buffer contains the number of words actually sent.

Jobs receiving messages can be activated when messages are sent through .RCVDC completion routines, while the sending jobs use .SDATC completion routines. The .MWAIT request is used for synchronizing message requests. It is similar to the .WAIT request that is used for normal I/O.

If you want one job to read or write data in a file opened by another active job, use the .CHCOPY request. For example, when the background job is processing data that is being collected by the foreground job, the .CHCOPY request enables you to copy channel information from the foreground job and to use the channel information to control a read or write request.

The multijob monitors always cause a context switch of critical items such as machine registers, the job status area, and floating-point processor registers (only swapped or context switched if the job is using .SFPA), when a different job is scheduled to run because it has a higher priority, or because the current job is blocked and a lower priority job is runnable. When the monitor saves a job's context, it saves the job-dependent information on the job's stack so that this information can be restored when the job is runnable again. (Timer Support)

Monitor timer support is provided through (Timer supportselecting) (Timer supportSee also .MRKT) the .MRKT request. The SB monitor, as distributed, does not have timer support, but can be selected during SYSGEN. Use the .MRKT request to specify the address of a routine that will be entered after a specified number of clock ticks. Like I/O completion routines, .MRKT routines are asynchronous and independent of the main program. After the specified time elapses, the main program is interrupted, the timer completion routine executes, and control returns to the interrupted program.

Pending .MRKT requests contained within the queue are identified by number. Pending timer requests can be canceled with a .CMKT request. .MRKT requests schedule by timer completion routines.

The programmed requests .MRKT/.CMKT and .TIMIO/.CTIMIO require request identification words as an argument. Certain ranges of values are reserved for different uses as shown in the following table.

(Values Used with .MRKT/.CMKT, .TIMIO/.CTIMIO\MRKT_TBL) (TAB1-3) (KEEP) (2\15) (1\To ensure a unique value for each handler, DIGITAL suggests that the value be assigned as 177000+devcod, where (devcod\ITALIC) represents the device identifier value used in the .DRDEF macro at the beginning of the handler.) (Range\Use) (Use GOLD T For table rows) (1-176777\For user applications with a .MRKT/.CMKT. Values in this range are canceled if a .CMKT request is issued with a value of 0.) (177000-177377\For use in device handler .TIMIO/.CTIMIO requests.(1)) (177400-177477\Reserved for multiterminal support.) (177500-177677\Reserved.) (177700\Used by the .TWAIT request.) (177701-177766\Reserved.) (177767-177777\DECnet.)

Values in range 177700 to 177777 are automatically canceled whenever a program terminates or aborts; however, values in the range 177000 to 177677 must be canceled individually by the routine that issued the .TIMIO request. This would occur, for example, in handler abort code.

Use the .TWAIT request to suspend a job for a specified time interval. For example, the .TWAIT request will let a compute-bound job relinquish CPU time to the rest of the system, so other jobs can be run. (Program Termination or Suspension\PTS)

Many jobs come to an execution (Program terminationsuspension) (Program terminationjob reset) (Program terminationSee also .SRESET, .HRESET) point when there is no further processing necessary until an external event occurs. In the multijob environment such a job can issue a .SPND request to (suspend\ITALIC) the execution of that job. While the foreground job is suspended, the background job runs. When the desired external event occurs, it is detected by a previously requested completion routine, which executes a .RSUM request to (resume\ITALIC) the job at the point it was suspended.

When a job is ready to terminate or reaches a serious error condition, it can reset the job environment with the .SRESET and .HRESET requests: (UNNUMBERED) .SRESET is a soft reset; that is, it reinitializes the monitor data base for the job, but allows queued I/O to run to completion. .HRESET is a hard reset; it stops all I/O for the job by calls to the handlers. .HRESET performs the same functions as .SRESET and resets queued I/O.

Using the programmed request .EXIT in a background job terminates the program and returns control to the keyboard monitor: (UNNUMBERED) If R0 contains a zero upon execution of this request, this causes hard reset that disables the commands REENTER, CLOSE, and START. If R0 contains a nonzero value upon exit from your program, this causes a soft reset, and commands REENTER, CLOSE, and START are not disabled.

In a foreground job, an .EXIT programmed request stops the job, and may return control to the keyboard monitor. You can remove the job from memory by issuing the UNLOAD command.

You may initiate the execution of another program with a .CHAIN request from a background job. Files remain open across a .CHAIN request and data is passed in memory to the chained job, so that it can continue processing. In FORTRAN, channel information is stored in the job's impure area, and this information is not preserved across a .CHAIN request. Therefore, close any channels in the first program, and reopen them in the program being chained to. (Job Communications)

System job support enables (Job communicationssending, receiving) (Job communicationsSee also .RCVD, .MWAIT, .SDAT) communications between any two jobs in the system by using a special .LOOKUP, .READx, and .WRITx requests. The background job, can send and receive messages between each other by using the .RCVD, .MWAIT and .SDAT programmed requests. (Mapped and Unmapped Regions)

In multijob environments, communication between jobs is (Regionsmapped) (Regionsunmapped) accomplished by the Message Handler (MQ) which performs like an ordinary RT-11 device handler in accepting and dispatching I/O requests from the queued I/O system. .READ and .WRITE requests are able to send messages between any two jobs as if they were data transfers to files. Both the sending and receiving job must issue a .LOOKUP request on a channel and use 'MQ' as the device specification and the logical job name of the job with which they are communicating as the file specification. In the case of .READ requests, the receiving buffer must be one word longer than the number of words expected. When the data transfer is completed, the first word of the buffer contains the number of words actually sent (identical to the .RCVD requests). This does not apply to the .WRITE requests; the first word of the sending buffer is the first word of the message to be sent.

When assigning logical job names to system jobs, programmed requests such as .LOOKUP, .CHCOPY, and .GTJB must use the job's current logical job name (See the (SUG_BOOK)). (Extended Memory Functions)

The RT-11 mapped monitors enable MACRO programs to (Programmed requestsextended memory functions) (Programmed requeststypes ) (Functionsextended memory functions) (Functionslist) (Request typeswindow) (Request typesregion) (Request typesmap) (Request typesstatus) (Request typesgeneral mapping control) (Request types.CRAW, .CRRG) (Request types.ELAW, .ELRG) (Request types.MAP, .UNMAP) (Request types.CMAP, .GCMAP) access extended memory by mapping their virtual addresses to physical locations in memory. This is done in conjunction with Memory Management Unit (MMU), a hardware option that converts a 16-bit virtual address to an 18- or 22-bit physical address.

Using the Virtual Run Utility (VBGEXE) enables your programs to run faster and with less low-memory space than your programs would otherwise require. These performance improvements result from running the programs as virtual jobs. If you are running under a mapped monitor, but there is not enough memory for your program to execute, try using VBGEXE. For more information, refer to the (SUM_BOOK), VBGEXE section. See V, VRUN, and SET RUN VBGEXE commands in the RT--11 command monitior.

Use programmed requests to access extended memory in a program. When accessing extended memory, first establish window and region definition blocks, then specify the amount of physical memory the program requires and describe the virtual addresses you plan to use. Do this by creating regions and windows, then associate virtual addresses with physical locations by mapping the windows to the regions. You can remap a window to another region or part of a region or you can eliminate a window or a region. Once the initial data structures are set up, manipulate the mapping of windows to regions that best meet your requirements.

There are five types of extended memory programmed requests: (UNNUMBERED) General mapping control Region requests Window requests Map requests Status requests

Window and region requests have their own data structures. RT-11 macro .WDBBK creates a window definition block and macro .RDBBK creates a region definition block. Both macros automatically define offsets and bit names. Two other macros, .WDBDF and .RDBDF, define only the offsets and bit names.

The programmed request .CRAW is used to create a window. To eliminate a window, use the .ELAW request. A region is created using the .CRRG request. You return a region to the free list of memory with the .ELRG request.

You map a window to a region with the .MAP request. If a window is already mapped to a region, this window is unmapped and the new one is mapped. Use the .UNMAP request to unmap a window. You obtain the mapping status of a window with the .GMCX request.

Mapping context information must be saved when virtual and privileged jobs are swapped out of memory. The .CMAP request defines and saves these mapping structures in the mapping context area (MCA) until the monitor restores them. The .GCMAP request obtains the current memory mapping context.

Several programmed requests are restricted when they are in a mapped monitors environment. These programmed requests and their restrictions are as follows:

(KEEP) (3\3\8) (\(.CDFN)\All channels must be in the lower 28K of memory (but not in the PAR1 region, 20000-37776 octal).) (\(.QSET)\All queue elements must be 10(10) words long and in the lower 28K of memory (but not in the PAR1 region, 20000-37776 octal).) (\(.SETTOP)\Effective only in the virtual address space that is mapped at the time the request is issued, unless the job was linked with the /V option (See the (SUM_BOOK))) (\(.CNTXSW)\Not usable in virtual jobs.)

Detailed information on programmed requests in an extended memory environment is given in the (SIM_BOOK).

The UNIBUS Mapping Register Handler (UB) supports UNIBUS mapping registers on UNIBUS processors. The UB handler provides direct memory access (DMA) support for 22-bit memory addressing during I/O operations. UMR support is appropriate for device handlers that perform I/O operations and are capable of DMA. UMR lets the handler access computer memory beyond the 18-bit 256K-byte boundary during I/O operations. For more information, refer to the (DEV_BOOK). (Interrupt Service Routines)

Some macros in system macro library (SYSMAC.SML) are not (Interrupt service routines) programmed requests, but are used like programmed requests in interrupt service communication to the monitor.

.INTEN, the first macro call in every interrupt routine, causes the system to use the system stack for interrupt service and enables the monitor scheduler to make note of the interrupt. If device service is all the routine does, .INTEN is the only call it has to make.

You must issue the .SYNCH call whenever you need to issue from the interrupt service routine, one or more programmed requests, such as .READ or .WRITE. The .INTEN call switches execution to the system state and, since programmed requests can only be made in the user state, the .SYNCH call handles the switch back to the user state. The code following the .SYNCH call executes as a completion routine. When .SYNCH is finished, the completion routine can execute programmed requests, initiate I/O, and resume the mainline code. The first word after the .SYNCH call is the return address on error, while the second word is the return on success. The (SIM_BOOK) contains a detailed description of interrupt service routines. (Device Handlers)

The system macro library (SYSMAC.SML) contains several macros that (Device handlers) simplify the writing of a device handler. Device handler macros are described in (PROG_REQ_CHAPT). The (DEV_book) also explains the use of these macros in writing a device handler. (Logical Name Translation Bypass)

Some programmed requests let you specify a "logical name translation bypass" (Device lookupbypass) (bypass), a modified form of device lookup. If you specify this form, only physical names of devices will be searched for. For example, if (bypass\ITALIC) is specified and a device DL0 is on the system with the logical name TMP assigned to it, you can find it by specifying DL0, but not TMP. This modified form is an unsupported interface and requires hand-coding of the request blocks, only use it under very limited circumstances.

You can use bypass for nearly all requests that specify a (dblock\ITALIC) or (dev.\ITALIC) The following requests specify a (dblock\ITALIC) support bypass:

(MULTIPAGE) (3\15\15) (.DELETE\.GFINFO\.SFINFO) (.ENTER\.GFSTAT\.SFSTAT) (.GFDATE\.LOOKUP\.RENAME)

Although .FPROT and .SFDAT do not support bypass, you can simulate their functionality by issuing .SFSTAT and .SFINFO. The following code fragment illustrates the coding required for bypass: ; xxxxxx is the request (e.g., LOOKUP) .LIBRARY "SRC:SYSTEM" .MCALL ..xxxxxx ;Request name with 2 dots (..LOOKUP) DOC$UN=1 ;Gen names of undocumented parts ..xxxxxx ... .xxxxxx args ;Request name with 1 dot (.LOOKUP) .=.-2 ;Crush EMT instruction for now BIS #..PHYS,A.DBLK(R0) ;Make dblock addr odd MOV #RETODD,A.URTN(R0) ;Supply bypass flag EMT ...xxxxxx ;Issue EMT (Name with 3 dots (...LOOKUP)) ... RETODD =: .+1 ;(Addr of RETURN)+1 RETURN AREA: .BLKW 5. ;Expanded request block

The following requests that specify a device support bypass are coded in the following manner: ..PHYS =: 1 ;Bypass flag value .DSTATUS #Reply!..PHYS,#dev .FETCH #Addr!..PHYS,#dev .RELEASE See below .FETCH #..PHYS,#dev ;use for .RELEASE

Note that .RELEASE is coded as a special form of .FETCH. (Consistency Checking)

(Consistency checking.ASSUME) (Consistency checking.Ck.Rn) (Consistency checking.CKxx) The .ASSUME macro tests the validity of the condition you specify. If the test result is false, MACRO generates an assembly error and displays an appropriate error message.

The .BR macro notifies you when program instructions that belong together are separated during assembly.

The .CKxx macro generates CK.Rn register checking macros; that is, when you specify a register(s) as an argument to .CKxx, CKxx generates checking macro CK.Rn for that register(s). (Programmed Request Summary)

Many programmed requests operate only in a specific RT-11 environment, such as under a multijob monitor or when using a special feature such as multiterminal operation. (PREREQ_ALLRT) lists the programmed requests that can be used in RT-11 environments, including multiterminal operation. (FB_XM_PRS) lists the additional programmed requests that can be used under the multijob monitors and mapped monitors. The EMT and function code for each request are shown in octal. Although only the first six characters of the programmed request are significant to the Macro assembler, the longer forms are shown to provide a better understanding of the request function. Also, the purpose of each request is briefly described.

Macros used in interrupt service routines and in writing device handlers are listed since they are a part of the system macro library.

(PREREQ_ALLRT) summarizes the programmed requests that work in all RT-11 environments. (Programmed requestsfor all environments)

(Programmed Requests for RT-11 Environments\PREREQ_ALLRT) (TAB1-6) (MULTIPAGE) (4\15\6\6) (Name\EMT\Code\Purpose) (.ABTIO(.ABTIOsummary)\374\13\Aborts I/O in progress on the specified channel) (.ADDR(.ADDRsummary)\--\--\Computes a specified address in a position-independent manner) (.ASSUME(.ASSUMEsummary)\--\--\Tests for a specified condition; if test is false, generates assembly error and prints descriptive message) (.BR(.BRsummary)\--\--\Warns if code which belongs together is separated during assembly) (.CALLK(.CALLsummary)\373\--\Transfers control (and alters mapping) from the current mode to the specified virtual address in Kernel mode) (.CALLS(.CALLSsummary)\--\--\Supports transfer of control to Supervisor mode; works with SHANDL Supervisor handler instructions) (.CDFN(.CDFNsummary)\375\15\Defines additional channels for I/O) (.CHAIN(CHAIN.summary)\374\10\Chains to another program (in background job only)) (.CKxx(.CKxxsummary)\--\--\Generates CK.Rn register checking macros for one or more registers.) (.CLOSE(.CLOSEsummary)\374\6\Closes the specified channel) (.CLOSZ(.CLOSZsummary)\375\45\Closes the channel opened by .ENTER; sets file size.) (.CMKT(.CMKTsummary)\375\23\Cancels an unexpired mark time request (Timer support).) (.CSIGEN(.CSIGENsummary)\344\--\Calls the Command String Interpreter (CSI) in general mode) (.CSISPC(.CSISPCsummary)\345\--\Calls the Command String Interpreter (CSI) in the special mode) (.CSTAT(.CSTATsummary)\375\27\Returns the status of the specified channel) (.CTIMIO(.CTIMIOsummary)\--\--\Used within a device handler as a macro call to cancel a mark time request (device timeout support)) (.DATE(.DATEsummary)\374\12\Moves the current date information into R0) (.DEBUG(.DEBUGsummary)\--\--\ Sets up .DPRINT environment.) (.DELETE(.DELETEsummary)\375\0\Deletes the file from the specified device) (.DEVICE(.DEVICEsummary)\375\14\Enables device interrupts to be disabled upon program termination) (.DPRINT\351\--\Inserts run-time messages in programs) (.DRAST(.DRASTsummary)\--\--\Used with device handlers to create the asynchronous entry points to the handler) (.DRBEG(.DRBEGsummary)\--\--\Used with device handlers to create a header and additional information in .ASECT locations) (.DRBOT(.DRBOTsummary)\--\--\Used with system device handlers to set up the primary driver) (.DRDEF(.DRDEFsummary)\--\--\Used with device handlers to set up handler parameters, call driver macros from the library, and define useful symbols) (.DREND(.DRENDsummary)\--\--\Used with device handlers to generate the table of pointers into the resident monitor) (.DREST(.DRESTsummary)\--\--\Places device-specific information in block 0 of device handler) (.DRFIN(.DRFINsummary)\--\--\Used with device handlers to generate the code required to exit to the completion code in the resident monitor) (.DRINS(.DRINSsummary)\--\--\Sets up installation code area in block 0 of a device handler, and defines system and data device installation entry points) (.DRPTR(.DRPTRsummary)\--\--\Places pointers in block 0 of device handler; pointers refer to service routines at address in that handler) (.DRSET(.DRSETsummary)\--\--\Used with device handlers to create the list of SET options for a device) (.DRSPF(.DRSPFsummary)\--\--\Defines special function codes supported by handler) (.DRTAB(.DRTABsummary)\--\--\Establishes file address of list of Digital-defined handler data tables) (.DRUSE(.DRUSEsummary)\--\--\Establishes file address of user-defined handler data tables) (.DRVTB(.DRVTBsummary)\--\--\Used with multivector device handlers to generate a table that contains the vector location, interrupt entry point, and processor status word for each device vector) (.DSTAT(.DSTATsummary)\342\--\Returns the status of a specified device) (.ENTER(.ENTERsummary)\375\2\Creates a new file for output) (.EXIT(.EXITsummary)\350\--\Exits the user program and optionally passes a command to KMON) (.FETCH(.FETCHsummary)\343\--\Loads a device handler into memory) (.FORK(.FORKsummary)\--\--\Generates a subroutine call in an interrupt service routine that permits long but not critical processing to be postponed until all other interrupts are dismissed) (.FPROT(.FPROTsummary)\375\43\Sets or removes a file's protection) (.GFDAT(.GFDATsummary)\375\44\Returns in R0 the creation date from a file's directory entry) (.GFINF(.GFINFsummary)\375\44\Returns in R0 the word contents of the directory entry offset specified in file's directory entry) (.GFSTA(.GFSTAsummary)\375\44\Returns in R0 the status information from a file's directory entry) (.GTIM(.GTIMsummary)\375\21\Gets the time of day) (.GTJB(.GTJBsummary)\375\20\Gets parameters of a job) (.GTLIN(.GTLINsummary)\345\--\Accepts an input line from either an indirect file or the console terminal) (.GVAL(.GVALsummary)\375\34\Returns contents of a monitor fixed offset) (.HERR(.HERRsummary)\374\5\Specifies termination of a job on fatal errors) (.HRESET(.HRESETsummary)\357\--\Terminates I/O transfers and does a .SRESET operation) (.INTEN(.INTENsummary)\--\--\Generates a subroutine call to notify the monitor that an interrupt has occurred, requests system state, and sets processor priority to the specified value) (.LOCK(.LOCKsummary)\346\--\Makes the monitor User Service Routine (USR) permanently resident until an .EXIT or .UNLOCK is executed; the user program is swapped out, if necessary) (.LOOKUP(.LOOKUPsummary)\375\1\Opens an existing file for input and/or output via the specified channel; opens a message channel to a specified job) (.MACS(.MACSsummary)\--\--\Selects EMT expansions compatible with most current version (only if you've previously specified ..V1 or ..V2)) (.MFPS(.MFPSsummary)\--\--\Reads the priority bits in the processor status word, but does not read the condition codes) (.MRKT(.MRKTsummary)\375\22\Marks time; sets an asynchronous routine to be entered after specified interval) (.MTATCH(.MTATCHsummary)\375\37\Attaches a terminal for exclusive use by the requesting job) (.MTDTCH(.MTDTCHsummary)\375\37\Detaches a terminal from one job and frees it for use by other jobs) (.MTGET(.MTGETsummary)\375\37\Returns the status of a specified terminal to the user) (.MTIN(.MTINsummary)\375\37\Operates as a .TTYIN request for a multiterminal configuration) (.MTOUT(.MTOUTsummary)\375\37\Operates as a .TTYOUT request for a multiterminal configuration) (.MTPRNT(.MTPRNTsummary)\375\37\Operates as a .PRINT request for a multiterminal configuration) (.MTPS(.MTPSsummary)\--\--\Sets the priority bits, condition codes, and T-bit in the processor status word) (.MTRCTO(.MTRCTOsummary)\375\37\ Operates as a .RCTRLO request for a multiterminal configuration) (.MTSET(.MTSETsummary)\375\37\Modifies terminal status in a multiterminal configuration) (.MTSTAT(.MTSTATsummary)\375\37\Provides multiterminal system status.) (.PEEK(.PEEKsummary)\375\34\Examines memory locations) (.POKE(.POKEsummary)\375\34\Changes memory locations) (.PRINT(.PRINTsummary)\351\--\Outputs an ASCII string terminated by a zero byte or a 200(8) byte) (.PROTECT(.PROTECTsummary)\375\31\Requests that specified vectors in the area from 0 to 476(8) be given exclusively to the current job) (.PURGE(.PURGEsummary)\374\3\Clears out a channel for reuse) (.PVAL(.PVALsummary)\375\34\Replaces contents of a monitor fixed offset) (.QELDF(.QELDFsummary)\\\Used with device handlers to define offsets in the I/O queue element) (.QSET(.QSETsummary)\353\--\Increases the size of the monitor I/O queue) (.RCTRLO(.RCTRLOsummary)\355\--\Enables output to the terminal; overrides any previous CTRL/O) ((stacked\braces) .READ(.READsummary) .READC(.READCsummary) .READW(.READWsummary) \375\10\ Transfers data on the specified channel to a memory buffer and returns control to the user program: (UNNUMBERED) For .READ, when the transfer request is entered in the I/O queue; no special action is taken upon completion of I/O For .READC, when the transfer request is entered in the I/O queue; upon completion of the read, control transfers asynchronously to the completion routine specified in the .READC request For .READW, when the transfer is complete ) (.RELEASE(.RELEASEsummary)\343\--\Removes a device handler from memory) (.RENAME(.RENAMEsummary)\375\4\Changes the name of the indicated file to a new name; an invalid operation for magtape) (.REOPEN(.REOPENsummary)\375\6\Restores the parameters stored via a .SAVESTATUS request and reopens the channel for I/O) (.RSUM(.RSUMsummary)\374\2\Causes the mainline code of the job to be resumed after it was suspended by a .SPND request) (.SAVESTATUS(.SAVESTATUSsummary)\375\5\Saves the status parameters of an open file in user memory and frees the channel for use) (.SCCA(.SCCAsummary)\375\35\Enables intercept of CTRL/C commands) (.SDTTM(.SDTTMsummary)\375\40\Sets the system date and/or time) (.SERR(.SERRsummary)\374\4\Inhibits most fatal errors from aborting the current job) (.SETTOP(.SETTOPsummary)\354\--\Specifies the highest memory location to be used by the user program) (.SFDAT(.SFDATsummary)\375\42\Changes a file creation date in a directory entry) (.SFINF(.SFINFsummary)\375\44\Returns in R0 the word contents of the directory entry offset specified in file's directory entry) (.SFPA(.SFPAsummary)\375\30\Sets user interrupt for floating-point processor exceptions) (.SFSTA(.SFSTAsummary)\375\44\Returns in R0 the status information from a file's directory entry) (SOB(SOBsummary)\--\--\Simulates the SOB instruction) (.SPCPS(.SPCPSsummary)\375\41\Used in a completion routine to change the flow of control of the mainline code (special feature)) (.SPFUN(.SPFUNsummary)\375\32\Performs special functions on magtape, cassette, diskette, and some disk devices) (.SPND(.SPNDsummary)\374\1\Causes the running job to be suspended) (.SRESET(.SRESETsummary)\352\--\Resets all channels and releases the device handlers from memory) (.SYNCH(.SYNCHsummary)\--\--\Generates a subroutine call that enables your program to perform programmed requests from within an interrupt service routine) (.TIMIO(.TIMIOsummary)\--\--\Generates a subroutine call in a handler to schedule a mark time request (timeout support)) (.TLOCK(.TLOCKsummary)\374\7\Indicates if the USR is currently used by another job and performs exactly as a .LOCK request) (.TRPSET(.TRPSETsummary)\375\3\Sets a user intercept for traps to monitor to vectors 4 and 10(8)) (.TTINR(.TTINRsummary)/.TTYIN(.TTYINsummary)\340\--\Reads one character from the keyboard buffer) (.TTYOUT(.TTYOUTsummary)/.TTOUTR(.TTOUTRsummary)\341\--\Transfers one character to the terminal input buffer) (.TWAIT(.TWAITsummary)\375\24\Suspends the running job for a specified amount of time) (.UNLOCK(.UNLOCKsummary)\347\--\Releases the USR after execution of a .LOCK and swaps in the user program, if required) (.UNPROTECT(.UNPROTECTsummary)\375\31\Cancels the .PROTECT vector protection request) (..V1..(..V1..summary)\--\--\Provides compatibility with Version 1 format) (..V2..(..V2..summary)\--\--\Provides compatibility with Version 2 format) (.WAIT(.WAITsummary)\374\0\Waits for completion of all I/O on a specified channel) ((stacked\braces) .WRITC(.WRITCsummary) .WRITE(.WRITEsummary) .WRITW(.WRITWsummary) \375\11\ Transfers data on the specified channel to a device and returns control to the user program: (UNNUMBERED) For .WRITC, when the transfer request is entered in the I/O queue; upon completion of the read, control transfers asynchronously to the completion routine specified in the .WRITC request For .WRITE, when the transfer request is entered in the I/O queue; no special action is taken upon completion of I/O For .WRITW, when the transfer is complete )

(FB_XM_PRS) lists program requests that can be used only in a multijob and mapped environment. (Programmed requestsmultijob environments) (Programmed requestsmapped environments)

(Multijob or Mapped Program Requests\FB_XM_PRS) (from PRM TAB1-7) (MULTIPAGE) (4\12\6\6) (1\Single-mapped) (2\Fully-mapped) (3\Multijob) (Name\EMT\Code\Purpose) (.CHCOPY(3)(.CHCOPYsummary)\375\13\Enables one job to access another job's channel) (.CMAP(2)(.CMAPsummary)\375\46\Controls separate I/D space, Supervisor mapping) (.CNTXSW(3)(.CNTXSWsummary)\375\33\Requests that the indicated memory locations be part of the context switch process) (.CRAW (1)(.CRAWsummary)\375\36\Creates a window in virtual memory) (.CRRG (1)(.CRRGsummary)\375\36\Creates a region in extended memory) (.ELAW (1)(.ELAWsummary)\375\36\Eliminates an address window in virtual memory) (.ELRG (1)(.ELRGsummary)\375\36\Eliminates an allocated region in extended memory) (.GCMAP(2)(.GCMAPsummary)\375\46\Returns CMAP status) (.GMCX (1)(.GMCXsummary)\375\36\Returns mapping status of a specified window) (.MAP (1)(.MAPsummary)\375\36\Maps a virtual address window to extended memory) (.MSDS(2)(.MSDSsummary)\375\46\Controls lockstep of User data space and Supervisor data space) (.MWAIT(3)(.MTWAITsummary)\374\11\Waits for messages to be processed) ((stacked\braces) .RCVD(3)(.RCVDsummary) .RCVDC(3)(.RCVDCsummary) .RCVDW(3)(.RCVDWsummary) \375\26\Receives data -- enables a job to read messages or data sent by FG or BG job. The three modes correspond to the .READ, .READC, and .READW requests) (.RDBBK (1)(.RDBBKsummary)\--\--\Reserves space in a program for a region definition block and sets up the region size and region status word) (.RDBDF (1)(.RDBDFsummary)\--\--\Defines the offsets and bit names associated with a region definition block) ((STACKED\BRACES) .SDAT(.SDAT(3)summary) .SDATC(.SDATC(3)summary) .SDATW(.SDATW(3)summary) \375\25\Sends messages or data to the FG or BG job. The three modes correspond to the WRITE, .WRITC, and .WRITW requests) (.UNMAP (1)(.UNMAPsummary)\375\36\Unmaps a virtual address memory window) (.WDBBK (1)(.WDBBKsummary)\--\--\Reserves space in a program for a window definition block and sets up the associated data) (.WDBDF (1)(.WDBDFsummary)\--\--\Defines the offsets and bit names associated with a window definition block)