.bp .pn 76 .cs 5 .mt 5 .mb 6 .pl 66 .ll 65 .po 10 .hm 2 .fm 2 .he CP/M-8000 Programmer's Guide 4.4 Character I/O Functions .ft All Information Presented Here is Proprietary to Digital Research .tc Get I/O Byte Function .ul Get I/O Byte Function .qu .ix get I/O byte function .sp 3 .nf FUNCTION 7: GET I/O BYTE Entry Parameters: Register R5: 07H Returned Values: Register R7: I/O Byte Value .sp 2 .fi .pp 5 The Get I/O Byte Function returns the current value of I/O Byte in register R7. The I/O Byte contains the current assignments for the logical devices CONSOLE, AUXILIARY INPUT, AUXILIARY OUTPUT, and LIST. Note that this function is valid only if the BIOS implements its I/O Byte Function. Refer to the \c .ul CP/M-8000 Operating System System Guide \c .qu for details on implementing the BIOS I/O Byte Function. .ix get I/O byte .bp .tc Set I/O Byte Function .ul Set I/O Byte Function .qu .ix set I/O byte function .sp 3 .nf FUNCTION 8: SET I/O BYTE Entry Parameters: Register R5: 08H Register R7: I/O Byte Value Returned Values: Register R7: 00H .sp 2 .fi .pp The Set I/O Byte Function changes the system I/O Byte value to the value passed in register R7. This function allows programs to modify the current assignments for the logical devices CONSOLE, AUXILIARY INPUT, AUXILIARY OUTPUT, and LIST in the I/O Byte. This function is valid only if the BIOS implements its I/O Byte Function. Refer to the \c .ul CP/M-8000 Operating System System Guide \c .qu for details on implementing the I/O Byte Function. .ix set I/O byte .sp 2 .he CP/M-8000 Programmer's Guide 4.5 System Control Functions .tc 4.5 System/Program Control Functions .sh 4.5 System/Program Control Functions .qs .ix system/program control functions .pp The System and program control functions described in this section warm boot the system, return the operating system version number, call the Basic I/O System (BIOS) functions, and, terminate and load programs. These functions are listed in Table 4-17. .sp 2 .ce .sh Table 4-17. System and Program Control Functions .sp .nf .in 13 Function Function Number .sp System Reset 0 .sp Return Version Number 12 .sp Set/Get User Code 32 .sp Chain to Program 47 .sp Flush Buffers 48 .sp Direct BIOS Call 50 .sp Program Load 59 .ix program control functions .ix system control functions .in 0 .bp .tc 4.5.1 System Reset Function .sh 4.5.1 System Reset Function .qs .ix system reset function .sp 3 .nf FUNCTION 0: SYSTEM RESET Entry Parameters: Register R5: 00H Returned Values: Function Does Not Return to Calling Program .sp 2 .fi .pp The System Reset Function terminates the current program and returns program control to the CCP command level. .ix system reset .bp .tc 4.5.2 Return Version Number Function .sh 4.5.2 Return Version Number Function .qs .ix return version number function .sp 3 .nf FUNCTION 12: RETURN VERSION NUMBER Entry Parameters: Register R5: 0CH Returned Values: Register R7: Version Number .fi .sp 2 .ix version dependent programming .ix version numbers .pp The Return Version Number Function provides information that allows version dependent programming. The one-word value 2022H is the version number returned in register R7 for Release 1.1 of CP/M-8000. Table 4-18 lists the version numbers this function returns for Digital Research operating systems. .sp 2 .ce .sh Table 4-18. Version Numbers .qs .sp .nf Operating System Version Version Number .sp CP/M-8000 1.1 2022H .sp CP/M-80 1.4 0014H .sp CP/M-80 2.2 0022H .sp CP/M-80 3.0 0031H .sp MP/M-80 1.1 0122H .sp MP/M-80 2.0 0130H .sp MP/M-80 2.1 0130H .sp 2 CP/M-86 1.0 1022H .sp CP/M-86 1.1 1022H .sp MP/M-86 2.0 1130H .sp MP/M-86 2.1 1130H .sp 2 Concurrent CP/M-86 1.0 1430H (for the IBM Personal Computer) .sp Concurrent CP/M-86 2.0 1431H .sp .pp .fi Add the hexadecimal value 0200 to any version number when the system implements CP/NET. For example, CP/M-80 Release 2.2 returns the version 0222H when the system implements CP/NET. .ix version number, return .he CP/M-8000 Programmer's Guide 4.5 System Control Functions .bp .tc 4.5.3 Set/Get User Code .sh 4.5.3 Set/Get User Code .qs .ix Set/Get user code .sp 3 .nf FUNCTION 32: SET/GET USER CODE Entry Parameters: Register R5: 20H Register R7: FFH (get) or User Code (set) Returned Values: Register R7: Current User Number .sp 2 .fi .ix user number .pp An application program can change or obtain the currently active user number by calling the Set/Get User Code Function. If the value in register R7 is FFH, the value of the current user number is returned in register R7. The value ranges from 0 to 15 (decimal). If register R7 contains a value in the range 0 through 15 (decimal), the current user number is changed to the value in register R7. When the program terminates and control returns to the CCP, the user number reverts to the BDOS default user number. The BDOS assumes the default is zero unless you explicitly specify the USER command to set an alternate default. .ix get or set user code .bp .tc 4.5.4 Chain To Program Function .sh 4.5.4 Chain To Program Function .qs .ix chain to program function .sp 3 FUNCTION 47: CHAIN TO PROGRAM Entry Parameters: Register R5: 2FH Returned Values: Register R7: Function Does Not Return to Calling Program .sp 2 .fi .pp The Chain to Program Function terminates the current program and executes the command line stored in the current DMA buffer. The format of the command line consists of a one-byte character count (N), the command line characters, and a null byte as shown in Figure 4-4. The character count contains the number of characters in the command line. The count must be no more than 126 characters. If an error occurs, you receive one of the CCP errors described in Appendix E. .sp 3 .nf N Command Line (N characters) 0 1 byte N bytes <\b_ 126 bytes 1 byte .fi .sp 2 .ce .sh Figure 4-4. Command Line Format in the DMA Buffer .bp .tc 4.5.5 Flush Buffers Function .sh 4.5.5 Flush Buffers Function .qs .ix flush buffers function .sp 3 .nf FUNCTION 48: FLUSH BUFFERS Entry Parameters: Register R5: 30H Returned Values: Register R7: Return Code success: 00H error: nonzero value .fi .sp 2 .pp The Flush Buffers Function calls a BIOS Flush Buffers Function (21), which forces the system to write the contents of any unwritten or modified disk buffers to the appropriate disks. Control and editing applications use this function to ensure data is periodically physically written to the appropriate disks. When the buffers are successfully flushed, this function returns the value 00H in register R7. However, if an error occurs, and this function does not complete successfully, this function returns a nonzero value in register R7. .bp .tc 4.5.6 Direct BIOS Call Function .sh 4.5.6 Direct BIOS Call Function .qs .ix direct BIOS call function .ix BIOS return code .ix BIOS parameter block (BPB) .sp 3 .nf FUNCTION 50: DIRECT BIOS CALL Entry Parameters: Register R5: 32H Register RR6: BPB Address Returned Values: Register R7: BIOS Return Code (if any) .sp 2 .fi .pp Function 50 allows a program to call a BIOS function and transfers control through the BDOS to the BIOS. The RR6 register contains the address of the BIOS Parameter Block (BPB), a 5-word memory area containing two BIOS function parameters, P1 and P2, as shown in Figure 4-5. When a BIOS function returns a value, it is returned in register R7. .pp Like other BDOS functions, your program must specify a SC #2 Instruction to invoke this BDOS function after the registers are loaded with the appropriate parameters. The starting location of the BPB must be an even-numbered address. .sp 3 .nf Field Size Function Number 1 word Value P1 1 longword Value P2 1 longword .fi .sp 2 .ce .sh Figure 4-5. BIOS Parameter Block (BPB) .qs .sp 3 In the above figure, the function number is a BIOS function number. See Appendix A. The two values, P1 and P2, are 32-bit BIOS parameters, which are passed in registers RR6 and D2.L before your program invokes the BIOS function. Appendix A contains a list of BIOS functions. For more details on BIOS functions, refer to the \c .ul CP/M-8000 Operating System System Guide. Note that if the parameters are addresses, they are .ul not mapped, so that the caller can specify addresses in any part of memory. .qu .ix direct BIOS call .bp .tc 4.5.7 Program Load Function .sh 4.5.7 Program Load Function .qs .ix program load function .sp 3 FUNCTION 59: PROGRAM LOAD Entry Parameters: Register R5: 3bH Register RR6: LPB Address Returned Values: Register R7: Return Code success: 00H error: 01H - 03H .fi .sp 2 .ix function code .ix load parameter block (LPB) .pp The Program Load function loads an executable command file into memory. In addition to the function code, passed in register R5, the address of the Load Parameter Block (LPB) is passed in register RR6. After a program is loaded, the BDOS returns one of the return codes listed below in register R7. .sp 2 .ce .sh Table 4-19. Program Load Function Return Codes .qs .sp .in 5 .nf Code Meaning .fi .ll 60 .in 14 .ti -8 .sp 00 the function is successful .sp .ti -8 01 insufficient memory exists to load the file or the header is bad .sp .ti -8 02 a read error occurs while the file is loaded in memory .sp .ti -8 03 bad relocation bits exist in the program file .sp .in 0 .ll 65 .fi .pp The LPB describes the program and denotes the address at which it is loaded. The format of the LPB is outlined in Figure 4-6. The starting location of the LPB must be an even-numbered address. .bp .nf Byte Content Size Offset 0H address of FCB of successfully opened program file 1 longword 4H lowest address of area in which to load program 1 longword 8H highest address of area in which to load program +1 1 longword CH address of base page (returned by BDOS) 1 longword 10H default user stack pointer (returned by BDOS) 1 longword 14H loader control flags 1 word .fi .sp 2 .ce .sh Figure 4-6. Format of the Load Parameter Block (LPB) .sp 2 .ix load parameter block (LPB) .pp Before a program specifies the Program Load function, the file must be opened with an Open File Function (15). The memory addresses specified for the program in the LPB must lie within the TPA. When the CCP calls the Program Load function to load a transient program, the LPB addresses are the boundaries of the TPA. .pp The loader control flags in the LPB select loader options as shown in Table 4-20. ========= ACTUALLY, THE LOAD ADDRESSES GET IGNORED =========== ========= IN THE PRESENT VERSION. ALSO, THE LOW =========== ========= AND HIGH ADDRESSES WILL BE CHANGED TO =========== ========= REFLECT THE SEGMENT ACTUALLY USED. =========== .sp 2 .ce .sh Table 4-20. Load Parameter Block Options .sp .ix load parameter block options .nf .in 5 .ll 60 Bit Number Value Meaning .sp .in .ti - 0 (least 0 load program in the lowest significant possible part of the byte) supplied address space .sp 1 load program in the highest possible part of the supplied address space .sp 1 - 15 (decimal) 0 Reserved, should be set to zero. .sp .in 0 .ll 65 .ix CCP .fi .pp The CCP uses the Program Load Function to load a command file. The CCP places the base page address on the program's stack. The base page address is located at the the address pointed to by register R15 (non-segmented) or RR14 (segmented), the stack pointer. The program must return to the CCP by executing the BDOS function 0 (Reset). .ix base page .pp The BDOS allocates memory for the base page within the limits set by the low and high addresses in the LPB and returns the address of the allocated base page in the LPB. Locations 0000H - 0024H of the base page are initialized by the BDOS. Locations 0025H through 0037H are not initialized but are allocated and reserved by the BDOS. The CCP initializes the remaining base page values when it loads a program. .ix initial stack pointer .pp The BDOS allocates a user stack located in the highest address of the TPA. The maximum size of the stack equals the address of the stack pointer minus the last address of the program plus 1. The value of the initial stack pointer is passed to the LPB by the BDOS. .pp For programs loaded by a transient program rather than the CCP, refer to Section 2.2.3. ============= THE FOLLOWING EXAMPLES HAVE TO BE COOKED UP ======== Appendix B contains two examples, an assembly language program and a C language program, that illustrate how a transient program loads another program with the Program Load Function but without the CCP. .ix program load .nx fourg