The CommodoreServer Internet Protocol (CSIP) Programmer's API

The CommodoreServer Internet Protocol, or CSIP, is a text-based, human-readable protocol for exchanging data and issuing commands on CommodoreServer.com.

This article describes what the protocol is and how to use it. It also documents all of the commands that are currently available and lists possibilities for the future.

CommodoreServer employs a powerful, yet easy-to-use and understand protocol for exchanging information with your Commodore computer to access disks and other account activities on CommodoreServer.com.  This protocol is a text-based, human-readable format and is designed for simplicity in both usage and programming.  You can use this protocol to write your own programs to access CommodoreServer.com content, such as disks.

Note: I recommend downloading and installing the CommodoreServer font so that you can read the Commodore text in this blog entry.

Download the font here and then refresh the page.

CSIP Example

V-1541 is a program that converts simple LOAD and SAVE operations into CSIP commands.  Let's look at an example.

LOAD "!",2

V-1541 promptly recognizes that a single exclamation point is the command for getting a list of disks.  V-1541 makes it easy to look at a list of disks by allowing you to type a single exclamation point instead of typing a series of commands to the server.  So behind the scenes, V-1541 issues a CSIP command to the server: DISKS 22

When this command is sent, it is requesting CommodoreServer.com to return a list of disks, one page at a time with 22 rows.  22 is used from the Commodore 64 because it has a maximum of 25 lines.  A little room is left for the message that V-1541 displays when the page fills up: PRESS ENTER TO CONTINUE OR PRESS 'S' TO STOP.

V-1541 sends these commands out through the Commodore's built-in RS-232 port (via the User Port).  The Comet64 Internet modem is pre-configured to send data that it receives from the RS-232 port and forwards it directly to CommodoreServer.com, on port 1541.  CommodoreServer is listening for CSIP commands on port 1541 and is able to recognize the DISKS command.

You might have an idea for a program or a need on another Commodore computer to access disk information from CommodoreServer.com without using the V-1541 software.  You can easily send the same commands by writing software that sends the commands to CommodoreServer.com.  There are several commands, documented below, to manipulate or retrieve disk data or data in another activity.

When you send a command, CommodoreServer usually responds with some sort of error code to indicate its success.  When reading the error number, you can safely assume that the first byte returned will be the digit zero (not a NULL character) if the operation succeeded.  Any other digit indicates an error.  If there was an error, you will have to refer to the error numbers for each command.  Generally speaking, a 500 error will be returned if there is an error, but can be different when more specific information is needed.  There are some errors that will be returned for operations that are invalid on a disk.  Disk errors follow the same number system that the Commodore disk drives use.

Below you will find a list of supported CSIP commands, their use and parameters.  Keep in mind that this specification is evolving and new commands will become available from time to time.  In no case will an already-existing command be changed in such a way that it breaks backward compatibility.  If there is a need to change a command, a new command will likely replace it.

CSIP Command Reference

Conventions Used in this Reference:

ITEMS SHOWN IN GREEN ARE REQUIRED PARAMETERS, UNLESS THEY ARE SURROUNDED BY SQUARE BRACKETS [], IN WHICH CASE THEY ARE OPTIONAL.

How to send commands to CommodoreServer.com

Commands are sent to CommodoreServer.com on port 1541.  Commands and parameters are always passed in the following way:

• Command is sent first.  If a parameter follows, a space is used to tell CommodoreServer that parameters are coming.
• Commands must be in UPPER case.
• 1st parameter is sent after the space.
• If additional parameters are sent, they are separated by commas.
• A command is executed when CHR$(13) is sent (a carriage return).

Example Command:

COMMAND PARAM1, PARAM2, PARAM3

Activities on CommodoreServer.com

Every command in the CSIP protocol is identified by the activity that will be performed. Currently, only one activity exists - the ability to manipulate disk images.  Each activity has its own set of commands.  By default, the disks activity is enabled.

Changing Activities

A programmer can change the activity, and thus be bound to the commands for that activity, by typing the following command:

GOTO ACTIVITY

Parameters

ACTIVITY is the name of the activity to use on CommodoreServer.com.  Currently, only the DISKS activity is allowed and is enabled by default.  Future activities will have their own set of commands and will also be documented in this article.

All Activities

Some commands will work the same, no matter which activity you are currently in.  These commands will work from any activity:

HELP

Displays a list of commands and the proper syntax for each for the current activity.

LOGIN USERNAME, PIN

Logs you into CommodoreServer.com so you can access disks and other account activities. The PIN is used so that you don't have to use and expose your password when you sign in from your Commodore computer.  Login attempts are limited and will be locked out after a few tries.  Users can reset the login attempt from the Web site.  Logging in as a new user would release all references to any account activity.

Parameters

USERNAME can be either the email address or screen name, depending on the settings in the user's account.

PIN is the remote access PIN that is assigned from within the user's account at CommodoreServer.com

LOGOUT

Logs you out of your account and puts you back into the Public Domain space.

QUIT

Logs you out of your account and disconnects the modem from the server.

Disk Activities

DISKS [XX]

Displays a list of disks available in the current folder for the currently-logged-in user.

Parameters

XX The number of lines to be shown per page. If omitted, the whole list will be sent.

Return values

CHR$(3) (ETX) to indicate end of page. Server will then wait for either the character S to stop sending additional pages or a CHR$(13)  (Carriage Return character) to continue to next page.

CHR$(4) (EOT) to indicate end of text - Server is done sending and returns to default listening mode.

INSERT FILENAME.D64

Virtually inserts a disk from within the current folder.

Parameters

FILENAME is the unique D64 filename. You can leave off the .D64 part of the filename.

REMOVE

Virtually removes the currently-inserted disk.

$ [XX]

Displays the contents of the currently-inserted disk.

Parameters

XX The number of lines to be shown per page. If omitted, the whole list will be sent.

Return values

CHR$(3) (ETX) to indicate end of page. Server will then wait for either the character S to stop sending additional pages or a CHR$(13)  (Carriage Return character) to continue to next page.

CHR$(4) (EOT) to indicate end of text - Server is done sending and returns to default listening mode.

NAME

Displays the filename and diskname/ID of the currently-inserted disk

LOAD FILENAME

Retrieves a binary program.  The first two bytes represent the size of the data, in LO-BYTE, HI-BYTE order.  The next two bytes are typically the memory location where the file should be loaded, in LO-BYTE, HI-BYTE order.

LOAD should not be executed without using a program to receive data because you need to prepare the Commodore for receiving the file.  Executing the command directly will only display garbage onto the screen.

Parameters

FILENAME is the filename to load from the currently-inserted disk.

SAVE FILENAME, SIZE [, TYPE]

Prepares the server to accept incoming binary or text data.  This should not be executed without using a program to prepare and send the data. You can add SEQ files to a disk if you know the size of your data beforehand.  Send the binary data after the server authorizes the transfer.

Parameters

FILENAME is the filename to be saved to the currently-inserted disk.

SIZE is two bytes that represent the size, in LO-BYTE, HI-BYTE order.  The first two bytes should be the program's start address in LO-BYTE, HI-BYTE order as well (except in the case of SEQ files).

TYPE is either PRG or SEQ If omitted, PRG is assumed.

BLOCKS

Retrieves the number of BLOCKS FREE for the currently-inserted disk

FIND TEXT [, XX]

Displays a list of files containing TEXT in the filename.

Parameters

TEXT is the text within any filename for the currently-logged-in user.

XX The number of lines to be shown per page. If omitted, the whole list will be sent.

Return values

CHR$(3) (ETX) to indicate end of page. Server will then wait for either the character S to stop sending additional pages or a CHR$(13)  (Carriage Return character) to continue to next page.

CHR$(4) (EOT) to indicate end of text - Server is done sending and returns to default listening mode.

CF FOLDER

Change to a new folder in the currently-logged-in user's account.  The term "folder" was chosen instead of directory to avoid confusion with directory of a disk.

Parameters

FOLDER is the folder to change to.  Sending / as the folder name will return to the root folder. You cannot combine levels of folders in one command, such as CF /ROOT/GAMES.  FOLDER must exist as a child of the current folder.

FOLDER can also be the name of a user, such as @PUBLIC. When done this way, you would be able to see all of the disks that the user PUBLIC shares with you. User names must be prefixed with the @ character. To change back to your own disks, use CF @.

MF FOLDER

Creates a folder as a child of the current folder in the currently-logged-in user's account.

Parameters

FOLDER is the name of the child folder that will be created in the current folder.

NEW D64FILENAME, DISKNAME, ID

Creates a newly-formatted disk in the current folder. NEW will not work as a way to format existing disks.

Parameters

D64FILENAME is the filename for your .d64 image - it cannot exist in the current folder.

DISKNAME is the 16-character name on the disk (the name that is displayed when viewing the directory).

ID is a 2-character ID for the disk.

SCRATCH FILENAME

Scratches (deletes) a file from the currently-inserted disk.

Parameters

FILENAME is the name of the existing file on the current disk to delete.  Scratch works similar to a real 1541 and will simply remove the entry from the directory and will mark all of the used sectors as free in the BAM.

GETSECTOR TRACK, SECTOR [, TYPE]

Retrieves the binary sector data on the currently-inserted disk.

Parameters

TRACK is a track on the disk where the data resides

SECTOR is the sector within the track where the data resides

TYPE is either B for binary data or H for hexadecimal values separated by spaces.  H is useful for humans while B is useful for programming.

PUTSECTOR TRACK, SECTOR

Prepares the server for a binary data transfer of 256 bytes on the given TRACK and SECTOR.  You should not attempt to execute this command without a program to perform the transfer.

Parameters

TRACK is a track on the disk where the data will be written

SECTOR is the sector within the track where the data will be written