CP/M-68J(TM - s100computers.com

CP/M-68J(TM Operating System

Programmer's Guide

[Q] DIGITAL

RESFARCHTM

CP/M-68(M Operating System

Programmer's Guide

COPYRIGHT

Copyright © 1983 by Digital Research. All rights reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of Digital Research, Post Office Box 579, Pacific Grove, California, 9395 0.

This documentation is, however, tutorial in nature. Thus, the reader is granted permission to include the example programs, either in whole or in part, in his or her own programs.

DISCLAIMER

Digital Research makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Further, Digital Research reserves the right to revise this publication and to make changes from time to time in the content hereof without obligation of Digital Research to notify any person of such revision or changes.

TRADEMARKS

CP/M, CP/M-86, and CPINET are registered trademarks of Digital Research. AS68, AR68, Concurrent CP/M-86, 'CP/M-68K, CP/M-80, DDT-68K, L068, MP/M- 80, MP/M-86, NM68, SENDC68, and SIZE68 are trademarks of Digital Research. Motorola is a registered trademark of Motorola Inc. Unix is a registered trademark of Bell Laboratories. IBM Personal Computer is a tradename of International Business Machines.

The CPIM-68K Operating System Programmer's Guide was prepared using the Digital Research TEX Text Formatter and printed in the United States of America.

Second Edition: June 1983

ii

Foreword

CP/M-68KTM is a single-user operating system designed for the Motorola® MC68000 or a compatible 68000 microprocessor. CP/M-68K requires a minimum of 64K bytes of random access memory (RAM) to run its base-level system, which contains the following CP/M® commands and utilities:

• CP/M Built-in Commands:

DIR DIRS ERA REN SUBMIT TYPE USER

• Standard CP/M Utilities:

DDT-68KTM ED PIP STAT

• Programming Utilities:

Archive (AR68) DUMP Relocation (RELOC) SIZE68 SENDC68

• Programming Tools

Assembler (AS68) Linker (L068) C Compiler* C Preprocessor*

* Described in the C Language Programming Guide for CPIM-68K.

CP/M-68K requires a minimum of 128K bytes of RAM to run the programming tools distributed with CP/M-68K.

iii

The CP/M-68K file system is based on and is upwardly compatible with the CP/M-80™ Version 2.2 and CP/M-86™ Version 1.1 file systems. However, CP/M-68K supports a much larger file size with a maximum of 32 megabytes per file.

CP/M-68K supports a maximum of 16 disk drives, with 512 megabytes per drive. CP/M-68K supports other peripheral devices that the Basic I/O System (BIOS) assigns to one of the four logical devices: LIST, CONSOLE, AUXILIARY INPUT, or AUXILIARY OUTPUT.

This guide describes the programming interface to CP/M-68K. The first few sections in this guide discuss the CP/M-68K architecture, memory models, executable programs, and file system access functions. Latter sections of this guide describe programming tools and utilities distributed with your CP/M-68K system.

This guide assumes you are an experienced programmer familiar with the basic programming concepts of assembly language. If you are not familiar with the Motorola 68000 assembly language, refer to the following Motorola manuals:

• 16-BIT Microprocessor User's Manual, third edition MC68000UM(AD3) • M68000 Resident Structured Assembler Reference Manual M68KMASM(D4)

Before you can use the facilities in this guide, your CP/M-68K system must be configured for your hardware environment. Normally, your system is configured for you by the manufacturer of your computer or the software distributor. However, if you have an unusual hardware environment, this may not be the case. Refer to the CP/M-68K Operating System System Guide for details on how to configure your system for a custom hardware environment.

New Functions and Implementation ,Changes

CP/M-68K has six new Basic Disk Operating System (BDOS) functions and additional implementation changes in the BDOS fu'nctions and data structures that differ from other CP/M systems. The new BDOS functions and implementation changes are listed in Appendix F.

Table F-4 in Appendix F contains functions and commands supported by other CP/M systems, but that are not supported by CP/M-68K.

iv

Table of Contents

1 Introduction to CP/M-68K

1.1 CP/M-68K System Architecture .... . 1.2 Transient Programs ...... . 1.3 File System Access . . . . . . . 1.4 Programming Tools and Commands 1.5 CP/M-68K File Specification 1.6 Wildcards . . . . . . . . 1. 7 CP/M-68K Terminology

2 The CCP and Transient Programs

2.1 2.2

2.3 2.4

CCP Built-in and Transient Commands Loading a Program in Memory .... 2.2.1 Base Page Initialization by the CCP 2.2.2 Loading Multiple Programs 2.2.3 Base Page Initialization .. . Exiting Transient Programs ...... . Transient Program Execution Model

3 Command File Format

3.1 3.2

3.3

The Header and Program Segments The Symbol Table ........ . 3.2.1 Printing the Symbol Table .. Relocation Information ..... . . 3.3.1 The Format of a Relocation Word

v

· 1-1 · 1-2

1-2 · 1-2

1-6 · 1-7 · 1-8

· 2-1 2-2

· 2-2 · 2-3

. . 2-3 · 2-4

2-5

· 3-1 · 3-4

. . 3-6 · 3-6

3-8

Table of Contents (continued)

4 Basic Disk Operatin~ System (BDOS) Functions

4.1 BDOS Functions and Parameters .... · . 4-3 4.1.1 Invoking BDOS Functions . . . . . · . 4-3 4.1.2 Organization Of BDOS Functions ..... · . 4-4

4.2 File Access Functions ........ · . 4-4 4.2.1 A File Control Block (FCB) · . 4-5 4.2.2 File Processing Errors · . 4-7 4.2.3 Open File Function 4-11 4.2.4 Close File Function ..... 4-12 4.2.5 Search For First Function 4-13 4.2.6 Search For Next Function ...... 4-14 4.2.7 Delete File Function .... 4-15 4.2.8 Read Sequential Function ..... 4-16 4.2.9 Write Sequential Function 4-17 4.2.10 Make File Function .... 4-19 4.2.11 Rename File Function ... 4-20 4.2.12 Set Direct Memory Access (DMA) Address Function 4-21 4.2.13 Set File Attributes Function 4-22 4.2.14 Read Random Function .. 4-24 4.2.15 Write Random Function 4-26 4.2.16 Compute File Size Function 4-28 4.2.17 Set Random Record Function 4-30 4.2.18 Write Random With Zero Fill Function . 4-32

4.3 Drive Functions .......... 4-33 4.3.1 Reset Disk System Function 4-34 4.3.2 Select Disk Function . . . . . 4-35 4.3.3 Return Login Vector Function 4-36 4.3.4 Return Current Disk Function 4-37 4.3.5 Write Protect Disk Function . ..... 4-38 4.3.6 Get Read-Only Vector Function 4-39 4.3.7 Get Disk Parameters Function 4-40 4.3.8 Reset Drive Function ..... 4-42 4.3.9 Get Dis~ Free Space Function ..... 4-43

vi


4.4 Character 110 Functions . . . . 4-44 '4.4.1 Console I/O Functions 4-45

Console Input Function 4-45 Console Output Function · ..... 4-46 Direct Console I/O Function 4-47 Print String Function ..... 4-49 Read Console Buffer Function 4-50 Get Console Status Function ...... 4-52

4.4.2 Additional Serial 110 Functions 4-53 Auxiliary Input Function · ..... 4-53 Auxiliary Output Function 4-54 List Output Function 4-55

4.4.3 110 Byte Functions 4-55 Get 110 Byte Function · .... 4-57 Set 110 Byte Function 4-58

4.5 System/Program Control Functions 4-58 4.5.1 System Reset Function 4-59 4.5.2 Return Version Number Function 4-60 4.5.3 Set/Get User Code ..... 4-62 4.5.4 Chain To Program Function 4-63 4.5.5 Flush Buffers Function ..... 4-64 4.5.6 Direct BIOS Call Function 4-65 4.5.7 Program Load Function . . ..... 4-67

4.6 Exception Functions . . . . . . . . 4-70 4.6.1 Set Exception Vector Function 4-71 4.6.2 Set Supervisor State 4-74 4.6.3 Get/Set TPA Limits ....... 4-75

vii


5 AS68 Assembler

5.1 Assembler Operation ..... . 5.2 Initializing AS68 .... . 5.3 Invoking the Assembler (AS68) 5.4 Assembly Language Directives 5.5 Sample Commands Invoking AS68 5.6 Assembly Language Differences 5.7 Assembly Language Extensions 5.8 Error Messages ....... .

6 L068 Linker

6.1 Linker Operation ........ . 6.2 Invoking the Linker (L068) . . . . . 6.3 Sample Commands Invoking L068 6.4 L068 Error Messages . . . . . . .

7 Programming Utilities

7.1 Archive Utility . . . . . . 7.1.1 AR68 Syntax ... 7.1.2 AR68 Operation ..... 7.1.3 AR68 Commands and Options 7.1.4 Errors ...... .

7.2 DUMP Utility .... . 7.2.1 Invoking DUMP 7.2.2 DUMP Output 7.2.3 DUMP Examples .... .

7.3 Relocation Utility .... . 7.3.1 Invoking RELOC 7.3.2 RELOC Examples

7.4 SIZE68 Utility . . . . . . . . 7.4.1 Invoking SIZE68 7.4.2 SIZE68 Output .. 7.4.3 SIZE68 Examples

7.5 SENDC68 Utility ..... 7.5.1 Invoking SENDC68 ..... 7.5.2 SENDC68 Example

viii

· 5-1 · 5-1 · 5-1 · 5-4 5-10 5-10 5-12 5-13

· . 6-1 · . 6-1

6-4 · . 6-4

· . 7-1 · 7-1

· . 7-3 · . 7-3

· 7-7 . .. 7-8

7-8 7-9

7-10 7-11 7-11 7-12 7-13 7-13 7-14 7-15 7-16 7-16 7-17


8 DDT-68K

8.1 DDT-68K Operation .......... . 8.1.1 Invoking DDT-68K ............. . 8.1.2 DDT-68K Command Conventions 8.1.3 Specifying Address ........ . 8.1.4 Terminating DDT-68K ..... . 8.1.5 DDT-68K Operation with Interrupts .... .

8.2 DDT-68K Commands ............ . 8.2.1 The D (Display) Command ..... . 8.2.2 The E (Load for Execution) Command 8.2.3 The F (Fill) Command ......... . 8.2.4 The G (Go) Command ....... . 8.2.5 The H (Hexadecimal Math) Command 8.2.6 The I (Input Command Tail) Command 8.2.7 The L (List) Command 8.2.8 The M (Move) Command 8.2.9 The R (Read) Command 8.2.10 The S (Set) Command ... 8.2.11 The T (Trace) Command 8.2.12 The U (Untrace) Command 8.2.13 The V (Value) Command .. 8.2.14 The W (Write) Command .. 8.2.15 The X (Examine CPU State) Command

8.3 Assembly Language Syntax for the L Command

ix

.... 8-1 8-1

· . 8-1 · 8-2

. ...... 8-2 . ... 8-3

· 8-3 8-3 8-4 8-5

. ...... 8-5 · . 8-6

· 8-6 · . 8-7

· 8-7 ... 8-8

· . 8-8 ... 8-9

8-10 8-10 8-10 8-11 8-12


Appendixes

A Summary of BIOS Functions

B Transient Program Load Example

C Base Page Format . . . .

D Instruction Set Summary

E Error Messages .. . . .

E.l AR68 Error Messages E.1.1 Fatal Diagnostic Error Messages E.1.2 AR68 Internal Logic Error Messages

E.2 AS68 Error Messages ............ . E.2.1 AS68 Diagnostic Error Messages .. . E.2.2 User-recoverable Fatal Error Messages E.2.3 AS68 Internal Logic Error Messages

E.3 BDOS Error Messages E.4 BIOS Error Messages ...... . E.S CCP Error Messages ....... .

E.5.1 Diagnostic Error Messages E.5.2 CCP Internal Logic Error Messages

E.6 DDT-68K Error Messages ........ . E.6.1 Diagnostic Error Messages .... . E.6.2 DDT-68K Internal Logic Error Messages

E.7 DUMP Error Messages ......... . E.8 L068 Error Messages . . . . . . . . . . . . .

E.8.1 Fatal Diagnostic Error Messages E.8.2 L068 Internal Logic Error Messages

E.9 NM68 Error Messages E.l0 RELOC Error Messages ..... E.ll SENDC68 Error Messages

E.ll.l Diagnostic Error Messages E.l1.2 SENDC68 Internal Logic Error Messages

E.12 SIZE68 Error Messages ............. .

x

· . A-l

· . B-1

· . C-1

· . D-l

· . E-l

. E-l · . E-l

E-4 E-5 E-5

E-l0 E-13 E-14 E-16 E-17 E-17 E-20 E-20 E-21 E-26 E-26 E-27 E-27 E-30 E-31 E-32 E-35 E-35 E-36 E-37


Appendixes (continued)

F New Functions and Implementation Changes .....

F.l BDOS Function and Data Structure Changes .. F.2 BDOS Functions Not Supported By CP/M-68K

xi

. . F-l

. F-2 .. F-3


Tables 1-1. Program Modules in the CPM.SYS File 1-2. CP/M-68K Commands (Programmer's Guide) 1-3. CP/M-68K Commands (User's Guide) 1-4. CP/M-68K Commands (C Manual) 1-5. Delimiter Characters . . . . . . . . . 1-6. CP/M-68K Terminology ....... . 1-7. CP/M-68K Programmer's Guide Conventions '3-1. Values for Symbol Types ......... . 3-2. Relocation Word Values (bits 0 through 2) 4-1. CP/M-68K BDOS Functions 4-2. BDOS Parameter Summary 4-3. File Access Functions, .... 4-4. Read-Write Error Response Options 4-5. Disk File Error Response Options . 4-6. Unsuccessful Write Operation Return Codes 4-7. File Attributes ............. . 4-8. Read Random Function Return Codes .. 4-9. Write Random Function Return Codes 4-10. Current Position Definitions 4-11. Drive Functions ..... . 4-12. Fields in the DPB and CDPB 4-13. Character 110 Functions . . 4-14. Direct Console 1/0 Function Values 4-15. Line Editing Controls ...... . 4-16. 1/0 Byte Fi,eld Definitions .... . 4-17. System and Program Control Functions 4-18. Version Numbers ......... . 4-19. Program Load Function Return Codes 4-20. Load Parameter Block Options 4-21 .. Valid Vectors and Exceptions .... 4-22. Values for Bits 0 and 1 in the TPAB Parameter Field

xii

1-1 1-3 1-4 1-5 1-7 1-8 1-9 3-5

· 3-8 · 4-1

.. 4-3 · 4-5

... 4-8 4-10

........ 4-18 4-23 4-25 4-27 4-30 4-33 4-41 4-44 4-48 4-51 4-56

.... ,. 4-58 4-61 4-67 4-69 4-73 4-77


5-1. Assembler Options ...... . 5-2. Assembly Language Directives 6-1. Linker Command Options . . 7-1. AR68 Command Line Components 7-2. AR68 Commands and Options 7-3. DUMP Command Line Components 7-4. DUMP Output Components ..... 7 -5. RELOC Command Line Components 7 -6. SIZE68 Command Line Components 7-7. SIZE68 Output Components ..... 7 -8. SENDC68 Command Line Components 8-1. DDT-68K Command Summary ......... . A-I. Summary of BIOS Functions ...... . C-1. Base Page Format: Offsets and Contents D-1. Instruction Set Summary ........ . D-2. Variations of Instruction Types ... . E-1. AR68 Fatal Diagnostic Error Messages ..... E-2. AS68 Diagnostic Error Messages . . . E-3. User-recoverable Fatal Error Messages E-4. BDOS Error Messages ..... . E-5. BIOS Error Messages ....... . E-6. CCP Diagnostic Error Messages . . . . E-7. DDT-68K Diagnostic Error Messages E-8. DUMP Error Messages ........ . E-9. L068 Fatal Diagnostic Error Messages E-10. NM68 Error Messages ....... : E-11. RELOC Error Messages . . . . . . . E-12. SENDC68 Diagnostic Error Messages E-13. SIZE68 Error Messages ...... . F-1. New BDOS Functions ........ . F-2. BDOS Function Implementation Changes F-3. BDOS Data Structure Implementation Changes F-4. BDOS Functions Not Supported by CP/M-68K

xiii

· 5-2 · 5-4 · 6-1

· . 7-2 · . 7-3

· 7-9 7-10 7-12 7-14 7-15 7-17

· . 8-2 · A-1 · C-1 · D-1

· .. D-4 · .. E-1 · .. E-5

E-10 E-14 E-17 E-18 E-21 E-27 E-28 E-32 E-33 E-36 E-37

· .. F-1 · F-2

F-2 · . F-3

Figures

Format of the Command Tail in the DMA Buffer CP/M-68K Default Memory Model ...... . CP/M-68K Memory Model with Inaccessible Memory Header for Contiguous Program Segments . . Header for Noncontiguous Program Segments Entry in Symbol Table . . . . . . . FCB Format for Rename Function DPB and CDBP ........ . 110 Byte ............. . Command Line Format in the DMA Buffer BIOS Parameter Block (BPB) ....... .

· . 2-3 . .. 2-S

2-6 . 3-2 . 3-3

. . . . .. . 3-4 4-20 4-40 4-SS 4-63 4-66

2-l. 2-2. 2-3. 3-l. 3-2. 3-3. 4-l. 4-2. 4-3. 4-4. 4-S. 4-6. 4-7. 4-8. 4-9.

Format of the Load Parameter Block (LPB) ........ . 4-68 4-71 4-7S 4-76

Exception Parameter Block (EPB) Transient Program Parameter Block Parameter Field in TP AB . . . . . .

Listings

B-1. Transient Program Load Example 1 B-2. Transient Program Load Example 2

xiv

· . B-1 · . B-S

Section 1 Introduction to CP/M-68K

CP/M-68K contains most of the facilities of other CP/M systems with additional features required to address up to sixteen megabytes of main memory available on the 68000 microprocessor. The CP/M-68K file system is upwardly compatible with CP/M-80 Version 2.2 and CP/M-86 Version 1.1. The CP/M-68Kfile structure supports a maximum of sixteen drives with up to 512 megabytes on each drive and a maximum file size of 32 megabytes.

1.1 CP 1M -68K Architecture

The CP/M-68K operating system resides in the file CPM.SYS on the system disk. A cold start loader resides on the first two tracks of the system disk and loads the CPM.SYS file into memory during a cold start. The CPM.SYS file contains the three program modules described in Table 1-1.

Table 1-1. Program Modules in the CPM.SYS File

Module I Mnemonic

Console Command Processor CCP

Basic Disk Operating System BDOS

Basic 110 System BIOS

I Description

User interface that parses the user command line.

Provides functions that access the file system.

Provides functions that interface peripheral device drivers for 110 processing.

The sizes of the CCP and BDOS modules are fixed for a given release of CP/M-68K. The BIOS custom module, normally supplied by the computer manufacturer or software distributor depends on the system configuration, which varies with the implementation. Therefore, the size of the BIOS also varies with the implementation.

f!ID DIGITAL RESEARCH™ -------------------------1-1

1.1 CP/M-68K Architecture CP/M-68K Programmer's Guide

The CP/M-68K operating system can be loaded to execute in any portion of memory above the locations reserved in the 68000 architecture for the exception vectors (OOOOH through 03FFH). All CP/M-68K modules remain resident in memory. The CCP cannot be used as a data area subsequent to transient program load.

1.2 Transient Programs

After CP/M-68K is loaded in memory, the remaining contiguous address space that is not occupied by the CP/M-68K operating system is called the Transient Program Area (TPA). CP/M-68K loads executable files, called command files, from disk to the TPA. These command files are also called transient commands or transient programs because they temporarily reside in memory, rather than being permanently resident in memory and configured in CP/M-68K. The format of a command file is described in Section 3.

1.3 File System Access

Programs do not specify absolute locations or default variables when accessing CP/M-68K. Instead, programs invoke BDOS and BIOS functions. Section 4 describes the BDOS functions in detail. Appendix A lists the BIOS calls. Refer to the CPIM-68K Operating System System Guide for detailed descriptions of the BIOS functions. In addition to these functions, CP/M-68K decreases dependence on absolute addresses by maintaining a base page in the TP A for each transient program in memory. The base page contains initial values for the File Control Block (FCB) and the Direct Memory Access (DMA) buffer. For details on the base page and loading transient programs, refer to Section 2.

1.4 Programming Tools and Commands

CP/M-68K contains a full set of programming tools that include an assembler (AS68), linker, (L068), Archive Utility (AR68), Relocation Utility (RELOC), DUMP Utility, SIZE68, and SENDC68. Each of these tools is discussed in the latter part of this guide. Table 1-2 lists the commands that invoke these tools. Tables 1-3 and 1-4 list other commands supported by CP/M-68K and the manual in which they are documented.

------------------------- f!ID DIGITAL RESEARCH™ 1-2

CP/M-68K Programmer's Guide 1.4 Programming Tools and Commands

Table 1-2 describes commands used in the CPIM-68K Operating System Programmer's Guide.

Table 1-2. CP/M-68K Commands (Programmer's Guide)

Command ~ Description

AR68 Invokes the Archive Utility (AR68). AR68 creates a library and/or deletes, adds, or extracts object modules from an existing library, such as the C Run-time Library.

AS68 Invokes the Assembler (AS68).

DDT Invokes DDT-68K, the CP/M-68K debugger.

DUMP Invokes the DUMP Utility that prints the contents of a file in hexadecimal and ASCII notation.

L068 Invokes the Linker.

NM68 Invokes the NM68 Utility that prints the symbol table of an object or command file.

RELOC Invokes the Relocation Utility that relocates a command file containing relocation information to an absolute address.

SENDC68 Invokes the SENDC68 Utility that converts a command file to the MOTOROLA S-record format.

SIZE68 Invokes the SIZE68 Utility that prints the total size of a command file and the size of each program segment in the file.

I!ID DIGITAL RESEARCH™ --------------------------1-3

1.4 Programming Tools and Commands CP/M-6SK Programmer's Guide

Table 1-3 describes commands used in the CP/M-68K Operating System User's Guide.

Table 1-3. CP/M-68K Commands (User's Guide)

Command I Description

DIR * Displays the directory of files on a specified disk.

DIRS* Displays the directory of system files on a specified disk.

ED Invokes the CP/M-68K text editor.

ERA * Erases one or more specified files.

PIP Copies, combines, and transfers specified files between peripheral devices.

REN* Renames an existing file to the new name specified in the command line.

SUBMIT* Executes a file of CP/M commands.

TYPE * Displays the contents of an ASCII file on the console.

USER * Displays or changes the current user number.

* CP/M-68K built-in commands

-------------------------I!ID DIGITAL RESEARCHT•

1-4

CP/M-68K Programmer's Guide 1.4 Programming Tools and Commands

Table 1-4 describes commands used in the C Language Programming Guide for CPIM-68K.

Table 1-4. CP/M-68K Commands (C Manual)

Command J Description

C Invokes a submit file that invokes the C compiler for compiling CP/M-68K C source files.

CP68 Invokes the C preprocessor for processing macros when you compile CP/M-68K C source files.

C068 Invokes the C parser when you compile CP/M-68K C source files.

C168 Invokes the assembly language code generator for the CP/M-68K C compiler when you compile C source files.

[!ill DIGITAL RESEARCH™ -------------------------1-5

1.5 CP/M-68K File Specification CP/M-68K Programmer's Guide

1.5 CP/M-68K File Specification

The CP/M-68K file specification is compatible with other CP/M systems. The format contains three fields: a I-character drive select code (d), a 1- through 8-character filename (f ... f), and a 1- through 3-character filetype (ttt) field as shown below.

Format d: ffffffff. ttt

Example B:MYRAH.DAT

The drive select code and filetype fields are optional. A colon (:) delimits the drive select field. A period (.) delimits the filetype field. These delimiters are required only when the fields they delimit are specified.

Values for the drive select code range from A through P when the BIOS implementation supports 16 drives, the maximum number allowed. The range for the drive code is dependent on the BIOS implementation. Drives are labeled A through P to correspond to the 1 through 16 drives supported by CP/M-68K. However, not all BIOS implementations support the full range.

The characters in the filename and filetype fields cannot contain delimiters (the colon and period). A command line and its file specifications, if any, that are entered at the CCP level are automatically put in upper-case internally before the CCP parses them.

However, not all commands and file specifications are entered at the CCP level. CP/M-68K does not prevent you from including delimiters in file specifications that are created or referenced by functions that bypass the CCP. For example, the BDOS Make File Function (22) allows you to create a file specification that includes delimiters, although the CCP cannot parse and access such a file.

In addition to the delimiter characters already mentioned, you should avoid using the delimiter characters in Table 1-5 in the file specification of a file you create. Several CP/M-68K built-in commands and utilities have special uses for these characters.

-------------------------I!ID DIGITAL RESEARCH'" 1-6

CP/M-68K Programmer's Guide 1.5 CP/M-68K File Specification

Table 1-5. Delimiter Characters

Character I Description

[ ] square brackets () parentheses <> angle brackets

equals sign * asterisk & ampersand

comma exclamation point bar question mark

I slash $ dollar sign

period colon semicolon

+ plus sign minus sign

1.6 Wildcards

CP/M-68K supports two wildcards, the question mark (?) and the asterisk (*). Several utilities and BDOS functions allow you to specify wildcards in a file specification to perform the operation or function on one or more files. However, BDOS functions support only the ? wildcard.

The ? wildcard matches any character in the character position occupied by this wildcard. For example, the file specification M?RAH.DAT indicates the second letter of the filename can be any alphanumeric character if the remainder of file specification matches. Thus, the ? wildcard matches exactly one character position.

The * wildcard matches one or more characters in the field or remainder of a field that this wildcard occupies. CP/M-68K internally pads the field or remaining portion of the field occupied by the * wildcard with? wildcards before searching for a match. For example, CP/M-68K converts the file B*.DAT to B???????DAT before searching for a matching file specification. Thus, any file that starts with the letter B and has a filetype of DAT matches this file specification.

[!ID DIGITAL RESEARCHTN --------------------------

1-7

1.6 Wildcards CP/M-68K Programmer's Guide

For details on wildcard support by a specific BDOS function, refer to the description of the function in Section 4 of this guide. For additional details on these wildcards and support by CP/M-68K utilities, refer to the CPIM-68K Operating System User's Guide.

1.7 CP/M-68K Terminology

Table 1-6 lists the terminology used throughout this guide to describe CP/M-68K values and program components.

Table 1-6. CP/M-68K Terminology

Term I Meaning

Nibble 4-hit value

Byte 8-hit value

Word 16-hit value

Longword 32-hit value

Address 32-hit value that specifies a location in storage

Offset A fixed displacement defined by the user to reference a location in storage, other data source, or destination.

Text Segment The section of a program that contains the program instructions.

Data Segment The section of a program that contains initialized data.

Block Storage Segment (bss) The section of a program that contains uninitialized data.

-------------------------I!TIJ DIGITAL RESEARCH™ 1-8

CP/M-68K Programmer's Guide 1.7 CP/M-68K Terminology

Table 1-7 describes conventions used in this manual.

Table 1-7. CP/M-68K Programmer's Guide Conventions

Convention I Meaning

[] Square brackets in a command line enclose optional parameters.

nH The capital letter H follows numeric values that are represented in hexadecimal notation.

numenc Unless otherwise stated, numeric values are represented in decimal values notation.

(n) BDOS function numbers are enclosed in parentheses when they appear in text.

. or ...

RETURN

CTRL-X

A vertical or horizontal elipsis indicates missing elements in a series unless noted otherwise.

The word RETURN refers to the RETURN key on the keyboard of your console. Unless otherwise noted, to invoke a command, you must press RETURN after you enter a command line from your console.

The mnemonic CTRL-X instructs you to press the key labeled CTRL while you press another key indicated by the variable X. For example, CTRL-C instructs you to press the CTRL key while you simultaneously press the key lettered C.

End of Section 1

I!ID DIGITAL RESEARCHTN --------------------------

1-9

Section 2 The CCP and Transient Programs

This section discusses the Console Command Processor (CCP), built-in and transient commands, loading and exiting transient programs, and CP/M-68K memory models.

2.1 CCP Built-in and Transient Commands

After an initial cold start, CP/M-68K displays a sign-on message at the console. Drive A, containing the system disk, is logged in automatically. The standard prompt (», preceded by the letter A for the drive, is displayed on the console screen. This prompt informs the user that CP/M-68K is ready to receive a command line from the console.

In response to the prompt, a user types the filename of a command file and a command tail, if required. CP/M-68K supports two types of command files, built-in commands and transient commands. Built-in commands are configured and reside in memory with CP/M-68K. Transient commands are loaded in the TPA and do not reside in memory allocated to CP/M-68K. The following list contains the seven built-in commands that CP/M-68K supports.

DIR DIRS ERA REN TYPE USER SUBMIT

A transient command is a machine-readable executable program file in memory. A transient command file is loaded from disk to memory. Section 3 describes the format of transient command files.

l!]] DIGITAL RESEARCH™ -------------------------2-1

2.1 CCP Built-in and Transient Commands CP/M-68K Programmer's Guide

When the user enters a command line, the CCP parses it and tries to execute the file specified. The CCP assumes a file is a command file when it has any filetype other than .SUB. When the user specifies only the filename but not the filetype, the CCP searches for and tries to execute a file with a matching filename and a filetype of either 68K or three blanks. The CCP searches the current user number and User Number 0 for a matching file. If a command file is not found, but the CCP finds a matching file with a filetype of SUB, the CCP executes it as a submit file.

2.2 Loading a Program in Memory

Either the CCP or a transient program can load a program in memory with the BDOS Program Load Function (59) described in Section 4.5. Afterthe program is loaded, the TPA contains the program segments (text, data, and bss), a user stack, and a base page. A base page exists for each program loaded in memory. The base page is a 256-byte data structure that defines a program's operating environment. Unlike other CP/M systems, the base page in CP/M-68K does not reside at a fixed absolute address prior to being loaded. The BDOS Program Load Function (59) determines the absolute address of the base page when the program is loaded into memory. The BDOS Program Load Function (59) and the CCP or the transient program initialize the contents of the base page and the program's stack as described below.

2.2.1 Base Page Initialization by the CCP

The CCP parses up to two filenames following the command in the input command line. The CCP places the properly formatted FCBs in the base page. The default DMA address is initialized at an offset of 0080H in the base page. The default DMA buffer occupies the second half of the base page. The CCP initializes the default DMA buffer to contain the command tail, as shown in Figure 2-1. The CCP invokes the BDOS Program Load Function (59) to load the transient program before the CCP parses the command line.

Program Load, Function 59, allocates space for the base page and initializes base page values at offsets OOOOH through 0024H from the beginning of the base page (see Appendix C). Values at offsets 0025H through 0037H are not initialized; but the space is reserved. The CCP parses the command line and initializes values at offsets 0038H through OOFFH. Before the CCP gives control to the loaded program, the CCP pushes the address of the transient program's base page and a return address within the CCP on the user stack. When the program is invoked, the top of the stack contains a return address within the CCP, which is pointed to by the stack pointer, register A 7. The address of the program's base page is located at a 4-byte offset from the stack pointer.

-------------------------I!ID DIGITAL RESEARCHT•

2-2

CP/M-68K Programmer's Guide 2.2 Loading a Program in Memory

2.2.2 Loading Multiple Programs

Multiple programs can reside in memory, but the CCP can load only one program at a time. However, a transient program, loaded by the CCP, can load one or more additional programs in memory. A program loads another program in memory by invoking the BDOS Program Load Function (59). Normally, the CCP supplies FCBs and the command tail to this function. The transient program must provide this information, if required, for any additional programs it loads when the CCP is not present.

2.2.3 Base Page Initialization by a Transient Program

A transient program invokes the BDOS Program Load Function (59) to load an additional program. The BDOS Program Load Function allocates space and initializes base page values at offsets OOOOH through 0024H for the program as described in Section 2.2.1. The transient program must initialize the base page values that the CCP normally supplies, such as FCBs, the DMA address, and the command tail, if the program being loaded requires these values. The command tail contains the command parameters but not the command. The format of the command tail in the base page consists of a 1-byte character count, followed by the characters in the command tail, and terminated by a null byte as shown in Figure 2-1. The command tail cannot contain more than 126 bytes plus the character count and the terminating null character.

COUNT CHARACTERS IN THE COMMAND TAIL o 1 BYTE N BYTES :5 126 BYTES

Figure 2-1. Format of the Command Tail in the DMA Buffer

Unlike the CCP, a transient program does not necessarily push the address of its base page and a return address on the user stack before giving control to the program that it loads with the Program Load Function. The transient program can be designed to push these addresses on the user stack of the program it loads if the program uses the base page.

The address of the base page for the loaded program is not pushed on the user stack by the Program Load Function (59). Instead, it is returned in the load parameter block (LPB), which is used by the BDOS Program Load Function. Appendix C summarizes the offsets and contents of a base page. Appendix B contains two examples, an assembly language program and a C language program, which illustrate how a transient program loads another program with the BDOS Program Load Function (59), but without the CCP. .

I!ID DIGITAL RESEARCHT• --------------------------

2-3

2.3 Exiting Transient Programs CP/M-68K Programmer's Guide

2.3 Exiting Transient Programs

CP/M-68K supports two ways to exit a transient program and return control to the CCP:

• Interactively, the user types CTRL-C at the console, the default I/O device

• Program a return to the CCP with either:

1. a Return From Subroutine (RTS) Instruction 2. the BDOS System Reset Function (0)

A user typing CTRL-C from the console returns control to the CCP only if the program uses any of the following BDOS functions.

• Console Output (2) • Print String (9) • Read Console Buffer (10)

On input, CTRL-C must be the first character that the user types on the line. CTRL-C terminates execution of the main program and any additional programs loaded beyond the CCP level. For example, a user who types CTRL-C while debugging a program terminates execution of the program being debugged and DDT-68K before the CCP regains control.

Typing CTRL-C in response to the system prompt resets the status of all disks to read-write.

To program a return to the CCP, specify a Return from Subroutine (RTS) Instruction or the BDOS System Reset Function (0).

The RTS instruction must be the last one executed in the program and the top of the stack must contain the system-supplied return address for control to return to the CCP. When a transient program begins execution, the top of the stack contains this systemsupplied return address. If the program modifies the stack, the top of the stack must contain this system-supplied return address before an R TS instruction is executed.

Invoking the BDOS System Reset Function (0) described in Section 4.5 is equivalent to programming a return to the CCP. This function performs a warm boot, which terminates the execution of a program before it returns program control to the CCP.

--------------------------[!ID DIGITAL RESEARCH™ 2-4

CP/M-68K Programmer's Guide 2.4 Transient Program Execution Model

2.4 Transient Program Execution Model

The memory model shown in Figure 2-2 illustrates the normal configuration of the CP/M-68K operating system after the CCP loads a transient program. CP/M-68K divides memory in two categories: System and the Transient Program Area (TPA).

CP/M-68K System memory contains the Basic Disk Operating System (BDOS), the Basic 110 System (BIOS), the Console Command Processor (CCP), and Exception Vectors. The bootstrap program initializes the memory locations in which these components reside. Other than exception vectors, which reside in memory locations OOOOH through 03fFH, the remaining components can reside anywhere in memory, provided the BDOS and CCP are contiguous.

The TPA consists of contiguous memory locations that are not occupied by the CP/M-68K operating system. A user stack, a base page, the three program segments (a text segment, an initialized data segment, and a block storage segment (bss)) exist for each transient program loaded in the TPA. The BDOS Program Load Function (59) loads a transient program in the TP A. If memory locations are not specified when the transient program is linked, the program is loaded in the TPA as shown in Figure 2-2.

HIGH MEMORY

SYSTEM

r-TRANSIENT PROGRAM

AREA (TPA)

SYSTEM

1

L BIOS

CP/M-68K BOOS CCP

USER STACK

FREE MEMORY

BSS

DATA

TEXT

BASE PAGE

EXCEPTION VECTORS

Figure 2-2. CP/M-68K Default Memory Model


2.4 Transient Program Execution Model CP/M-68K Programmer's Guide

Some systems can configure and load CP/M-68K in such a manner that one or more portions of memory cannot be addres~ed by the CP/M-68K operating system (see Figure 2-3). CP/M-68K cannot access this memory. CP/M-68K does not' know the memory exists and cannot define or configure the memory in the BIOS because CP/M-68K requires that the TPA is one contiguous area. However, a transient program that knows this memory exists can access it. Also, note that CP/M-68K does not support or require memory management.

HIGH MEMORY

SYS TEM

I-SIENT TRAN

PROG AR (TP

RAM EA A)

SYS TEM I LOW MEMORY

1

NOT ACCESSIBLE TO CP/M-68K

C BIOS

CP/M-68K BOOS cCP

USER STACK

FREE MEMORY

BSS

DATA

TEXT

BASE PAGE

EXCEPTION VECTORS

Figure 2-3. CP/M-68K Memory Model with Inaccessible Memory

End or Section 2

---------------------,------I!ID DIGITAL RESEARCH™ 2-6

Section 3 Command File Format

This section describes the format of a command file. The linker processes one or more compiled or assembled files to produce an executable machine-readable file called a command file. By default, a command file has a filetype of 68K.

A command file always contains a header, two program segments (a text segment and an initialized data segment), and optionally contains a symbol table and relocation information. These components are described in the following sections.

3.1 The Header and Program Segments

The header, the first component in the file, specifies the size and starting address of the other components in the command file, which are listed below.

• Program segments:

text: contains the program instructions.

data: contains data initialized within the command file.

block storage segment (bss): specifies space for uninitialized data generated by the program during execution. Although space for the bss is specified in the source command file, the space is not allocated until the command file is loaded in memory. Therefore,.the source command file on the disk contains no uninitialized data.

• Symbol table: defines referenced symbols.

• Relocation information: specifies the relative relocation of each word within each program segment, if required.

I!ID DIGITAL RESEARCHTN --------------------------3-1

3.1 The Header and Program Segments CP/M-68K Programmer's Guide

The command file format supports two types of headers. The size and content of each type differs. The contiguity of the program segments determines which type of header a command file contains. When the program segments must be contiguous, the file contains a 14-word header in the format shown in Figure 3-1. When the program segments can be noncontiguous, the file contains an 18-word header in the format shown in Figure 3-2. The first word of each header contains a hexadecimal integer that defines which type of header the file contains.

BYTE OFFSET

OH

2H

6H

OAH

OEH

12H

16H

1AH

SAMPLE VALUES

601AH I 2376H

422H

1806H

142H

OOOOH

500H

OOH I

SIZE

1 WORD

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 WORD

CONTENTS

INTEGER 601AH DENOTES TEXT, DATA, AND BSS ARE CONTIGUOUS

NUMBER OF BYTES IN TEXT SEGMENT

NUMBER OF BYTES IN DATA SEGMENT

NUMBER OF BYTES IN BSS

NUMBER OF BYTES IN SYMBOL TABLE

RESERVED; ALWAYS ZERO

BEGINNING OF TEXT SEGMENT AND OF PROGRAM EXECUTION

INTEGER FLAG FOR RELOCATION BITS; IF 0, RELOCATION BITS EXIST; IF NOT 0, NO RELOCATION BITS EXIST.

Figure 3-1. Header for Contiguous Program Segments

To create a file that can contain noncontiguous program segments, specify the -T, -D, and -B linker options described in Section 6 when you link the files. The header, identified by 601BH denotes the size and location of each program segment. Note that this header indicates the program segments can be noncontiguous and does not imply the segments must be noncontiguous. See Figure 3-2.

--------------------------- [!ID DIGITAL RESEARCH'" 3-2

CP/M-68K Programmer's Guide

BYTE OFFSET

OH

2H

6H

OAH

OEH

12H

16H

1AH

SAMPLE VALUES

601BH I 57864H

446H

2568H

69H

OOOOH

500H

~OH I

1CH ~ ___ 5_7_D_6_4H ___ -i

20H 581AAH ~-------~

SIZE

1 WORD

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 WORD

1 LONGWORD

1 LONGWORD

3.1 The Header and Program Segments

CONTENTS

INTEGER 601BH DENOTES TEXT, DATA, AND BSS CAN BE NONCONTIGUOUS

NUMBER OF BYTES IN TEXT SEGMENT

NUMBER OF BYTES IN DATA SEGMENT

NUMBER OF BYTES IN BSS

NUMBER OF BYTES IN SYMBOL TABLE

RESERVED; ALWAYS ZERO

BEGINNING OF TEXT SEGMENT AND OF PROGRAM EXECUTION

INTEGER FLAG FOR RELOCATION BITS; IF 0, RELOCATION BITS EXIST; IF NOT 0, NO RELOCATION BITS EXIST.

STARTING ADDRESS OF DATA SEGMENT

STARTING ADDRESS OF BSS

Figure 3-2. Header for Noncontiguous Program Segments

The linker computes the size of the segments in bytes. The result is always rounded up to an even number. For example, the linker adds a byte to a program segment that contains an odd number of bytes. The linker does not include the size of the header when it computes the size of the segments.

After a program is linked and loaded in memory, it contains three program segments: text, initialized data, and uninitialized data (bss). The BDOS Program Load Function (59) zeroes the bss when a program is loaded. A program begins execution at the beginning of the text segment. See Figures 3-1 and 3-2.

lrn DIGITAL RESEARCH'" ---------------------------3-3

3.2 The Symbol Table CP/M-68K Programmer's Guide

3.2 The Symbol Table

The symbol table lists all the symbols specified in a program. Each symbol in the table consists of a 7 -word entry that describes the symbol name, type, and value. See Figure 3-3.

FIELD BYTE

/ N A

M E

WORD

NAME

'" NULL NULL

NULL NULL

TYPE --. A400H

/ VALUE A6FOH

" Figure 3-3. Entry in Symbol Table

------------------------[ID DIGITAL RESEARCH™ 3-4

CP/M-68K Programmer's Guide 3.2 The Symbol Table

The name field, the first four words, contains the ASCII name of the symbol. This field is padded with null characters when the ASCII name is less than eight characters. The fifth word contains the symbol type. Valid values are listed in Table 3-1.

Table 3-1. Values For Symbol Types

Type I Value

defined 8000H

equated 4000H

global 2000H

equated register 1000H

external reference 800H

data based relocatable 400H

text based relocatable 200H

bss based relocatable 100H

When specifying a symbol type with multiple characteristics, the linker uses an OR instruction to combine several of the preceding values. For example, to specify a defined, global, data based, relocatable symbol, the linker combines the values of each characteris- . tic for a value of A400H.

The last field in an entry is the value field. It consists of a longword that contains the value of the symbol. The value can be an address, a register number, the value of an expression, or some other value. When the value field is nonzero and the type field contains an external symbol, the linker interprets the symbol to be a common region in which the size of the region equals the value of the symbol.


3-5

3.2 The Symbol Table CP/M-68K Programmer's Guide

3.2.1 Printing the Symbol Table

Use the NM68 Utility to print the symbol table of an object or command file. To invoke this utility, specify the NM68 command and filename as shown.

NM68 filename.O [>filespec]

You must enter the filename of an object file or a command file. You can optionally redirect the NM68 output from your console to a file. To redirect the NM68 output to a file, specify a greater than sign (» followed by a file specification after the filename and filetype of the file from which NM68 prints the symbol table.

The NM68 utility does not sort the symbols; it prints them in the order in which they appear in the file. Each symbol name is printed, followed by its value and one or more of the following type descriptors:

• equ (equated) • global • equreg (equated register) • external • data • text • bss • abs (absolute)

3.3 Relocation Information

Relocation information is optional. The header relocation word, the last word in the header, indicates whether relocation information exists. When its value is zero, relocation information exists. None exists when the its value is nonzero.

Relocation information specifies the relocation of words in program segments. One word of relocation information, called a relocation word, exists for each word in each of the program segments. The assembler and compiler generate relocation words for external symbols and address constants referenced in the text and data program segments. The linker and sometimes the BDOS Program Load Function (59) use these relocation words as described in Table 3-2.

--------------------------OCID DIGITAL RESEARCH™ 3-6

CP/M-68K Programmer's Guide 3.3 Relocation Information

The linker resolves external symbols when linking files by modifying bits 0 through 2 of each relocation word that references an external symbol. After being modified, the relocation word indicates the program segment that the symbol references. Therefore, instead of referencing an external symbol, the relocation word references a word located in one of the program segments. Because the linker only modifies relocation words that refer to external symbols, relocation words that do not reference this type of symbol have the same value in the source file input to the linker and the executable file output by the linker.

The BDOS Program Load Function uses relocation words when it loads a program in a location other than the one at which it was linked. The Program Load Parameter Block (LPB) used by the Program Load Function specifies where the program is loaded. When the LPB specifies a location other than the linked location, the BDOS computes a bias (the difference between where a program segment is linked and where it will be loaded in memory). When loading the program, the BDOS adds the bias as indicated by the relocation words to the address of the relocatable words in the text and/or data segments. However, when the BDOS loads the program in the memory locations at which it was linked, the BDOS does not use the relocation words.

I!ID DIGITAL RESEARCHTN

3-7

3.3 Relocation Information CP/M-68K Programmer's Guide

3.3.1 The Format of a Relocation Word

A relocation word is a 16-bit quantity. Bits 0 through 2 in each relocation word indicate the type of address referenced and, if applicable, designate the segment to which the relocation word refers. Values for these bits are described in Table 3-2.

Value I 00

01

02

03

04

05

06

07

Table 3-2. Relocation Word Values (bits 0 through 2)

Description

no relocation information required; the reference is absolute

reference relative to the base address of the data segment

referenc~ relative to the base address of the text segment

reference relative to the base address of the bss

references an undefined symbol

references the upper word of a longword; the next relocation word contains the value determining whether the reference is absolute or dependent on the base address of the text or data segments, or the bss.

16-bit PC-relative reference

indicates the first word of an instruction, which does not require relocation information.

The remaining bits, 3 through 15, are not used unless the program references an external symbol. In that case, these bits contain an index to the symbol table. The index specifies the entry number of the symbol listed in the symbol table. Entry numbers iri the symbol table are numbered sequentially starting with zero.

End of Section 3

-------------------------- [!]I DIGITAL RESEARCHT. 3-8

Section 4 Basic Disk Operating System

(BDOS) Functions

To access a file or a drive, to output characters to the console, or to reset the system, your program must access the CP/M-68K file system through the Basic Disk Operating System (BDOS). The BDOS provides functions that allow your program to perform these tasks. Table 4-1 summarizes the BDOS functions.

Table 4-1. CP/M-68K BDOS Functions

F# I Function I Type

0 System Reset System/Program Control 1 Console Input Character 110, Console Operation 2 Console Output Character I/O, Console Operation 3 Auxiliary Input*· Character 110, Additional Serial I/O 4 Auxiliary Output* Character 110, Additional Serial 11O 5 List Output Character 110, Additional Serial 11O 6 Direct Console I/O Character 110, Console Operation 7 Get I/O Byte* 110 Byte 8 Set 110 Byte * 110 Byte 9 Print String Character 110, Console Operation

10 Read Console Buffer Character I/O, Console Operation 11 Get Console Status Character 110, Console Operation 12 Return Version Number System Control 13 Reset Disk System Drive 14 Select Disk Drive 15 Open File File Access 16 Close File File Access 17 Search for First File Access 18 Search for Next File Access 19 Delete File File Access 20 Read Sequential File Access

* Must be implemented in the BIOS

[QJ DIGITAL RESEARCHTN -------------------------

4-1

4 Basic Disk Operating System (BDOS) Functions CP/M-68K Programmer's Guide

Table 4-1. (continued)

F# I Function I Type

21 Write Sequential File Access 22 Make File File Access 23 Rename File File Access 24 Return Login Vector Drive 25 Return Current Disk Drive 26 Set DMA Address File Access 28 Write Protect Disk Drive 29 Get Read-Only Vector Drive 30 Set File Attributes File Access 31 Get Disk Parameters Drive 32 Set/Get User Code System/Program Control 33 Read Random File Access 34 Write Random File Access 35 Compute File Size File Access 36 Set Random Record File Access 37 Reset Drive Drive 40 Write Random With File Access

Zero Fill 46 Get Disk Free Space Drive 47 Chain To Program System/Program Control 48 Flush Buffers System/Program Control 50 Direct BIOS Call System/Program Control 59 Program Load System/Program Control 61 Set Exception Vector Exception 62 Set Supervisor State Exception 63 Get/Set TP A Limits Exception

-------------------------\!ID DIGITAL RESEARCHTN

4-2

CP/M-68K Programmer's Guide 4.1 BDOS Functions and Parameters

4.1 BDOS Functions and Parameters

To invoke a BDOS function, you must specify one or more parameters. Each BDOS function is identified by a number, which is the first parameter you must specify. The function number is loaded in the first word of data register DO (DO.W). Some functions require a second parameter, which is loaded, depending on its size, in the low order word (D1.W) or longword (D1.L) of data register D1. Byte parameters are passed as 16-bit words. The low order byte contains the data, and the high order byte should be zeroed. For example, the second parameter for the Console Output Function (2) is an ASCII character, which is a byte parameter. The character is loaded in the low order byte of data register Dl (D1.W). Some BDOS functions return a value, which is passed in the first word of data register DO (DO.W). The hexadecimal value FFFF is returned in register DO.W when you specify an invalid function number in your program. Table 4-2 illustrates the syntax and summarizes the registers that BDOS functions use.

Table 4-2. BDOS Parameter Summary

BDOS Parameter

Function Number Word Parameter Longword Parameter Return Value,ifany

4.1.1 Invoking BDOS Functions

I Register

DO.W D1.W D1.L DO.W

After the parameters for a function are loaded in the appropriate registers, the program must specify a Trap 2 Instruction to access the BDOS and invoke the function. The following example illustrates the assembler syntax required to invoke the Console Output Function (2).

frlOl.le .1..,1 #2 tdO *Moves the function nUMber to the first *word in data re~ister DO.

frlol.Je.I..,1 #'U' tdl *Mol.les the ASCII character upper-case U *to the first word in data re~ister 01.

trap #2 *Accesses the BOOS to invoKe the function.

I!ID DIGITAL RESEARCH™ ---------------------------4-3

4.1 BDOS Functions and Parameters CP/M-68K Programmer's Guide

The example above outputs the ASCII character upper-case U to the console. The assembler move instructions load register DO.W with the number 2 for the BDOS Console Output Function and register D1.W with the ASCII character upper-case U. A pair of single (") or double ("") quotation marks must enclose an ASCII character. The Trap 2 Instruction invokes the £DOS Output Console Function, which echos the character on the console's screen.

4.1.2 Organization of BDOS Functions

The parameters and operation performed by each BDOS function are described in the following sections. Each BDOS function is categorized according to the function it performs. The categories are listed below.

• File Access • Drive Access • Character I/O • System/Program Control • Exception

As you read the description of the functions, notice that some functions require an address parameter designating the starting location of the direct memory access (DMA) buffer or file control block (FCB). The DMA buffer is an area in memory where a 128-byte record resides before a disk write function and after a disk read operation. Functions often use the DMA buffer to obtain or transfer data. The FCB is a 33- or 3 6-byte data structure that file access functions use. The FCB is described in Section 4.2.1.

4.2 File Access Functions

This section describes file access functions that create, delete, search for, read, and write files. They include the functions listed in Table 4-3.

--------------------------llID DIGITAL RESEARCH™ 4-4

CP/M-68K Programmer's Guide 4.2 File Access Functions

Table 4-3. File Access Functions

Function

Open File

Close File

Search For First

Search For Next

Delete File

Read Sequential

Write Sequential

Make File

Rename File

I

Set DMA Address

Read Random

Write Random

Compute File Size

Write Random With Zero Fill

4.2.1 A File Control Block (FCB)

Function Number

15

16

17

18

19

20

21

22

23

26

33

34

35

40

Most of the file access functions in Table 4-3 require the address of a File Control Block (FCB). A FCB is a 33- or 36-byte data structure that provides file access information. The FCB can be 33 or 36 bytes when a file is accessed sequentially, but it must be 36 bytes when a file is accessed randomly. The last three bytes in the 36-byte FCB contain the random record number, which is used by random I/O functions and the Compute File Size Function (35). The starting location of a FCB must be an even-numbered address. The format of a FCB and definitions of each of its fields follow.

[!ID DIGITAL RESEARCH™ -------------------------4-5

4.2 File Access Functions CP/M-68K Programmer's Guide

Field

Byte 00 01 02 08 09 10 11 12 13 14 15 16

dr drivecode(0-16) o = > use default drive for file 1 = > auto disk select drive A, 2 = > auto disk select drive B,

16 = > auto disk select drive P.

f1. .. f8 contain the filename in ASCII upper-case. High bit should equal 0 when the file is opened.

t1,t2,t3 contain the filetype in ASCII

ex

s1

s2

rc

dO ... dn

upper-case. The high bit should equal 0 when the file is opened. For the Set File Attributes Function (see Section 4.2.13), t1', t2', and t3' denote the high bit. The following list indicates which attributes are set when these bits are set and equal the value 1. tl' = 1 = > Read-Only file t2' = 1 = > SYS file t3' = 1 = > Archive

contains the current extent number, normally set to 00 by the user, but is in the range 0 - 31 (decimal) for file 1/0

reserved for internal system use

reserved for internal system use, set to zero for Open (15), Make (22), Search (17,18) file functions.

record count field, reserved for system use

filled in by CPIM, reserved for system use

31 32 33 34 35

------------------------- IIID DIGITAL RESEARCHTM 4-6


cr current record to be read or written; for a sequential read or write file operation, the program normally sets this field to zero to access the first record in the file

rO,rl ,r2 optional, contain random record number in the range 0-3FFFFH; bytes rO, rl, and r2 are a 24-bit value with the most significant byte rO and the least significant byte r2. Random I/O functions use the random record number in this field.


For users of other versions of CP/M, note that both CP/M-SO Version 2.2 and CP/M-6SK perform directory operations in a reserved area of memory that does not affect the DMA buffer contents, except for the Search For First (17) and Search For Next (IS) Functions in which the directory record is copied to the current DMA buffer.

4.2.2 File Processing Errors

When a program calls a BDOS function to process a file, an error condition can cause the BDOS to return one of five error messages to the console:

• CP/M Disk read error • CP/M Disk write error • CP/M Disk select error • CP/M Disk change error • CP/M Disk file error: ffffffff.ttt is read-only.

Except for the CP/M Disk file error, CP/M-6SK displays the error message at the console in the format:

"error message text" on drive x

The "error message text" is one of the error messages listed above. The variable x is a one-letter drive code that indicates the drive on which CP/M-6SK detects the error. CP/M-6SK displays the CP/M Disk file error in the preceding format.

When CP/M-6SK detects one of these errors, the BDOS traps it. CP/M-6SK displays a message indicating the error and, depending on the error, allows you to abort the program, retry the operation, or continue processing. Each of these errors and their options are described in Table 4-4.

lIID DIGITAL RESEARCH™ --------------------------4-7


CP/M issues a CP/M Disk read or write error when the BDOS receives a hardware error from the BIOS. The BDOS specifies BIOS read and write sector commands when the BDOS executes file-related system functions. If the BIOS read or write routine detects a hardware error, the BIOS returns an error code to the BDOS that results in CP/M-68K displaying a disk read or write error message at your console. In addition to the error message, CP/M-68K also displays the option message:

Do YOU want to Abort (A) t Retry (R) t or Continue with bad data (C)?

In response to the option message, you type one of the letters enclosed in parentheses and a RETURN. Table 4-4 describes each of these options.

Option I A

R

C

Table 4-4. Read-Write Error Message Response Options

Action

The A option or CTRL-C aborts the program and returns control to the CCP. CP/M-68K returns the system prompt (» preceded by the drive code.

The R option retries the operation that caused the error. For example, it rereads or rewrites the sector. If the operation succeeds, program execution continues as if no error occurred. However, if the operation fails, the error message and option message is displayed again.

The C option ignores the error that occurred and continues program execution. The C option is not an appropriate response for all types of programs. Program execution should not be continued in some cases. For example, if you are updating a data base and receive a read or write error but continue program execution, you can corrupt the index fields and the entire data base. For other programs, continuing program execution is recommended. For example, when you transfer a long text file and receive an error because one sector is bad, you can continue transferring the file. After the file is transferred, review the file. Using an editor, add the data that was not transferred due to the bad sector.

Any response other than an A, R, C, or CTRL-C is invalid. The BDOS reissues the option message if you enter any other response.

-------------------------- [!ill DIGITAL RESEARCH™ 4-8


The CP/M Disk select error occurs when you select a disk but you receive an error due to one of the following conditions.

• You specified a disk drive not supported by the BIOS. • The BDOS receives an error from the BIOS. • You specified a disk drive outside the range A through P.

Before the BDOS issues a read or write function to the BIOS, the BDOS issues a disk select function to the BIOS. If the BIOS does not support the drive specified in the function, or if an error occurs, the BIOS returns an error to the BDOS, which in turn, causes CP/M-68K to display the disk select error at your console. If the error is caused by a BIOS error, CP/M-68K returns the option message:

Do you want to Abort (A) orRetry (R)?

To select one of the options in the message, specify one of the letters enclosed in parentheses. The A option terminates the program and returns control to the CCP. The R option tries to select the disk again. If the disk select function fails, CP/M-68K redisplays the disk select error message and the option message.

However, if the error is caused because you specify a disk drive outside the range A through P, only the CP/M Disk select error is displayed. CP/M-68K aborts the program and returns control to the CCP.

Your console displays the CP/M Disk change error message when the BDOS detects the disk in the drive is not the same disk that was logged in previously. Your program cannot recover from this error. Your program terminates. CP/M-68K returns program control to the CCP.

You log in a disk by accessing the disk or resetting the disk or disk system. The Select Disk Function (14) resets a disk. The Reset Disk System Function (13) resets the disk system. Files cannot be open when your program invokes either of these functions.

You receive the CP/M Disk file error and option messages (shown below) if you call the BDOS to write to a file that is set to read-only status. Either a STAT command or the BDOS Set File Attributes Function (30) sets a file to read-only status.

[!Q] DIGITAL RESEARCHT• --------------------------

4-9


CP/M DisK file error: ffffffff.ttt is read only.

Do YOU want to: ChanSe it to read/write (C) f or Abort (A)?

The variable ffffffff.ttt in the error message denotes the filename and filetype. To select one of the options, specify one of the letters enclosed in parentheses. Each option is described in Table 4-5.

Option I C

A

Table 4-5. Disk File Error Response Options

Action

Changes the status of this file from read-only to read-write and continues executing the program that was being processed when this error occurred.

Terminates execution of the program that was being processed and returns program control to the CCP. The status of the file remains read-only. If you enter a CTRL-C, it has the same effect as specifying the A option.

CP/M-68K reprompts with the option message if you enter any response other than those described above.

--------------------------[!ID DIGITAL RESEARCH TN

4-10


4.2.3 Open File Function

FUNCTION 15: OPEN FILE

Entry Parameters: Register DO.W: OFH

Register D 1.L: FCB Address

Returned Values: Register DO. W: Return Code

success: OOH - 03H error: FFH


The Open File Function matches the filename and filetype fields of the FCB specified in register D1.L with these fields of a directory entry for an existing file on the disk. When a match occurs, the BDOS sets the FCB extent (ex) field and the second system (S2) field to zero before the BDOS opens the file. Setting these one-byte fields to zero opens the file at the base extent, the first extent in the file. In CP/M-68K, files can be opened only at the base extent. In addition, the physical I/O mapping information, which allows access to the disk file through subsequent read and write operations, is copied to fields dO through dn of the FCB. A file cannot be accessed until it has been opened successfully. The open function returns an integer value ranging from OOH through 03H in DO.W when the open operation is successful. The value FFH is returned in register DO.W when the file cannot be found.

The question mark (?) wildcard can be specified for the filename and filetype fields of the FCB referenced by register D1.L. The? wildcard has the value 3FH. For each position containing a ? wildcard, any character constitutes a match. For example, if the filename and filetype fields of the FCB referenced by D1.L contain only? wildcards, the BDOS accesses the first directory entry. However, you should not create a FeB of all wildcards for this function because you cannot ensure which file this function opens.

Note that the current record field (cr) in the FCB must be set to zero by the program for the first record in the file to be accessed by subsequent sequential I/O functions. However, setting the current record field to zero is not required to open the file.

i!ID DIGITAL RESEARCHT• -------------------------

4-11


4.2.4 Close File Function

FUNCTION 16: CLOSE FILE

Entry Parameters: Register DO.W: 10H Register D1.L: FCB Address

Returned Values: Register DO.W: Return Code

success: OOH-03H error: FFH

The Close File Function performs the inverse of the Open File Function. When the FCB passed in D1.L was opened previously by either an Open File (15) or Make File (22) Function, the close function updates the FCB in 'the disk directory. The process used to match the FCB with the directory entry is identical to the Open File Function (15). An integer value ranging from OOH though 03H is returned in DO.W for a successful close operation. The value FFH is returned in DO.W when the file cannot be found in the directory. When only read functions access a file, closing the file is not required. However, a file must be closed to update its disk directory entry when write functions access the file.

-------------------------I!ID DIGITAL RESEARCH™ 4-12


4.2.5 Search For First Function

FUNCTION 17: SEARCH FOR FIRST

Entry Parameters: Register DO.W: 11H Register D 1.L: FCB Address



The Search For First Function scans the disk directory allocated to the current user number to match the filename and filetype of the FCB addressed in register D1.L with the filename and filetype of a directory entry. The value FFH is returned in register DO.W when a matching directory entry cannot be found. An integer value ranging from OOH through 03H is returned in register DO.W when a matching directory entry is found.

The directory record containing the matching entry is copied to the buffer at the current DMA address. Each directory record contains four directory entries of 32 bytes each. The integer value returned in DO. W indexes the relative location of the matching directory entry within the directory record. For example, the value 01H i~dicates that the matching directory entry is the second one in the directory record in the buffer. The relative starting position of the directory entry within the buffer is computed by multiplying the value in DO.W by 32 (decimal), which is equivalent to shifting the binary value of DO.W left 5 bits.

When the drive (dr) field contains a ? wildcard, the auto disk select function is disabled and the default disk is searched. All entries including empty entries for all user numbers in the directory are searched. The search function returns any matching entry, allocated or free, that belongs to any user number. An allocated directory entry contains the filename and filetype of an existing file. A free entry is not assigned to an existing file. If the 'first byte of the directory entry is ESH, the entry is free. A free entry is not always empty. It can contain the filename and filetype of a deleted file because the directory entry for a deleted file is not zeroed.



4.2.6 Search For Next Function

FUNCTION 18: SEARCH FOR NEXT

Entry Parameters: Register DO.W: 12H



The Search For Next Function scans the disk directory for an entry that matches the FCB and follows the last matched entry, found with this or the Search For First Function (17).

A program must invoke a Search For First Function before invoking this function for the first time. Subsequent Search For Next Functions can follow, but they must be specified without other disk related BDOS functions intervening. Therefore, a Search For Next Function must follow either itself or a Search For First Function.

The Search For Next Function returns the value FFH in DO.W when no more directory entries match.

-------------------------- rrn DIGITAL RESEARCH™

4-14


4.2.7 Delete File Function

FUNCTION 19: DELETE FILE



success: OOH error: FFH


The Delete File Function removes files and deallocates the directory entries for and space allocated to files that match the filename in the FCB pointed to by the address passed in D1.L. The filename and filetype can contain wildcards, but the drive select code cannot be a wildcard as in the Search For First (17) and Search For Next (18) Functions. The value FFH is returned in register DO.W when the referenced file cannot be found. The value OOH is returned in DO.W when the file is found.

IIID DIGITAL RESEARCHT• --------------------------

4-15


4.2.8 Read Sequential Function

FUNCTION 20: READ SEQUENTIAL



success: OOH error: 01H

The Read Sequential Function reads the next 128-byte record in a file. The FCB passed in register D1.L must have been opened by an Open File (15) or the Make File Function (22) before this function is invoked. The program must set the current record field to zero following the open or make function to ensure the file is read from the first record in the file. After the file is opened, the Read Sequential Function reads the 128-byte record specified by the current record field from the disk file to the current DMA buffer. The FCB current record (cr) and extent (ex) fields indicate the location of the record that is read. The current record field is automatically incremented to the next record in the extent after a read operation.

When the current. record field overflows, the next logical extent is automatically opened and the current record field is reset to zero before the read operation is performed. After the first record in the new extent is read, the current record field contains the value 01H.

The value OOH is returned in register DO.W when the read operation is successful. The value of 01H is returned in DO.W when the record being read contains no data. Normally, the no data situation is encountered at the end of a file. However, it can also occur when this function tries to read either a previously unwritten data block or a nonexistent extent. These situations usually occur with files created or appended with the BDOS Write Random Function (34).



4.2.9 Write Sequential Function

FUNCTION 21: WRITE SEQUENTIAL

Entry Parameters: Register DO.W: lSH RegisterD1.L: FCBAddress


success: OOH error: 01Hor02H

The Write Sequential Function writes a 128-byte record from the DMA buffer to the disk file whose FCB address is passed in register D 1.L. The FCB must be opened by either an Open File (15) or Make File (22) Function before your program invokes the Write Sequential Function. The record is written to the current record, specified in the FCB current record (cr) field.

The current record field is automatically incremented to the next record. When the current record field overflows, the next logical extent of the file is automatically opened and the current record field is reset to zero before the write operation. After the write operation, the current record field in the newly opened extent is set to 01H.

Records can be written to an existing file. However, newly written records can overlay existing records in the file because the current record field usually is set to zero after a file is opened or created to ensure a subsequent sequential 1/0 function accesses the first record in the file.

The value OOH is returned in register DO.W when the write operation is successful. A nonzero value in register DO.W indicates the write operation is unsuccessful due to one of the following conditions.

[ID DIGITAL RESEARCH™ --------------------------4-17


Value I 01

02

Table 4-6. Unsuccessful Write Operation Return Codes

Meaning

No available directory space - This condition occurs when the write command attempts to create a new extent that requires a new directory entry and no available directory entries exist on the selected disk drive.

No available data block - This condition is encountered 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.

-------------------------- [jID DIGITAL RESEARCHTN

4-18


4.2.10 Make File Function

FUNCTION 22: MAKE FILE



success: OOH - 03H error: FFH


The Make File Function creates and opens a new file on a specified disk or the default disk. The address of the FCB for the file is passed in register D1.L. You must ensure the FCB contains a filename that does not already exist in the referenced disk directory. The drive field (dr) in the FCB indicates the drive on which the directory resides. The disk directory is on the default drive when the FCB drive field contains a zero.

The BDOS creates the file and initializes the directory and the FCB in memory to indicate an empty file. The program must ensure that no duplicate filenames occur. Invoking the Delete File Function (19) prior to the Make File Function excludes the possibility of duplicate filenames.

Register DO.W contains an integer value in the range OOH through 03H when the function is successful. Register DO.W contains the value FFH when a file cannot be created due to insufficient directory space.

[!ID DIGITAL RESEARCHT• --------------------------

4-19

4.2 File Access Functions CP/M-6SK Programmer's Guide

4.2.11 Rename File Function

FUNCTION 23: RENAME FILE




The Rename File Function uses the FCB specified in register D1.L to change the filename and filetype of all directory entries for a file. The first 12 bytes of the FCB contains the file specification for the file to be renamed as shown in Figure 4-1. Bytes 16 through 27 (dO through d12) contain the new name of the file. The filenames and filetypes specified must be valid for CP/M. Wildcards cannot be specified in the filename and filetype fields. The FCB drive field (dr) at byte position 0 selects the drive. This function ignores the drive field at byte position 16, if it is specified for the new filename. Register DO.W contains th~ value zero when the rename function is successful. It contains the value FFH when the first filename in the FCB cannot be found during the directory scan.

FCB byte position

FCB BYTE POSITION

o 1 2 3 4 5 6 7 a 9 10 11 16 17 18 19 20 21 22 23 . . . 27

I DR I F1 I F2 I F3 I F4 I F5 I F6 I F7 I Fa I TL I T2 I T3 I ... 1 DO 1 01 1 02 1 03 1 04 1 05 1 06 1 07 I ... 1 0121 .. ·1

I I I I OLD FILE SPECIFICATION NEW FILE SPECIFICATION

Figure 4-1. FCB Format for Rename Function

In the above figure, horizontal ellipses indicate FCB fields that are not required for this function. Refer to Section 4.2.1 for a description of all FCB fields.



4.2.12 Set Direct Memory Access (DMA) Address Function

FUNCTION 26: SET DMA ADDRESS

Entry Parameters: Register DO. W: 1AH Register D1.L: DMAAddress

Returned Values: Register DO.W: OOH

The Set DMA Address Function sets the starting address of the 128-byte DMA buffer. DMA is an acronym for Direct Memory Access, which often refers to disk controllers that directly access memory to transfer data to and from the disk subsystem. Many computer systems use non-DMAaccess in which the data is transferred through programmed I/O operations. In CP/M the term DMA is used differently. The DMA address in CP/M-68K is the beginning address of a 128-byte data buffer, called the DMA buffer. The DMA buffer is the area in memory where a data record resides before a disk write operation and after a disk read operation. The DMA buffer can begin on an even or odd address.

I!ID DIGITAL RESEARCHTN -------------------------

4-21


4.2.13 Set File Attributes Function

FUNCTION 30: SET FILE A TIRIBUTES

Entry Parameters: Register DO.W: 1EH Register D1.L: FCB Address



The Set File Attributes Function sets or resets file attributes supported by CP/M-68K and user defined attributes' for application programs. CP/M-68K supports read-only, system, and archive attributes.

The high bit of each character in the ASCII filename (£1 through f8) and filetype (t1 through t3) fielcfs in the FCB denotes whether attributes are set. When the high bit in any of these fields has the value 1, the attribute is set. Table 4-7 denotes the FCB fields and their attributes.

The address of the FeB is passed in register D1.L. Wildcards cannot be specified in the filename and filetype fields.

This function searches the directory on the disk drive, specified in the FCB drive field (dr), for directory entries that match the FCB filename and filetype fields. All matching directory entries are updated with the attributes this function sets.

A zero is returned in register DO.W when the attributes are set. However, if a matching entry cannot be found, register DO.W contains FFH.

-------------------------l!ID DIGITAL RESEARCHT. 4-22


Table 4-7. File Attributes

Field I Attribute

f1 through f4 User-defined attributes for application programs.

f5 through f8 Reserved for future use by CP/M-68K.

t1

t2

t3

The Read-Only attribute indicates the file status is Read-Only. The BDOS does not allow write commands to write to a file whose status is Read-Only. The BDOS does not permit a Read-Only file to be deleted or renamed.

The System attribute indicates the file is a system file. Some built-in commands and system utilities differentiate between system and user files. For example, the DIRS command provides a directory of system files. The D IR command provides a directory of user files for the current user number. For details on these commands, refer to the CPIM-68K Operating System User's Guide.

The Archive attribute is reserved but not used by CP/M-68K. If set, it indicates that the file has been written to backup storage by a user-written archive program. To implement this facility, the archive program se~s this attribute when it copies a file to backup storage; any programs updating or creating files reset this attribute. The archive program backs up only those files that have the Archive attribute reset. Thus, an automatic backup facility restricted to modified files can be implemented easily.

The Open File (15) and Close File (16) Functions do not use the high bit in the filename and filetype fields when matching filenames. However, the high bits in these fields should equal zero when you open a file. Also, the Close File Function does not update the attributes in the directory entries when it closes a file.

[j]J DIGITAL RESEARCH™ --------------------------4-23


4.2.14 Read Random Function

FUNCTION 33: READ RANDOM



success: OOH error: 01H,03H

04H,06H

The Read Random Function reads records randomly, rather than sequentially. The file must be opened with an Open File Function (15) or a Make File Function (22) before this function is invoked. The address of a 36-byte FCB is passed in register D1.L. The FCB random record field denotes the record this function reads. The random record field is a 24-bit field, with a value ranging" from OOOOOH through 3FFFFH. This field spans bytes rO, r1, and r2 which are bytes 33 through 35 of the FCB. The most significant byte is first, rO, and the least significant byte, r2, is last. This byte sequence is consistent with the addressing conventions for the 68000 microprocessor but differs from other versions of CP/M.

The random record number must be stored in the FCB random record field before the BDOS is called to read the record. After reading the record, register DO.W either contains an error code (see Table 4-8), or the value OOH which indicates the read operation was successful. In the latter case, the current DMA buffer contains the randomly accessed record. The record number is not incremented. The FCB extent and current record fields are updated to correspond to the location of the random record that was read. A subsequent Read Sequential (20) or Write Sequential (21) Function starts from the record which was randomly accessed. Therefore, the randomly read record is reread when a program switches from randomly reading records to sequentially reading records. This is also true for the Write Random Functions (34,40). The last record written is rewritten if the program switches from randomly writing records to sequentially writing records with the Write Sequential Function (21). However, a program can obtain the effect of sequential 1/0 operations by incrementing the random record field following each Read Random Function (33) or Write Random Function (34,40).

------------------------- [!Q] DIGITAL RESEARCHTY 4-24


Numeric codes returned in register DO.W following a random read operation are listed in Table 4-8.

Code I 00

01

03

04

06

Table 4-8. Read Random Function Return Codes

Meaning

Success - returned in DO. W when the Read Random Function succeeds.

Reading unwritten data - returned when a random read. operation accesses a previously unwritten data block.

Cannot close current extent - returned when the BDOS cannot close the current extent prior to moving to the new extent containing the FCB random record number. This error can be caused by an overwrit- . ten FCB or a read random operation on an FeB that has not been opened.

Seek to unwritten extent - returned when a random read operation accesses a nonexistent extent. This error situation is equivalent to error 01.

Random record number out of range - returned when the value of the FCB random record field is greater than 3FFFFH.

(!ID DIGITAL RESEARCHT• ---------------------------

4-25


4.2.15 Write Random Function

FUNCTION 34: WRITE RANDOM

Entry Parameters: Register DO.W: 22H RegisterDl.L: FCBAddress



05H,06H

The Write Random Function writes a 128-byte record from the current DMA address to the disk file that matches the FCB referenced in register D1.L. Before this function is invoked, the file must be opened with either the Open File Function (15) or the Make File Function (22).

This function requires a 36-byte FCB. The last three bytes of the FCB contain the random record field. It contains the record number of the record that is written to the file. To append to an existing file, the Compute File Size Function (35) can be used to write the random record number to the FCB random record field. For a new file, created with the Make File Function (22), you do not need to use the Compute File Size Function to write the first record in the newly created file. Instead, specify the value OOH in the FCB random record field. The first record written to the newly created file is zero.

When an extent or data block must be allocated for the record, the Write Random Function allocates it before writing the record to the disk file. The random record number is not changed following a Write Random Function. Therefore, a new random record number must be written to the FCB random record field before each Write Random Function is invoked.

--------------------------I!]] DIGITAL RESEARCH™ 4-26


However, the logical extent number and current record field of the FCB are updated and correspond to the random record number that is written. Thus, a Read Sequential (20) or Write Sequential (21) Function that follows a Write Random Function, either rereads or rewrites the record that was accessed by the Read or Write Random Function. To avoid overwriting the previously written record and simulate sequential write functions, increment the random record number after each Write Random Function.

After the Write Random Function completes, register DO.W contains either an error code (see Table 4-9), or the value OOH that indicates the operation was successful.

Code I 00

02

03

05

06

Table 4-9. Write Random Function Return Codes

Meaning

Success - returned when the Write Random Function succeeds without error.

No available date block - occurs when the Write Random Function attempts to allocate a new data block to the file, but the selected disk does not contain any unallocated data blocks.

Cannot close current extent - occurs when the BDOS cannot close the current extent prior to moving to the new extent that contains the record specified by the FeB random record field. This error can be caused by an overwritten FCB or a write random operation on an FCB that has not been opened.

No available directory space - occurs when the write function attempts to create a new extent that requires a new directory entry but the selected disk drive does not have any available directory entries.

Random record number out of range - returned when the value of the FCB random record field is greater than 3FFFFH.

[!ID DIGITAL RESEARCH TW ---------------------------

4-27


4.2.16 Compute File Size Function

FUNCTION 35: . COMPUTE FILE SIZE



success: File Size written to FCB Random Record Field

error: Zero written to FCB Random Record Field

The Compute File Size Function computes the size of a file and writes it to the random record field of the 36-byte FCB whose address is passed in register D1.L.

The FCB filename and filetype are used to scan the directory for an entry with a matching filename and filetype. If a match cannot be found, the value zero is written to the FCB random record field. However, when a match occurs, the virtual file size is written in the FCB random record field.

------------------------- i!ID DIGITAL RESEARCH™ 4-28


The virtual file size is the record number of the record following the end of the file. The virtual size of a file corresponds to the physical size when the file is written sequentially. However, the virtual file size may not equal the physical file size when the records in the file were created by random write functions. The Compute File Size Function computes the file size by adding the value 1 to the record number of last record in a file. However, for files that contain randomly written records, the record number of the last record does not necessarily indicate the number of records in a file. For example, the number of the last record in a sparse file does not denote the number of records in the file. Record numbers for sparse files are not usually sequential. Therefore, gaps can exist in the record numbering sequence. You can create sparse files with the Write Random Functions (34 and 40).

In addition to computing the file size, you can use this function to determine the end of an existing file. For example, when you append data to a file, this function writes the record number of the first unwritten record to the FCB random record field. When you use the Write Random (34) or the Write Random With Zero Fill (40) Function, your program more efficiently appends data to the file because the FCB already contains the appropriate record number.

[lID DIGITAL RESEARCHNI --------------------------

4-29


4.2.17 Set Random Record Function

FUNCTION 36: SET RANDOM RECORD

Entry Parameters: Register DO.L: 24H Register Dl.L: FCB Address

Returned Values: Register DO: OOH

Register FCB: Random Record Field Set

The Set Random Record Function calculates the random record number of the current position in the file. The current position in the file is defined by the last operation performed on the file. Table 4-10 lists the current position relative to operations performed on the file.

Operation

Open file

Create file

Random read

Random write

Sequential read

Sequential write

Table 4-10. Current Position Definitions

I Function

Open File (15)

Make File (22)

Read Random (33)

Write Random (34) Write Random With Zero Fill (40)

Read Sequential (20)

Write Sequential (21)

I Current Position

record 0

record 0

last record read

last record written

record following the last record read·

record following the last record written

-------------------------IIQJ DIGITAL RESEARCHTN

4-30


This function writes the random record number in the random record field of the 36-byte FCB whose address your program passes in register D 1.L.

You can use this function to set the random record field of the next record your program accesses when it switches from accessing records sequentially to accessing them randomly. For example, your program sequentially reads or writes 128-byte data records to an arbitrary position in the file that is defined by your program. Your program then invokes this function to set the random record field in the FCB. The next random read or write operation that your program performs accesses the next record in the file.

Another application for this function is to create a key list from a file that you read sequentially. Your program sequentially reads and scans a file to extract the positions of key fields. After your program locates each key, it calls this function to compute the random record position for the record following the record containing the key. To obtain the random record number of the record containing the key, subtract one from the random record number that this function calculates. CP/M-68K reads and writes 128-byte records. If your record size is also 128 bytes, your program can insert the record position minus one into a table with the key for later retrieval. By using the random record number stored in the table when your program performs a random read or write operation, your program locates the desired record more efficiently.

Note that if your data records are not equal to 128 bytes, your program must store the random record number and an offset into the physical record. For example, you must generalize this scheme for variable-length records. To find the starting position of key records, your program stores the buffer-relative position and the random record number of the records containing keys.

[j]J DIGITAL RESEARCHTN ---------------------------

4-31


4.2.18 Write Random with Zero Fill Function

FUNCTION 40: WRITE RANDOM WITH ZERO FILL




OSH,06H

The Write Random With Zero Fill Function, like the Random Write Function (34), writes a 128-byte record from the current DMA buffer to the disk file. The address of a 36-byte FCB is passed in register D1.L. The last three bytes contain the FCB random record field. This field specifies the record number of the record that this write random function writes to the file. Refer to Write Random Function (34) for details on the FCB and setting its random record field.

Like the Write Random Function, this function allocates a data block before writing the record when a block is not already allocated. However, in addition to allocating the data block, this function also initializes the block with zeroes before writing the record. If your program uses this function to write random records to files, it ensures that the contents of unwritten records in the block are predictable.

After the random write function completes, register DO.W contains either an error code (see Table 4-9), or the value OOH, which indicates the operation was successful.

--------------------------i!ID DIGITAL RESEARCH™ 4-32

CP/M-68K Programmer's Guide 4.3 Drive Functions

4.3 Drive Functions

This section describes drive functions that reset the disk system, select and writeprotect disks, and return vectors. They include the functions listed in Table 4-11.

Table 4-11. Drive Functions

Function I Function Number

ResetDiskSystem 13

Select Disk 14

Return Login Vector 24

Return Current Disk 25

Write Protect Disk 28

Get Read-Only Vector 29

Get Disk Parameters 31

Reset Drive 37

Get Disk Free Space 46

~ DIGITAL RESEARCHT• --------------------------

4-33

4.3 Drive Functions CP/M-68K Programmer's Guide

4.3.1 Reset Disk System Function

FUNCTION 13: RESET DISK SYSTEM

Entry Parameters: Register DO.W: ODH


The Reset Disk System Function restores the file system to a reset state. All disks are set to read-write (see Write Protect Disk (28) and Get Read-Only Vector (29) Functions), and all the disk drives are logged out. This function can be used by an application program that requires disk changes during operation. The Reset Drive Function (37) can also be used for this purpose. All files must be closed before your program invokes this function.

-------------------------IIQJ DIGITAL RESEARCHT•

4-34


4.3.2 Select Disk Function

FUNCTION 14: . SELECT DISK

Entry Parameters: Register DO.W: OEH RegisterD1.W: DiskNumber


4.3 Drive Functions

The Select Disk Function designates the disk drive specified in register D1.W as the default disk for subsequent file operations. The decimal numbers 0 through 15 correspond to drives A through P. For example, D1.W contains a 0 for drive A, a 1 for drive B, and so forth through 15 for a full 16-drive system. In addition, the designated drive is logged-in if it is currently in the reset state. Logging in a drive places it in an on-line status which activates the drive's directory until the next cold start, or Reset Disk System (13) or Reset Drive (37) Function.

When the FCB drive code equals zero (dr = OH), this function references the currently selected drive. However, when the FCB drive code value is between 1 and 16, this function references drives A through P.

If this function fails, CP/M-68K returns a CP/M Disk select error, which is described in Section 4.2.2.

IIID DIGITAL RESEARCHT• -------------------------

4-35


4.3.3 Return Login Vector Function

FUNCTION 24: RETURN LOGIN VECTOR


Returned Values: Register DO.W: Login Vector

The Return Login Vector Function returns in register DO.W a 16-bitvalue that denotes the log-in status of the drives. The least significant bit corresponds to the first drive A, and the high order bit corresponds to the sixteenth drive, labeled P. Each bit has a value of zero or one. The value zero indicates the drive is not on-line. The value one denotes the drive is on-line. When a drive is logged in, its bit in the log-in vector has a value of one. Explicitly or implicitly logging in a drive sets its bit in the log-in vector. The Select Disk Function (14) explicitly logs in a drive. File operations implicitly log in a drive when the FCB drive field (dr) contains a nonzero value.

--------------------------!!QJ DIGITAL RESEARCH™ 4-36


4.3.4 Return Current Disk Function

FUNCTION 25: RETURN CURRENT DISK


Returned Values: Register DO.W: Current Disk

The Return Current Disk Function returns the current default disk number in register DO. W. The disk numbers range from 0 through 15, which correspond to drives A through P. Note that this numbering convention differs from the FCB drive field, which specifies integers 1 through 16 correspond to drives labeled A through P.


4-37


4.3.5 Write Protect Disk Function

FUNCTION 28: WRITE PROTECT DISK

Entry Parameters: Register DO.W: lCH


The disk write protect function provides temporary write protection for the currently selected disk. Any attempt to write to the disk, before the next cold start, warm start, disk system reset, or drive reset operation produces the message:

DisK change error on drive x

Your program terminates when this error occurs. Program control returns to the CCP.

--------------------------[l]] DIGITAL RESEARCH™ 4-38


4.3.6 Get Read-Only Vector Function

FUNCTION 29: GET READ-ONLY VECTOR

Entry Parameters: Register DO.W: lDH

Returned Values: Register DO.W: Read-Only

Vector Value

The Get Read-Only Vector Function returns a 16-bit vector in register DO.W. The vector denotes drives that have the temporary read-only bit set. Similar to the Return Login Vector Function (24), the least significant bit corresponds to drive A, and the most significant bit corresponds to drive P. The Read-Only bit is set either by an explicit call to the Write Protect Disk Function (28), or by the automatic software mechanisms within CP/M-68K that detect changed disks.

I!ID DIGITAL RESEARCHT• -------------------------

4-39

4.3 Drive Functions CP/M-6SK Programmer's Guide

4.3.7 Get Disk Parameters Function

FUNCTION 31: GET DISK PARAMETERS

Entry Parameters: Register DO.W: 1FH Register D1.L: CDPB Address


CDPB: ContainsDPBValues

The Get Disk Parameters Function writes a copy of the 16-byte BIOS Disk Parameter Block (DPB) for the current default disk, called the CDPB, at the address specified in register D1.L. Figure 4-2 illustrates the format of the DPB and CDPB. The values in the CDPB can be extracted and used for display and space computation purposes. Normally, application programs do not use this function. For more details on the BIOS DPB, refer to the CPIM-68K Operating System System Guide.

SPT BSH BLM EXM RES DSM DRM RES CKS OFF

16 8 8 I 8 I 8 I 16 I 16 I 16 I 16 16

Figure 4-2. DPB and CDBP

------------------------[!Q] DIGITAL RESEARCHTlI

4-40


Table 4-12 lists the fields in the DPB and CDPB.

Field

SPT

BSH

BLM

EXM

RES

DSM

DRM

RES

CKS

OFF

Table 4-12. Fields in the DPB and CDPB

I Description

Number of 128-byte logical sectors per track

Block shift factor

Block mask

Extent mask

Reserved byte

Total number of blocks on the disk

Total number of directory entries on the disk

Reserved for system use

Length (in bytes) of the checksum vector

Track offset to disk directory

I!Q] DIGITAL RESEARCHTII ------------------------

4-41


4.3.8 Reset Drive Function

FUNCTION 37: RESET DRIVE

Entry Parameters: Register DO.W: 25H Register D 1. W : Drive Vector


The Reset Drive function restores specified drives to the reset state. A reset drive is not logged-in and its status is read-write. Register D1.W contains a 16-bit vector indicating the drives this function resets. The least significant bit corresponds to the first drive, A. The high order bit corresponds to the sixteenth drive, labeled P. Bit values of 1 indicate the drives this function resets.

To maintain compatibility with other Digital Research operating systems, this function returns the value zero in register DO.W.

--------------------------I!QJ DIGITAL RESEARCH™ 4-42


4.3.9 Get Disk Free Space Function

FUNCTION 46: GET DISK FREE SPACE

Entry Parameters: Register DO.W: 2EH Register D1.W: Disk Number


DMA Buffer: Free Sector Count

The Get Free Disk Space Function returns the free sector count, the number of free 128-byte sectors on a specified drive, in the first four bytes of the current DMA buffer. The drive number is passed in register D1.W. CP/M-68K assigns disk numbers sequentially from 0 through 15 (decimal). Each number corresponds to a drive in the range A through P. For example, the disk number for drive A is 0 and for drive B, the number is 1.

Note that these numbers do not correspond to those in the drive field of the FCB. The FCB drive field (dr) uses the numbers 1 through 16 (decimal) to designate drives.

[!ID DIGITAL RESEARCH™ -------------------------4-43

4.4 Character 110 Functions CP/M-68K Programmer's Guide

4.4 Character lID Functions

Character I/O functions read or write characters serially to a peripheral device. Character I/O functions supported in CP/M-68K are described in this section and listed in Table 4-13.

Table 4-13. Character 110 Functions


Console Operations

Console Input 1

Console Output 2

Direct Console I/O 6

Print String 9

Read Console Buffer 10

Get Console Status 11

Additional Serial I/O

Auxiliary Input 3

Auxiliary Output 4

List Output 5

I/O Byte

Get I/O Byte 7

Set 110 Byte 8

-------------------------!!ill DIGITAL RESEARCH™

4-44

CP/M-68K Programmer's Guide 4.4 Character I/O Functions

4.4.1 Console I/O Functions

This section describes functions that read from, write to, and report the status of the logical device CONSOLE.

Console Input Function

FUNCTION 1: CONSOLE INPUT


Returned Values: Register DO.W: ASCII Character

The Console Input function reads the next character from the logical console device (CONSOLE) to register DO.W. Printable characters, along with carriage return, line feed, and backspace (CTRL-H), are e·choed to the console. Tab characters (CTRL-I) are expanded into columns of eight characters. Other CONTROL characters, such as CTRL-C, are processed. The BDOS does not return to the calling program until a character has been typed. Thus, execution of the program is suspended until a character is ready.

[!QJ DIGITAL RESEARCH™ --------.,..........-----------------4-45


Console Output Function

FUNCTION 2: CONSOLE OUTPUT

Entry Parameters: Register DO.W: 02H Register D 1. W: ASCII Character

Returned Values: Register DO: OOH

The ASCII character from D1.W is sent to the logical console. Tab characters expand into columns of eight characters. In addition, a check is made for stop scroll (CTRL-S), start scroll (CTRL-Q), and the printer switch (CTRL-P). This function also processes CTRL-C, which aborts the operation and warm boots the system. If the console is busy, execution of the calling program is suspended until' the console accepts the character.

-------------------------1fID DIGITAL RESEARCH™ 4-46


Direct Console 110 Function

FUNCTION 6: DIRECT CONSOLE I/O

Entry Parameters: Register DO.W: 06H Register Dl.W: OFFH (input)

OFEH (status)

Returned Values:

or Character (output)

Register DO.W: Character or Status

Direct Console I/O is supported under CP/M-68K for those specialized applications where character-by-character console input and output are required without the control character functions CP/M-68K supports. This function bypasses all of CP/M-68K's normal CONTROL character functions such as CTRL-S, CTRL-Q, CTRL-P, and CTRL-C.

Upon entry to the Direct Console 110 Function, register D1.W contains one of the following values.

[i]] DIGITAL RESEARCH™ -------------------------4-47

4.4 Character 1/0 Functions CP/M-68K Programmer's Guide

Value

FFH

FEH

ASCII character

I Table 4-14. Direct Console 110 Function Values

Meaning

denotes a CONSOLE input request

denotes a CONSOLE status request

output to CONSOLE where CONSOLE is the logical console device

When the input value is FFH, the Direct Console 1/0 Function calls the BIOS Conin Function, which returns the next console input character in DO.W but does not echo the character on the console screen. The BIOS Conin function waits until it receives a character. Thus, execution of the calling program remains suspended until a character is ready.

When the input value is FEH, the Direct Console 1/0 Function returns the status of the console input in register DO.W. When register DO.W contains the value zero, no console input exists. However, when the value in DO.W IS nonzero, console input, is ready to be read by the BIOS Conin Function.

When the input value in D1.W is neither FEH nor FFH, the Direct Console 110 Function assumes that D1.W contains a valid ASCII character, which is sent to the console.

--------------------------I!QJ DIGITAL RESEARCH™

4-48

CP/M-68K Programmer's Guide 4.4 Character 110 Functions

Print String Function

FUNCTION 9: PRINT STRING

Entry Parameters: Register DO.W: 09H Register D1.L: String Address


The Print String function sends the character string stored in memory at the location given in register D1.L to the logical console device (CONSOLE) until a dollar sign ($) is encountered in the string. Tabs are expanded as in the Console Output Function (2), and checks are made for stop scroll (CTRL-S), start scroll (CTRL-Q), and the printer switch (CTRL-P).

IIID DIGITAL RESEARCHT• -------------------------:4--4:-:::-9


Read Console Buffer Function

FUNCTION 10: READ CONSOLE BUFFER

Entry Parameters: Register DO.W: OAH Register D1.L: Buffer Address

Returned Values: Register DO.W: OOH Register Buffer: Character Count

and Characters

The Read Buffer function reads a line of edited console input from the logical console device (CONSOLE) to a buffer address passed in register D1.L. Console input is terminated when the input buffer is filled, or, a RETURN (CTRL-M) or a line feed (CTRL-J) character is entered. The input buffer addressed by D1.L takes the form:

D 1.L: + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 +n

mx nc c1 c2 c3 c4 c5 c6 c7 ??

The variable mx is the maximum number of characters the buffer holds. The variable nc is the total number of characters placed in the buffer. Your program must set the mx value prior to invoking this function. The mx value can range in value from 1 through 255 (decimal). The characters entered from the keyboard follow the nc value. The value nc is returned to the buffer. It can range from 0 to the value of mx. If the nc value is less than the mx value, uninitialized characters follow the last character. Uninitialized characters are denoted by the double question marks (??) in the above figure. A terminating RETURN or line feed character is not placed in the buffer and is not included in the total character count nco

This function supports several editing control functions, which are briefly described in Table 4-15.

-------------------------I!]] DIGITAL RESEARCHTM 4-50


Table 4-15. Line Editing Controls

Keystroke I Result

RUBIDEL removes and echoes the last character

CONTROL-C reboots when it is the first character on a line

CONTROL-E causes physical end-of-line

CONTROL-H backspaces one character position

CONTROL-j (line-feed) terminates input line

CONTROL-M (return) terminates input line

CONTROL-P starts and stops the echoing of console output to the logical LIST device

CONTROL-Q restarts console 110 after CTRL-S halts it

CONTROL-R retypes the current line on the next line

CONTROL-S halts console 110 and waits for CTRL-Q to restart it

CONTROL-U echoes a pound sign (#) indicating ignore characters previously input on the current line before it positions the cursor on the next line

CONTROL-X backspaces to beginning of current line

Certain functions that position the cursor to the leftmost position (for example, CONTROL-X) move the cursor to the column position where the cursor was prior to invoking the Read Console Buffer Function. This convention makes your data input and line correction more legible.


4.4 Character 1/0 Functions CP/M-6SK Programmer's Guide

Get Console Status Function

FUNCTION 11: GET CONSOLE STATUS

Entry Parameters: Register DO.W: OBH

Returned Values: Register DO.W: ConsoleStatus

The Get Console Status Function checks whether a character has been typed at the logical console device (CONSOLE). If a character is ready, a nonzero value is returned in register DO.W; otherwise the value OOH is returned in DO.W.

-------------------------IIQJ DIGITAL RESEARCHTN

4-52


4.4.2 Additional Serial 1/0 Functions

This section describes additional serial I/O functions that read and write data to devices defined by I/O Byte Functions (7,8).

Auxiliary Input Function

FUNCTION 3: AUXILIARY INPUT


Returned Values: Register DO.W: ASCII Character

The Auxiliary Input function reads the next character from the auxiliary input device into register DO.W. Execution of the calling program remains suspended until the character is read. This function assumes the BIOS implements its Auxiliary Input Function. When more than one auxiliary input port exists, the BIOS should implement the I/O Byte Function. For details on the BIOS Auxiliary Input and 110 Byte Functions, refer to the CPIM-68K Operating System System Guide.

[!Q) DIGITAL RESEARCH TW --------------------------

4-53

4.4 Character I/O Functions CP/M-68K Programmer's Guide

Auxiliary Output Function

FUNCTION 4: AUXILIARY OUTPUT

Entry Parameters: Register DO.W: 04H Register Dl.W: ASCII Character


The Auxiliary Output function sends a character from register D1.W to the auxiliary output device. Execution of the calling program remains suspended until the hardware buffer receives the output character. This function assumes the BIOS implements its Auxiliary Output Function. When more than one auxiliary output port exists, the BIOS should implement the 110 Byte Function. For details on the BIOS Auxiliary Output and 110 Byte Functions, refer to the CPIM-68K Operating System System Guide.

--------------------------iIID DIGITAL RESEARCH"" 4-54


List Output Function

,FUNCTION 5: LIST OUTPUT

Entry Parameters: Register DO.W: OSH Register D 1. W: ASCII Character


The List Output function sends the ASCII character in register D1.W to the logical list device (LIST).

4.4.3 1/0 Byte Functions

This section describes the I/O Byte Functions. The I/O Byte is an 8-bit value that assigns physical devices, represented by 2-bit fields, to each of the logical devices: CONSOLE, AUXILIARY INPUT, AUXILIARY OUTPUT, and LIST as shown in Figure 4-3. The 110 Byte functions allow programs to access the I/O byte to determine its current value (Get I/O Byte) or to modify it (Set I/O Byte). These functions are valid only if the BIOS implements its I/O Byte Function. Refer to the CP/M-68K Operating System System Guide for details on implementing the I/O Byte Function.

MOST SIGNIFICANT LEAST SIGNIFICANT

1/0 BYTE LIST AUXILIARY OUTPUT AUXILIARY INPUT CONSOLE BITS 1r-----

7,-6---"T---

5-,4----.----3-,2---.,-----1-,O-----,

Figure 4-3. I/O Byte

I!ID DIGITAL RESEARCH'" -------------------------4-55


The value in each field ranges from 0-3. The value defines the assigned source or destination of each logical device, as shown in Table 4-16.

Table 4-16. liD Byte Field Definitions

CONSOLE field (bits 1,0) o -console is assigned to the console printer (TTY:) 1 - console is assigned to the CRT device (CRT:) 2 - batch mode: use the AUXILIARY INPUT as the CONSOLE input, and the

LIST device as the CONSOLE output (BAT:) 3 - user defined console device (UC1:)

AUXILIARY INPUT field (bits 3,2) 0- AUXILIARY INPUT is the Teletype device (TTY:) 1 - AUXILIARY INPUT is the high-speed reader device (PTR:) 2 - user defined reader # 1 (URi:) 3 - user defined reader # 2 (UR2:)

AUXILIARY OUTPUT field (bits 5,4) o -AUXILIARY OUTPUT is the Teletype device (TTY:) 1 - AUXILIARY OUTPUT is the high-speed punch device (PTP:) 2 - user defined punch # 1 (UPi:) 3 - user defined punch # 2 (UP2:)

LIST field (bits 7,6) o -LIST is the Teletype device (TTY:) 1 - LIST is the CRT device (CRT:) 2 - LIST is the line printer device (LPT:) 3 - user defined list device (ULi:)

The implementation of the BIOS I/O Byte Function is optional. PIP and STAT are the only CP/M-68K utilities that use the I/O Byte. PIP accesses physical devices. STAT designates and displays logical to physical device assignments. For details on implementing the I/O Byte Function, refer to the CP/M-68K Operating System System Guide.

-----------------------I!ID DIGITAL RESEARCH TN

4-56


Get 110 Byte Function

FUNCTION 7: GET 110 BYTE

Entry Parameters: . Register DO.W: 07H

Returned Values: Register DO.W: I/OByteValue

The Get 110 Byte Function returns the current value of I/O Byte in register DO.W. The I/O Byte contains the current assignments for the logical devices CONSOLE, AUXILIAR Y INPUT, AUXILIARY OUTPUT, and LIST. Note that this function is valid only if the BIOS implements its 110 Byte Function. Refer to the CP/M-68K Operating System System Guide for details on implementing the BIOS 110 Byte Function.

[!Q] DIGITAL RESEARCHTM ------------------------4-57


Set 110 Byte Function

FUNCTION 8: SET 110 BYTE

Entry Parameters: Register DO.W: 08H Register D1.W: 1/0 Byte Value


The Set 1/0 Byte Function changes the system 1/0 Byte value to the value passed in register D1.W. This function allows programs to modify the current assignments for the logical devices CONSOLE, AUXILIARY INPUT, AUXILIARY OUTPUT, and LIST in the 110 Byte. This function is valid only if the BIOS implements its 1/0 Byte Function. Refer to the CPIM-68K Operating System System Guide for details on implementing the 1/0 Byte Function.

4.5 System/Program Control Functions

The System and program control functions described in this section warm boot the system, return the operating system version number, call the Basic 110 System (BIOS) functions, and terminate and load programs. These functions are listed in Table 4-17.

Table 4-17. System and Program Control Functions


System Reset 0

Return Version Number 12

Set/GetUserCode 32

Chain To Program 47

Flush Buffers 48

Direct BIOS Call 50

Program Load 59

-------------------------i!ID DIGITAL RESEARCH™ 4-58

CP/M-68K Programmer's Guide 4.5 System/Program Control Functions

4.5.1 System Reset Function

FUNCTION 0: SYSTEM RESET

Entry Parameters: Register DO.W: OOH

Returned Values: Function Does Not Return to Calling Program

The System Reset Function terminates the current program and returns program control to the CCP command level.


4.5 System/Program Control Functions CP/M-68KProgrammer's Guide

4.5~2 Return Version Number Function

FUNCTION 12: RETURN VERSION NUMBER

Entry Parameters: Register DO.W: OCH

Returned Values: Register DO. W: Version Number

The Return Version Number Function provides information that allows version dependent programming. The one-word value 2022H is the version number returned in register DO.W for Release 1.1 of CP/M-68K. Table 4-18 lists the version numbers this function returns for Digital Research operating systems.

--------------------------lIQ] DIGITAL RESEARCH™ 4-60


Table 4-18. Version Numbers

Operating System

CP/M-6SK

CP/M-80

CP/M-SO

CP/M-SO

MP/M-SOTM

MP/M-SO

MP/M-SO

CP/M-S6

CP/M-S6

MP/M-S6™

MP/M-S6

Concurrent CP/M-S6™ (for the IBM® Personal Computer)

Concurrent CP/M-S6

I Version I Version Number

1.1 2022H

1.4 0014H

2.2 0022H

3.0 0031H

1.1 0122H

2.0 0130H

2.1 0130H

1.0 1022H

1.1 1022H

2.0 1130H

2.1 1130H

1.0 1430H

2.0 1431H

Add the hexadecimal value 0200 to any version number when the system implements CPINET®. For example, CP/M-SO Release 2.2 returns the version 0222H when the system implements CPINET.

[iiJ DIGITAL RESEARCH TW -----------------------

4-61

4.5 System/Program Control Functions CP/M-68K Programmer's Guide

4.5.3 Set/Get User Code

FUNCTION 32: SET/GET USER CODE

Entry Parameters: Register DO.W: 20H Register D1.W: FFH (get)

or User Code (set)

Returned Values: Register DO. W: Current User Number

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 D1.W is FFH, the value of the current user number is returned in register DO.W. The value ranges from 0 to 15 (decimal). If register D1.W contains a value in the range 0 through 15 (decimal), the current user number is changed to the value in register D1.W. 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.

--------------------------I!QJ DIGITAL RESEARCHTN

4-62


4.5.4 Chain To Program Function

FUNCTION 47: CHAIN TO PROGRAM

Entry Parameters: Register DO.W: 2FH

Returned Values: Register DO.W: Function Does Not Return

to Calling Program

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.

N COMMAND LINE (N CHARACTERS) o 1 BYTE N BYTES ~ 126 BYTES 1 BYTE

Figure 4-4. Command Line Format in the DMA Buffer

[!Q] DIGITAL RESEARCH™ -----------'------------------4-63

4.5 System/Program Control Functions CP/M-6SK Programmer's Guide

4.5.5 Flush Buffers Function

FUNCTION 48: FLUSH BUFFERS



success: OOH error: nonzero value

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 OOH in register DO.W. However, if an error occurs, and this function does not complete successfully, this function returns a nonzero value in register DO.W.

-------------------------- [!]] DIGITAL RESEARCH™ 4-64


4.5.6 Direct BIOS Call Function

FUNCTION 50: DIRECT BIOS CAll

Entry Parameters: Register DO.W: 32H Register D l.l: BPB Address

Returned Values: Register DO.l:' BIOS Return Code (if any)

Function 50 allows a program to call a BIOS function and transfers control through the BDOS to the BIOS. The D1.l register contains the address of the BIOS Parameter Block (BPB), a 5-word memory area containing two BIOS function parameters, PI and P2, as shown in Figure 4-5. When a BIOS function returns a value, it is returned in register DO.L.

like other BDOS functions, your program must specify a Trap 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.

[!ill DIGITAL RESEARCHT• -------------------------

4-65

4.5 System/Program Control Functions

FIELD

FUNCTION NUMBER I VALUE P1

VALUE P2


SIZE

1 WORD

1 LONGWORD

1 LONGWORD

Figure 4-5. BIOS Parameter Block (BPB)

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 D1.L 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 CPIM-68K Operating System System Guide.

------------------------- [!ill DIGITAL RESEARCH" 4-66


4.5.7 Program Load Function

FUNCTION 59: PROGRAM LOAD

Entry Parameters: Register DO.W: 3BH Register D1.L: LPB


success: OOH error: 01H-03H

The Program Load function loads an executable command file into memory. In addition to the function code, passed in register DO.W, the address of the Load Parameter Block (LPB) is passed in register D 1.L. After a program is loaded, the BDOS returns one of the following return codes in register DO.W.

Table 4-19. Program Load Function Return Codes .

Code I Meaning

00 the function is successful

01 insufficient memory exists to load the file or the header is bad

02 a read error occurs while the file is loaded in memory

03 bad relocation bits exist in the program file



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.

BYTE OFFSET CONTENT

OH

4H

8H

CH

10H

14H

ADDRESS OF FCB OF SUCCESSFULLY OPENED PROGRAM FILE

LOWEST ADDRESS OF AREA IN WHICH TO LOAD PROGRAM

HIGHEST ADDRESS OF AREA IN WHICH TO LOAD PROGRAM +1

ADDRESS OF BASE PAGE (RETURNED BY BDOS)

DEFAUT USER STACK POINTER (RETURNED BY BDOS)

LOADER CONTROL FLAGS J

Figure 4-6. Format of the Load Parameter Block (LPB)

SIZE

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 LONGWORD

1 WORD

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 TP A. When the CCP calls the Program Load function to load a transient program, the LPB addresses are the boundaries of the TP A.

-------------------------.[!Q] DIGITAL RESEARCHTN

4-68


The loader control flags in the LPB select loader options as shown in Table 4-20.

Table 4-20. Load Parameter Block Options

Bit Number

o (least significant byte)

1-15 (decimal)

I Value I o

Meaning

load program in the lowest possible part of the supplied address space

1 load program in the highest possible part of the supplied address space

o Reserved, should be setto zero.

The CCP uses the Program Load Function to load a command file. The CCP places a return address to itself on the top of the stack for the program being loaded. The program can exit and return to the CCP by performing a Return from Subroutine (RTS) instruction. However, if the program modifies the stack, it must reset the top of the stack to point to the CCP address before the program executes a RTS instruction. The CCP also places the base page address on the program's stack. The base page address is located four bytes from the address pointed to by register A7, the stack pointer. The assembly language notation for this offset is 4(A7) or 4(sp). The format of the base page is outlined in Appendix C.

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 OOOOH - 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.

The BDOS allocates a user stack in the TP A normally at the highest address. The value of the initial stack pointer is passed to the LPB by the BDOS.

IIID DIGITAL RESEARCH™ -------------------------

4-69


For programs loaded by a transient program rather than the CCP, refer to Section 2.2.3. 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.

4.6 Exception Functions

This section describes the Set Exception (61), Set Supervisor State (62), and the Get/Set TPA Limits Functions that set exceptions for error handling and other exception processing.

-------------------------- [l]J DIGITAL RESEARCHT•

4-70

CP/M-68K Programmer's Guide 4.6 Exception Functions

4.6.1 Set Exception Vector Function

FUNCTION 61: SET EXCEPTION VECTOR

Entry Parameters: Register DO.W: 3DH Register D 1.L: EPB Address



The Set Exception Vector Function allows a program to reset current exception vectors, set new exception vectors, and create exception handlers for the 68000 microprocessor.

In addition to passing the function number in register DO.W, a program must pass the address of the Exception Parameter Block (EPB) in register D 1.L. The EPB is a 10-byte data structure containing a .one-word vector number and two longword vector values. See Figure 4-7. The EPB specifies the exception and the address of the new exception handler. Table 4-21 lists valid exceptions that correspond to 68000 microprocessor hardware. The starting location of the EPB must be an even-numbered address.

FIELD

VECTOR NUMBER I NEW DEFINED VECTOR VALUE

OLD VECTOR VALUE RETURNED BY BOOS

SIZE

1 WORD

1 LONGWORD

1 LONGWORD

Figure 4-7. Exception Parameter Block (EPB)

IIID DIGITAL RESEARCHTN --------------------------4-71

4.6 Exception Functions CP/M-68K Programmer's Guide

The vector number identifies the exception. The New Vector Value specifies the address of the new exception handler for the specified exception. The BDOS returns in the Old Vector Value Field, the value that the exception vector contained before this function was invoked. The BDOS replaces the old vector value with the new vector value in its table of exception handlers and returns the address of the old exception handler to the old vector value in the EPB. After the BDOS sets the new exception vector, it passes the value OOH in register DO.W. However, if an error, such as a bad vector, occurs while the vector is being set, this function passes the value FFH in register DO.W. The bad vector error occurs when a vector other than one listed in Table 4-21 is specified for this function.

When an exception occurs, before the BDOS passes control to an exception handler, the BDOS restores the system state (user or supervisor) to the state of the system before it incurred the exception. To return from an exception handler to the normal processing state, the last instruction an exception handler executes is a Return and Restore (R TR) instruction.

Bus and address errors require special handling because they push four additional words onto the stack. For example, when a bus error occurs, the system pushes flags, the access address, and the instruction register onto the stack. An exception handler must pop these off the stack before it executes a R TR instruction.

If an exception handler does not exist for an exception, when that exception occurs, the BDOS default exception handler returns an exception message to the logical console device (CONSOLE) before it aborts the program. The BDOS exception message format is defined as follows.

Exception nn at user address aaaaaaaa. Aborted.

where:

nn

aaaaaaaa

is a hexadecimal number in the range 2 through 17 or 24 through 2F that defines all exceptions excluding reset, hardware interrupts, and system Traps 0 through 3.

is the address of the instruction following the one that caused the exception.

--------------------------- [!ID DIGITAL RESEARCHT•

4-72


Except for exceptions handled by resident system extensions (RSXs), the BDOS reinitializes all vectors to the default exception handler when the BDOS System Reset Function (0) is invoked. Any exception vectors, which your program sets, are reset after the BDOS warm boots the system. An RSX is a program that is not configured in the operating system but remains resident in memory after it is loaded. RSXs normally provide additional system functions. The Get/Set TP A Limits Function (63) allows you to create an area in the TPA in which one or more RSXs can reside ..

*

Table 4-21. Valid Vectors and Exceptions

Vector I Exception

2 Bus Error

3 Address Error

4 Illegal Instruction

S Zero Divide

6 CHK Instruction

7 TRAPV Instruction

8 Privilege Violation

9 Trace

10 Line 1010 Emulator

11 Line 1111 Emulator

32* Trap 0

33* Trap 1

36** Trap 4

37** TrapS

38** Trap 6

39** Trap 7

Vectors reserved for Resident System Extensions (RSX) implemented with the Get/Set TPA Limits Function (63).

* * Recommended Trap vectors for applications.

~ DIGITAL RESEARCHTN --------------------------

4-73


4.6.2 Set Supervisor State

FUNCTION 62: SET SUPERVISOR STATE

Entry Parameters: Register DO.W: 3EH


The Set Supervisor Function puts the calling program in supervisor state. This function should not be used by novice programmers and experienced programmers should be careful when invoking this function.

The user stack is swapped when the program enters supervisor state. On return from this function, the stack pointer, register A7, is the supervisor stack pointer and not the user stack pointer. Thus, you cannot use register A7 to reference the user stack.

The supervisor stack is used by the BDOS and BIOS. This stack is 300 longwords or 1200 bytes long. The percent of the stack used by the system is dependent on the operation being performed and those previously performed. Therefore, you cannot predict how much of the stack is available for program operations. To avoid stack overflow and overwriting the system, you should not push more than a few dozen bytes onto the stack, especially when you call BDOS and BIOS functions.

An alternate method of avoiding stack overflow is to switch to a private supervisor stack. You create the stack by loading into A7 the address of an area in memory that you use as the supervisor stack. The address must be an even address. If you call BDOS and BIOS functions, your private supervisor stack should be 300 longwords, more than the space required by the program. If your program exits supervisor mode, make sure your program restores the system stack pointer to its original value. The supervisor stack is reinitialized when the system warm boots.

Note that in future CP/M-68K upward compatible systems, this function may not exist, or will require privilege for the calling process to access this function, or the function will fail. If it fails the value FFH will be passed to DO.W. However, no privilege· is currently necessary. The function is always successful and the value OOH is passed in register DO.W.

--------------------------[!Q] DIGITAL RESEARCHTN

4-74

CP/M-6SK Programmer's Guide 4.6 Exception Functions

4.6.3 Get/Set TPA Limits

FUNCTION 63: GET/SET TPA LIMITS

Entry Parameters: Register DO.W: 3FH Register D 1.L: TP AB Address

Returned Values: Register DO.W: OOH Register TPAB: ContainsTPA Values

The Get/Set TP A Limits Function allows you to obtain or set the boundaries of the Transient Program Area (TPA). You must load the address of the Transient Program Area Block (TPAB) in register D1.L. The TPAB is a 5-word data structure consisting of one word and two longwords. You create the TPAB in the TPA as illustrated in Figure 4-8.

BYTE OFFSET

OOH

02H

06H

FIELD

PARAMETERS I LOW TPA ADDRESS

HIGH TPA ADDRESS '+1

SIZE

1 WORD

1 LONGWORD

1 LONGWORD

Figure 4-8. Transient Program Parameter Block

I.!!tl DIGITAL RESEARCH™ ------------------------4-75


The value of the first two bits in the one-word Parameters Field determines whether this function gets or sets the TP A limits and which fields you supply. Figure 4-9 illustrates the format of the parameters field.

PARAMETERS FIELD

RESERVED BITS (2-15) = 0

BITS: 1 0 VALUES = 1/0 1/0

Figure 4-9. Parameters Field in TPAB

Bit Zero determines whether you get or set the TPA limits. When the value of bit zero is zero, the BDOS returns the current TP A boundaries in the Low and High Address fields of the TP AB. When the value of bit zero is one, the BDOS sets new TPA boundaries. The BDOS uses the values that you specify in the Low and High TPA address fields of the TP AB to set the new TP A boundaries.

When you set the TP A boundaries, bit one determines whether the boundaries are temporary or permanent. When the value of bit one is zero, the TPA boundaries that you set are temporary; when the system warm boots, the previous TP A limits are restored. When the value of bit one is one, the TPA values that you set are permanent; they are not changed when the system warm boots.

Bits 2 through 15 contain zeroes. These bits are reserved for future use. Table 4-22 summarizes the values of bits zero and one.

-------------------------- [j]] DIGITAL RESEARCH™ 4-76


Table 4-22. Values For Bits 0 and 1 in the TPAB Parameters Field

Bit 1 Value I Explanation

o 0 Return boundaries of current TP A in TP AB Low and High Address Fields.

1

1 Set new TP A boundaries with the values loaded in TPAB Low and High address fields.

0, Restore previous TP A values when the system warm boots.

1 Permanently replace the TP A boundaries with the ones you specify in the Low and High TP AB Address Fields.

The following examples illustrate and explain values for bits zero and one.

Examples:

1. Get TPA Limits

1 0

o 0

This function returns the boundaries of the current TP A in the Low and High Address Fields of the TP AB when the value of bit zero equals o.

2. Temporarily Set TPA Limits

1 0

o 1

[j]J DIGITAL RESEARCH TW -------------------------

4-77


This function temporarily sets the TP A boundaries to the boundaries that you supply in the Low and High Address Fields of the TP AB when bit zero equals 1 and bit one equals o. The TPA boundaries are reset when the system warm boots.

3. Permanently S(!t TPA Limits

1 0

1 1

This fur£..:tion permanently sets the TP A boundaries to the values that you supply in the Low and High Address Fields of the TP AB when the value of bit zero equals 1 and bit one equals 1. The TP A limits remain set until this function is called to reset the boundaries or you cold boot system.

End of Section 4

-------------------------l!ID DIGITAL RESEARCHTN

4-78

Section 5 AS68 Assembler

5.1 Assembler Operation

The CP/M-68K Assembler, AS68, assembles an assembly language source program for execution on the a 68000 microprocessor. It produces a relocatable object file and, optionally, a listing. The assembly language accepted by AS68 is identical to that of the Motorola 68000 assembler described in the Motorola manuals: M68000 Resident Structured Assembler Reference Manual M68KMASM(D4) and the 16-bit Microprocessor User's Manual, third edition MC68000UM(AD3). Appendix D contains a summary of the instruction set. Exceptions and additions are described in Sections 5.6 and 5.7.

5.2 Initializing AS68

If the file AS68SYM.DA T is not on your disk, you must create this file to initialize AS68 before you can use AS68 to assemble files. To initialize AS68, specify the AS68 command, the -I option, and the filename AS68INIT as shown below.

ABBS -I ABBS1N1T

AS68 creates the output file AS68SYMB.DAT, which AS68 requires when it assembles programs. After you create this file, you need not specify this command line again unless you reconfigure your system to have different TP A boundaries.

5.3 Invoking the Assembler (AS68)

Invoke AS68 by entering a command of the following form:

AS68 [-F d:] [-P] [-S d:] [-U] [-L] [-N] [-I] [-0 object filename] source filename [> listing filename]

[!Q] DIGITAL RESEARCHT. ------------------------5-1

5.3 Invoking the Assembler (AS68) CP/M-68K Programmer's Guide

Table 5-1. Assembler Options

Option Meaning

-F d:

The -F option specifies the drive on which temporary files are created. The variable d: is the drive designation, which must be followed by a colon. If this option is not specified, the temporary files that AS68 creates are created on the current drive.

-I

The -I option initializes the assembler. See Section 5.2 for details.

-p

If specified, AS68 produces and prints a listing on the standard output device which, by default, is the console. You can redirect the listing, including error messages, to a file by using the >1isting filename parameter. Note that error messages are produced whether or not the -p option is· specified. No listing is produced, however, unless you specify the -P option.

-S d:

The -S option indicates the drive on which the assembler initialization file, AS68SYMB.DAT, resides. This file is created when you initialize AS68. See Section 5.2. AS68 reads the file AS68SYMB.DAT before it assembles a source file. The variable, d:, is the drive designation; it must be followed by a colon. If you do not specify this option, AS68 assumes the initialization file is on the default drive.

-U

Causes all undefined symbols in the assembly to be treated as global references.

-L

Ensures all address constants are generated as longwords. Use the -L option for programs that require more than 64K for execution or if the TPA is not contained in the first 64K bytes of memory. If -L is not specified, the program is assembled to run in the first 64 K bytes of memory. If an address in the assembly does not fit within one word an error occurs. Appendix E describes all AS68 errors.

-------------------------- [!ill DIGITAL RESEARCH™ 5-2

CP/M-68K Programmer's Guide 5.3 Invoking the Assembler (AS68)


Option Meaning

-N

Disables optimization of branches on forward references. Normally, wherever possible, AS68 uses the 2-byte form of the conditional branch and the 4-byte BSR instruction to speed program execution and reduce the instruction size instead of the 6-byte ]SR instruction.

source filename

This is the only required parameter. It is the file specification of the assembly language source program to be assembled.

> listing filename

If specified, the listing requested with the -P option is directed to the specified file rather than to your console terminal, the standard output device. The error messages are produced in the listing file. Note that if you do not request a listing file, you can still redirect the error messages to a file by specifying the greater than symbol (» immedi-ately followed by a file specification.

IIQ] DIGITAL RESEARCH'" --------------------------5-3

5.4 Assembly Language Directives CP/M-68K Programmer's Guide

5.4 Assembly Language Directives

This section alphabetically lists and briefly describes the directives AS68 supports.

Table 5-2. Assembly Language Directives

Directive Meaning

comm label, expression

The common directive (comm) specifies the label and size of a common area, which can be shared by separately assembled programs. The linker, L068, links all common areas with the same label to the same address. The size of the common area is determined by the value of the largest expression when more than one common area with the same label exists.

data

The data directive instructs AS68 to change the assembler base seg-ment to the data segment.

bss

The bss directive instructs AS68 to change the assembler base segment to the block storage segment (bss). Instructions and data cannot be assembled in the bss. However, symbols can be defined and storage can be reserved with the .ds directive in the bss.

dc operand [,operand, ... ]

The define constant directive (dc) defines one or more constants in memory. When you specify more than one operand, separate each with a comma. The operand can contain a symbol or an expression that is assigned a numeric value by AS68, or the value of the constant in decimal, hexadecimal, or ASCII notation. If you specify an ASCII value, you must enclose the string ~n single quotes ('). Although an ASCII character is only seven bits in length, each character is assigned a byte of memory. The eighth bit always equals zero.

You can specify the constants to be bytes, words, or longwords. The following list illustrates the notation for each of these size specifica-tions and describes the rules that apply to them.

--------------------------I!ID DIGITAL RESEARCH™ 5-4

CP/M-68K Programmer's Guide 5.4 Assembly Language Directives


Directive Meaning

dc.b The constants are byte constants. If you specify an odd number of bytes, AS68 fills the odd byte on the right with zeroes unless the next statement is another dc.b directive. When the next statement is a dc.b directive, the dc.b uses the odd byte. Byte constants are not relocatable.

dc.w The constants are word constants. If you specify an odd number of bytes, AS68 fills the last word on the right with zeroes to force an even byte count. The only way to specify an odd number of bytes is with an ASCII constant. Word constants can be relocated. J

dc.! The constants are longword constants. If less than a multiple of four bytes is entered, AS68 fills the last longword on the right with zeroes to force a multiple of four bytes. Longword constants can be relocated.

ds operand

The define storage directive (ds) reserves memory locations. The contents of the memory that it reserves is not initialized. The operand specifies the number of bytes, words, or longwords that this directive reserves. The notation for these size specifications is shown below.

ds.b reserves memory locations in bytes

ds.w reserves memory locations in words

ds.l reserves memory locations in longwords

end

The end directive informs AS68 that no more source code follows this directive. Code, comments, or multiple carriage returns cannot follow this directive.

endc

The endc directive denotes the end of the code that is conditionally assembled. It is used with other directives that conditionally assemble code.

[l]] DIGITAL RESEARCHT• --------------------------

5-5



Directive Meaning

equ expression

The equate directive (equ) assigns the value of the expression in the operand field to the symbol in the label field that precedes the directive. The syntax for the equate directive is

label EQU expression

The label and operand fields are required. The label must be unique; it cannot be defined anywhere else in the program. The expression cannot include an undefined symbol or one that is defined following the expression. Forward references to symbols are not allowed for this directive.

even

The even directive increments the location counter to force an even boundary. For example, if specified when the location counter is odd, the location counter is incremented by one so that the next instruction or data field begins on an even boundary in memory.

globllabel[,label...] xdef label[,label...] xref label[,label...]

These directives make the label(s) external. If the labels are defined in the current assembly, this statement makes them available to other routines during a load by L068. If the labels are not defined in the current assembly, they become undefined external references, which L068 links to external values with the same label in other routines. If you specify the -U option, the assembler makes all undefined labels external.

--------------------------I!QJ DIGITAL RESEARCHTN

5-6



Directive Meaning

ifeq expression ifne expression ifle expression iflt expression ifge expression ifgt expression

All of the directives listed above are conditional directives in which the expression is tested against zero for the condition specified by the directive. If the expression is true, the code following is assembled; otherwise, the code is ignored until an end conditional directive (endc) is found. The directives and the conditions they test are listed below.

ifeq equal to zero ifne not equal to zero ifle less than or equal to zero iflt less than zero ifge greater or equal to zero ifgt grea ter than zero

ifc 'string1', 'string2' ifnc 'string1', 'string2'

The conditional string directive compares two strings. The 'c' condi-tion is true if the strings are exactly the same. The 'nc' condition is true if they do not match.

!lID DIGITAL RESEARCHTN ---------------------------

5-7



Directive Meaning

offset expression

org expression

page

The offset directive creates a dummy storage section by defining a table of offsets with the define storage directive (ds). The storage definitions are not passed to the linker. The offset table begins at the address specified in the expression. Symbols defined in the offset table are internally maintained. No instructions or code-generating directives, except the equate (equ) and register mask (reg) directives, can be used in the table. The offset directive is terminated by one of the following directives:

bss data end section text

The absolute origin directive (org) sets the location counter to the value of the expression. Subsequent statements are assigned absolute memory locations with the new value of the location counter. The expression cannot contain any forward, undefined, or external references.

The page directive causes a page break which forces text to print on the top of the next page. It does not require an operand or a label and it does not generate machine code.

The page directive allows you to set the page length for a listing of code. If you use this directive and print the source code by specifying the -P option in the AS68 command line, pages break at predefined rather than random places. The page directive does not appear on the printed program listing.

-------------------------- [i]] DIGITAL RESEARCH™ 5-8



Directive Meaning

reg reglist

The register mask directive builds a register mask that can be used by movem instruction. One or more registers can be listed in ascending order in the format:

R?[-R[/R?[ -R? ... ] ... ]]

Replace the R in the above format with a register reference. Any of the following mnemonics are valid:

AO-A7 DO-D7 RO-R15

The following example illustrates a sample register list.

A2-A4/A7/D1/D3-D5

You can also use commas to separate registers:

A 1 tA2 tD5 tD7

section #

The section directive defines a base segment. The sections can be numbered from 0 to 15 inclusive. Section 14 always maps to data. Section 15 is bss. All other section numbers denote text sections.

text

The text directive instructs AS68 to change the assembler base segment to the text segment. Each assembly of a program begins with the first word in the text segment.

I!ID DIGITAL RESEARCHTN --------------------------5-9

5.5 Sample Commands Invoking AS68 CP/M-68K Programmer's Guide

5.5 Sample Commands Invoking AS68

A)ASSB -u -L TEST.S

This command assembles the source file TEST.S and produces the object file TEST.O. Error messages appear on the screen. Any undefined symbols are treated as global.

A)ASSB -P SMPL.S )SMPL.L

This command assembles the source file SMPL.S and produces the object file SMPL.O. The program 'must run in the first 64K of memory; that is, no address can be larger than 16 bits. Error messages and the listing are directed to the file SMPL.L.

5.6 Assembly Language Differences

The syntax differences between the AS68 assembly language and Motorola's assembly language are described in the following list.

1. All assembler directives are optionally preceded by a period (.). For example,

• e q II or e q II

• d 5 or d 5

2. AS68 does not support, but accepts and ignores the following Motorola directives:

corTlline rTlas.,2 idnt opt

3. The Motorola .set directive is implemented as the equate directive (equ).

4. AS68 accepts upper- and lower-case characters. You can specify instructions and directives in either case. However, labels and variables are case sensitive. For example, the label START and Start are not equivalent.

5. For AS68, all labels must terminate with a colon (:). For example,

A: FOO:

However, if a label begins in column one, it ~eed not terminate with a colon (:).

------------------------- [!ill DIGITAL RESEARCH™ 5-10

CP/M-68K Programmer's Guide 5.6 Assembly Language Differences

6. For AS68, ASCII string constants can be enclosed in either single or double quotes. For example,

'ABeD' lI ac 14 11

7. For AS68, registers can be referenced with the following mnemonics:

rO- r15 RO-R15 dO-d7 00-07 aO-a7 AO-A7 Upper- and lower-case references are equivalent. Registers RO-R7 are the same as DO-D7 and R8-R15 are the same as AO-A7.

8. For AS68, comment lines cannot begin with an asterisk that is immediately followed by an equals sign (* =), since the location counter can be manipulated with a statement of the form:

*= expr

9. Use caution when manipulating the location counter forward. An expression can move the counter forward only. The unused space is filled with zeros in the text or data segments.

10. For AS68, comment lines can begin with an asterisk followed by an equals sign (* =) but only if one or more spaces exist between the asterisk and the equals sign:

* = This command loads Rl with zeros. * = Branch to subroutine XYZ

11. For AS68, the syntax for short form branches is bxx.b rather than bxx.s

12. The Motorola assembler supports a programming model in which a program consists of a maximum of 16 separately relocatable sections and an optional absolute section. AS68 distributed with CP/M-68K does not support this model. Instead, AS68 supports a model in which a program contains three segments, text, data, and bss as described in Sections 2 and 3 of this guide.

IIIDDIGITAL RESEARCHTN --------------------------5-11

5.7 Assembly Language Extensions CP/M-68K Programmer's Guide

5.7 Assembly Language Extensions

The following enhancements have been added to AS68 to aid the assembly language programmer by making the assembly language more efficient:

1. When the instructions add, sub, cmp are used with an address register in the source or destination, they generate adda, suba, and cmpa. When the clr instruction is used with an address register (Ax), it generates sub Ax, Ax.

2. add, and, cmp, eor, or, sub are allowed with immediate first operands and actually generate addi, andi, cmpi, eori, ori, subi, instructions if the second operand is not register direct.

3. All branch instructions generate short relative branches where possible, including forward references.

4. Any shift instruction with no shift count specified assumes a shift count of one. For example, as 1 r 1 is equivalent to as 1 :1:1: 1 t r 1 •

5. A jsr instruction is changed to a bsr instruction if the resulting bsr is shorter than the jsr instruction.

6. The. text directive causes the assembler to begin assembling instructions in the text segment.

7. The .data directive causes the assembler to begin assembling initialized data in the data segment.

8. The .bss directive instructs the assembler to begin defining storage in the bss. No instructions or constants can be place in the bss because it is for uninitialized data only. However, the .ds directives can be used to define storage locations, and the location counter (*) can be incremented.

9. The .globl directive in the form:

.globllabel[,label] ...

makes the labels external. If they are otherwise defined (by assignment or appearance as a label) they act within the assembly exactly as if the .globl directive was not given. However, when linking this program with other programs, these symbols are available to other programs. Conversely, if the given symbols are not defined within the current assembly, the linker can combine the output of this assembly with that of others which define the symbols.

---:------------------------- !!ill DIGITAL RESEARCH TN

5-12

CP/M-6SK Programmer's Guide 5.7 Assembly Language Extensions

10. The common directive (comm) defines a common region, which can be accessed by programs that are assembled separately. The syntax for the common directive is

.comm label, expression

The expression specifies the number of bytes that is allocated in the common region. If several programs specify the same label for a common region, the size of the region is determined by the value of the largest expression.

The common directive assumes the label is an undefined external symbol in the current assembly. However, the linker, L068, is special-cased, so all external symbols, which are not otherwise defined, and which have a nonzero value, are defined to be in the bss, and enough space is left after the symbol to hold expression bytes. All symbols which become defined in this way are located before all the explicitly defined bss locations.

11. The .even directive causes the location counter (*), if positioned at an odd address, to be advanced by one byte so the next statement is assembled at an even address.

12. The instructions, move, add, and sub, specified with an immediate first operand and a data (D) register as the destination, generate Quick instructions, where possible.

5.8 Error Messages

Appendix E lists the error messages generated by AS68.

End of Section 5

[!IDDIGITAL RESEARCH™ ---------------------------5-13

6.1 Linker Operation

Section 6 L068 Linker

L068 is the CP/M-68K Linker that combines several AS68 assembled (object) programs into one executable command file. All external references are resolved. The linker must be used to create executable programs, even when a single object program contains no unresolved references. The argument routines are concatenated in the order specified. The entry point of the output is the first instruction of the first routine.

6.2 Invoking the Linker (L068)

Invoke L068 by entering a command of the following form:

L068 [-F d:] [-R] [-S] [-I] [-Uname] [-0 filename] [-X] [-Zaddress]

Option

-Fd:

[-Daddress] [-Baddress] object filename [object filename] [>message filename]

Table 6-1. Linker Command Options

Meaning

The -F option specifies the drive on which temporary files are created. The variable d: is the drive designation.

-R

The -R option preserves the relocation bits so the resulting executable program is relocatable.

-s If specified, the output is stripped; the symbol table and relocation bits are removed to save memory space.

!!ID DIGITAL RESEARCH TW -------------------------

6-1

6.2 Invoking the Linker (L068) CP/M-68K Programmer's Guide


Option Meaning

-I

If -lis specified, no 16-bit address overflow messages are generated. When you assemble a program without the AS68 -L option, the linker may generate address overflow messages if the program contains addresses longer than 16 bits.

-Uname

Forces linking of a library module which resolves the name parameter, even if the name is not referred to by any other module being linked. Normally library modules are only linked when they are needed to resolve references in other modules. You can use this option to create a program from a library if the module resolving the name parameter calls other modules in the library.

-0 filename

If specified, the object file produced by L068 has the filename that you specify following the -0 option. The -0 option and filename are separated by one or more spaces. If you do not specify a filename, the object file has the name C.OUT.

-x If specified, the symbol table includes all local symbols except those that begin with the letter L. If not specified, L068 puts only global symbols in the symbol table. This option is provided so that you can discard compiler internally-generated labels that begin with the letter L while retaining symbols local to routines.

-Taddress -Zaddress

The -T and -Z options are equivalent. If specified, the hexadecimal address given is defined by L068 as the beginning address for the text segment. This address defaults to zero, or it can be specified as any even hexadecimal number between 0 and FFFFFFFFH. This option is especially useful for stand-alone programs, or for putting programs in ROM. Hexadecimal characters can be in upper-case or lower-case.

--------------------------IIID DIGITAL RESEARCHT•

6-2

CP/M-68K Programmer's Guide 6.2 Invoking the Linker (L068)


Option Meaning

-Daddress

If specified, the hexadecimal address given is defined by L068 as the beginning address for the data segment. This address defaults to the next byte after the end of the text segment, or it can be specified as any even hexadecimal number between 0 and FFFFFFFF. This option is especially useful for stand-alone programs or for putting programs in ROM. Hexadecimal address characters can be in upper-case or lower-case.

-Baddress

If specified, the hexadecimal address given is defined by L068 as the beginning address for the bss. This address defaults to the next byte after the end of the data segment, or it can be specified as any even hexadecimal number between 0 and FFFFFFFF.

object filename [object filename]

The name of one or more object files produced by the assembler AS68. These are the object files that L068 links.

>message filename

If specified, error messages produced by L068 are redirected to the file that you specify immediately after the greater than (» sign. If you do not specify a filename, error messages are written to the standard default output device, which typically is your console terminal.


6-3

6.3 Sample Commands Invoking L068 CP/M-68K Programmer's Guide ~

6.3 Sample Commands Invoking L068

A)LOBB -5 -0 T£5T,BBK T£5T,O

This command links assembled file TEST.O into file TEST.68K and strips out the symbol table and relocation bits.

A)LOBB -T4000 -OBOOO -BCOOO A,O B,O C,O

This command links assembled files A.O, B.O, and c.o to the default output file C.OUT. The text segment starts at location 4000H; the data segment starts at location 8000H; and the bss starts at location COOOH.

A)LOBB -1 -0 T£5T,BBK T£5T,0 T£5T1,0 >£RROR

This command links assembled files TEST.O and TEST1.0 to file TEST.68K. Any 16-bit address overflow errors are ignored; error messages are directed to the file ERROR.

6.4 L068 Error Messages

Appendix E lists the error messages that L068 displays.

End of Section 6

------------------------I!QJ DIGITAL RESEARCHT•

6-4

Section 7 Programming Utilities

CP/M-68K supports five programming utilities: Archive (AR68), DUMP, Relocation (RELOC), SIZE68, and SENDC68. AR68 allows you to create and modify libraries. DUMP displays the contents of files in hexadecimal and ASCII notation. RELOC creates an absolute command file from a relocatable command file. SIZE68 displays the total size of a memory image command file and the size of each of its prograni segments. SENDC68 creates a file of Motorola S-records from a command file. S-records are l described in the CPIM-68K Operating System System Guide. This section describes each of these utilities in a separate subsection.

7.1 Archive Utility

The Archive Utility, AR68, creates a library or replaces, adds, deletes, lists, or extracts object modules in an existing library. AR68 can be used on the C Run-Time Library distributed with CP/M-68K and documented in the C Language Programming Guide for CPIM-68K for the 68000 microprocessor.

7.1.1 AR68 Syntax

To invoke AR68, specify the components of the following command line. Optional components are enclosed in square brackets ([ ]).

AR68 DRTWX[A V][FD:] [OPMOD] ARCHIVE OBMOD1 [OBMOD2 ... ][>filespec]

You can specify multiple object modules in a command line provided the command line does not exceed 127 bytes. The delimiter character between components consists of one or more spaces.

[l]] DIGITAL RESEARCH'· -------------------------7-1

7.1 Archive Utility CP/M-68K Programmer's Guide

Table 7-1. AR68 Command Line Components

Component Meaning

AR68

invokes the Archive Utility. However, if you specify only the AR68 command, AR68 returns the following command line syntax and system prompt shown below.

A)AR68

us a ~e: ARBS DRTWX[ AV][FD: ][DPMDD] ARCH I VE DBMDD 1 [DBMDD2 ••• ][)f i 1 e spe c]

A)

DRTWX

indicates you must specify one of these letters as an AR68 command. Each of these one-letter commands and their options are described in Section 7.1.3.

AV

indicates you can specify one or both of these one-letter options. These options are described with the commands in Section 7.1.3.

OPMOD

is an object module within the library that you specify. The OPMOD parameter indicates the position in which additional object modules reside when you incorporate modules in the library and specify the A option.

FD:

specifies the drive on which the temporary file created by AR68 resides. The variable D is the drive select code; it must be followed by a colon (:). AR68 creates a temporary file called AR68.TMP that AR68 uses as a scratchpad area.

ARCHIVE

is the file specification of the library.

OBMOD1 [OBMOD2 ... ]

indicates one or more object modules in a library that AR68 deletes, adds, replaces, or extracts.

-------------------------- OCQJ DIGITAL RESEARCHTM 7-2

CP/M-68K Programmer's Guide 7.1 Archive Utility


Component Meaning

>filespec

redirects the output to the file specification that you specify, rather than sending the output to the standard output device, which is usually the console device (CONSOLE). You can redirect the output for any of the AR68 commands described in Section 7.1.3.

7.1.2 AR68 Operation

AR68 sequentially parses the command line only once. AR68 searches for, inserts, replaces, or deletes object modules in the library in the sequence in which you specify them in the command line. Section 7.1.3 describes each of the commands AR68 supports.

When AR68 processes a command, it creates a temporary file called AR68.TMP. AR68 creates and uses AR68.TMP when it processes AR68 commands. After the operation is complete AR68 erases AR68.TMP. However, depending on when an error occurs, AR68.TMP is not always erased. If this occurs, erase AR68.TMP with the ERA command and refer to Appendix E for error messages output by AR68.

7.1.3 AR68 Commands and Options

This section describes AR68 commands and their options. Examples illustrate the effect and interaction between each command and the options it supports.

Table 7-2. AR68 Commands and Options

Command I Option

D

V

I Meaning

deletes from the library one or more object modules specified in the command. You can specify the V option for this command.

lists the modules in the library and indicates which modules are retained and deleted by the D command. The V option precedes modules retained in the library with the lower-case letter c and modules deleted from the library with the lower-case letter d.

[l]] DIGITAL RESEARCHTN --------------------------

7-3

7.1 Archive Utility

Command I Option I

R



Meaning

A)ARBB DV MYRAHfARC ORCfO e red.o e blue.o d ore.o e .... Ihite.o

A)

The D command deletes the module ORe.O from the library MYRAH.ARC. In addition to listing the modules in the library, the V option indicates which modules are retained and deleted.

creates a library when the one specified in the command line does not exist or replaces or adds object modules to an existing library. You must specify one or more object modules.

You can replace more than one object module in the library by specifying their module names in the command line. However, when the library contains more than one module with the same name, AR68 replaces only the first module it finds that matches the one specified in the command line. AR68 replaces modules already in the library only if you specify their names prior to the names of new modules to be added to the library. For example, if you specify the name of a module that you want replaced after the name of a module that you are adding to the library, AR68 adds both modules to the end of the library.

By default, the R command adds new modules to the end of the library. The R command adds an object module to a library if:

• The object module does not already exist in the library.

• You specify the A option in the command line.

• The name of a module follows the name of a module that does not already exist in the library.

-------------------------[l]] DIGITAL RESEARCH™ 7-4


Command I Option

A

V

7.1 Archive Utility


Meaning

The A option indicates where AR68 adds modules to the library. You specify the relative position by including the OPMOD parameter with the A option.

In addition to the A option, the R command also supports the V option, which lists the modules in the library and indicates the result of the operation performed on the library. All options are described below. Examples illustrate their use. adds one or more object modules following the module specified in the command line:

A)AR68 RAV SDAv,a MYRAH,ARC MaRK,a MAIL,a c much.o c sdav.o a worK.o a mail.o c less.o

The RA V command adds the object modules WORK.O and MAlL.O after the module SDAV.O in the library MYRAH.ARC. The V option, described below, lists all the modules in the library. New modules are preceded by the lower-case letter a and existing modules are preceded by the lowercase letter c.

lists the object modules that the R command replaces or adds.

A)AR68 RV JNNK,MAN NAIL,a MRENCH,a c saw.o c ham.o r nail.o c screw.o a wrench.o

A)

[!QJ DIGITAL RESEARCH™ -------------------------7-5

7.1 Archive Utility

Command I Option I

T

V

CP/M-6SK Programmer's Guide


Meaning

The R command replaces the object module NAIL.O and adds the module WRENCH.O to the library JNNK.MAN. The V option lists object modules in the library and indicates which modules are replaced or added. Each object module that is replaced is preceded with the lower-case letter r and each one that is added is preceded with the lower-case letter a.

requests AR68 print a table of contents or a list of specified 'modules in the library. The T command prints a table of contents of all modules in the library only when you do not specify names of object modules in the command line.

displays the size of each file in the table of contents as shown in the following example.

A)ARGB TV WINE,BAD rl ... l- rl ... l- rl ... l- 0/0 8818 rose.o rl ... l- r .... l- rl ... l- 0/0 2348 1 ... lhite.o r .... l- r .... l- rl ... l- 0/0 388 red.o

A)

The T command prints a table of contents in the library WINE.BAD. In addition to listing the modules in the library, the V option indicates the size of each module. The character string rw-rw-rw- 010 that precedes the module size is meaningless for CP/M-68K. However, if the file is transferred to a UNIX® system, the character string denotes the file protection and file owner. The size specified by the decimal number that precedes the object module name indicates the number of bytes in the module.

------------------------- [!Q] DIGITAL RESEARCHT•

7-6

CP/M-68K Programmer's Guide 7.1 Archive Utility


Command I Option 1 Meaning

W writes a copy of an object module in the library to the >filespec parameter specified in the command line. This command allows you to extract a copy of a module from a library and rename the copy when you write it to another disk, as shown below. For this command, the >filespec parameter is not optional.

A>AR68 W GD,ARC NDW,D '>B:NEWNAME,D

The W command writes a copy of the object mod-ule NOW.O from the library GO.ARC to the file NEWNAME.O on drive B.

X extracts a copy of one or more object modules from a library and writes them to the default disk. If no object modules are specified in the command line, the X command extracts a copy of each module in the library.

V lists only those modules the X command extracts from the library. It precedes each extracted module with the lower-case letter:

A )AR68 XV JNN/f,MAN SAW,D HAM,D SCREW,D x saw.o x h alrl. 0 x screw.o

The V option with the X command lists only the modules SA W.O, HAM.O, and SCREW.O that the X command extracts from the library JNNK.MAN and precedes each of these modules with the lower-case letter x.

[!Q] DIGITAL RESEARCHTN --------------------------

7-7

7.1 ARCHIVE Utility CP/M-68K Programmer's Guide

7.1.4 Errors

When AR68 incurs an error during an operation, the operation is not completed. The original library is not modified if the operation would have modified the library. Thus, no modules in the library are deleted, replaced, added, or extracted. Refer to Appendix E for error messages output by AR68.

When you specify the >filespec parameter in the command line to redirect the output and one or more errors occur, the error messages are sent to the output file. Thus, you cannot detect the errors without displaying or printing the file to which the output was sent. If the contents of the output file is an object file (see the W command), you must use the DUMP Utility described in Section 7.2 to read any error messages.

7.2 DUMP Utility

The DUMP Utility (DUMP) displays the contents of a CP/M file in both hexadecimal and ASCII notation. You can use DUMP to display any CP/M file regardless of the format of its contents (binary data, ASCII text, an executable file).

7.2.1 Invoking DUMP

Invoke DUMP by entering a command in the following format.

DUMP [ -sxxxx ] filename1 [ >filename2 ]

-------------------------I!ID DIGITAL RESEARCH™ 7-8

CP/M-68K Programmer's Guide 7.2 DUMP Utility

Table 7-3. DUMP Command Line Components

Component I Meaning

-sxxxx xxxx is an optional offset (in hexadecimal) into the file. If specified, DUMP starts dumping the contents of the file from the byte-offset xxxx and continues until it displays the contents of the entire file. By default, DUMP starts dumping the contents of the file from the beginning of the file until it dumps the contents of the entire file.

filenamel is the name of the file you want to dump.

>filename2 the greater than sign (» followed by a filename- or logical device optionally redirects the output of DUMP. You can specify any valid CP/M specification, or one of the logical device names CON: (console) or LST: (list device). If you do not specify this optional parameter, DUMP sends its output to the console.

7.2.2 DUMP Output

DUMP sends the output to the console (or to a file or device, if specified), 8 words per line, in the following format:

rrrr 00 (ffffff): hhhh hhhh hhhh hhhh hhhh hhhh hhhh hhhh * aaaaaaaaaaaaaaaa *

[Q] DIGITAL RESEARCH™ -------------------------7-9

7.2 DUMP Utility CP/M-68K Programmer's Guide

Table 7-4. DUMP Output Components

Component I Meaning

rrrr is the record number (CP/M records are 128 bytes) of the current line of the display.

00 is the offset (in hex bytes) from the beginning of the CP/M record.

ffffff is the offset (in hex bytes) from the beginning of the file.

hhhh is the contents of the file displayed in hexadecimal.

aaaaaaaa is the contents of the file displayed as ASCII characters. If any character is not representable in ASCII, it is displayed as a period (.).

7.2.3 DUMP Examples

The following example shows the DUMP Utility. The example shows the contents of a command file that contains both binary and ASCII information.

A)duMP dUMP,68k 0000 00 (000000): 601a 0000 lb3a 0000 011d 0000 Oe5e 0000 *' •••• a ••••••• " •• * 0000 10 (000010) : 0000 0000 0000 0000 0900 ffff 603a a320 * •••••••••••• 'ac * 0000 20 (000020): 5275 6e7a 696d 6520 a36f 7079 7269 6768 *RuntiMe CoPYri~h* 0000 30 (000030) : 7a20 3139 3832 2062 7920 lIa69 6769 71161 *t 1982 by Di~ita*

0000 lIO (OOOoao) : 6c20 5265 7365 6172 6368 2056 3031 2c30 *1 Research V01.0* 0000 50 (000050): 3320 206f oooa 2268 0018 26a9 d3e8 001c *3 O •• "h •• &cISh •• *

.... (and so on) ...

--------------------------I!QJ DIGITAL RESEARCH™ 7-10

CP/M-68K Programmer's Guide 7.3 Relocation Utility

7.3 Relocation Utility

The Relocation Utility (RELOC) creates an absolute file from a relocatable command file. See Section 3 for a description of the CP/M-68K command file format. An absolute file is a file that is loaded at an absolute address. RELOC creates the absolute file by relocating the address constants in the file before it strips off the relocation bits. Thus, RELOC creates a new file but does not alter the original file.

The advantage of using RELOC is RELOC decreases the size of the file and increases performance. You can load the absolute command file into memory approximately twice as fast as its relocatable counterpart and it occupies half the disk storage space.

7.3.1 Invoking RELOC

You invoke RELOC by entering a command in the format:

RELOC [-Baddress] input filename output filename

[ij] DIGITAL RESEARCHT• -------------------------

7-11

7.3 Relocation Utility CP/M-68~ Programmer's Guide

Table 7-5. RELOC Command Line Components

Component I Meaning

-Baddress The address parameter is the absolute address for the command file. The address parameter is optional. If you do not specify the address parameter, RELOC uses the base address at which it runs as the default address for relocating the input file. See the first example in Section 7.3.2. The base address of the file is normally the lowest address in the TP A + 100H .

. . input filename The input filename is the file specification of the relocatable command

file that RELOC converts to an absolute file.

output filename The output filename is the file specification of the absolute file RELOC creates.

7.3.2 RELOC Examples

This section contains two examples of RELOC. The first example illustrates how to relocate a file with the filetype of REL to the bottom of the TP A. You can use this example to create an absolute command file that runs in the bottom of the TP A. The second example illustrates how to specify an alternate address for a command file.

1. In this example, the RELOC.REL file distributed with CP/M-68K is used to relocate itself. The resulting file, RELOC.68K, uses its base address for the absolute address of an input file when the address parameter of the input file is not specified. You can ·use this example to relocate other utilities with a filetype of REL so that they also run in the bottom of the TP A.

A)RELOC.REL RELOC.REL RELOC.BBK

The RELOC.REL file relocates itself and outputs the file RELOC.68K. The command file RELOC.68K is an absolute file that runs at the bottom of the TPA.

------------------------- [!ID DIGITAL RESEARCHTN

7-12

CP/M-68K Programmer's Guide 7.3 Relocation Utility

2. In this example, RELOC creates an absolute file that must be loaded at a specific address.

A)RELOC -8500 JUNK,REL JUNK,BBK

RELOC converts the relocatable command file, JUNK.REL, to the absolute command file, JUNK.68K, which must load into memory at location SOOH.

7.4 SIZE68 Utility

The SIZE68 Utility (SIZE68) displays the sizes of each program segment within one or more command files and the total memory needed by each file. CP/M-68K command files usually have a filetype of .68K or .REL. The size of a command file returned by SIZE68 and the size of a command file returned by the STAT command are not equal. The file size returned by SIZE68 includes the size of the text, data, and bss program segments but does not include the size of the header, symbol table, and relocation bits. For more details on the CP/M-68K command file format, refer to Section 3. For more details on the STAT command, refer to the CPIM-68K Operating System User's Guide.

7.4.1 Invoking SIZE68

You invoke SIZE68 by entering the SIZE68 command line in the following format:

SIZE68 filename [filename2 filename3 ... ] [ >outfile ]

!!ill DIGITAL RESEARCH'" -------------------------7-13

7.4 SIZE68 Utility CP/M-68K Programmer's Guide

Component I filename

filename 1 filename2

>outfile

Table 7-6. SIZE68 Command Line Components

Meaning

the file specification of a file whose size you want to determine.

one or more additional file specifications of files whose size you want to determine. SIZE68 can process multiple files, provided the command line does not exceed 128 bytes.

specifies the file specification to which SIZE68 sends its output. If you do not specify an output file specification, SIZE68 sends the output to the console. For the output file specification, you can specify a valid CP/M filename, or one of the logical device names CON: (console), or LST: (list device).

7.4.2 SIZE68 Output

SIZE68 produces one output line for each input file you specify. The output line should be in the following format:

filename: csize + dsize + bsize = totsize (hexsize) stack size =' ssize

-------------------------- [!IDDIGITAL RESEARCH™ 7-14

CP/M-68K Programmer's Guide 7.4 SIZE68 Utility

Table 7-7. SIZE68 Output Components

Component I Meaning

cSIze is the size, in decimal bytes, of the text segment of the file.

dsize is the size, in decimal bytes, of the data segment of the file.

bsize is the size, in decimal bytes, of the block storage segment (bss) of the file.

totsize is the total size, in decimal bytes, of the memory image occupied by the file. It is the sum of csize, dsize, and bsize.

hexsize is the same value as totsize, expressed in hexadecimal bytes.

sSIze is the size of the stack required by the file.

For an explanation of the program segments of a command file, see Section 3, Command File Format.

7.4.3 SIZE68 Examples

This section contains examples of the SIZE68 Utility.

1. The SIZE68 command line specified in this example returns the size of one command file and its program segments.

A>sizeBB reloc,BBk reloc.88k:11330+1012+2822=15284 (3BAO) stacksize=O

The program file reloc.68k contains a 11330-byte (decimal) text segment, a 1012-byte (decimal) data segment, and a 2922-byte (decimal) bss. The total size of the program file is 15264 decimal bytes, which is the same as 3BAO hexadecimal bytes. The header in the Reloc.68k file does not specify a minimum stack size. However, when CP/M-68K loads a command file, CP/M-68K always reserves at least 256 bytes for the user stack. CP/M-68K also creates a 256-byte base page. Therefore, to run reloc.68k, the minimum size of the TPA cannot be less than 15776 decimal bytes (15264 bytes for the program, 256 bytes for the stack, and 256 bytes for the base page).

l!ID DIGITAL RESEARCHT. --------------------------7-15

7.4 SIZE68 Utility CP/M-68K Programmer's Guide

2. The SIZE68 command line specified in this example returns the size of several program files and their program segments.

A)sizeBB size,BBk, dUMP,BBk size88.88R:7010+388+3708=1110a (2680) stac~\ size = 0 dll{T1P.88~\:898a+288+3878=10928 (2A60) stac~\ size = 0

When you specify multiple file specifications in a command line, use a comma to delimit each file specification.

3. If you specify a file that is not a common file, SIZE68 returns an error message as shown below.

A)sizeBB clink,sub Not c.out forMat: clinR.sub

SIZE68 printed an error message because clink. sub is an ASCII file and not a command file. Files input to SIZE68 must be command files. Refer to Section 3 for the format of CP/M-68K command files.

7.5 SENDC68 Utility

The SENDC68 Utility (SENDC68) creates a file with Motorola S-record format from an absolute command file. S-records are a means of representing an absolute program in ASCII character form. For a detailed description of the S-record format, refer to the CPIM-68K Operating System System Guide.

7.5.1 Invoking SENDC68

You invoke SENDC68 by entering a command in the following format:

SENDC68 [-] input file [output file]

------------------------- l!IDDIGITAL RESEARCH™

7-16

CP/M-68K Programmer's Guide 7.5 SENDC68 Utility

Component I

input file

output file

Table 7-8. SENDC68 Command Line Components

Meaning

The hyphen is optional. If you specify the hyphen, SENDC68 does not create any S-records for the bss program segment. If you do not specify the hyphen, SENDC68 fills the bss with zeroes. Thus, if you specify the hyphen, SENDC68 creates a smaller S-record file.

The file specification for the command file that SENDC68 converts to S-record format. The command file must be an absolute file in the format produced by L068 or RELOC.

The file specification of the SENDC68 output file containing the S-records. If you do not specify a file, SENDC68 sends the S-record that it outputs to the console.

7.5.2 SENDC68 Example

This section contains an example of the SENDC68 command line. The following example illustrates how to create a file that contains Motorola S-records from an absolute command file.

A)SENDC68 - JUNK,68K JUNK,SR

In the above example, SENDC68 creates the S-record file JUNK.SR from the absolute command file JUNK.68K. However, the file JUNK.SR does not contain S-records for the bss program segment.

End of Section 7

ill DIGITAL RESEARCHT• -------------------------

7-17

8.1 DDT-68K Operation

Section 8 DDT-68K

DDT-68KTM allows you to test and debug programs interactively in a CP/M-68K environment. You should be familiar with the MC68000 Microprocessor, the assembler (AS68) and the CP/M-68K operating system. .

8.1.1 Invoking DDT-68K

Invoke DDT-68K by entering one of the following commands:

DDT DDT f i 1 enafTle

The first command loads and executes DDT -68K. After displaying its sign-on message and the hyphen (-) prompt character, DDT-68K is ready to accept commands. The second command invokes DDT-68K and loads the file specified by filename. If the filetype is not specified, it defaults to the 68K filetype. The second form of the command is equivalent to the sequence:

A)DDT DDT-68K Cop~'ri9'ht 1882t Di9'ital Research -Ef i 1 en afTle

At this point, the program that was loaded is ready for execution.

8.1.2 DDT-68K Command Conventions

When DDT-68K is ready to accept a command, it prompts you with a hyphen (-). In response, you can type a command line or a CONTROL-C ("C) to end the debugging session (see Section 8.1.4). A command line can have as many as 64 characters, and must be terminated with a RETURN. While entering the command, use standard CP/M line-editing functions to correct typing errors. See Table 4-15. DDT-68K does not process the command line until you enter a RETURN.

[!ID DIGITAL RESEARCH'" -------------------------8-1

8.1 DDT -68K Operation CP/M-68K Programmer's Guide

The first nonblank character of each command line determines the command action. Table 8-1 summarizes DDT -68K commands. They are defined individually in Section 8.2.

Table 8-1. DDT-68K Command Summary

Command I Action

D display memory in hexadecimal and ASCII E load program for execution F fill memory block with a constant G begin execution with optional breakpoints H hexadecimal arithmetic I set up file control block and command tail L list memory using MC68000 mnemonics M move memory block R read disk file into memory S set memory to new values T trace program execution U untrace program monitoring V show memory layout of disk file read W write contents of memory block to disk X examine and modify CPU state

The command character can be followed by one or more arguments, which may be hexadecimal values, filenames, or other information, depending on the command. Some commands can operate on byte, word, or longword data. The letter W for word or a L for longword must be appended to the command character for commands that operate on multiple data lengths. Details for specific commands are provided with the command descriptions. Arguments are separated from each other by commas or spaces.

8.1.3 Specifying Addresses

Most DDT-68K commands require one or more addresses as operands. All addresses are entered as hexadecimal numbers of up to eight hexadecimal digits (32 bits).

8.1.4 Terminating DDT-68K

Terminate OOT-68K by typing a lC in response to the hyphen prompt. This returns control to the CCP.

-------------~------------ (l]] DIGITAL RESEARCHTM 8-2

CP/M-68K Programmer's Guide 8.1 DDT-68K Operation

8.1.5 DDT-68K Operation with Interrupts

DDT-68K operates with interrupts enabled or disabled, and preserves the interrupt state of the program being executed under DDT-68K. When DDT-68K has control of the CPU, either when it is initially invoked, or when it regains control from the program being tested, the condition of the interrupt mask is the same as it was when DDT-68K was invoked, except for a few critical regions where interrupts are disabled. While the program being tested has control of the CPU, the user's CPU state, which can be displayed with the X command, determines the state of the interrupt mask.

Note that DDT-68K uses the Trace and Illegal Instruction exceptions. Therefore, programs debugged under test should not use these.

8.2 DDT-68K Commands

This section defines DDT-68K commands and their arguments. DDT-68K commands give you control of program execution and allow you to display and modify system memory and the CPU state.

8.2.1 The D (Display) Command

The D command displays the contents of memory as 8-bit, 16-bit, or 32-bit hexadecimal values and in ASCII. The forms are:

D Ds Ds,f DW DWs DWs,f DL DLs DLs,f

where s is the starting address, and f is the last address that DDT-68K displays.

Memory is displayed on one or more lines. Each line shows the values of up to 16 memory locations. For the first three forms, the display line appears as follows:

aaaaaaaa bb bb ... bb cc ... cc


8-3

8.2 DDT-68K Commands CP/M-68K Programmer's Guide

where aaaaaaaa is the address of the data being displayed. The bb's represent the contents of the memory locations in hexadecimal, and the c's represent the contents of memory in ASCII. Any nongraphic ASCII characters are represented by periods.

In response to the Ds form of the D command, shown above, DDT-68K displays 12 lines that start from the current address. Form Ds,f displays the memory block between locations sand f. Forms DW, DWs, and DWs,f are identical to D, Ds, and Ds,f except the contents of memory are displayed as 16-bit values, as shown below:

aaaaaaaa wwww wwww ... wwwwcccc ... cc

Forms DL, DLs, and DLs,f are identical to D, Ds, and Ds,f except the contents of memory are displayed as 32-bit or longword values, as shown below:

aaaaaaaa llllllllllllllll ... llllllll ecce ecce ...

During a display, the D command may be aborted by typing any character at the console.

8.2.2 The E (Load for Execution) Command

The E command loads a file in memory so that a subsequent G, T or U command can begin program execution. The syntax for the E command is:

E<filename>

where <filename> is the name of the file to be loaded. If no file type is specified, the filetype 68K is assumed.

An E command reuses memory used by any previous E command. Thus, only one file at a time can be loaded for execution.

When the load is complete, DDT-68K displays the starting and ending addresses of each segment in the file loaded. Use the V command to display this information at a later time.

If the file does not exist or cannot be successfully loaded in the available memory, DDT-68K displays an error message. See Appendix E for error messages returned by DDT-68K.

--------------------------I!Q] DIGITAL RESEARCH TN

8-4

CP/M-68K Programmer's Guide 8.2 DDT-68K Commands

8.2.3 The F (Fill) Command

The F command fills an area of memory with a byte, word, or longword constant. The forms are

Fs,f,b FWs,f,w FLs,f,1

where s is the starting address of the block to be filled, and f is the address of the final byte of the block within the segment specified in s.

In response to the first form, DDT-68K stores the 8-bitvalue b in locations s through f. In the second form, the I6-bit value w is stored in locations s through f in standard form: the high 8 bits are first, followed by the low 8 bits. In the third form, the 32-bit value I is stored in locations s through f with the most significant byte first.

If s is greater than f, DDT-68K responds with a question mark. Also, if b is greater than FF hexadecimal (255), w is greater than FFFF hexadecimal (65,535), or I is greater than FFFFFFFF hexadecimal (4,294,967,295), DDT-68K responds with a question mark. DDT-68K displays an error message if the value stored in memory cannot be read back successfully. This error indicates a faulty or nonexistent RAM location.

8.2.4 The G (Go) Command

The G command transfers control to the program being tested, and optionally sets one to ten breakpoints. The forms are

G G,bl, ... bIO Gs Gs,bl, ... bIO

where s is the address where program begins executing and bi through blO are addresses of breakpoints.

In the first two forms, no starting address is specified. DDT-68K starts executing the program at the address specified by the program counter (PC). The first form transfers control to your program without setting any breakpoints. The second form sets breakpoints before passing control to your program. The next two forms are analogous to the first two except that the PC is first set to s.

IIID DIGITAL RESEARCHT• --------------------------

8-5

8.2 DDT -68K Commands CP/M-68K Programmer's Guide

Once control has been transferred to the program under test, it executes in real time until a breakpoint is encounter~d. At this point, DDT-68K regains control, clears all breakpoints, and displays the CPU state in the same form as the X command. When a breakpoint returns control to DDT -68K, the instruction at the breakpoint address has not yet been executed. To set a breakpoint at the same address, you must specify a T or U command first.

8.2.5 The H (Hexadecimal Math) Command

The H command computes the sum and difference of two 32-bit values. The form is:

Ha,b

where a and b are the values whose sum and difference DDT-68K computes. DDT-68K displays the sum (ssssssss) and the difference (dddddddd) truncated to 32 bits on the next line:

ssssssss dddddddd

8.2.6 The I (Input Command Tail) Command

The I command prepares a file control block (FCB) and command tail buffer in the base page of the last file loaded with the E command. The form is

I<command tail>

where <command tail> is the character string which usually contains one or more filenames. The first filename is parsed into the default file control block at 005CH. The optional second filename, if specified, is parsed into the second default file control block beginning at 0038H. The characters in the <command tail> are also copied to the default command buffer at 0080H. The length of the <command tail> is stored at 0080H, followed by the character string terminated with a binary zero.

If a file has been loaded with the E command, DDT-68K copies the file control block and command buffer from the base page of DDT-68K to the base page of the program loaded.

-------------------------I!ID DIGITAL RESEARCH™

8-6


8.2.7 The L (List) Command

The L command lists the contents of memory in assembly language. The forms are

L Ls Ls,f

where s is the starting address, and f is the last address in the list.

The first form lists 12 lines of disassembled machine code from the cur-rent address. The second form sets the list address to s and then lists 12 lines of code. The last form lists disassembled code from s through f. In all three cases, the list address is set to the next unlisted location in preparation for a subsequent L command. When DDT-68K regains control from a program being tested (see G, T and U commands), the list address is set to the address in the program counter (PC).

Long displays can be aborted by typing any key during the list process. Or, enter CONTROL-S (is) to halt the display temporarily. A CONTROL-Q (iQ) restarts the display after is halts it.

The syntax of the assembly language statements produced by the L command is described in the Motorola 16-Bit Microprocessor User's Manual, third edition, MC68000UM(AD3).

8.2.8 The M (Move) Command

The M command moves a block of data values from one area of memory to another. The form is

Ms,f,d

where s is the starting address of the block to be moved, f is the address of the final byte to be moved, and d is the address of the first byte of the area to receive the data. Note that if d is between sand f, part of the block being moved will be overwritten before it is moved, because data is transferred starting from location s.

I!ID DIGITAL RESEARCHTM -------------------------8-7


8.2.9 The R (Read) Command

The R command reads a file to a contiguous block in memory. The format is

R <filename>

where <filename> is the name and type of the file to be read.

DDT-68K reads the file into memory and displays the starting and ending addresses of the block of memory occupied by the file. A Value (V) command can redisplay the information at a later time. The default display pointer (for subsequent Display (D) commands) is set to the start of the block occupied by the file.

8.2.10 The S (Set) Command

The 5 command can change the contents of bytes, words, or longwords in memory. The forms are

5s SWs 5Ls

where s is the address where the change is to occur.

DDT-68K displays the memory address and its current contents on the following line. In response to the first form, the display is

aaaaaaaa bb

In response to the second form, the display is

aaaaaaaa wwww

In response to the third form, the display is

aaaaaaaa mllm

where bb, wwww, and mUlll are the contents of memory in byte, word, and longword formats, respectively.

-------------------------I!QJ DIGITAL RESEARCH™

8-8


In response to one of the above displays, you can alter the memory location or leave it unchanged. If a valid hexadecimal value is entered, the contents of the byte, word, or longword in memory is replaced with the value entered. If no value is entered, the contents of memory are unaffected and the contents of the next address are displayed. In either case, DDT-68K continues to display successive memory addresses and values until either a period or an invalid value is entered.

DDT-68K displays an error message if the value stored in memory cannot be read back successfully. This error indicates a faulty or nonexistent RAM location.

8.2.11 The T (Trace) Command

The T command traces program execution for 1 to OFFFFFFFFH program steps. The forms are

T Tn

where n is the number of instructions to execute before returning control to the console.

After DDT -68K traces each instruction, it displays the current CPU state and the disassembled instruction in the same form as the X command display.

Control transfers to the program under test at the address indicated in the PC. If n is not specified, one instruction is executed. Otherwise, DDT-68K executes n instructions and displays the CPU state after each step. You can abort a long trace before all the steps have been executed by typing any character at the console.

After a Trace (T) command, the list address used in the L command is set to the address of the next instruction to be executed.

Note that DDT-68K does not trace through a BDOS interrupt instruction, since DDT-68K itself makes BDOS calls and the BDOS is not reentrant. Instead, the entire sequence of instructions from the BDOS interrupt through the return from BDOS is treated as one traced instruction.

[ID DIGITAL RESEARCHT• --------------------------

8-9

8.2 DDT-68K Commands· CP/M-68K Programmer's Guide

8.2.12 The U (Untrace) Command

The U command is identical to the Trace (T) command except that the CPU state is displayed only after the last instruction is executed, rather than after every step. The forms are

U Un

where n is the number of instructions to execute before control returns to the console. You can abort the Untrace (U) command before all the steps have been executed by typing any key at the console.

8.2.13 The V (Value) Command

The V command displays information about the last file loaded with the Load For Execution (E) or Read (R) commands. The form is

V

If the last file was loaded with the E command, the V command displays the starting address and length of each of the segments contained in the file, the base page pointer, and the initial stack pointer. The format of the display is

Text base=00000500 data base=OOOOOB72 bss base=00003FDA text len9'th=00000872 data len9'th=000031188 bss len9'th=OOOOA1BO base pa9'e address=OOOOOllOO initial stad, pointer=000088Dll

If no file has been loaded, DDT -68K responds to the V command with a question mark (?).

8.2.14 The W (Write) Command

The W command writes the contents of a contiguous block of memory to disk. The forms are

W <filename> W <filename> ,s,f

The <filename> is the file specification of the disk file that receives the data. The letters sand f are the first and last addresses of the block to be written. If f does not specify the last address, DDT-68K uses the same value that was used for s.

-------------------------[QJ DIGITAL RESEARCH'" 8-10


If the first form is used, DDT-68K assumes the values for sand f from the last file read with a R command. If no file is read by an R command, DDT-68K responds with a question mark (?). This form is useful for writing out files after patches have been installed, assuming the overall length of the file is unchanged.

If the file specified in the W command already exists on disk, DDT-68K deletes the existing file before it writes the new file.

8.2.15 The X (Examine CPU State) Command

The X command displays the entire state of the CPU, including the program counter (PC), user stack pointer (usp), system stack pointer (ssp), status register (by field), all eight data registers, all eight address registers, and the disassembled instruction at the memory address currently in the pc. The forms are

X Xr

wher'e r is one of the following registers:

DO to D7, AO to A7, PC, USP, or SSP

The first form displays the CPU state as follows:

PC = 000 1 8000 US P = 0000 1 000 SSP = 00002000 S T = F F F F = > (etc.) D 00001000 OOOOODO 1 ••• 00000001 A OOOBOAOO OOOAOO 1 0 ••• 00000000 lea $18028 tAO

The first line includes:

PC Program Counter USP User Stack Pointer SSP System Stack Pointer ST Status Register

Following the Status Register contents on the first display line, the values of each bit in the Status Register are displayed, as shown in the following sample:

TR SUP IM=7 EXT NEG ZER DFL CRY

I!ID DIGITAL RESEARCHT• -------------------------

8-11


This sample display includes:

TR SUP

IM=7 EXT NEG ZER OFL CRY

Trace Bit Supervisor Mode Bit Interrupt Mask = 7 Extend Negative Zero Overflow Carry

The second form, Xr, allows you to change the value in the registers of the program being tested. The r denotes the register. DDT-68K responds by displaying the current contents of the register, leaving the cursor on that line. If you type a RETURN, the value is not changed. If you type a new valid value and a RETURN, the register is changed to the new value. The contents of all registers except the Status Register can be changed.

8.3 Assembly Language Syntax for the L Command

In general, the syntax of the assembly language statements used in the L command is standard Motorola 68000 assembly language. Several minor exceptions are given in the following list:

• DDT-68K prints all numeric values in hexadecimal. • DDT-68K uses lower-case mnemonics. • DDT-68K assumes word operations unless a byte or longword specification is

explicitly stated.

End of Section 8

-------------------------[!ID DIGITAL RESEARCH™ 8-12

Appendix A Summary of BIOS Functions

Table A-1lists the BIOS functions supported by CP/M-68K. For more details on these functions, refer to the CPIM-68K Operating System System Guide.

Table A-1. Summary of BIOS Functions

Function J F# J Description

Init 0 Called for Cold Boot Warm Boot 1 Called for Warm Start Const 2 Check for Console Character Ready Conin 3 Read Console Character In Conout 4 Write Console Character Out List 5 Write Listing Character Out Auxiliary Output 6 Write Character to Auxiliary Output Device Auxiliary Input 7 Read from Auxiliary Input Device Home 8 Move to Track 00 Seldsk 9 Select Disk Drive Settrk 10 Set Track Number Setsec 11 Set Sector Number Setdma 12 Set DMA Offset Address Read 13 Read Selected Sector Write 14 Write Selected Sector Listst 15 Return List Status Sectran 16 Sector Transla te Get Memory Region

Table Address 18 Address of Memory Region Table . Get 110 Byte 19 Get 110 Mapping Byte Set 110 Byte 20 Set 110 Mapping Byte Flush Buffers 21 Writes Modified Buffers Set Exception Vector 22 Sets Exception Vector

End of Appendix A

[!QJ DIGITAL RESEARCHTW -------------------------=---A-1

Appendix B Transient Program Load Examples

This appendix contains two examples, an assembly language program and a C language program. Both illustrate how a transient program loads another program with the BDOS Program Load Function (59) but without the CCP.

Examples:

1. The following example is an AS68 assembly language program that loads another program into the TP A.

* * reboot printstr open setdflla P9'flll df 9'ettpa

* * * start:

* *

BDDS Function Definitions

0 8

15 26 58 63

.text

DPEN file to be loaded

lin f, a6,$O fllove.l 8 (a6) ,aO lea $5c(aO),al fllove .1 a 1 ,d 1 fllove .w #open,dO trap #2 CfllP i #255,dO beq openerr

*MarK stacK fraMe *9'et the address of the base pa9'e *9'et address of 1st parsed FCB in base pa9'e *put that address in re9'ister dl *put BDoS function nUMber in re9'ister dO *try to open the file to be loaded *test dO for BDoS error return code *if dO = 255 then 9'oto openerr

COMPute Address to Load File

Listing B-1. Transient Program Load Example 1

~DIGITALRESEARCHTW--------------------------------------------------------------

B-1

·1.'····' , .

;~ p .". ~

B Transient Program Load Example CP/M-68K Programmer's Guide

clear:

* * * * * *

1110 V e. 1 $18(aO) ,d2 ItlO I.Ie. 1 $1c(aO) ,d3 add.1 d2,d3

1110 ve. 1 $20(aO),dll sub #100,dll 1110 1.1 e .1 dll,d5 add.1 d3,dll Illove.1 d3,a3

sub #1 ,d5 c I r. b (a3)+

dbf d5,clear

FILL the LPB

*get starting address of bss froM base page *get length of bss *COMPute first free byte of MeMOry *after bss *get length of free MeMOry after bss *leave SOMe extra rOOM *save that length in register d5 *COMPut~ high end of free MeMOry after bss *get the starting address of free MemOry *into a3 *adJust loop counter *clear out free MeMOry

*decreMent loop counter and loop until *negative

Low address becoMes first free byte of MemOry after bss High address of area in which to load prograM becomes the Low address plus length of free MemOry

*---------------------------------------------------------------------------------*

*

*

* * *

1110 I.le. 1 d3 ,I olAlad r

1110 ve. 1 dll,hiadr

1110 IJ e. 1 al ,LPB 1110 ve .IAI #pglllldf ,dO 11101.1 e. 1 #LPB,d1 trap #2 tst #dO bne lderr

*get low end of area in which to load *p ro g ralll *get high end of area in which to load *p ro g ralll *put address of open FeB into LPB *get BOOS prograM load function nUMber *put address of LPB into register d1 *do the prograM load *was the load successful? *if not then print error Message

Set default OMA address

Move.1 baspag,d1 add #$80,d1 Move.w #setdMa,dO trap

*d1 points to new prograM's base page *d1 points to default dMa in base page *get BOOS function number *set the default dMa add~ess

Listing B-1. (continued)

-----------------------------!!ID DIGITAL RESEARCH TN

B-2

CP/M-68K Programmer's Guide B Transient Program Load Example

* *

*

*

*

* openerr:

*

Iderr:

print:

c(lld rtn:

*

*

*

*

NOIAI push needed add resses on stacf:

(Ilovea.l

(110 ve. 1 (Ilove.l

(Ilove.l

(110 ve. 1

rts

us rstf: ,a7 baspag,al al,-(sp)

#c(lldrtn,-(sp) 8(al) ,-(sp)

*set UP user stacf: pointer *get address of base page

*push base page address

*push return address

*push add ress to jU(11P to *jU(11P to nelAI prOgra(ll

P ri nt ERROR (lleSSage

(Ilove.l

bra (110 I)e. 1

(110 I) e. IAI

trap

(110 I)e. IAI

trap

DATA

.data

.even

#0 pen(11S 9 ,d 1

p ri nt

#loaderr,dl

*get address of error message

*to be printed

*get address of error message to *be printed

#printstr,dO *get BOOS function number *print the message #2

#reboot,dO #2

*get BOOS function number

*warmboot and return to the CCP


~DIGITALRESEARCHTM-----------------------------------------------------------B-3


* * LPB: I olAlad r:

* hiadr:

* baspag: usrstf~:

flags:

* * * TPAB:

loaderr: openlTlsg:

LOAD PARAMETER BLOCK

• d s. 1 • ds. 1

.ds.l

• ds. 1 • d s • 1 • de .1,..1 0

*FCB address of prografrl file *Low boundary of area in which *to load prografrl *High boundary of area in which to *to load program *Base page address of loaded prograM *Loaded program's initial stacH pointer *Load program function control flags

TPA Parameter BlocH

• el.len • de .IAI

• ds. 1 .ds.l

.even

.end

o

.dc.b 13t10,'PrografTl Load Error$'

.dc.b 13,10,'Unable to Open File$'


----------------------------- [!ill DIGITAL RESEARCHTM B-4


2. The following example is a C language transient program that loads another program in the TP A without the assistance of the CCP. The C language program calls an AS68 assembly language routine to perform tasks not permitted by the C language.

1*---------------------------------------------------- ---------------------*

'C' Language Program to Load Another Program into the TPA

*----------------------------------------------------- --------------------*1

1* DEFINES *1

#define 5SS_DFFSET (10ng)Ox18 #define FCB_DFFSET (10ng)Ox5C #define 5SS_LENGTH (10ng)Ox1C #define FREE-MEMORY (10ng)Ox20 #define DMA_OFFSET (10ng)Ox80 #define ROOM (10ng)Ox100 #define NULL '0 ' #define CR (10ng)13 #define LF (10ng)10 #define REBOOT 0 #define CON_OUT 2 #define PRINTSTR 8 #define OPEN 15 #define SETDMA 26 #define PGMLDF 58 #define GETTPA 63

Listing B-2. Transient Program Load Example 2

I!IDDIGITAL RESEARCH™ ----------------------------B-5

B Transient Program Load Example

1* Error Messases *1

char openrrlss[20J "Unable to Open File$"; char 10adrrlssU9J "PrOSrafTl Load Error$";

1* Load ParaMeter BlocK *1

extern Ions LPB,lowadr,hiadr,baspas,usrstK; extern int flass;

1* TPA ParaMeter BlocK *1

extern int TPAB; extern long low,hish;



----------------------------- [!]) DIGITAL RESEARCH™ B-6

CP/M-6SK Programmer's Guide B Transient Program Load Example

openfile(baseaddr) 1********************************1 register char {

*baseaddr; 1* base page address *1 1* *1

register long register long register char

*tl,*t2; count; *pt rl ,*pt r2;

1* 1* 1*

pointers Ion g wo rd pointers

to long word values *1 value *1

to character values *1 1* *1 1* *1

ptrl = baseaddr + FCB_OFFSET; if(bdos(OPEN,ptrl) <= 3)

1* 1*

get address trY to open

of FCB *1 the f i Ie *1

{

tl = baseaddr + BSS_OFFSET;

t2 = baseaddr + BSS_LENGTH;

lowadr = *tl + *t2;

p t r2 = Iowa d r

t2 = baseaddr + FREE_MEMORY;

1* 1* 1* 1* 1* 1* 1* 1* 1* 1* 1* 1* 1*

*1 set pointer to STARTING add r *1 of the BSS segment *1 set pointer to LENGTH of *1 the BS5 segment *1 compute the fir s t free byte *1 address of memo ry af t e r the *1 B55 segment *1 *ptr2 now points to firs t *1 f re e byte in MeMOry *1 get length of f re e memory *1 after the B55 segment *1

*1 hiadr = *t2 + lowadr 1* COMPute high end of available*1

count = *t2 - ROOM while(count--)

*ptr2++ = NULL; LPB = ptrl;

1* 1* 1* 1* 1* 1*

MemOry *1 Leave SOMe extra rooM in MeM *1 Clear out available MeMOry *1 with NULL byte values *1 firs t Ion g of pa raMet e r blK *1 gets the address of the FeB *1

1********************************1 1*-----------------------------------7---------------- --*

If the Load is Successful

1. Set the Default DMA address 2. Call ASSeMbly Code to push

the base page address, the return address, and the address yOU wish to JUMP to.

*----------------------------------------------------- -*1

if(bdos(PGMLDF,&LPB) == 0) {

}

else

bdos(5ETDMA,(baspag + DMA_OFF5ET»j push ( ) ;

error(PGMLDF) ;


[!Q) DIGITAL RESEARCHT• ------------------------------

B-7


}

}

else error(OPEN) i

error(fla!fl int fla!fi {

}

Main ( l {

}

* * *

* * *

bdos(CON_OUT,CRl i bdos(CON_OUT,LFlj if(fla!f == OPEN)

bdos(PRINTSTR,openMS!fl j else

bdos(PRINTSTR,loadMs!fl j bdos(REBOOT'(lon!flOl;

bdos(REBOOT'(lon~)O) j

********************************************************** * * * * *

ASSeMbly Lan!fua!fe Module Needed to Assist 'C' code to Load a Pro!fraM into the TPA *

* *

**********************************************************

MaKe All these labels GLOBAL

.!flobl _bdos • !f lob I _LPB .!flobl _lowadr .!flobl _hiadr .!flobl _baspa!f • !f lob I _usrst.: .!flobl _fla!fs .!flobl _TPAB .!flobl _low .!flobl _hi!fh .!flobl _start .!flob I _openfile .!flobl _push • !f lob I _Main

Get the address of the base pa!fe


----------------------------- I!ID DIGITAL RESEARCHTN

B-8


_start:

* * * _bdos:

* * * _push:

* * *

linf, aG,#O Illove.! S(aG) ,-(sp) jsr _openfile

Call the BOOS

ITIOve.IAI 4(sp) ,dO (rIO V e • 1 G ( s p) ,d 1 trap #2 rts

*link and allocate *push the address of the base page *julllP to 'C' code to open the file

*get the BOOS function nUlllber *get the BOOS parallleter *call the BOOS *return

Push the needed addresses on to the stack

III 0 v ea. 1 _1.1 S r s t f, ,a 7 III 0 V e • 1 _b asp a g , a 1 (rlove.l al,-(sp) 1T101)e • 1 #_lTlain ,-( sp) (rIO I) e .1 S(al) ,-(sp) rts

DATA

.data

.even

*set UP the user stack pointer *get address of user base page *push base page address *push return address *push address to jl.t(rlP to *jUlrlP to n e'A' progralTl


[!Q) DIGITAL RESEARCH™ -----------------------------B-9


* * * ~LPB:

~l 01,.1 ad r: * ~hiad r: * ~baspag:

~us rstf,: ~fla9's:

* * *

~TPAB:

~loIAI:

~high:

* * *

Load ParalTlete r

• ds. 1 • ds. 1

• ds. 1

• ds. 1 • ds. 1 • dc ,1.,1 0

TPA Paralrleter

.even

• dc .IAI 0 • d s. 1

• d s. 1

B I 0 cf,

BID cf,

*FCB address of prOgraM file *Low boundary of area in which *to load prOgraM *High boundary of area in which to *to load prOgraM *Base page address of loaded prOgraM *loaded prOgraM'S initial stacK pointer *Load prOgraM function control flags

END of ASSeMbly Language Code

.end


End of Appendix B

----------------------------- [!Q] DIGITAL RESEARCHTN

B-I0

Appendix C Base Page Format

Table C-l shows the format of the base page. The base page describes a program's environment. The Program Load Function (59) allocates space for a base page when this function is invoked to load an executable command file. For more details, on the Program Load Function and command files, refer to the appropriate sections in this manual.

Table C-l. Base Page Format: Offsets and Contents

Offset I Contents

0000 - 0003 Lowest address of TPA (from LPB)

0004 - 0007 1 + Highest address of TPA (from LPB)

0008 - OOOB Starting address of the Text Segment

OOOC - OOOF Length of Text Segment (bytes)

0010 - 0013 Starting address of the Data Segment (initialized data)

0014 - 0017 Length of Data Segment

0018 - 001B Starting address of the bss (uninitialized data)

001C - 001F Length of bss

0020 - 0023 Length of free memory after bss

0024 - 0024 Drive from which the program was loaded

I!ID DIGITAL RESEARCH™ ------------------------C-l

C Base Page Format

Offset

0025 - 0037

0038 - OOSB

OOSC - 007F .

0080 - OOFF

I


Table C-l. (continued)

Contents

Reserved, unused

2nd parsed FCB from Command Line

1st parsed FCB from Command Line

Command Tail and Default DMA Buffer

End of Appendix C

------------------------ !!IDDIGITALRESEARCH™ C-2

AppendixD Instruction Set Summary

This appendix contains two tables that describe the assembler instruction set distributed with CP/M-68K. Table D-lsummarizes the assembler (AS68) instruction set. Table D-2lists variations on the instruction set listed in Table D-l. For details on specific instructions, refer to Motorola's 16-Bit Microprocessor User's Manual, third edition, MC68000UM(AD3 ).

Table D-l. Instruction Set Summary

Instruction I abcd add and asl asr

bcc bchg belr bra bset bsr btst

chk elr cmp

dbcc divs divu

Description

Add Decimal with Extend Add Logical AND Arithmetic Shift Left Arithmetic Shift Right

Branch Conditionally Bit Test and Change Bit Test and Clear Branch Always Branch Test and Set Branch to Subroutine Bit Test

Check Register Against Bounds Clear Operand Compare

Test Condition, Decrement and Branch Signed Divide Unsigned Divide

!lID DIGITAL RESEARCHTW --------------------------

D-l

D Instruction Set Summary CP/M-68K Programmer's Guide

Table D-l. (continued)

Instruction I Description

eor Exclusive Or exg Exchange Registers ext Sign Extend

jmp Jump jsr Jump to Subroutine

lea Load Effective Address link Link Stack lsI Logical Shift Left lsr Logical Shift Right

move Move movem Move Multiple Registers movep Move Peripheral Data muls Signed Multiply mulu Unsigned Multiply

nbcd Negate Decimal with Extend neg Negate nop No Operation no Ones Complement

or Logical OR

pea Push Effective Address

reset Reset External Devices rol Rotate Left without Extend ror Rotate Right without Extend roxl Rotate Left with Extend roxr Rotate Right with Extend rte Return from Exception rtr Return and Restore rts Return from Subroutine

-------------------------- [j]] DIGITAL RESEARCHTN

D-2

CP/M-68K Programmer's Guide D Instruction Set Summary

Instruction I sbcd scc stop sub swap

tas trap trap v tst

unlk

Table D-1. (continued)

Description

Subtract Decimal with Extend Set Conditional Stop Subtract Swap Data Register Halves

Test and Set Operand Trap Trap on Overflow Test

Unlink

[j]] DIGITAL RESEARCH TW --------------------------

D-3

D Instruction Set Summary CP/M-68K Programmer's Guide

Table D-2. Variations of Instruction Types

Instruction J Variation

add

and

cmp

eor

move

neg

or

add adda addq addi addx

and andi andi toccr andi tosr

cmp cmpa cmpm cmpl

eor eori eori to ccr eori to sr

move movea moveq movetoccr movetosr move from sr movetousp

neg negx

or ori ori to ccr ori to sr

I Description

Add Add Address Add Quick Add Immediate Add with Extend

Logical AND AND Immediate AND Immediate to Condition Code AND Immediate to Status Register

Compare Compare Address Compare Memory Compare Immediate

Exclusive OR Exclusive 0 R Immediate Exclusive Immediate to Condition Codes Exclusive 0 R Immediate to Condition Codes

Move Move Address Move Quick Move to Condition Codes Move to Status Register Move from Status Register Move to User Stack Pointer

Negate Negate with Extend

Logical OR OR Immediate OR Immediate to Condition Codes OR Immediate to Status Register

--------------------------IIID DIGITAL RESEARCHTY

D-4


Instruction I Variation

sub sub suba subi subq subx

Table D-2. (continued)

I

End of Appendix D

D Instruction Set Summary

Description

Subtract Subtract Address Subtract Immediate Subtract Quick Subtract with Extend

[!ill DIGITAL RESEARCHTN --------------------------

D-5

Appendix E Error Messages

This appendix lists the error messages returned by the internal components of CP/M-68K and by the CP/M-68K programmer's utilities. The sections are arranged alphabetically by the name of the internal component or utility. The error messages are listed alphabetically within each section, with explanations and suggested user responses.

E.l AR68 Error Messages

The CP/M-68K Archive Utility, AR68, returns two types of fatal error messages: diagnostic and logic. Both types of fatal error messages are returned at the console as they occur.

E.l.1 Fatal Diagnostic Error Messages

The AR68 errors are listed in Table E-l in alphabetic order with explanations and suggested user responses.

Table E-l. AR68 Fatal Diagnostic Error Messages

Message Meaning

filenaflle not in archi!.le f i 1 e

The object module indicated by the variable f i 1 en a fll e is not in the library. Check the filename before you reenter the command line.

cannot create f i 1 en afll e

The drive code for the file indicated by the variable f i 1 en a fll e is invalid, or the disk to which AR68 is writing is full. Check the drive code. If it is valid, the disk is full. Erase unnecessary files, if any, or insert a new disk before you reenter the command line.

I!ID DIGITAL RESEARCH TW -------------------------

E-1

:.·1 .. ·.··':·'.:·. .. . J: _

'"

E.l AR68 Error Messages CP/M-68K Programmer's Guide

Table E-1. (continued)

Message Meaning

cannot open filenarTle

The file indicated by the variable f i len aM e cannot be opened because the filename or the drive code is incorrect. Check the drive code and the filename before you reenter the command line.

inl.Jalid option fla~: x

The symbol, letter, or number in the command line indicated by the varible x is an invalid option. Refer to the section of this manual on AR68 for an explanation of the command line options. Specify a valid option and reenter the command line.

not archil.Je fOrfrlat: filenaMe

The file indicated by the variable f i len a fr\ e is not a library. Ensure that you are using the correct filename before you reenter the com-mand line.

not object file: filenarTle

The file indicated by the variable f i 1 en a rTl e is not an object file, and cannot be added to the library. Any file added to the library must be an object file, output by the assembler, AS68, or the compiler. Assem-ble or compile the file before you reenter the AR68 command line.

one and anI}' one of DRTWH fla~s required

The AR68 command line requires one of the D, R, T, W, or X commands, but not more than one. Reenter the command line with the correct command. Refer to the section of this manual on AR68 for an explanation of the AR68 commands.

_filenarTle not in librar}'

The object module indicated by the variable f i len aM e is not in the library. Ensure that you are requesting the filename of an existing object module before you reenter the command line.

--------------------------[!Q] DIGITAL RESEARCHTN

E-2

CP/M-68K Programmer's Guide E.l AR68 Error Messages


Message Meaning

Read error on filenallle

The file indicated by the variable f i 1 en a ITI e cannot be read. This message means one of three things: the file listed at f i 1 en a III e is corrupted; a hardware error has occurred; or when the file was created, it was not correctly written by AR68 due to an error in the internal logic of AR68.

Cold start the system and retry the operation. If you receive this error message again, you must erase and recreate the file. Use your backup file, if you maintained one. If the error reoccurs, check for a hardware error. If the error persists, contact the place you purchased your system for assistance. You should provide the following information:

• Indicate which version of the operating system you are using.

• Describe your system's hardware configuration.

• Provide sufficient information to reproduce the error. Indicate which program was running at the time the error occurred. If possible, you should also provide a disk with a copy of the program.

telT1P file ",'rite error

The disk to which AR68 was writing the temporary file is full. Erase unnecessary files, if any, or insert a new disk before you reenter the command line.

usage: ARB8 DRHJ}{[AIJ][FD:] [DPMOD] ARCHIIJE OBMODl [DBMOD2'tt][)filespec]

This message indicates a syntax error in the command line. The correct format for the command line is given, with the possible options in brackets. Refer to the section in this manual on AR68 for a more detailed explanation of the command line.

I!ID DIGITAL RESEARCH™ --------------------------E-3

E.l AR68 Error Messages CP/M-68K Programmer's Guide


Message Meaning

Write error on filenaMe

The disk to which AR68 is writing the file indicated by the variable f i 1 e n a tTl e is full. Erase unnecessary files, if any, or insert a new disk before you reenter the command line.

E.1.2 AR68 Internal Logic Error Messages

This section lists messages indicating fatal errors in the internal logic of AR68. If you receive one of these messages, contact the place you purchased your system for assistance. You should provide the following information:

1. Indicate which version of the operating system you are using.

2. Describe your system's hardware configuration.

3. Provide sufficient information to reproduce the error. Indicate which program was running at the time the error occurred. If possible, you should also provide a disk with a copy of the program.

cannot reopen filename

seek error on library

Seek error on tempname

Unable to re-create--library is in filename

Note: for the above error, Una b 1 eta r e - ere ate - - 1 i bra r}' i 5 i n f i 1 en a tTl e, you should rename the temporary file indicated by the variable f i 1 en a tTl e. AR68 used the library to create the temporary file and then deleted the library in order to replace it with the updated temporary file. This error occurred because AR68 cannot write the temporary file back to the original location. The entire library is in the temporary file.

--------------------------[!ID DIGITAL RESEARCH™ E-4

CP/M-68K Programmer's Guide E.2 AS68 Error Messages

E.2 AS68 Error Messages

The CP/M-68K assembler, AS68, returns both nonfatal, diagnostic error messages and fatal error messages. Fatal errors stop the assembly of your program. There are two types of fatal errors: user-recoverable fatal errors and fatal errors in the internal logic of AS68.

E.2.1 AS68 Diagnostic Error Messages

Diagnostic messages report errors in the syntax and context of the program being assembled without interrupting assembly. Refer to the Motorola 16-Bit Microprocessor User's Manual for a full discussion of the assembly language syntax.

Diagnostic error messages appear in the following format:

& line no. error message text

The ampersand (&) indicates that the message comes from AS68. The "line no." indicates the line in the source code where the error occurred. The "error message text" describes the error. Diagnostic error messages are printed at the console after assembly, followed by a message indicating the total number of errors. In a printout, they are printed on the line preceding. the error. The AS68 diagnostic error messages are listed in Table E-2 in alphabetic order.

Table E-2. AS68 Diagnostic Error Messages

Message Meaning

&: line no. bac.,I,.,la rd assi 9'ntTlent to * The assignment statement in the line indicated illegally assigns the location counter (*) backward. Change the location counter to a forward assignment and reassemble the source file.

&: line no. bad use of s}'trlbol

A symbol in the source line indicated has been defined as both global and common. A symbol can be either global or common, but not both. Delete one of the directives and reassemble the source file.

[ID DIGITAL RESEARCHT• --------------------------

E-5

E.2 AS68 Error Messages CP/M-68K Programmer's Guide


Message Meaning

&: line no. constant reCJui red

An expression on the line indicated requires a constant. Supply a constant and reassemble the source file.

&: line no. end statefTlent not at end of source

The end statement must be at the end of the source code. The end statement cannot be followed by a comment or more than one carriage return. Place the end statement at the end of the source code, followed by a single carriage return only, and reassemble the source file.

&: line no. illegal addressing fTlO d e

The instruction on the line indicated has an invalid addressing mode. Provide a valid addressing mode and reassemble the source file.

&: line no. illegal constant

The line indicated contains an illegal constant. Supply a valid constant and reassemble the source file.

&: line no. illegal expr

The line indicated contains an illegal expression. Correct the expres-sion and reassemble the source file.

&: line no. illegal external

The line indicated illegally contains an external reference to an 8-bit quantity. Rewrite the source code to define the reference locally or use a 16-bit reference and reassemble the source file.

&: line no. illegal forfTlat

An expression or instruction in the line indicated is illegally formatted. Examine the line. Reformat where necessary and reassemble the source file.

&: line no. illegal index register

The line indicated contains an invalid index register. Supply a valid register and reassemble the source file.

--------------------------IIID DIGITAL RESEARCH™ E-6



Message Meaning

&: line no. illegal relati\)e address

An addressing mode specified is not valid for the instruction in the line indicated. Refer to the Motorola 16-Bit Microprocessor User's Manual for valid register modes for the specified instruction. Rewrite the source code to use a valid mode and reassemble the file.

& line no. illegal shift count

The instruction in the line indicated shifts a quantity more than 31 times. Modify the source code to correct the error and reassemble the source file.

&: line no. illegal size

The instruction in the line indicated requires one of the following three size specifications: b (byte), w (word), or I (longword). Supply the correct size specification and reassemble the source file.

& line no. illegal string

The line indicated contains an illegal string. Examine the line. Correct the string and reassemble the source file.

& line no. illegal text delirTliter

The text delimiter in the line indicated is in the wrong format. Use single quotes ( , t ext ') or double quotes ( lite x til) to delimit the text and reas~emble the source file.

& line no. illegal 8-bit displacerrlent

The line indicated illegally contains a displacement larger than 8-bits. Modify the code and reassemble the source file.

& line no. illegal 8-bit irrHTlediate

The line indicated illegally contains an immediate operand larger than 8-bits. Use the 16- or 32-bit form of the instruction and reassemble the source file.

I!ID DIGITAL RESEARCH1V --------------------------

£-7

E.2 AS68 Error Messages CP/M-6SK Programmer's Guide


Message Meaning

&: line no. illegal is-bit displacelTlent

The line indicated illegally contains a displacement larger than 16-bits. Modify the code and reassemble the source file.

&: line no. illegal is-bit ilTlITlediate

The line indicated illegally contains an immediate operand larger than 16-bits. Use the 32-bit form of the instruction and reassemble the source file.

&: line no. invalid data list

One or more entries in the data list in the line indicated is invalid. Examine the line for the invalid entry. Replace it with a valid entry and reassemble the source file.

&: line no. invalid fir s t operand

The first operand in an expression in the line indicated is invalid. Supply a valid operand and reassemble the source file.

&: line no. inl.lalid instruction length

The instruction in the line indicated requires one of the following three size specifications: b (byte), w (word), or I (longword). Supply the correct size specification and reassemble the source file.

&: line no. inl.lalid label

A required operand is not present in the line indicated, or a label reference in the line is not in the correct format. Supply a valid label and reassemble the source file.

&: line no. inl.lalid opcode

The opcode in the line indicated is nonexistent or invalid. Supply a valid opcode and reassemble the source file.

&: line no. invalid second operand

The second operand in an expression in the line indicated is invalid. Supplya valid operand and reassemble the source file.

-------------------------- I!QJDIGITAL RESEARCH™ E-S

CP/M-68K Programmer's Guide E.2 AS68 Error Mess~

Message

& line no.


Meaning

label redefined

This message indicates that a label has been defined twice. The second definition occurs in the line indicated. Rewrite the source code to specify a unique label for each definition and reassemble the source file.

& line no. Missin~)

An expression in the line indicated is missing a right parenthesis. Supply the missing parenthesis and reassemble the source file.

& line no. no label for operand

& line no.

B: line no.

B: line no.

B: line no.

An operand in the line indicated is missing a label. Supply a label and reassemble the source file.

opcode redefined

A label in the line indicated has the same mnemonics as a previously specified opcode. Respecify the label so that it does not have the same spelling as the mnemonic for the opcode. Reassemble the source file.

re~ister required

The instruction in the line indicated requires either a source or destination register. Supply the appropriate register and reassemble the source file.

relocation error

An expression in the line indicated contains more than one externally defined global symbol. Rewrite the source code. Either make one of the externally defined global symbols a local symbol, or evaluate the expression within the code. Reassemble the source file.

S}'irlbOl requi red

A statement in the line indicated requires a symbol. Supply a valid symbol and reassemble the source file.


E-9



Message Meaning

&: line no. undefined s}'ITlbol in equate

One of the symbols in the equate directive in the line indicated is undefined. Define the symbol and reassemble the source file.

&: line no. undefined S)'ITlbol

The line indicated contains an defined symbol that has no been de-clared global. Either define the symbol within the module or define it as a global symbol and reassemble the source file.

E.2.2 User-recoverable Fatal Error Messages

The fatal error messages for AS68 are described in Table E-3. When an error occurs because the disk is full, AS68 creates a partial file. You should erase the partial file to ensure that you do not try to link it.

Table E-3. User-recoverable Fatal Error Messages

Message Meaning

& cannot create init: ASG8SYMB.DAT

AS68 cannot create the initialization file because the drive code is incorrect or the disk to which it was writing the file is full. If you used the -S switch to redirect the symbol table to another disk, check the drive code. If it is correct, the disk is full. Erase unnecessary files, if any, or insert a new disk before you reinitialize AS68. Erase the partial file that was created on the full disk to ensure that you do not try to link it.

& expr opstK overflow

An expression in the line indicated contains too many operations for the operations stack. Simplify the expression before you reassemble the source code.

& expr tree overflow

The expression tree does not have space for the number of terms in one of the expressions in the indicated line of source code. Rewrite the expression to use fewer terms before you reassemble the source file.

-------------------------- [!ill DIGITAL RESEARCH™ E-l0



Message Meaning

& I/O error on loader output file

The disk to which AS68 was writing the loader output file is full. AS68 wrote a partial file. Erase unnecessary files, if any, or insert a new disk and reassemble the source file. Erase the partial file that was created on the full disk to ensure that you do not try to link it.

& I/O write error on it file.

The disk to which AS68 was writing the intermediate text file is full. AS68 wrote a partial file. Erase unnecessary files, if any, or insert a new disk and reassemble the source file. Erase the partial file that was created on the full disk to ensure that you do no~ try to link it.

&: it read error itoffset= no.

The disk to which AS68 was writing the intermediate text file is full. AS68 wrote a partial file. The variable Ito f f 5 e t = no. indicates the first zero-relative byte number not read. Erase unnecessary files, if any, or insert a new disk and reassemble the source file. Erase the partial file that was created on the full disk to ensure that you do not try to link it.

& Object file write error

I The disk to which AS68 was writing the object file is full. AS68 wrote a partial file. Erase unnecessary files, if any, or insert a new disk and reassemble the source file. Erase the partial file that was created on the full disk to ensure that you do not try to link it.

& overflow of external table

The source code uses too many externally defined global symbols for the size of the external symbol table. Eliminate some externally defined global symbols and reassemble the source file.

& Read Error On Inter~ediate File: ASXXXXn

The disk to which AS68 was writing the intermediate text file AS }.{ }.{}{}{ is full. AS68 wrote a partial file. The variable n indicates the drive on which AS}{}{ }.{}{ is located. Erase unnecessary files, if any, or insert a new disk and reassemble the source file. Erase the partial file that was created on the full disk to ensure that you do not try to link it.


E-11



Message Meaning

& SYMbol table overflow

The program uses too many symbols for the symbol table. Eliminate some symbols before you reassemble the source code.

& Unable to open file filenaMe

The source filename indicated by the variable f i len a tT} e is invalid or, has an invalid drive code or user number. Check the filename, drive code, and user number: Respecify the command line before you reassemble the source file.

& Unable to open input file

The filename in the command line indicated does not exist, or has an invalid drive code or user number. Check the filename, drive code, and user number. Respecify the command line before you reassemble the source file.

& Unable to open teMPOrarY file

Invalid drive code or the disk to which AS68 was writing is full. Check the drive code. If it is correct, the disk is full. Erase unnecessary files, if any, or insert a new disk before you reassemble the source file.

& Unable to read init file: ASG8SYMB.DAT

The drive code or user number used to specify the initialization file is invalid or the assembler has not been initialized. Check the drive code and user number. Respecify the command line before you reassemble the source file. If the assembler has not been initialized, refer to the section in this manual on AS68 for instructions.

& Write error on init file: ASG8SYMB.DAT

The disk to which AS68 was writing the initialization file is full. AS68 wrote a partial file. Erase unnecessary files, if any, or insert a new disk and reassemble the source file. Erase the partial file that was created on the full disk to ensure that you do not try to link it.

-------------------------- I!ID DIGITALRESEARCH™ E-12



Message Meaning

& write error on it file

The disk to which AS68 was writing the intermediate text is full. AS68 wrote a partial file. Erase unnecessary files, if any, or insert a new disk. Erase the partial file that was created on the full disk to ensure that you do not try to link it. Reassemble the source file.

E.2.3 Internal Logic Error Messages

This section lists messages indicating fatal errors in the internal logic of AS68. If you receive one of these messages, contact the place you purchased your system for assistance. You should provide die following information.




Errors:

& doitrd: buffer botch pitix=nnn itbuf=nnn end=nnn

& doitwr: it buffer botch

& invalid radix in oconst

& i.t. overflow

& it sync error ittY=nnn

& seeK error on it file

& outword: bad rlflg

I!ID DIGITAL RESEARCH'" --------------------------E-13

E.3 BDOS Error Messages CP/M-68K Programmer's Guide

E.3 BDOS Error Messages

The CP/M-68K Basic Disk Operating System, BDOS, returns fatal error messages at the console. The BDOS error messages are listed in Table E-4 in alphabetic order with explanations and suggested user responses.

Table E-4. BDOS Error Messages

Message Meaning

CP/M Dis., chan9'e error on drive x

The disk in the drive indicated by the variable x is not the same disk the system logged in previously. When the disk was replaced you did not enter a CTRL-C to log in the current disk. Therefore, when you attempted to write to, erase, or rename a file on the current disk, the BDOS set the drive status to read-only and warm booted the system. The current disk in the drive was not overwritten. The drive status was returned to read-write when the system was warm booted. Each time a disk is changed, you must type a CTRL-C to log in the new disk.

CP/M Dis., file error: filenaMe is Read-OnlY. Do YOU .... Iant to: Chan9'e it to read/write (C) t

or Abort (A)?

You attempted to write to, erase, or rename a file whose status is Read-Only. Specify one of the options enclosed in parentheses. If you specify the C option, the BDOS changes the status of the file to read-write and continues the operation. The Read-Only protection previously assigned to the file is lost.

If you specify the A option or a CTRL-C, the program terminates and CPM-68K returns the system prompt.

--------------------------IIID DIGITAL RESEARCHTlI

E-14

CP/M-6SK Programmer's Guide E.3 BOOS Error Messages


Message Meaning

CP/M Disk read error on drive x Do YOU want to: Abort (A) t Retr}' (R) t

or Co~tinue with bad data (C)?

BDOS. This message indicates a hardware error. Specify one of the options enclosed in parentheses. Each option is described below.

Option Action

A or CTRL-C Terminates the operation and CP/M-68K returns the system prompt.

R

C

Retries the operation. If the retry fails, the system reprompts with the option message.

Ignores the error and continues program execution. Be careful if you use this option. Program execution should not be continued for some types of programs. For example, if you are updating a data base and receive this error but continue program execution, you can corrupt the index fields and the entire data base. For other programs, continuing program execution is recommended. For example, when you transfer a long text file and receive an error because one sector is bad, you can continue transferring the file. After the file is transferred, review the file, and add the data that was not transferred due to the bad sector.

CP/M Disk select error on drive x Do }'OU .... Iant to: Abort (A) f Retr}' (R)

There is no disk in the drive or the disk is not inserted correctly. Ensure that the disk is securely.inserted in the drive. If you enter the R option, the system retries the operation. If you enter the A option or CTRL-C the program terminates and CPM-68K returns the system prompt.

I!]] DIGITAL RESEARCHTN ---------------------------

E-15

E.3 BDOS Error Messages CP/M-68K Programmer's Guide


Message Meaning

CP/M DisK ~elect error on drive x

The disk selected in the command line is outside the range A through P. CP/M-68K can support up to 16 drives, lettered A through P. Check the documentation provided by the manufacturer to find out which drives your particular system configuration supports. Specify the correct drive code and reenter the command line.

--------------------------l!QJ DIGITAL RESEARCH TN

E-16

CP/M-68K Programmer's Guide E.4 BIOS Error Messages

E.4 BIOS Error Messages

The CP/M-68K BIOS error messages are listed in Table E-S in alphabetic order with explanations and suggested user responses.

Table E-5. BIOS Error Messages

Message Meaning

BIOS ERROR -- DISK X NOT SUPPORTED

The disk drive indicated by the variable }-{ is not supported by the BIOS. The BDOS supports a maximum of 16 drives, lettered A through P. Check the manufacturer's documentation for your system configuration to find out which of the BDOS drives your BIOS implements. Specify the correct drive code and reenter the command line.

BIOS ERROR -- Invalid DisK Status

The disk controller returned unexpected or incomprehensible information to the BIOS. Retry the operation. If the error persists, check the hardware. If the error does not come from the hardware, it is caused by an error in the internal logic of the BIOS. Contact the place you purchased your system for assistance. You should provide the following information.




E.5 CCP Error Messages

The CP/M-68K Console Command Processor, CCP, returns two types of error messages at the console: diagnostic and internal logic error messages.


E.S CCP Error Messages CP/M-68K Programmer's Guide

E.5.1 Diagnostic Error Messages

The CCP error messages are listed in Table E-6 in alphabetic order with explanations and suggested user responses.

Table E-6. CCP Diagnostic Error Messages

Message Meaning

bad relocation inforMation bits

This message is a result of a BDOS Program Load Function (59) error. It indicates that the file specified in the command line is not a valid executable command file, or that the file has been corrupted. Ensure that the file is a command file. Section 3 of this manual describes the format of a command file. If the file has been corrupted, reassemble or recompile the source file, and relink the file before you reenter the command line.

File already exists

This error occurs during a REN command. The name specified in the command line as the new filename already exists. Use the ERA command to delete the existing file if you wish to replace it with the newfile.If not, select another filename and reenter the REN command line.

insufficient MeMOry or bad file header

This error cOlild result from one of three causes:

1. The file is not a valid executable command file. Ensure that you are requesting the correct file. This error can occur when you enter the filename before you enter the command for a utility. Check the appropriate section of this manual or the CPIM-68K Operating System User's Guide for the correct command syntax before you reenter the command line. If you are trying to run a program when this error occurs, the program file may have been corrupted. Reassemble or recompile the source file and relink the file before you reenter the command line.

2. The program is too large for the available memory. Add more memory boards to the system configuration, or rewrite the program to use less memory.

--------------------------[j]] DIGITAL RESEARCHTN

E-18

CP/M-68K Programmer's Guide E.S CCP Error Messages

Message

No file


Meaning

3. The program is linked to an absolute location in memory that cannot be used. The program must be made relocatable, or linked to a usable memory location. The BDOS Get/Set TP A Limits Function (63) returns the high and low boundaries of the memory space that is available for loading programs.

The filename specified in the command line does not exist. Ensure that you use the correct filename and reenter the command line.

No wildcard filenaMes

The command specified in the command line does not accept wildcards in file specifications. Retype the command line using a specific filename.

read error on prograM load

This message indicates a premature end-of-file. The file is smaller than the header information indicates. Either the file header has been corrupted or the file was only partially written. Reassemble, or recompile the source file, and relink the file before you reenter the command line.

SUB file not found

The file requested either does not exist, or does not have a filetype of SUB. Ensure that you are requesting the correct file. Refer to the section on SUBMIT in the CPIM-68K Operating System User's Guide for information on creating and using submit files.

REN newfile=oldfile

The syntax of the REN command line is incorrect. The correct syntax is given in the error message. Enter the REN command followed by a space, then the new filename, followed immediately by an equals sign ( =) and the name of the file you want to rename.

1m DIGITAL RESEARCH™ ---------------------------E-19

E.5 CCP Error Messages CP/M-68K Programmer's Guide


Message Meaning

Too Many ar~UMents: a r ~ UfTl e n t?

The command line contains too many arguments. The extraneous arguments are indicated by the variable a r ~ U fTl e n t. Refer to the CPIM-68K Operating System User's Guide for the correct syntax for the command. Specify only as many arguments as the command syntax allows and reenter the command line. Use a second command line for the remaining arguments, if appropriate.

User:l* ran~e is [0-15]

The user number specified in the command line is not supported by the BIOS. The valid range is enclosed in the square brackets in the error message. Specify a user number between 0 and 15 (decimal) when you reenter the command line.

E.5.2 CCP Internal Logic Error Messages

The following message indicates an undefined failure of the BDOS Program Load Function (59).

Pro~raM Load Error

If you receive this message, contact the place you purchased your system for assistance. You should provide the following information.




E.6 DDT -68K Error Messages

The CP/M-68K debugger, DDT-68K, returns two types of error messages: nonfatal diagnostic error messages and fatal errors in the internal logic of DDT-68K.

-------------------------- [ij] DIGITAL RESEARCH'" E-20

CP/M-68K Programmer's Guide E.6 DDT-68K Error Messages_

E.6.1 Diagnostic Error Messages

Diagnostic error messages are returned at the console as the error occurs. The DDT-68K error messages are listed in Table E-7 in alphabetic order with explanations and suggested user responses.

Table E-7. DDT-68K Diagnostic Error Messages

Message Meaning

Bad or nonexistent RAM at HEX no.

This error occurs in response to a Set (S), Set Word (SW), or Set Longword (SL) command. The message indicates one of two things.

1. The memory location at HE}{ no. is read-only, an I/O port, or nonexistent. Use another location.

2. The memory location is damaged. Check the hardware.

Bad relocation bits

This message is returned from the BDOS Program Load Function (59), and means one of two things.

1. The command file has been corrupted. Rebuild the file. Reassemble or recompile the source file, and relink the file before you reenter the DDT-68K command line.

2. The file is linked to an absolute location in memory that is already occupied by DDT-68K. Link the file to another location: DDT-68K

/ occupies approximately 20K of memory, and resides at the highest addresses within the TP A. The recommended location for linking your file is the base address of the TP A + 100H. BDOS Function 63, Get/Set TPA Limits, returns the high and low boundaries of the TPA.

[j]) DIGITAL RESEARCHTW --------------------------

E-21

E.6 DDT-68K Error Messages CP/M-68K Programmer's Guide


Message Meaning

Cannot create file

This error occurs during a Write (W) command. The disk to which DDT-68K is writing has no more directory space available: in effect, the disk is full. If you have another drive available, reenter the Write (W) command and direct the file to the disk on that drive. If you do not have another drive available, you must exit DDT-68K (and lose the contents of memory). Erase unnecessary files, if any, or insert a new disk.

Cannot open file

This error occurs during a Read (R) command. It indicates an incorrect user number, drive code, or filename. Check the user number, drive code, and filename before you reenter the command line.

Cannot open prograM file

This message occurs in response to a Load for Execution (E) command. It indicates an incorrect user number, drive code, or filename. Check the user number, drive code, and filename before you reenter the command line.

ERRORt no program or file loaded.

This error message occurs in response to a Value (V) command when you specify the command but no file is loaded. Load a file before you reenter the V command. The file can be loaded with a Load for Execution (E) or Read (R) command, or by specifying the filename when you invoke DDT-68K.

File too big -- read truncated

This message occurs during a Read (R) command when the file being read is too large to fit in memory. DDT-68K reads only the portion of the file that can be read into the existing memory. To debug this program, additional memory boards must be added to the system configuration.

--------------------------[ID DIGITAL RESEARCH'· E-22

CP/M-68K Programmer's Guide E.6 DDT-68K Error Messages


Message Meaning

File 1",lrite error

The disk to which DDT-68K is writing is full or the disk contains a bad sector. Retry the command. If the error persists, and you have another disk drive available, redirect the output to the disk on that drive. If you do not have another drive available, you must exit DDT-68K. Use the STAT command to check the space on the disk. If it is full, erase unnecessary files, if any, or insert a new disk. Because the contents of memory are lost when you exit DDT-68K, you must reload the file in memory. If the disk was not full, it has a bad sector. You should replace the disk.

**illegal size fold

This error occurs during a List (L) command. The size field of the instruction being disassembled has an illegal value. Use a Display (D) command to display the location of the error. This error could be caused by one of three things:

1. The memory location being disassembled does not contain an instruction. Ensure that the area selected is an instruction. If not, reenter the L command with a correct location.

2. The size field of the instruction has been corrupted. Use the debugging commands in DDT-68K to look for an error that causes the program to overwrite itself. Refer to the section in this manual on DDT-68K for a complete description of the DDT-68K commands and options.

3. An invalid instruction was generated by the compiler or assembler used to create the program. Recompile or reassemble the source file before you reinvoke DDT-68K.

~ DIGITAL RESEARCHT• --------------------------

E-23

E.6 DDT -68K Error Messages CP/M-68K Programmer's Guide


Message Meaning

Insufficient MeMOry or bad file header

This message occurs in response to a Load for Execution (E) command. The error could be caused by one of three things:

1. The system you are using does not have enough memory available. Ensure that the program and DDT-68K fit into the TPA. Exit DDT-68K. Use the SIZE68 Utility to display the amount of space your program occupies in memory. DDT-68K is approximately 20K bytes. The BDOS Get/Set TP A Limits Function (63) returns the high and low boundaries of the TP A. If you do not have sufficient space in the TP A to execute your command file and DDT-68K simultaneously, additional memory boards must be added to the system configuration.

2. The file is not a command file or has a corrupted header. If the command file does not run, but you are sure that your memory space is adequate, use the R command to look at the file and check the format. You may be trying to debug a file that is not a command file. If it is a command file, the header may have been corrupted. Reassemble or recompile the source file before you reenter the E command line. If the error persists, it may be caused by an error in the internal logic of DDT -68K. Contact the place you purchased your system for assistance. You should provide the following information:

a. Indicate which version of the operating system you are using.

b. Describe your system's hardware configuration.

c. Provide sufficient information to reproduce the error. Indicate which program was running at the time the error occurred. If possible, you should also provide a disk with a copy of the program.

--------------------------IIID DIGITAL RESEARCH TN

E-24

CP/M-68K Programmer's Guide E.6 DDT-68K Error Messages


Message Meaning

3. The command file you are debugging is linked to an absolute location in memory that is already occupied by DDT-68K. DDT-68K is approximately 20K bytes, and usually resides in the highest addresses of the TP A. The recommended location for linking your file is the base address of the TPA + 100H. The BDOS Get/Set TPA Limits Function (63) returns the high and low boun-daries of the TP A.

Read e r ro r

This message may indicate one of three things. Try the operation again. If the error persists, try the responses indicated:

1. A write error at the time the file was created. You must recreate the file. If the error reoccurs, or if you cannot write to the disk, the disk is bad.

2. A bad disk. Use PIP or COpy to copy the file from the bad disk to a new disk. Any files that cannot be copied must be recreated or replaced from backup files. Discard the damaged disk.

3. A hardware error. If the error persists, check your hardware.

un H.l"IOIAll"I opcode

This error occurs in response to a List (L) command if the memory location being disassembled does not contain a valid instruction. The error may have been caused by one of three things:

1. You gave the L command the wrong address. Reenter the L com-mand with the correct address.

2. The file is not a command file. Ensure that the file you specify is a command file and reenter the L command.

[!ill DIGITAL RESEARCH™ --------------------------E-25

E.6 DDT-68K Error Messages CP/M-68K Programmer's Guide


Message Meaning

3. The command file has been corrupted. Reassemble or recompile the source file before you reread it into memory with a Load for Execution (E) or Read (R) command, as appropriate. If the problem persists, use the debugging commands in DDT-68K to look for an error in the program that causes it to overwrite itself. Refer to the section in this manual on DDT-68K for a complete description of the DDT-68K commands and options.

E.6.2 DDT -68K Internal Logic Error Messages

This section lists fatal errors in the internal logic of DDT-68K. If you receive one of these messages, contact the place you purchased your system for assistance. You should provide the following information.




Errors:

ille~al instruction forMat #

Unknown pro~raM load error

E.7 DUMP Error Messages

DUMP returns fatal, diagnostic error messages at the console. The DUMP error messages are listed in Table E-8 in alphabetic order with explanations and suggested user responses.

-------------------------- [!IDDIGITAL RESEARCH™ E-26

CP/M-68K Programmer's Guide E.7 DUMP Error Messages

Table E-8. DUMP Error Messages

Message Meaning

Unable to open f i 1 en afTI e

Either the drive code for the input file indicated by the variable f i 1 e n a fTI e is incorrect, or the filename is misspelled. Check the

filename and drive code before you reenter the DUMP command line.

Usage: dUCTIP [-shhhhhhJ file

The command line syntax is incorrect. The correct syntax is given in the error message. Specify the DUMP command and the filename. If you want to display the contents of the file from a specific address in the file, specify the -S option followed by the address. Refer to the section in this manual on the DUMP Utility for a discussion of the DUMP command line and options.

E.8 L068 Error·Messages

The CP/M-68K Linker, L068, returns two types of fatal error messages: diagnostic and logic. Both types of fatal error messages have the following format:

: error message text

The colon (:) indicates that the error message comes from L068. The "error message text" describes the error.

E.8.1 Fatal Diagnostic Error Messages

A fatal diagnostic error prevents your program from linking. When the error is caused by a full disk, erase the partial file that L068 created on the disk that received the error to ensure that you do not use the file. The L068 diagnostic errors are listed in Table E-9 in alphabetic order with explanations and suggested user responses.

I!ID DIGITAL RESEARCH'· --------------------------E-27

E.8 L068 Error Messages CP/M-68K Programmer's Guide

Table E-9. L068 Fatal Diagnostic Error Messages

Message Meaning

: duplicate definition in ptfilenaMe

The symbol indicated by the variable p is defined twice. The variable f i len a fTI e indicates the file in which the second definition occurred. Rewrite the source code. Provide a unique definition for each symbol ' and reassemble or recompile the source code before you relink the file.

: file forMat error: filenafTle

The file indicated by the variable f i len a fTI e is either not an object file or the file has been corrupted. Ensure that the file is an object file, output by the assembler or compiler. Reassemble or recompile the file before you relink it.

: File ForMat Error: Invalid SYMbol fla~s = fla~s L068 does not recognize the symbol flags indicated by the variable f I a ~ s. The file L068 read is either not an object file or it has been corrupted. Ensure that the file is an object file, output by the assembler or compiler. Reassemble or recompile the file before you relink it.

: File ForfTlat Error: inl.lalid relocation fla~ in filenafTle

The contents of the file indicated by the variable f i I e 11 a fTl e are incorrectly formatted. The file either is not an object file or has been. corrupted. Ensure that the file is an object file, output by the assembler or compiler. If the file is an object file but this error occurs, the file has been corrupted. Reassemble or recompile the file before you re- : link it.

: File ForMat Error: no relocation bits in filenafTle

The file indicated by the variable f i 1 en a fTl e either is not an object file or has been corrupted. Ensure that the file is an object file, output by the assembler or compiler. If the file is an object file but this error occurs, then the file has been corrupted. Reassemble or recompile the file before you relink it.

: Ille~al option p

The option in the command line indicated by the variable p is invalid. Supply a valid option and relink.

--------------------------[!ID DIGITAL RESEARCHTN

E-28

CP/M-68K Programmer's Guide E.8 L068 Error Messages


Message Meaning

: Invalid 10G8 argument list

This message indicates format errors or invalid options in the command line. Examine the command line to locate the error. Correct the error and relink.

: output file write error

The disk to which L068 is writing is full. Erase unnecessary files, if any, or insert a new disk before you reenter the L068 command line.

: read error on file: filenalTle

The object file indicated by the variable f i len a ITI e does not have enough bytes. The file either is incorrectly formatted or has been corrupted. This error is commonly caused when the input to L068 is a partially assembled or compiled object file. The assembler, AS68, and some compilers create partial object files when they receive the dis ~\ f u I I abo r t message while assembling or compiling a file. Ensure that the file is a complete object file. Reassemble or recompile the file before you relink it.

: symbol table overflow

The object code contains too many symbols for the size of the symbol table. Rewrite the source code to use fewer symbols. Reassemble or recompile the source code before you relink the file.

: Unable to create filename

Either the output file indicated by f i len a ITI e has an invalid drive code, or the disk to which L068 is writing is full. Check the drive code. If it is correct, the disk is full. Erase unnecessary files, if any, or insert a new disk before you reenter the L068 command line.

: unable to open filename

The filename indicated by the variable f i len alTI e is invalid, or the file does not exist. Check the filename before you reenter the L068 command line.


E.8 L068 Error Messages CP/M-68K Programmer's Guide


Message Meaning

: Unable to open teITIPOrar}' file: filenalTle

Either the file, indicated by f i len a ITI e, has an invalid drive code, specified by the f option, or the disk to which L068 is writing is full. Check the drive code. If it is correct, the disk is full. Erase unnecessary files, if any, or insert a new disk before you reenter the L068 command line.

: Undefined s}'ITlbol (s)

The symbol or symbols which are listed one per line on the lines following the error message are undefined. Provide a valid definition and reassemble the source code before you reenter the L068 command line.

E.8.2 L068 Internal Logic Error Messages

This section lists messages indicating fatal errors in the internal logic of L068. If you receive one of these messages, contact the place you purchased your system for assistance. You should provide the following information:




--------------------------I!]) DIGITAL RESEARCH™ E-30

CP/M-68K Programmer's Guide E.8 L068 Error Messages

Errors:

asgnext botch

finalwr: text size error

relative address overflow at Ix in sn

seeK error on file f i I enafTle

short address overflow in fi lenafrle

unable to reopen filenaMe

E.9 NM68 Error Messages

NM68 returns fatal diagnostic error messages at the console. The NM68 error messages are listed in Table E-l0 in alphabetic order with explanations and suggested user responses.

l!ID DIGITAL RESEARCHTN ---------------------------

E-31

E.9 NM68 Error Messages CP/M-68K Programmer's Guide

Table E-10. NM68 Error Messages

Message Meaning

File forMat error: filenaMe

The input file indicated by the variable f i 1 en aM e is neither an object file nor a command file. This message can also indicate a corrupted file. NM68 prints the symbol table of an object file or a command file. Ensure that the file is one of these types of file. If the file is an object or command file and you receive this message, the file is corrupted. Rebuild the file with the compiler or assembler. If the file is a command file, relink it. Reenter the NM68 command line.

read error on file: filenaMe

The input file indicated by the variable f i 1 en aM e is truncated. Rebuild the file with the compiler or assembler. If the file is a command file, relink it. Reenter the NM68 command line.

unable to open filenaMe

The filename indicated by the variable f i 1 e n aM e is incorrect. Check the spelling of the filename and reenter the command line.

Usage: nMG8 obJectfile

The command line syntax is incorrect. Use the syntax given in the error message and reenter the command line.

E.10 RELOC Error Messages

The Relocation Utility (RELOC) returns fatal error messages at the console. RELOC error messages are listed in Table E-11 in alphabetic order with explanations and suggested user responses.

------------------------- [l]] DIGITAL RESEARCH" E-32

CP/M-68K Programmer's Guide E.I0 RELOC Error Messages

Table E-11. RELOC Error Messages

Message Meaning

create filenalTle

Either the drive code for the output file indicated by the variable f i 1 e n a ITl e is incorrect, or the disk to which RELOC is writing is

full. Check the drive code. If it is correct, the disk is full. Erase unnecessary files, if any, or insert a new disk before you reenter the RELOC command line.

Cannot open file

The input file indicated by the variable f i 1 en a tTl e does not exist. Ensure that you type the correct filename when you reenter the RELOC command line.

Cannot re-open filenaMe

This error message indicates a hardware error. Check the hardware for errors. This error most often occurs in the disk, disk drive, or memory.

file forMat error: filena{Ile

This error occurs because the first word in the header record of the command file must contain the value 601AH and the file must contain relocation bits. If your file does not meet these criteria, you cannot use RELOC.

1. The file indicated by the variable f i 1 en a tTl e is not a command file with contiguous program segments (the first word in the header record is 601AH). If the file is an object file, link it before you reenter the RELOC command line.

2. The file does not have relocation bits because it is already linked to an absolute location. Use the original source file that contains relocation bits with RELOC.

Illegal base address=hex no.

The odd base address indicated by the variable hex no. is invalid under CP/M-68K. Base addresses must be even. Specify an even base address and reenter the RELOC command line.

[!QJ DIGITAL RESEARCHT• --------------------------

E-33

E.10 RELOC Error Messages CP/M-68K Programmer's Guide


Message Meaning

Ille~al option: x

The option specified for the RELOC command must be -b. The invalid option is indicated by the variable x . Replace the invalid option with -b and reenter the RELOC command line.

Ille~al reloc = x at address

This message may indicate one of two things:

1. The command file is truncated or corrupted. RELOC recognized the error because the relocation value indicated by the variable x is invalid. The variable add res s indicates the location in memory of the invalid relocation value. Rebuild the file. Reassemble or recompile, and relink the file before you reenter the RELOC command line.

2. The file has no relocation bits. Use the original source code with relocation bits and try again.

Read error on filenaMe

The input file indicated by the variable f i len a ITI e is truncated or corrupted. Rebuild the file. Reassemble, or recompile, and relink the file before you reenter the RELOC command line.

1S-bit overflow at address

The address indicated by the variable add res s cannot contain a 16-bit quantity. Source code that uses 16-bit offsets must fit in the first 64K bytes of memory. BDOS Function 63, Get/Set TPA Limits,

,returns the high and low boundaries of the memory available for loading programs. SIZE68 displays the amount of memory space a program occupies. Use the Get/Set TPA Limits Function and SIZE68 to ensure that the program fits in the first 64 K of memory. If the program does not fit, you must rewrite the source code to use 32-bit offsets.

-------------------------- [!QJ DIGITAL RESEARCHTN

E-34

CP/M-6SK Programmer's Guide E.10 RELOC Error Messages

Table E-l1. (continued)

Message Meaning

Usage: reloc -bhhhhhh input ouput where hhhhhh is new base address

input is relocatable file output is absolute file

This message indicates a syntax error in the RELOC command line. The correct syntax is given in the error message. Retype the command line with the correct syntax. Refer to the section in this manual on the RELOC Utility for more detailed information on the command line syntax.

Write error on filenaMe Offset = x data = x error = x

The disk to which RELOC is writing is full. Erase unnecessary files, if any, or insert a new disk before you reenter the RELOC command line.

E.ll SENDC68 Error Messages

SENDC68 returns two types of fatal error messages: diagnostic and internal logic error messages.

[!Q] DIGITAL RESEARCHT• --------------------------

. E-35

E.11 SENDC68 Error Messages CP/M-68K Programmer's Guide

E.ll.l Diagnostic Error Messages

The SENDC68 diagnostic error messages are listed in Table E-12 in alphabetic order with explanations and suggested user responses.

Table E-12. SENDC68 Diagnostic Error Messages

Message Meaning

file forfTlat error: filenarrte

The file indicated by the variable f i 1 en afTl e is not a command file. The file input to SENDC68 must be a command file, output by the linker (L068). Ensure that the file specified is a command file.

read error on file: filenafrle

The file indicated by the variable f i 1 en a fTl e is truncated. Rebuild the file by recompiling or reassembling, and relink it before you reenter the SENDC68 command line.

unable to create filenaMe

This message indicates an invalid drive code for the output file indicated by the variable f i len a fTl e . It can also mean that the disk to which SENDC68 is writing is full. Check the drive code. If it is correct, the disk is full. Erase unnecessary files, if any, or insert a new disk before you reenter the SENDC68 command line.

unable to open filenaMe

The input file indicated by the variable f i 1 en a fTl e does not exist. Check the filename and retype the SENDC68 command line.

Usa~e: sendcGB [-] COMMandfile [outputfile]

This message indicates a syntax error in the SENDC68 command line. The correct syntax is given in the error message. Retype the command line using the correct syntax.

E.ll.2 SENDC68 Internal Logic Error Messages

The following is a fatal error in the internal logic of SENDC68.

seek error on file filenaMe

-------------------------- l!QJ lJltJlTAL RESEARCH'" E-36

CP/M-68K Programmer's Guide E.ll SENDC68 Error Messages

If you receive this message, contact the place you purchased your system for assistance. You should provide the following information.




E.12 SIZE68 Error Messages

SIZE68 returns fatal, diagnostic error messages at the console. The SIZE68 error messages are listed in Table E-13 in alphabetic order with explanations and suggested user responses.

Table E-13. SIZE68 Error Messages

Message Meaning

File forlTlat error: filenalTle

The file indicated by tht:: variable f i 1 en a ITI e is neither an object file nor a command file. SIZE68 reqUIres eIther an object file, output by the assembler or the compiler, or a command file, output by the linker. Ensure that the file specified is one of these and reenter the SIZE68 command line.

re ad e r ro r on filenalTle

The file indicated by the variable f i 1 en a ITI e is truncated. Rebuild the file. Reassemble or recompile, and relink the source file before you reenter the SIZE68 command line.

unable to open filenalTle

Either the drive code is incorrect, or the file indicated by the variable f i 1 enalTle does not exist. Check the drive code and filename. Reenter the SIZE68 command line.

End of Appendix E

OCID DIGITAL RESEARCHT• --------------------------

E-37

Appendix F New Functions and Implementation Changes

CP/M-68K has six new Basic Disk Operating System (BDOS) functions and additional implementation changes in the BDOS functions and data structures that differ from other CP/M systems.

Table F-1. New BDOS Functions

Function I Number

Get Free Disk Space 46

Chain To Program 47

Flush Buffers 48

Set Exception Vector 61

Set Supervisor State 62

Get/Set TP A Limits 63

®JDIGITAL RESEARCHT• -----------------------

F-l

F.1 BDOS Function and Data Structure Changes CP/M-68K Programmer's Guide

F.1 BDOSFunction and Data Structure Changes

Implementation changes in CP/M-68K BDOS functions and data structures are described in the following table:

Table F-2. BDOS Function Implementation Changes

BDOS Function I Number I Implementation Change

Return Version Number 12

Reset Disk System 14

Open File 15

Get Disk Parameters 31

Contains the version number 2022H indicatingCP/M-68KVersion 1.1.

Does not log in disk drive A when it resets the disk system.

Opens a file only at extent 0, the base extent.

Returns a copy of the Disk Parameter Block (DPB).

Table F-3. BDOS Data Structure Implementation Changes

Structure

Base Page

File Control Block

I Implementation Change

Additional information has been added. The base page is no longer located at a fixed address. Appendix C outlines the structure of the base page.

The byte sequence for the Random Record Field has changed. The most significant byte (rO) is first and the least significant byte (r2) is last.

------------------------- [!ill DIGITAL RESEARCH™ F-2

CP/M-68K Programmer's Guide F.2 BOOS Functions Not Supported by CP/M-68K

F.2 BDOS Functions Not Supported by CP/M-68K

The following table contains functions and commands supported by other CP/M systems, but that are not supported by CP/M-68K.

Table F-4. BDOS Functions Not Supported by CP/M-68K

BDOS Function I Number

Get Address of Allocation Vector 27

Set DMA Base+ 51

Get DMA Base + 52

Get Maximum Memory* 53

Get Absolute Memory* 54

Allocate Absolute Memory* 55

Free Memory* 56

Free All Memory* 57

+ The 68000 microprocessor does not have a segmented architecture. Therefore, functions involving segment registers are not relevant to CP/M-68K.

* CP/M-68K does not have memory management functions.

In addition to the above BDOS Functions, CP/M-68K does not support the Assemble (A) command in DDT-68K.

End of Appendix F

I!IDDIGITAL RESEARCH™ -------------------------F-3

A

A command (AR68), 7-5 absolute

file, 7-9 origin directive (org), 5-8

access operating system, 1-2 additional serial 110 functions, 4-53 address, 1-8

errors, 4-72 AR68, 1-3, 7-1

commands, 7-3 error messages, E-1 errors, 7-8

archive utility (AR68), 1-3, 7-1 AS68, 1-3

assembly language, 5-10 error messages, E-5 instruction set, D-1 invoking, 5-1, 5-10

assembler (AS68) operation, 1-3,5-1 assembly language

directives, 5-3 extensions, 5-12

auxiliary

B

input, 4-53, A-1 output, 4-54, A-1

-Baddress, L068, 6-3 bad vector error, 4-72 base page, 1-2,2-2,4-69, C-1 Basic Disk Operating System (BDOS),

1-1,2-5 Basic 110 System (BIOS), 1-1,2-5

Index

.bass directive, 5-12 BDOS, 1-1

functions, 4-1 direct console 110, 4-47 error messages, E-14 invoking, 4-3 organization of, 4-4 output console function, 4-4 parameters, 4-3 system reset function, (0),2-4

BIOS, 1-1 error messages, E-16 functions, A-1 parameter block (BPB), 4-65 return code, 4-65

block storage segment (bss), 1-8 branch instructions, 5-12 bsr instruction, 5-12 bss, 1-8

directive, 5-4 built-in commands, 2-1 bus errors, 4-72

c CCP, 1-1,4-69 CDPB, 4-40 chain to program function, 4-63 character 110 functions, 4-44 close file function, 4-12, 4-23 cold start loader, 1-1 command

file format, 1-2, 3-1 tail, 2-3

common directive (comm), 5-4, 5-13 compute file size function, 4-28


Index-l

conditional directives, 5-7 Conin function, A-I Conout function, A-I console buffer, 4-50 Console Command Processor (CCP),

1-1,2-5 console 110 functions, 4-45, 4-46 Const function, A-I CP/M-68K,

architecture, ·1-2 commands, 1-3, 1-4 default memory model, 2-5 file specification, 1-6 \ operating system, 1-1 terminology, 1-8 text editor, 1-4

CPM.SYS file, 1-1 CPU, state of, 8-11 current default disk numbers, 4-37

D

D, DDT-68K Display command, 8-3 D, AR68 command, 7-3 -Daddress (L068), 6-3 data

directive, 5-4, 5-12 segment, 1-8

DDT-68K, 1-3 command

conventions, 8-1 summary, 8-2

error messages, E-20 operation, 8-1 terminating, 8-2

define constant directive (dc), 5-4 storage directive (ds), 5-5

delete file function, 4-15 delimiter characters, 1-6

DIR, 1-4 direct BIOS call function, 4-65 direct console 110 function, 4-47 DIRS, 1-4 disk

change error, 4-7, 4-38 directory, 4-13 file error, 4-7, 4-9 read error, 4-7 select error, 4-7 write error, 4-7

DMA buffer, 4-21 DPB, 4-40 drive

functions, 4-33 select code, 1-6

DUMP, 1-3, 7-1, 7-8 DUMP

E

error messages, E-26 invoking, 7-8 output, 7-8

E, DDT-68K Load for Execution command, 8-4

editing control functions, 4-50 end directive, 5-5 endc directive, 5-5 equate directive (equ), 5-6 ERA, 1-4 error messages

AR68 fatal, E-l AS68, E-5 BDOS, E-14 BIOS, E-16 DDT-68K, E-20 DUMP, E-26 L068, E-27 NM68, E-31

-------------------------I!QJ DIGITAL RESEARCH™ Index-2

RELOC, E-32 SENDC68, E-35 SIZE 68, E-37

errors, address, 4-72 AR68, 7-8 bus, 4-72

even directive, 5-6 exception

functions, 4-70 handler, 4-71, 4-74 parameter block (EPB), 4-71 vectors, 1-1,2-5,4-71

exiting transient programs, 2-4

F

F, DDT-68K Fill command, 8-5 -F, L068 option, 5-13 file

access functions, 4-4 attributes, 4-22, 4-23 Control Block (FCB), 4-5 loading, 2-2 processing errors, 4-7 size, 4-28 structure, 1-1 system access, 1-2 filetype fields, 1-6 flush buffers function, 4-64, A-I free sector count, 4-43 function code, 4-67 functions

BDOS, 4-1 console, 4-44

G

G, DDT-68K Go command, 8-5 get

address of disk parameter block, 4-40 console status, 4-52 disk free space, 4-43 disk parameters, 4-40 110 byte, 4-57, A-I memory region table address, A-I or set user code, 4-62 Read-Only vector, 4-39 /set TPA limits, 4-75

.globl directive, 5 -12

H

H, DDT-68K Hexadecimal Math command, 8-6

header, 3-1 home function, A-I

I

-I, L068 option, 6-2 I , DDT-68K Input Command Tail

command, 8-6 I/O functions

byte, 4-55 character, 4-44 direct console, 4-47

init function, A-I initial stack pointer, 4-69 instruction set summary, (AS68), D-l invoking

AR68, 6-1 AS68, 5-10 BDOS functions, 4-3

[I]l DIGITAL RESEARCH™ -------------------------Index-3

DUMP, 7-8 RELOC, 7-11 SIZE68, 7-13

IOBYTE, 4-55

J

jsr instruction, 5-12

L

L, DDT-68K List command, 8-7 line editing controls, 4-51 linker (L068) operation, 6-1 List

function, A-1 output function, 4-55

Listst function, A-1 L068, 1-3

error messages, E-27 load parameter block (LPB), 4-67,4-68 loading a program in memory, 2-2 logical

console device, 4-45, 4-50,4-72 list device (LIST), 4-55

login vector, 4-36 longword, 1-8

M

M, DDT-68K Move command, 8-7 make file function, 4-19 message filename, L068, 6-3 multiple programs, loading, 2-3

N

nibble, 1-8 NM68

o

error messages, E-31 utility, 1-3

object filename option (L068), 6-3 offset directive, 1-8, 5-8 -0, L068 option, 6-2 open file function, 4-11, 4-23,4-24 operating system access, 1-2 options, AR68, 7-3

p

page directive, 5-8 physical file size, 4-29 PIP, 1-4 print string function, 4-49 printer switch, 4-46 program

control functions, 4-58 counter (PC), 8-5, 8-11 execution tracing of, 8-9 load function, 4-67, 4-69 loading, 2-2 load parameter block (LPB), 3-7 segments, 2-2, 3-1

programming tools and commands, 1-2 utilities, 7-1

------------------------- l!IDDIGITAL RESEARCHT•

Index-4

R

R (Read) command AR68, 7-4 DDT-68K, 8-8

random record field and number, 4-24,4-29

read console buffer function, 4-50 error, 4-8 function, A-1 . random function, 4-24 sequential function, 4-16

read-only bit, 4-39 register mask directive, 5-9 RELOC error messages, E-32 relocation

information, 3-6 utility (RELOC), 1-3, 7-1, 7-9, 7-11 words, 3-8

REN, 1-4 rename file function, 4-20 reset

disk system function, 4-34 drive function, 4-42

resident system extensions (RSXs), 4-73 return

current disk function, 4-37 from subroutine (RTS), 4-69 login- vector function, 4-36 version number function, 4-60

-R, L068 option, 6-1 RSX, 4-73

s S, DDT-68K Set command, 8-8 search for first function, 4-13 search for next function, 4-14

section directive, 5-9 . Sectran function, A-1 segment

block, 1-8 data, 1-8 text, 1-8

Seldsk function, A-1 select disk function, 4-35 SENDC68

error messages, E-35 utility, 1-3, 7-1, 7-4

serial 110 functions, 4-53 set

direct memory access (DMA) address, 4-21

exception vector, 4-71, A-1 file attributes, 4-22, 4-23 110 byte, 4-58, A-1 random record, 4-30, 4-31 supervisor state, 4-74 /Get user code, 4-62

Setdma function, A-1 Setsec function, A-1 Settrk function, A-1 shift instruction, 5-12 SIZE68

error messages, E-37 output, 7-14 utility, 1-3, 7-1

-S, L068 option, 6-1 sparse files, 4-29 start scroll, 4-46 status register, 8 -11 stop scroll, 4-46 SUBMIT, 1-4 supervisor stack and state, 4-74 symbol

table, 3-1, 3-4 printing of, 3-6

type,. 3-7

I!IDDIGITAL RESEARCH™ -------------------------Index-S

system

T

control functions, 4-58 reset function, 4-59 stack pointer, 8-11 state, 4-72

-Taddress, L068, 6-2 T, DDT-68K Trace command, 8-9 T, AR68 command, 7-6 tab characters, 4-45 terminating DDT-68K, 8-2 text

directive, 5-9, 5-12 segment, 1-8

TP AB parameters field, 4-76 transient

command, 2-1 program area (TP A), 4-75 programs, 1-2

exiting, 2-4 Trap 2 instruction,4-4 TYPE, 1-4

u -Uname, L068 option, 6-2 U, DDT-68K Untrace command, 8-9 user

number, 4-62 stack, 2-2

pointer, 8-11 USER, 1-4

v V, DDT-68K Value command, 8-10 V, AR68 option, 7-3, 7-5, 7-6, 7-7 vector number and values, 4-71 version

dependent programming, 4-60 numbers, 4-61

return, 4-60 virtual file size, 4-29

w W, Write command

AR68, 7-6 DDT-68K, 8-10

warm boot function, A-1 wildcards, 1-7, 4-11 word, 1-8 write

x

error, 4-7 function, A-1 protect disk function, 4-38 random function, 4-26 sequential function, 4-17, 4-18

X, DDT-68K Examine CPU State command, 8-11

X, AR68 command, 7-7 -X, L068 option, 6-2

z -Zaddress, L068, 6-2

------------------------- i!IDDIGITAL RESEARCH'" Index-6

Reader Comment Card We welcome your comments and suggestions. They help us provide you with better product documentation.

Date

1. What sections of this manual are especially helpful?

2. What suggestions do you have for improving this manual? What information is missing or incomplete? Where are examples needed?

3. Did you find errors in this manual? (Specify section and page number.)

CP / M-68KTM Operating System Programmer's Guide Second Edition: June 1983 1015-2023-002

COMMENTS AND SUGGESTIONS BECOME THE PROPERlY Of DIGITAL RESEARCH.

---- .......... _- - "'- - .....,..""-~ -- ----~- --

From: ______________________ _

BUSINESS REPLY MAIL FIRST CLASS / PERMIT NO. 182 / PACIFIC GROVE, CA

POSTAGE WILL BE PAID BY ADDRESSEE

[!ID DiGITAL RESEARCH ®

Attn: Publications Production

P.O. BOX 579 PACIFIC GROVE, CA 93950-9987

11.1 •••• 11.1.1 ••• 1.1.11 ••• 1.1 •• 1.1 •• 1 •• 1.1 ••• 1 ••• 111

NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES

1.\

1015-202:

CP/M-68J(TM - s100computers.com

Documents