BDOS FUNCTION 30: SET FILE ATTRIBUTES
By calling the Set File Attributes function, a program can modify a file's attributes and set its last record byte count. Other BDOS functions can be called to interrogate these file parameters, but only Function 30 can change them. The file attributes that can be set or reset by Function 30 are f1' through f4', Read-Only, t1', System, t2', and Archive, t3'. The register pair DE addresses an FCB containing a filename with the appropriate attributes set or reset. The calling program must ensure that it does not specify an ambiguous filename. In addition, if the specified file is password detected, the correct password must be placed in the first eight bytes of the current DMA buffer or have been previously established as the default password (see Function 106). Interface attribute f6' specifies whether the last record byte count of the specified file is to be set:
If interface attribute f6' is set, the calling program must set the cr field of the referenced FCB to the byte count value. A program can access a file's byte count value with the BDOS Open, Search, or Search Next functions. Function 30 searches the referenced directory for entries belonging to the current user number that matches the FCB specified name and type fields. The function then updates the directory to contain the selected indicators, and if interface attribute f6' is set, the specified byte count value. Note that the last record byte count is maintained in byte 13 of a file's directory FCBS. File attributes t1', t2', and t3' are defined by CP/M 3. (They are described in Section 2.3.4.) Attributes f1' through f4' are not presently used, but can be useful for application programs, because they are not involved in the matching program used by the BDOS during Open File and Close File operations. Indicators f5' through f8' are reserved for use as interface attributes. Upon return, Function 30 returns a Directory Code in register A with the value 0 if the function is successful, or 0FFH, 255 Decimal, if the file specified by the referenced FCB is not found. Register H is set to zero in both of these cases. If a physical or extended error is encountered, the Set File Attributes function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is the default mode, a message identifying the error is displayed at the console, and the program is terminated. Otherwise, Function 30 returns to the calling program with register A set to 0FFH, and register H set to one of the following physical or extended error codes:
| |
BDOS FUNCTION 31: GET ADDR(DPB PARMS)
Function 31 returns in register pair HL the address of the BIOS-resident Disk Parameter Block, DPB, for the currently selected drive. (Refer to the CP/M Plus (CP/M Version 3) Operating System System Guide for the format of the DPB). The calling program can use this address to extract the disk parameter values. If a physical error is encountered when the BDOS error mode is one of the return modes (see Function 45), Function 31 returns the value 0FFFFH in the register pair HL. | |
BDOS FUNCTION 32: SET/GET USER CODE
A program can change, or interrogate the currently active user number by calling Function 32. If register E = 0FFH, then the value of the current user number is returned in register A, where the value is in the range of 0 to 15. If register E is not 0FFH, then the current user number is changed to the value of E, modulo 16. | |
BDOS FUNCTION 33: READ RANDOM
The Read Random function is similar to the Read Sequential function except that the read operation takes place at a particular random record number, selected by the 24-bit value constructed from the three byte, r0, r1, r2, field beginning at position 33 of the FCB. Note that the sequence of 24 bits is stored with the least significant byte first, r0, the middle byte next, r1, and the high byte last, r2. The random record number can range from 0 to 262,143. This corresponds to a maximum value of 3 in byte r2. To read a file with Function 33, the calling program must first open the base extent, extent 0. This ensures that the FCB is properly initialized for subsequent random access operations. The base extent may or may not contain any allocated data. Function 33 reads the record specified by the random record field into the current DMA address. The function automatically sets the logical extent and current record values, but unlike the Read Sequential function, it does not advance the current record number. Thus, a subsequent Read Random call rereads the same record. After a random read operation, a file can be accessed sequentially, starting from the current randomly accessed position. However, the last randomly accessed record is reread or rewritten when switching from random to sequential mode. If the BDOS Multi-Sector Count is greater than one (see Function 44), the Read Random function reads multiple consecutive records into memory beginning at the current DMA. The r0, r1, and r2 field of the FCB is automatically incremented to read each record. However, the FCBs random record number is restored to the first record's value upon return to the calling program. Upon return, the Read Random function sets register A to zero if the read operation was successful. Otherwise, register A contains one of the following error codes:
Error Code 01 is returned if no data exists at the next record position of the file. Usually, the no data situation is encountered at the end of a file. However, it can also occur if an attempt is made to read a data block that has not been previously written. Error Code 03 is returned when the Read Random function cannot close the current extent prior to moving to a new extent. Error Code 04 is returned when a read random operation accesses an extent that has not been created. Error Code 06 is returned when byte 35, r2, of the referenced FCB is greater than 3. Error Code 10 is returned if a media change occurs on the drive after the referenced FCB is activated by a BDOS Open or Make Call. Error Code 255 is returned if a physical error is encountered, and the BDOS error mode is one of the return modes (see Function 45). If the error mode is the default mode, a message identifying the physical error is displayed at the console, and the calling program is terminated. When a physical error is returned to the calling program, register H contains one of the following error codes:
On all error returns except for physical errors, A = 255, the Read Random function sets register H to the number of records successfully read before the error is encountered. This value can range from 0 to 127 depending on the current BDOS Multi-Sector Count. It is always set to zero when the Multi-Sector Count is equal to one. | |
BDOS FUNCTION 34: WRITE RANDOM
The Write Random function is analogous to the Read Random function, except that data is written to the disk from the current DMA address. If the disk extent or data block where the data is to be written is not already allocated, the BDOS automatically performs the allocation before the write operation continues. To write to a file using the Write Random function, the calling program must first open the base extent, extent 0. This ensures that the FCB is properly initialized for subsequent random access operations. If the file is empty, the calling program must create the base extent with the Make File function before calling Function 34. The base extent might or might not contain any allocated data, but it does record the file in the directory, so that the file can be displayed by the DIR utility. The Write Random function sets the logical extent and current record positions to correspond with the random record being written, but does not change the random record number. Thus, sequential read or write operations can follow a random write, with the current record being reread or rewritten as the calling program switches from random to sequential mode. Function 34 makes an Update date and time stamp for the file if the following conditions are satisfied: the referenced drive has a directory label that requests Update date and time stamping if the file has not already been stamped for update by a previous BDOS Make or Write call. If the BDOS Multi-Sector Count is greater than one (see Function 44), the Write Random function reads multiple consecutive records into memory beginning at the current DMA. The r0, r1, and r2 field of the FCB is automatically incremented to write each record. However, the FCB's random record number is restored to the first record's value when it returns to the calling program. Upon return, the Write Random function sets register A to zero if the write operation is successful. Otherwise, register A contains one of the following error codes:
Error Code 02 is returned when the write command attempts to allocate a new data block to the file and no unallocated data blocks exist on the selected disk drive. Error Code 03 is returned when the Write Random function cannot close the current extent prior to moving to a new extent. Error Code 05 is returned when the write function attempts to create a new extent that requires a new directory entry and no available directory entries exist on the selected disk drive. Error Code 06 is returned when byte 35, r2, of the referenced FCB is greater than 3. Error Code 10 is returned if a media change occurs on the drive after the referenced FCB is activated by a BDOS Open or Make Call. Error Code 255 is returned if a physical error is encountered and the BDOS error mode is one of the return modes (see Function 45). If the error mode is the default mode, a message identifying the physical error is displayed at the console, and the calling program is terminated. When a physical error is returned to the calling program, it is identified by register H as shown below:
On all error returns, except for physical errors, A = 255, the Write Random function sets register H to the number of records successfully written before the error is encountered. This value can range from 0 to 127 depending on the current BDOS Multi-Sector Count. It is always set to zero when the Multi-Sector Count is equal to one. | |
BDOS FUNCTION 35: COMPUTE FILE SIZE
The Compute File Size function determines the virtual file size, which is, in effect, the address of the record immediately following the end of the file. The virtual size of a file corresponds to the physical size if the file is written sequentially. If the file is written in random mode, gaps might exist in the allocation, and the file might contain fewer records than the indicated size. For example, if a single record with record number 262,143, the CP/M 3 maximum is written to a file using the Write Random function, then the virtual size of the file is 262,144 records even though only 1 data block is actually allocated. To compute file size, the calling program passes in register pair DE the address of an FCB in random mode format, bytes r0, r1 and r2 present. Note that the FCB must contain an unambiguous filename and filetype. Function 35 sets the random record field of the FCB to the random record number + 1 of the last record in the file. If the r2 byte is set to 04H, then the file contains the maximum record count 262,144. A program can append data to the end of an existing file by calling Function 35 to set the random record position to the end of file, and then performing a sequence of random writes starting at the preset record address. Note: the BDOS does not require that the file be open to use Function 35. However, if the file has been written to, it must be closed before calling Function 35. Other wise, an incorrect file size might be returned. Upon return, Function 35 returns a zero in register A if the file specified by the referenced FCB is found, or an 0FFH in register A if the file is not found. Register H is set to zero in both of these cases. If a physical error is encountered, Function 35 performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is the default mode, a message identifying the error is displayed at the console and the program is terminated. Otherwise, Function 35 returns to the calling program with register A set to 0FFH, and register H set to one of the following physical errors:
| |
BDOS FUNCTION 36: SET RANDOM RECORD
The Set Random Record function returns the random record number of the next record to be accessed from a file that has been read or written sequentially to a particular point. This value is returned in the random record field, bytes r0, r1, and r2, of the FCB addressed by the register pair DE. Function 36 can be useful in two ways, First, it is often necessary to initially read and scan a sequential file to extract the positions of various key fields. As each key is encountered, Function 36 is called to compute the random record position for the data corresponding to this key. If the data unit size is 128 bytes, the resulting record number minus one is placed into a table with the key for later retrieval. After scanning the entire file and tabularizing the keys and their record numbers, you can move directly to a particular record by performing a random read using the corresponding random record number that you saved earlier. The scheme is easily generalized when variable record lengths are involved, because the program need only store the buffer-relative byte position along with the key and record number to find the exact starting position of the keyed data at a later time. A second use of Function 36 occurs when switching from a sequential read or write over to random read or write. A file is sequentially accessed to a particular point in the file, then Function 36 is called to set the record number, and subsequent random read and write operations continue from the next record in the file. | |
BDOS FUNCTION 37: RESET DRIVE
The Reset Drive function programmatically restores specified drives to the reset state. A reset drive is not logged-in and is in Read-Write status. The passed parameter in register pair DE is a 16-bit vector of drives to be reset, where the least significant bit corresponds to the first drive A, and the high-order bit corresponds to the sixteenth drive, labelled P. Bit values of 1 indicate that the specified drive is to be reset. | |
BDOS FUNCTION 38: ACCESS DRIVE
This is an MP/M function that is not supported under CP/M 3. If called, the file system returns a zero in register A indicating that the access request is successful. | |
BDOS FUNCTION 39: FREE DRIVE
This is an MP/M function that is not supported under CP/M 3. If called, the file system returns a zero in register A indicating that the free request is successful. | |
BDOS FUNCTION 40: WRITE RANDOM WITH ZERO FILL
The Write Random With Zero Fill function is identical to the Write Random function (Function 34) with the exception that a previously unallocated data block is filled with zeros before the record is written. If this function has been used to create a file, records accessed by a read random operation that contain all zeros identify unwritten random record numbers. Unwritten random records in allocated data blocks of files created using the Write Random function (Function 34) contain uninitialized data. | |
BDOS FUNCTION 41: TEST AND WRITE RECORD
The Test and Write Record function is an MP/M II function that is not supported under CP/M 3. If called, Function 41 returns with register A set to 0FFH and register H set to zero. | |
BDOS FUNCTION 42: LOCK RECORD
The Lock Record function is an MP/M II function that is supported under CP/M 3 only to provide compatibility between CP/M 3 and MP/M. It is intended for use in situations where more than one running program has Read-Write access to a common file. Because CP/M 3 is a single-user operating system in which only one program can run at a time, this situation cannot occur. Thus, under CP/M 3, Function 42 performs no action except to return the value 00H in register A indicating that the record lock operation is successful. | |
BDOS FUNCTION 43: UNLOCK RECORD
The Unlock Record function is an MP/M II function that is supported under CP/M 3 only to provide compatibility between CP/M 3 and MP/M. It is intended for use in situations where more than one running program has Read-Write access to a common file. Because CP/M 3 is a single-user operating system in which only one program can run at a time, this situation cannot occur. Thus, under CP/M 3, Function 43 performs no action except to return the value 00H in register A indicating that the record unlock operation is successful. | |
BDOS FUNCTION 44: SET MULTI-SECTOR COUNT
The Set Multi-Sector Count function provides logical record blocking under CP/M 3. It enables a program to read and write from 1 to 128 records of 128 bytes at a time during subsequent BDOS Read and Write functions. Function 44 sets the Multi-Sector Count value for the calling program to the value passed in register E. Once set, the specified Multi-Sector Count remains in effect until the calling program makes another Set Multi-Sector Count function call and changes the value. Note that the CCP sets the Multi-Sector Count to one when it initiates a transient program. The Multi-Sector Count affects BDOS error reporting for the BDOS Read and Write functions. If an error interrupts these functions when the Multi-Sector is greater than one, they return the number of records successfully read or written in register H for all errors except for physical errors (A = 255). Upon return, register A is set to zero if the specified value is in the range of 1 to 128. Otherwise, register A is set to 0FFH. | |
BDOS FUNCTION 45: SET BDOS ERROR MODE
Function 45 sets the BDOS error mode for the calling program to the mode specified in register E. If register E is set to 0FFH, 255 decimal, the error mode is set to Return Error mode. If register E is set to OFEH, 254 decimal, the error mode is set to Return and Display mode. If register E is set to any other value, the error mode is set to the default mode. The Set BDOS Error Mode function determines how physical and extended errors (see Section 2.3.13) are handled for a program. The Error Mode can exist in three modes: the default mode, Return Error mode, and Return and Display Error mode. In the default mode, the BDOS displays a system message at the console that identifies the error and terminates the calling program. In the return modes, the BDOS sets register A to 0FFH, 255 decimal, places an error code that identifies the physical or extended error in register H and returns to the calling program. In Return and Display mode, the BDOS displays the system message before returning to the calling program. No system messages are displayed, however, when the BDOS is in Return Error mode. | |
BDOS FUNCTION 46: GET DISK FREE SPACE
The Get Disk Free Space function determines the number of free sectors, 128 byte records, on the specified drive. The calling program passes the drive number in register E, with 0 for drive A, 1 for B, and so on, through 15 for drive P in a full 16- drive system. Function 46 returns a binary number in the first 3 bytes of the current DMA buffer. This number is returned in the following format: fs0 fs1 fs2 Disk Free Space Field Format
Note that the returned free space value might be inaccurate if the drive has been marked Read-Only. Upon return, register A is set to zero if the function is successful. However, if the BDOS Error Mode is one of the return modes (see Function 45), and a physical error is encountered, register A is set to 0FFH, 255 decimal, and register H is set to one of the following values:
| |
BDOS FUNCTION 47: CHAIN TO PROGRAM
The Chain To Program function provides a means of chaining from one program to the next without operator intervention. The calling program must place a command line terminated by a null byte, 00H, in the default DMA buffer. If register E is set to 0FFH, the CCP initializes the default drive and user number to the current program values when it passes control to the specified transient program. Otherwise, these parameters are set to the default CCP values. Note that Function 108, Get/Set Program Return Code, can be used to pass a two byte value to the chained program. Function 47 does not return any values to the calling program and any encountered errors are handled by the CCP. | |
BDOS FUNCTION 48: FLUSH BUFFERS
The Flush Buffers function forces the write of any write-pending records contained in internal blocking/deblocking buffers. If register E is set to 0FFH, this function also purges all active data buffers. Programs that provide write with read verify support need to purge internal buffers to ensure that verifying reads actually access the disk instead of returning data that is resident in internal data buffers. The CP/M 3 PIP utility is an example of such a program. Upon return, register A is set to zero if the flush operation is successful. If a physical error is encountered, the Flush Buffers function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, a message identifying the error is displayed at the console and the calling program is terminated. Otherwise, the Flush Buffers function returns to the calling program with register A set to 0FFH and register H set to the following physical error code:
| |
BDOS FUNCTION 49: GET / SET SYSTEM CONTROLBLOCK
Function 49 allows access to parameters located in the CP/M 3 System Control Block (SCB). The SCB is a 100-byte data structure residing within the BDOS that contains flags and data used by the BDOS, CCP and other system components. Note that Function 49 is a CP/M 3 specific function. Programs intended for both MP/M II and CP/M 3 should either avoid the use of this function or isolate calls to this function in CP/M 3 version-dependent sections. To use Function 49, the calling program passes the address of a data structure called the SCB parameter block in register pair DE. This data structure identifies the byte or word of the SCB to be updated or returned. The SCB parameter block is defined as: SCBPB: DB OFFSET ; Offset within SCB
DB SET ; 0FFH if setting a byte
; 0FEH if setting a word
; 001H - 0FDH are reserved
; 000H if a get operation
DW VALUE ; Byte or word value to be set
The OFFSET parameter identifies the offset of the field within the SCB to be updated or accessed. The SET parameter determines whether Function 49 is to set a byte or word value in the SCB or if it is to return a byte from the SCB. The VALUE parameter is used only in set calls. In addition, only the first byte of VALUE is referenced in set byte calls. Use caution when you set SCB fields. Some of these parameters reflect the current state of the operating system. If they are set to invalid values, software errors can result. In general, do not use Function 49 to set a system parameter if another BDOS function can achieve the same result. For example, Function 49 can be called to update the Current DMA Address field within the SCB. This is not equivalent to making a Function 26, Set DMA Address call, and updating the SCB Current DMA field in this way would result in system errors. However, you can use Function 49 to return the Current DMA address. The System Control Block is summarized in the following table. Each of these fields is documented in detail in Appendix A. Table 3-4. System Control Block
If Function 49 is called with the OFFSET parameter of the SCB parameter block greater than 063H, the function performs no action but returns with registers A and HL set to zero. | |
BDOS FUNCTION 50: DIRECT BIOS CALLS
Function 50 provides a direct BIOS call through the BDOS to the BIOS. The calling program passes the address of a data structure called the BIOS Parameter Block (BIOSPB) in register pair DE. The BIOSPB contains the BIOS function number and register contents as shown below: BIOSPB: db FUNC ; BIOS function no.
db AREG ; A register contents
dw BCREG ; BC register contents
dw DEREG ; DE register contents
dw HLREG ; HL register contents
System Reset (Function 0) is equivalent to Function 50 with a BIOS function number of 1. Note that the register pair BIOSPB fields (BCREG, DEREG, HLREG) are defined in low byte, high byte order. For example, in the BCREG field, the first byte contains the C register value, the second byte contains the B register value. Under CP/M 3, direct BIOS calls via the BIOS jump vector are only supported for the BIOS Console I/O and List functions. You must use Function 50 to call any other BIOS functions. In addition, Function 50 intercepts BIOS Function 27 (Select Memory) calls and returns with register A set to zero. Refer to the CP/M Plus (CP/M Version 3) Operating System System Guide for the definition of the BIOS functions and their register passing and return conventions. | |
BDOS FUNCTION 59: LOAD OVERLAY
Only transient programs with an RSX header can use the Load Overlay function because BDOS Function 59 is supported by the LOADER module. The calling program must have a header to force the LOADER to remain resident after the program is loaded (see Section 1.3). Function 59 loads either an absolute or relocatable module. Relocatable modules are identified by a filetype of PRL. Function 59 does not call the loaded module. The referenced FCB must be successfully opened before Function 59 is called. The load address is specified in the first two random record bytes of the FCB, r0 and r1. The LOADER returns an error if the load address is less than 0100H, or if performing the requested load operation would overlay the LOADER, or any other Resident System Extensions that have been previously loaded. When loading relocatable files, the LOADER requires enough room at the load address for the complete PRL file including the header and bit map (see Appendix B). Otherwise an error is returned. Function 59 also returns an error on PRL file load requests if the specified load address is not on a page boundary. Upon return, Function 59 sets register A to zero if the load operation is successful. If the LOADER RSX is not resident in memory because the calling program did not have a RSX header, the BDOS returns with register A set to 0FFH and register H set to zero. If the LOADER detects an invalid load address, or if insufficient memory is available to load the overlay, Function 59 returns with register A set to OFEH. All other error returns are consistent with the error codes returned by BDOS Function 20, Read Sequential. | |
BDOS FUNCTION 60: CALL RESIDENT SYSTEM EXTENSION
Function 60 is a special BDOS function that you use when you call Resident System Extensions. The RSX subfunction is specified in a structure called the RSX Parameter Block, defined as follows: RSXPB: db FUNC ; RSX Function number
db NUMPARMS ; Number of word Parameters
dw PARMETER1 ; Parameter 1
dw PARMETER2 ; Parameter 2
. . .
dw PARMETERN ; Parameter n
RSX modules filter all BDOS calls and capture RSX function calls that they can handle. If there is no RSX module present in memory that can handle a specific RSX function call, the call is not trapped, and the BDOS returns 0FFH in registers A and L. RSX function numbers from 0 to 127 are available for CP/M 3 compatible software use. RSX function numbers 128 to 255 are reserved for system use. | |
BDOS FUNCTION 98: FREE BLOCKS
The Free Blocks function scans all the currently logged-in drives, and for each drive returns to free space all temporarily-allocated data blocks. A temporarily-allocated data block is a block that has been allocated to a file by a BDOS write operation but has not been permanently recorded in the directory by a BDOS close operation. The CCP calls Function 98 when it receives control following a system warm start. Be sure to close your file, particularly any file you have written to, prior to calling Function 98. In the nonbanked version of CP/M 3, Function 98 frees only temporarily allocated blocks for systems that request double allocation vectors in GENCPM. Upon return, register A is set to zero if Function 98 is successful. If a physical error is encountered, the Free Blocks function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, a message identifying the error is displayed at the console and the calling program is terminated. Otherwise, the Free Blocks function returns to the calling program with register A set to 0FFH and register H set to the following physical error code:
| |
BDOS FUNCTION 99: TRUNCATE FILE
The Truncate File function sets the last record of a file to the random record number contained in the referenced FCB. The calling program passes the address of the FCB in register pair DE, with byte 0 of the FCB specifying the drive, bytes 1 through 11 specifying the filename and filetype, and bytes 33 through 35, r0, r1, and r2, specifying the last record number of the file. The last record number is a 24 bit value, stored with the least significant byte first, r0, the middle byte next, r1, and the high byte last, r2. This value can range from 0 to 262,143, which corresponds to a maximum value of 3 in byte r2. If the file specified by the referenced FCB is password protected, the correct password must be placed in the first eight bytes of the current DMA buffer, or have been previously established as the default password (see Function 106). Function 99 requires that the file specified by the FCB not be open, particularly if the file has been written to. In addition, any activated FCBs naming the file are not valid after Function 99 is called. Close your file before calling Function 99, and then reopen it after the call to continue processing on the file. Function 99 also requires that the random record number field of the referenced FCB specify a value less than the current file size. In addition, if the file is sparse, the random record field must specify a record in a region of the file where data exists. Upon return, the Truncate function returns a Directory Code in register A with the value 0 if the Truncate function is successful, or 0FFH, 255 decimal, if the file is not found or the record number is invalid. Register H is set to zero in both of these cases. If a physical or extended error is encountered, the Truncate function performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, a message identifying the error is displayed at the console and the program is terminated. Otherwise, the Truncate function returns to the calling program with register A set to 0FFH and register H set to one of the following physical or extended error codes:
| |
BDOS FUNCTION 100: SET DIRECTORY LABEL
The Set Directory Label function creates a directory label, or updates the existing directory label for the specified drive. The calling program passes in register pair DE the address of an FCB containing the name, type, and extent fields to be assigned to the directory label. The name and type fields of the referenced FCB are not used to locate the directory label in the directory; they are simply copied into the updated or created directory label. The extent field of the FCB, byte 12, contains the user's specification of the directory label data byte. The definition of the directory label data byte is:
If the current directory label is password protected, the correct password must be placed in the first eight bytes of the current DMA, or have been previously established as the default password (see Function 106). If bit 0, the low-order bit, of byte 12 of the FCB is set to 1, it indicates that a new password for the directory label has been placed in the second eight bytes of the current DMA. Note that Function 100 is implemented as an RSX, DIRLBL.RSX, in nonbanked CP/M 3 systems. If Function 100 is called in nonbanked systems when the DIRLBL.RSX is not resident an error code of 0FFH is returned. Function 100 also requires that the referenced directory contain SFCBs to activate date and time stamping on the drive. If an attempt is made to activate date and time stamping when no SFCBs exist, Function 100 returns an error code of 0FFH in register A and performs no action. The CP/M 3 INITDIR utility initializes a directory for date and time stamping by placing an SFCB record in every fourth entry of the directory. Function 100 returns a Directory Code in register A with the value 0 if the directory label create or update is successful, or 0FFH, 255 decimal, if no space exists in the referenced directory to create a directory label, or if date and time stamping was requested and the referenced directory did not contain SFCBs. Register H is set to zero in both of these cases. If a physical error or extended error is encountered, Function 100 performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is the default mode, a message identifying the error is displayed at the console and the calling program is terminated. Otherwise, Function 100 returns to the calling program with register A set to 0FFH and register H set to one of the following physical or extended error codes:
| |
BDOS FUNCTION 101: RETURN DIRECTORY LABEL DATA
The Return Directory Label Data function returns the data byte of the directory label for the specified drive. The calling program passes the drive number in register E with 0 for drive A, 1 for drive B, and so on through 15 for drive P in a full sixteen drive system. The format of the directory label data byte is shown below:
Function 101 returns the directory label data byte to the calling program in register A. Register A equal to zero indicates that no directory label exists on the specified drive. If a physical error is encountered by Function 101 when the BDOS Error mode is in one of the return modes (see Function 45), this function returns with register A set to 0FFH, 255 decimal, and register H set to one of the following:
| |
BDOS FUNCTION 102: READ FILE DATE STAMPS AND PASSWORD MODE
Function 102 returns the date and time stamp information and password mode for the specified file in byte 12 and bytes 24 through 32 of the specified FCB. The calling program passes in register pair DE, the address of an FCB in which the drive, filename, and filetype fields have been defined. If Function 102 is successful, it sets the following fields in the referenced FCB: byte 12 : Password mode field
Byte 12 equal to zero indicates the file has not been assigned a password. In nonbanked systems, byte 12 is always set to zero.
The date stamp fields are set to binary zeros if a stamp has not been made. The format of the time stamp fields is the same as the format of the date and time structure described in Function 104. Upon return, Function 102 returns a Directory Code in register A with the value zero if the function is successful, or 0FFH, 255 decimal, if the specified file is not found. Register H is set to zero in both of these cases. If a physical or extended error is encountered, Function 102 performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, a message identifying the error is displayed at the console and the calling program is terminated. Otherwise, Function 102 returns to the calling program with register A set to 0FFH and register H set to one of the following physical or extended error codes:
| |
BDOS FUNCTION 103: WRITE FILE XFCB
The Write File XFCB function creates a new XFCB or updates the existing XFCB for the specified file. The calling program passes in register pair DE the address of an FCB in which the drive, name, type, and extent fields have been defined. The extent field specifies the password mode and whether a new password is to be assigned to the file. The format of the extent byte is shown below: FCB byte 12 (ex) : XFCB password mode
If the specified file is currently password protected, the correct password must reside in the first eight bytes of the current DMA, or have been previously established as the default password (see Function 106). If bit 0 is set to 1, the new password must reside in the second eight bytes of the current DMA. Upon return, Function 103 returns a Directory Code in register A with the value zero if the XFCB create or update is successful, or 0FFH, 255 decimal, if no directory label exists on the specified drive, or the file named in the FCB is not found, or no space exists in the directory to create an XFCB. Function 103 also returns with 0FFH in register A if passwords are not enabled by the referenced directory's label. On nonbanked systems, this function always returns with register A = 0FFH because passwords are not supported. Register H is set to zero in all of these cases. If a physical or extended error is encountered, Function 103 performs different actions depending on the BDOS error mode (see Function 45). If the BDOS error mode is the default mode, a message identifying the error is displayed at the console and the calling program is terminated. Otherwise, Function 103 returns to the calling program with register A set to 0FFH and register H set to one of the following physical or extended error codes:
| |
BDOS FUNCTION 104: SET DATE AND TIME
The Set Date and Time function sets the system internal date and time. The calling program passes the address of a 4-byte structure containing the date and time specification in the register pair DE. The format of the date and time (DAT) data structure is:
The date is represented as a 16-bit integer with day 1 corresponding to January 1, 1978. The time is represented as two bytes: hours and minutes are stored as two BCD digits. This function also sets the seconds field of the system date and time to zero. | |
BDOS FUNCTION 105: GET DATE AND TIME
The Get Date and Time function obtains the system internal date and time. The calling program passes in register pair DE, the address of a 4-byte data structure which receives the date and time values. The format of the date and time, DAT, data structure is the same as the format described in Function 104. Function 105 also returns the seconds field of the system date and time in register A as a two digit BCD value. | |
FUNCTION 106: SET DEFAULT PASSWORD
The Set Default Password function allows a program to specify a password value before a file protected by the password is accessed. When the file system accesses a password-protected file, it checks the current DMA, and the default password for the correct value. If either value matches the file's password, full access to the file is allowed. Note that this function performs no action in nonbanked CP/M 3 systems because file passwords are not supported. To make a Function 106 call, the calling program sets register pair DE to the address of an 8-byte field containing the password. | |
BDOS FUNCTION 107: RETURN SERIAL NUMBER
Function 107 returns the CP/M 3 serial number to the 6-byte field addressed by register pair DE. | |
BDOS FUNCTION 108: GET/SET PROGRAM RETURN CODE
CP/M 3 allows programs to set a return code before terminating. This provides a mechanism for programs to pass an error code or value to a following job step in batch environments. For example, Program Return Codes are used by the CCP in CP/M 3's conditional command line batch facility. Conditional command lines are command lines that begin with a colon, :. The execution of a conditional command depends on the successful execution of the preceding command. The CCP tests the return code of a terminating program to determine whether it successfully completed or terminated in error. Program return codes can also be used by programs to pass an error code or value to a chained program (see Function 47, Chain To Program). A program can set or interrogate the Program Return Code by calling Function 108. If register pair DE = 0FFFFH, then the current Program Return Code is returned in register pair HL. Otherwise, Function 108 sets the Program Return Code to the value contained in register pair DE. Program Return Codes are defined in Table 3-5. Table 3-5. Program Return Codes
| |
BDOS FUNCTION 109: GET/SET CONSOLE MODE
A program can set or interrogate the Console Mode by calling Function 109. If register pair DE = 0FFFFH, then the current Console Mode is returned in register HL. Otherwise, Function 109 sets the Console Mode to the value contained in register pair DE. The Console Mode is a 16-bit system parameter that determines the action of certain BDOS Console I/O functions. The definition of the Console Mode is:
Note that the Console Mode bits are numbered from right to left. The CCP initializes the Console Mode to zero when it loads a program unless the program has an RSX that overrides the default value. Refer to Section 2.2.1 for detailed information on Console Mode. | |
BDOS FUNCTION 110: GET/SET OUTPUT DELIMITER
A program can set or interrogate the current Output Delimiter by calling Function 110. If register pair DE = 0FFFFH, then the current Output Delimiter is returned in register A. Otherwise, Function 110 sets the Output Delimiter to the value contained in register E. Function 110 sets the string delimiter for Function 9, Print String. The default delimiter value is a dollar sign, $. The CCP restores the Output Delimiter to the default value when a transient program is loaded. | |
BDOS FUNCTION 111: PRINT BLOCK
The Print Block function sends the character string located by the Character Control Block, CCB, addressed in register pair DE, to the logical console, CONOUT:. If the Console Mode is in the default state (see Section 2.2.1), Function 111 expands tab characters, CTRL-I, in columns of eight characters. It also checks for stop scroll, CTRL-S, start scroll, CTRL-Q, and echoes to the logical list device, LST:, if printer echo, CTRL-P, has been invoked. The CCB format is:
| |
BDOS FUNCTION 112: LIST BLOCK
The List Block function sends the character string located by the Character Control Block, CCB, addressed in register pair DE, to the logical list device, LST:. The CCB format is:
| |
BDOS FUNCTION 152: PARSE FILENAME
The Parse Filename function parses an ASCII file specification and prepares a File Control Block, FCB. The calling program passes the address of a data structure called the Parse Filename Control Block, PFCB, in register pair DE. The PFCB contains the address of the input ASCII filename string followed by the address of the target FCB as shown below: PFCB: DW INPUT ; Address of input ASCII string
DW FCB ; Address of target FCB
The maximum length of the input ASCII string to be parsed is 128 bytes. The target FCB must be 36 bytes in length. Function 152 assumes the input string contains file specifications in the following form: {d:}filename{.typll}{;password}
where items enclosed in curly brackets are optional. Function 152 also accepts isolated drive specifications d: in the input string. When it encounters one, it sets the filename, filetype, and password fields in the FCB to blank. The Parse Filename function parses the first file specification it finds in the input string. The function first eliminates leading blanks and tabs. The function then assumes that the file specification ends on the first delimiter it encounters that is out of context with the specific field it is parsing. For instance, if it finds a colon, and it is not the second character of the file specification, the colon delimits the entire file specification. Function 152 recognizes the following characters as delimiters:
If Function 152 encounters a non-graphic character in the range 1 through 31 not listed above, it treats the character as an error. The Parse Filename function initializes the specified FCB shown in Table 3-6. Table 3-6. FCB Format
If an error occurs, Function 152 returns an 0FFFFH in register pair HL. On a successful parse, the Parse Filename function checks the next item in the input string. It skips over trailing blanks and tabs and looks at the next character. If the character is a null or carriage return, it returns a 0 indicating the end of the input string. If the character is a delimiter, it returns the address of the delimiter. If the character is not a delimiter, it returns the address of the first trailing blank or tab. If the first non-blank or non-tab character in the input string is a null, 0, or carriage return, the Parse Filename function returns a zero indicating the end of string. If the Parse Filename function is to be used to parse a subsequent file specification in the input string, the returned address must be advanced over the delimiter before placing it in the PFCB. | |
|
End of Section 3 Continue in... |
page URL: www.bigfoot.com/~c128page/cpm3-prg/cpm3pg3b.htm
contact: c128page@bigfoot.com