1. Date
2. Dir
3. Help
4. Using More Than One Disk Drive
5. Format
6. Pip
7. Type
8. Rename
9. Erase

1. ED
2. Wordstar
3. dBase II
4. SuperCalc2
5. Turbo Pascal 2.0

1. Adventure

1. Assumptions

   This article assumes that you already know a little bit about the Commodore 128 and the Vice x128 emulator. You don't have to be an expert, but if you know what the Commodore 128 is, and know the basics of using Vice then you should be fine. Especially important is knowing how to attach disk images to Vice.

   It is also assumed you understand that CP/M is an operating system that is different from the 128's regular Basic 7.0 system, and you want to learn more about it.

2. Tools Used

   The instructions in this article were written using Vice 3.7 for x86_64 running on a Windows 11 laptop with keypad. They were also checked using a MacBook Pro running macOS 11.7.4 with the same version of Vice.

1. The Boot Disk

   Unlike the other operating systems for the Commodore 128 (when it is in 128 or 64 mode) CP/M requires a special boot disk. This disk needs to be attached to the #8 drive for CP/M to start up.

   The Commodore 128 came with a special, double-sided CP/M disk. Side one was used to boot up the system, and side two had some CP/M utilities. In order to boot up your Vice x128 emulator, you will need a copy of side one of that disk. You can download a good copy, which has fixed the Y2K bug, from our site. Once you download a copy, you'll see that it is labeled "CPMY2K.D71". This disk isn't exactly the same as the one that shipped with the original Commodore 128 hardware, but in my opinion it is better.

   If you want the originals, you can download the two disk images (one for front and back) at http://www.zimmers.net/anonftp/pub/cbm/demodisks/c128/index.html The front of the disk is in the file cpm.system.622-3282252.d64.gz and the utilities from the back of the disk are contained in the file cpm.utilities.d64.gz.

   

2. Booting Up CP/M

   1. Start the x128 Vice emulator. (Note: The Commodore 128 had two display modes: 40 columns and 80 columns. The emulator shows both of these at the same time, but you can only work in one of them. The 40 column one is green, and the 80 column one is black and twice as wide.)
   2. If you are working in the 40 column screen: press the 40/80 DISPLAY key once.
      1. You can do this a couple of different ways:
         1. Hover your mouse over the "80col:" section at the bottom of the emulator screen and click on it.
         2. Press the key on your keyboard that corresponds to the 40/80 DISPLAY key - on my computer that is the "/" in the numberpad.
      2. This will cause the emulator to boot up in 80 column mode when you restart it (and trust me, CP/M is much nicer and easier in 80 columns!) and will also cause the "80col:" section at the bottom of the emulator screen to turn green - which indicates that the button is pressed.
   3. Attach the CP/M boot disk image that you downloaded in step II.A above. You should attach it to drive #8.
   4. Type BOOT and press the return key. You can also do a soft or hard reset.
   1. You will see Booting... then Booting CP/M Plus and a bunch of stuff printed to the screen, finally you'll see CP/M 3.0 On the Commodore 128
   2. If you are not seeing anything on the black 80 column screen, then check the green 40 column one. If you are in this screen then CP/M still works - it is just more inconvenient to use. Since you can only see 40 columns of text at a time, you'll need to scroll right and left by typing Ctrl-right-arrow and Ctrl-left-arrow. I'd suggest that you press the 40/80 DISPLAY key and reset your system so that it boots up in 80 column mode.
   3. This all should take about 30 seconds or so.
   5. When you finally see the A> prompt and a blinking cursor then CP/M is booted and ready for your input.

   

CP/M is *not* case sensitive, so you can type commands in upper case or lower case (or a combination of the two) - it doesn't matter.

1. Date

   Typing the command date by itself will tell you what date and time the computer thinks it is. You'll probably see something like Thu 05/28/1987 01:00:29 - which is most likely not correct!

   You can set the current date and time by typing date set which will prompt you to enter the current date and time. Make sure to enter them in the *exact* format it asks for - especially don't enter years with four digits - or you will see the error message Illegal time/date specification.

   Also, remember that pesky Y2K bug from the late 1990s? Well it may rear its ugly head again if you aren't using a patched version of CP/M. If you are using the disk image labeled "CPMY2K.D71" from step II.A above then you should be fine. If you aren't using a patched version then you will have problems if you try to enter a year greater than 1999.

   Once you have the current date and time entered, try the date command again to verify that it is correct.

   An important note about the current date and time: you need to set it *every* time you boot up CP/M, or it will use the defaults. This can be inconvenient, but if you are creating files where you want the correct date and time then it is worth the effort.

   

2. Dir

   Dir is short for "directory" and will display a list of files on a disk.

   Typing dir by itself will list the files on the current drive. The output of dir can be several lines long. Each line begins with the drive designation letter, something like A: and is followed by filenames, which are separated from each other by a colon.

   Seeing something like A: CPM+ SYS : CCP COM means that there are two files listed - CPM+.SYS and CCP.COM. Filenames can be up to 8 characters long, and are followed by a 3 character extension - which usually indicates the file type. Note that even though you don't see a period between filename and extension in the dir listing, usually whenever you refer to a file you will type the period: INFO.DAT not INFO DAT.

   

3. Help

   Help is a feature that has different topics available, depending on what disk the system is operating on. For this section I am assuming you are working with the system boot disk labeled "CPMY2K.D71".

   Typing help by itself will clear the screen, display the help utility and list the topics available. It also changes the input prompt to HELP>. You can look over the topics available, and type one of them at the prompt to get more information.

   Try typing dir at the help prompt. The help utility will give you information about the dir command, and display a list of subtopics - in this case BUILT-IN" and WITHOPTIONS. To see more about either of those subtopics you need to type a dot followed by the subtopic name, like this: .BUILT-IN. The system will display more information, and give you some more subtopics. You can follow this to your heart's content.

   Typing a question mark at the help prompt will display a list of help topics. If you want to jump directly to a subtopic you can type the main topic followed by a space followed by the subtopic: dir withoptions.

   To exit the help utility just press return at the help prompt, and it will return you to the A> prompt.

   

4. Using More Than One Disk Drive

   It is common to use more than one disk drive with CP/M, and it is easy to change between drives - at the prompt just type the letter of the new drive, followed by a colon. But first let's go over how to set up more than one drive in the x128 Vice emulator, and how to create new disk images for it, then we can learn some commands to help us practice working with multiple drives.

   1. Setting up multiple drives in Vice x128

      The first thing we need to do is set the drive type for drive #9, so that we have access to a second disk drive we can use:

      1. Go to Preferences > Settings > Peripheral devices > Drive
      2. Click on Drive 9
      3. Set the Drive model as CBM 1571
      4. Make sure "Save settings on exit" is clicked
      5. Click on Close

      

   2. Create a new disk image in Vice x128 and attach it to drive #9:
      1. Go to File > Create and attach an empty disk image...
      2. Select unit #9
      3. Set disk type to d71
      4. Type the name of the file in the field at the top. This is the name you will see on your host computer's file system. (Be sure to check your path, as it likes to default to the place that vice is located!)
      5. Type the name of the disk image in the field at the bottom. This is the name you will see when using the disk in CP/M.
      6. Click save
      7. Type dir b: to list the contents of the disk in drive b - it should just show a bunch of colons at this point

      

5. Format

   Now that we have a second disk drive available, and a blank disk image we can use, we need to format the disk for CP/M use. (This was a common practice back in the day when many vendors used the same disk size, but had their own file systems.)

   First, we need a CP/M disk that has the format command on it. (The front of the original CP/M system disk, listed in step II.A above will work.) Make sure this disk in in drive A: and the new disk image you created is in drive B:

   1. From the  A>  prompt type  format  and press return
   2. From the format screen, use the down arrow key to move down and highlight  Select Different Drive  and press return
   3. Highlight  Drive B  and press return
   4. Highlight  C128 Single Sided  and press return
   5. Type  $  to continue with the formatting
   6. Wait... this takes a minute or two to complete
   7. Type  n  so the system won't format another disk. This will exit the format program.
   8. Now type  dir b:  - it should say  No File  since the disk is empty

   

6. Pip

   Note: For the next few commands, make sure you have the front of the original C128 CP/M disk in drive A: (See step II.A above)

   Pip (which stands for Peripheral Interchange Program) is the name of the program that copies files in CP/M. Let's try it out by copying a text file from A: to our newly formatted disk in drive B:

   1. From the  A>  prompt, type  pip b:=a:read.me  and press return. This will copy the "read.me" file from A: to B:
   2. Type  b:  to change to that drive
   3. Take a look at the directory now and make sure the file copied correctly

   Pip is a powerful command with lots of options, try the help command to look at all the stuff it can do.

7. Type

   Note: The next three commands we'll discuss (type, rename and erase) are built-in commands. That means they are always available, and are not required to be loaded from disk. DIR is also a built-in command.

   To display a text file on screen we use the "type" command. From the prompt type  type read.me  and press return. You should see some information about CP/M 3.0 on the Commodore 128.

   TYPE can be abbreviated as TYP, so entering  typ read.me  would produce the same results.

   

8. Rename

   To rename a file, use the rename command followed by the new file name, an equals sign, and the old file name. Make sure you're using the B: drive, and try it out by typing  rename newread.me=read.me . Use DIR to confirm that the filename was changed.

   RENAME can also be abbreviated at REN.

9. Erase

   Deleting, or erasing, a file is also super easy. Just type  erase  followed by the name of the file you wish to erase. Let's try it out by using its abbreviated command - type  era newread.me  and use DIR to confirm that the file no longer exists.

   

There are more CP/M commands, but these are the basic ones that will help you get around the operating and file systems. Use HELP, or see the CP/M manual, for other commands. You can find an online copy of the CP/M Plus User's Guide manual at https://www.oldcomputers-ddns.org/public/pub/manuals/cpm3_users_guide_(600).pdf.

CP/M is about more than just issuing commands, you can actually do practical stuff too! In this section we'll go over some of the useful things you can do.

1. ED

   ED is CP/M's text editor. One of its original purposes was to enter and edit source code files. If you've never used an old school editor before, and are use to modern editors, then be aware that ED is not intuitive nor is it easy to use! However, I doubt you are going through this tutorial in hopes of finding a new text editor that you can use in your daily life ;-).

   Keep in mind that ED is a line editor - meaning that it works with text on a line-by-line basis. Also, it uses the concept of a character pointer (CP) to move between lines and characters on a line. You won't see any actual pointer in ED, but to be proficient with it you'll need to keep track of where it's at.

   For this part of the tutorial I am going to assume that you have a disk in A: with the ED command on it (most boot disks have it), and that you have a work disk in B: where you can save the text file we'll be working with. And since we'll be creating and working with files in this section, be sure to set the current date and time - if that is important to you.

   1. From the  A:  prompt, type  ed b:test.dat . You should see  NEW FILE , then  : *  - this means ED is in command mode and awaiting your input.
   2. Type  i  to enter input mode. This will allow you to enter text one line at a time. (Note: if you type uppercase  I  it will convert all the chars you type to uppercase!)
   3. Type in at least three lines of text, pressing return after each line.
      1. If the backspace or delete buttons don't do what you think they should do, then try using Ctrl-h to delete characters.
      2. When you are finished typing in text, use Ctrl-z to return to command mode again.
   4. Type  e  to save the file and exit ED. You can check that your file was created by issuing the  DIR  command on B: and you can view your new file by using the  TYPE  command.
   5. Now let's edit the file you just created. Type  ed b:test.dat 
   6. Type  #a  to append (or read) the file into the memory buffer so you can work on it.
   7. Type  b  to move the CP to the beginning of the file.
   8. Type  10t  to type (or display) the first 10 lines of your file.
   9. Let's replace the second line of text
      1. Type  b  to move the CP to the beginning of the file.
      2. Type  1  to move the CP down one line. This will also display the text of that line.
      3. Type  1k  to kill (or delete) one line.
      4. Type  i  to enter insert mode.
      5. Type in some text for a new line, pressing enter and then Ctrl-z when you are done.
      6. Type  b  to move the CP to the beginning of the file.
      7. Type  3t  to display the first three lines of your file, and verify that line #2 is the new one.
   10. Now let's add some text to the third line.
       1. Type  b  to move the CP to the beginning of the file
       2. Type  2  to move the CP down 2 lines, so it is at the beginning of line #3
       3. Type  3c  to move the CP 3 characters to the right
       4. Type  iXXX <ctrl-z> <return> 
       5. Move your CP back to the beginning of the file, and display four lines to verify that the text was inserted at the proper point.
   11. You can continue to edit your file, or type  h  to save without exiting (although you'll need to use  #a  to append the lines into memory again), or type  e  to save and exit to the CP/M prompt.

   As you can see, it takes some practice to get used to editing text with ED! However, there are a lot of other commands you can use with it. For more information about using ED see the Ed Command summary listing in section 5 of the CP/M 3 User's Guide, on page 5-30, and section 6 - which goes into much more detail about it. You can find an online copy of the CP/M 3 User's Guide manual at https://www.oldcomputers-ddns.org/public/pub/manuals/cpm3_users_guide_(600).pdf.

   

2. Wordstar

   WordStar was a word processor that was popular on CP/M machines in the early 1980s. Even though it is much easier to use than ED, it is still quite a bit different than today's word processors. Let's give version 3 a try and see what it's like.

   You can get the WordStar 3.3 program at http://www.zimmers.net/anonftp/pub/cpm/prod/index.html. If you get WordStar at this link you'll notice that it is in .d81 disk format. This means you'll need to have a 1581 virtual drive set up to read it. (See section III.D.1 above if you need help doing that.)

   We are going to be saving our test WordStar document to the same disk that has the WordStar command on it. However, if you want to save your WordStar documents on a different disk then either prepend the drive name, such as  b: , to the filename, or change your logged in drive. (One more piece of fun-ness: to save files to a different logged drive, make sure you first copy the file "WSOVLY1.OVR" to the disk where you want to save your documents - otherwise you'll see an  ERROR E46  message!)

   Note: If you get stuck and find that the Esc key isn't working, you can use the F9 key instead.

   1. Attach the disk image and type  ws  at the prompt. After seeing a couple of introduction screens, you'll end up at the Opening Menu page. This screen has a few sections:
      1. The Status line. This is the top line of the screen, and in the upper left corner it probably says  not editing  right now, but that will change when we start doing things.
      2. Below that is the Menu area, which shows a list of commands you can enter. Commands are grouped by type in this area.
      3. Next is the Directory area, which shows most of the files on the currently logged in (working) disk.
      4. The blank area at the bottom of the screen is the Text area.
   2. Type  d  (don't press return) to open a new document file. When you do, notice that the cursor jumps to the Status line, waits a second and then displays some new text in the Menu area.
   3. Type a name for your new file, something like  wstest1.doc  and press return. WordStar will tell you that it is a new file, and then present you with a new status line and a text area where you can type.
   4. Type some lines. When you are done press  Ctrl-k , release them, and press  d . This will save your file and return you to the Opening Menu page.
   5. Now let's edit our file: press  d  again to edit a document, but this time type the name of the file we previously created. It will load the file and return you to the text area so you can edit it.
   6. Make some edits, but this time save your document by pressing  Ctrl-k s  - which will save and resume editing.
   7. When you are all done editing, type  Ctrl-k d  to save and return to the Opening Menu. Notice that the directory area lists your new file, and also a backup of it - indicated by the  .BAK  file extension.
   8. Press  x  to exit WordStar and return to the system prompt.

   WordStar is actually pretty cool, and has a lot of commands that come in quite handy. Take a look at the manual to learn more about what it can do and how to use it. You can find the manual at http://www.bitsavers.org/pdf/microPro/Wordstar_3.3/Wordstar_3.3_Reference_Manual_1983.pdf.

   

3. dBase II

   dBase II was another killer application for CP/M in the early 1980s. Once again, the user interface isn't anything like what we have today but it is still interesting to see what using it was like. Let's try out version 2.

   You can get a disk image with dBase II on it at http://www.zimmers.net/anonftp/pub/cpm/prod/index.html.

   1. Attach the disk image to a virtual 1571 drive, and type  dbase  to start up the application.
   2. You will first be prompted for today's date. You can enter that, or press return to skip it. It will then show you a couple lines of info about the program and present you with a dot prompt. dBase II uses a dot as the prompt, and this lets you know that it is ready to accept your commands.
   3. Let's create a new database: enter  create 
   4. When it prompts you for a filename enter  people  - you can use either uppercase or lowercase letters.
   5. It will then ask you to enter record structure. Type  name,c,15  for 001. This means that your first field will be named "name", be of type character, and can be up to 15 characters long.
   6. For field 002 type  dept:num,c,2  and for field 003 type  salary,n,8,2 .
   7. For field 004 just press return without typing anything.
   8. It will ask you if you want to input data now, type  y .
   9. You can now enter your first record using the fields that you just set up. Enter a few records - here is an example of what you can enter: name =  Alazar, Pat , dept:num =  75  and salary =  50000.00 .
   10. When you are finished you can exit record entry by just pressing return at the name prompt. This will take you back to the dot prompt.
   11. Now let's look at a list of all the records in your database. Type  use people , press return, enter  list . This will display the records you've entered.
   12. Let's try sorting the records in alphabetical order. Type  sort on name to abcorder , then  use abcorder  then  list  again.
   13. If you want to enter more records, use the "append" command.
   14. To end your dBase II session type  quit  at the dot prompt. This will exit the program and return you to the CP/M prompt.
   15. The next time you start up dBase II you can continue working with the people database, just type  use people  at the dot prompt then you can issue commands against it.

   We've really only just scratched the surface of what dBase II can do. You can learn more about it by checking out the manual at https://archive.org/details/bitsavers_necAPC8190rsGuideFeb83_9145866/mode/2up?view=theater (That is actually the manual for version 2.3 on CP/M-86, which isn't exactly the same as the one we're using here, but it is close enough!)

   

4. SuperCalc2

   SuperCalc2 was a spreadsheet that was popular on CP/M machines in the early 1980s. It was a competitor to VisiCalc and Lotus 1-2-3. Its layout is similar to other spreadsheet programs, but the commands are a bit different. Let's give it a try.

   You can download the disk image for SuperCalc2 version 1.00 from our site: SuperCalc_v2.d71.

   1. Remember to set the current date and time for your system.
   2. Attach the disk image to a drive.
   3. Type  sc2  to start up the application.
   4. Press return to start a new spreadsheet
   5. It will display a new, empty sheet and it is ready for input into cell A1. We know it is cell A1 because that cell is highlighted in reverse text, but also the status line (3rd from bottom) displays  > A1 . Keep a close eye on the status line because sometimes it is difficult to tell where the highlighted cell is!
   6. Before jumping in, let's go over some basic commands and concepts in SuperCalc2:
      1. Notice the small arrow on the status line, that tells you which cell will be highlighted next, after you press return.
      2. To change or edit the contents of a cell, just move to the cell and type the new value.
      3. To delete (or blank out) the contents of a cell type  /b 
      4. If you make a mistake when entering the contents of a cell, don't use the backspace or delete keys - they won't work. Instead use the arrow keys to go back to your mistake and then just type over it.
      5. If you get stuck at any point and aren't sure what to do, just type  ?  and SuperCalc2 will give you context sensitive help - cool!
      6.  Ctrl-z  will cancel an operation.
   7. Let's create a small, basic worksheet:
      1. To enter text into a cell start by tying one double quote. In cell A1 type this:  "Food: 
      2. In cell A2 type:  "Gas: 
      3. In cell A3 type:  "Total: 
      4. Now move to cell B1. To do that use the arrow keys and notice that the cell number changes on the status line. Or type  =  and cell number to jump to that cell, like this:  =b1 
      5. In cell B1 type a value, like this:  550 
      6. In cell B2 type another value, like:  100 
      7. In cell B3 enter a sum command by typing  sum(b1:b2)  - notice that SuperCalc will automatically update the cell contents and the worksheet.
   8. To save your worksheet we need to use what is called a "slash command".
      1. Type:  /s 
      2. Type the name of the file to save, something like  wksht1 
      3. Type  a  to save the whole worksheet, not just part of it
   9. Now that you are done with our super simple example, here are some more Slash Commands that you can try out:
      1.  /z  = delete entire worksheet
      2.  /q, y  = exit without saving
      3.  /l, name, a  = load all of the worksheet called "name"

   The disk has some sample worksheets on it that you can load and play around with. One good one is called "sample" - try loading it and see what it has.

   Once again, we have barely touched on what SuperCalc2 is capable of doing. Take a look at the manual at https://deramp.com/downloads/altair/software/manuals/SuperCalc2.pdf and try out some of the other things you can do with this cool program!

   

5. Turbo Pascal 2.0

   Turbo Pascal was a popular compiler and integrated development environment for both CP/M and DOS in the 1980s. Let's take a look at version 2.0, which came out in 1984. You can get a copy of the Turbo Pascal 2.0 disk at http://www.zimmers.net/anonftp/pub/cpm/programming/index.html

   1. Insert the disk into drive B:
   2. Type turbo to start the program
   3. Type y to include error messages
   4. Press e to edit, then enter a new file name
   5. Enter some lines of Pascal. Here is a good, small program:
      program Hello;
      begin
          writeln('Hello World!');
      end.
   6. Press Ctrl-k Ctrl-d to exit, then at the > prompt press return to see the menu
   7. Press s to save your file
   8. Notice that "Work file:" now shows the name of the program you are currently working with
   9. Press c to compile
      1. If there is a problem compiling, you will see an error # and an error message, usually followed by Press <ESC>
      2. If the "Esc" key doesn't work, try the F9 key
      3. This will return you to the source code, and place the cursor on the offending line
      4. Fix the problem, then return to the menu to save and compile again
   10. Press r to run your program
   11. To make an executable program:
       1. From the main menu, type O for compiler Options
       2. Type c to move the arrow to Com-file
       3. Type q to quit to the main menu
       4. Type c to compile. This will take a minute as the program creates and writes your .com file to disk
       5. Type d for Dir, then *.com as the directory mask - you should see your newly created .com file listed
       6. You can execute it right from Turbo Pascal by typing X for eXecute, then the name of your program, like "test.com". It will run and you will see your output
       7. You can also run your program by returning to the main menu, typing q to Quit, then typing the name of your .com program from the system prompt

   If you are interested in learning more about Turbo Pascal you can find the 2.0 manual at https://archive.org/details/bitsavers_borlandturVersion2.0Reference1984_8178030/mode/2up (If you refer to the appendices, remember to use appendix A for CP/M-80, since the C128 uses the Z80 chip for CP/M!)

   

1. Adventure

   Adventure, a.k.a. Colossal Cave Adventure, is one of the first (if not *the* first) text adventure games. It started life in the mid 1970s on the PDP-10 mainframe computer. Originally written by Will Crowther, the game underwent several expansions (mostly by Don Woods) over the next couple of decades. Versions of the game are often differentiated by the number of total points possible. There are several CP/M versions of the game, but let's try out the 550 point version known as B01, which is Mike Goetz's CP/M port from the spring of 1981.

   1. You can download a zip file containing several versions of the game from our site.
   2. Attach the disk image for adv-B01.d71 to one of your CP/M drives.
   3. Type adv to start the game
   4. You will see a welcome screen and a prompt asking if you'd like instructions. You can type yes or no, but either way you'll eventually start the game when it tells you where you are standing and you see the > prompt.
   5. This is a game like all other old school text adventures - meaning you tell the computer what to do by inputing one or two word commands. Try it out now by typing enter building
   6. You can pick up objects by typing something like get lamp (That command is also the name of a fine documentary about text adventure games!)
   7. Type inventory to see what you are currently holding.
   8. Exit the house and go down, do a bit of exploring until you find the entrance to the Colossal Cave.
   9. The goal of the game is to find the many treasure items and return them to the well house.
   10. There are many commands, but here are a few more useful ones that you should know:
       1. help will tell you more about how to play the game.
       2. drop will let you drop some item you are carrying.
       3. score will show you how many points you currently have.
       4. quit will exit the game after showing your score and opining on your exploring abilities.
       5. news will give you some information about this version of the game.

   Adventure is fun game that can provide many hours of happiness! There are many places where you can get help, hints, maps and more. Here are a few good ones:

   1. Take a look at the file "ADVENT.WS" on the disk image. It is a walkthrough for the game - but be careful to not read more than you want!
   2. A great online resource for all things Adventure (including maps!) can be found at https://rickadams.org/adventure/.
   3. Our site has an instruction manual for the Commodore 64 version of Colossal Adventure. That one is by Level 9 Computing, and isn't quite the same as this B01 version, but it does have some good hints!