Programming notes: Difference between revisions

From Color 64 BBS Wiki
← Older edit
m Protected "Programming notes" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[programming features|Programming Features]] - <strong>Miscellaneous Programming Notes</strong>
[[programming features|Programming Features]] - <strong>Miscellaneous Programming Notes</strong>


== Misc Programming Notes ==


<strong>Rainbow mode:</strong>
=== Rainbow Mode ===


If you place an F1 character inside the quotes of text to be sent, rainbow mode will be turned on, using the system colors defined in SETUP.  Turn off by placing an F3 character inside the quotes.  
If an <strong>F1</strong> character is placed inside a quoted text string that is being sent to the user, Rainbow Mode will be enabled. 
In this mode, characters are displayed using the system color sequence defined in SETUP.


To disable Rainbow Mode, place an <strong>F3</strong> character inside the quoted text.


<strong>Color Sequencing:</strong>  
Example:
<code>"{F1}Rainbow text here{F3}"</code>


If you place an F5 character inside the quotes, the cursor will change to the next color from the sequence defined in SETUP.


=== Color Sequencing ===


<strong>Border Color:  </strong>
If an <strong>F5</strong> character is placed inside a quoted text string, the cursor will advance to the <em>next color</em> in the color sequence defined in SETUP. 
This allows color cycling within printed output without explicitly specifying each color.


If you place an F7 character inside the quotes, the border/screen will change to black.


To reset the background color or uppercase mode, do the following: <strong>GOSUB 13680 </strong>
=== Border Color ===


If an <strong>F7</strong> character is placed inside a quoted text string, the border and screen background will switch to black.


<strong>Sequential File Display:</strong>
To restore the normal background color and uppercase mode, execute:


To read a sequential file from the System Files, use the following:
<code>GOSUB 13680</code>
: <strong>f$="filename":gosub205 </strong>




<strong>Data Input from File:</strong>
=== Sequential File Display ===


To input data from a sequential file you may be using for data storage, you can use normal INPUT commands as always.  There are ML routines to do the same thing, but it is not necessary that you use it; INPUT# should work fine in most cases.
To display a sequential file located in the <em>System Files</em> area:


<code>F$="filename":GOSUB 205</code>


<strong>Capture User Input:  </strong>
This routine opens the file, sends its contents to both the screen and modem, and then closes the file.


* To input a typed line from the user, use <strong>GOSUB 310</strong>.  Your caller's input will be stored in I$.


* To get one character from the modem/console, use <strong>GOSUB 110</strong>.  If a character had been typed, it will be stored in A$.
=== Data Input from File ===


* To wait for a Y/N response, use <strong>GOSUB 1010</strong>.  Their response will be in A$.  
Sequential files used for data storage can be read using standard BASIC file input commands.


* To ask "Are you sure?", use <strong>GOSUB 1005 </strong>
Example:
<code>INPUT#</code>


Although machine language routines exist to perform similar functions, they are not required for most applications. Standard BASIC file I/O generally performs adequately for typical BBS modules.


<strong>Caller Log:</strong>


To store something in the caller log, do one of the following:
=== Capture User Input ===
: <strong>a$="info to save":gosub8004</strong> or
: <strong>i$="info to save":gosub8003 </strong>


Color 64 provides several routines for capturing user input.


<strong>Carrier Lost Check:</strong>
* To input a full line typed by the user: 
  <code>GOSUB 310</code> 
  The result is stored in the variable <strong>I$</strong>.


After inputting from the user or reading a seq file, if you check the value of P, you will be able to determine if there has been a carrier lost. If P=255, then either carrier was lost or there has been a timeout.  If P=1 then the caller typed CTRL/P and you should assume they want to abort the current function.  Generally, after every input, it is recommended to have the following line of code: <strong>IF P THEN RETURN </strong>
* To read a single character from the modem or console: 
  <code>GOSUB 110</code>  
  If a character was typed, it will be stored in <strong>A$</strong>.


* To prompt for a Yes/No response: 
  <code>GOSUB 1010</code> 
  The result (<code>Y</code> or <code>N</code>) will be returned in <strong>A$</strong>.


<strong>Disk Error Check:</strong>
* To display the standard "Are you sure?" confirmation prompt: 
  <code>GOSUB 1005</code>


To check the error channel after accessing the disk drive, use <strong>GOSUB 510</strong>.  If there was a disk error, it will automatically print to your screen and the caller's.  The variables er, er$, et, es will contain the disk status.  Some types of disk errors will not print and should be handled by your routine if necessary.  They are #62, #63, #64 and #73.  Also, if there is a disk full error, <strong>GOSUB 510</strong> will automatically validate the disk.


=== Caller Log ===


<strong>Select Systems Drive:</strong>
To store information in the caller log, use one of the following methods:


To select the system files drive: <strong>GOSUB 481</strong>  
<code>A$="info to save":GOSUB 8004</code>


or


<strong>Convert Input (I$) to Numeric Format:</strong>
<code>I$="info to save":GOSUB 8003</code>


To convert I$ to a numeric format, use <strong>GOSUB 610</strong>.  The numeric value will be held in variable I.  And if I$ contains non-numeric information, the variable I will be equal to 0.  
These routines append the specified information to the caller log maintained by the BBS.




<strong>Spare Commands:</strong>
=== Carrier Lost Check ===


To use one of the "spare" commands in SETUP, refer to the table below to determine which command to use.  
After user input or sequential file reads, you can test the variable <strong>P</strong> to determine if the connection has been interrupted.


{| class="wikitable
Possible values of <strong>P</strong> include:
 
* <strong>P=255</strong> – Carrier lost or timeout occurred 
* <strong>P=1</strong> – Caller pressed <code>CTRL/P</code> to abort
 
It is recommended that programs include the following line after input operations:
 
<code>IF P THEN RETURN</code>
 
This ensures the routine exits cleanly if the caller disconnects or aborts the operation.
 
 
=== Disk Error Check ===
 
To check the disk error channel after accessing a disk drive:
 
<code>GOSUB 510</code>
 
If an error occurred, the message will automatically be printed to both the local screen and the caller's terminal.
 
The following variables will contain the error information:
 
* <strong>ER</strong> – Error number 
* <strong>ER$</strong> – Error description 
* <strong>ET</strong> – Error track 
* <strong>ES</strong> – Error sector
 
Some disk status codes are not automatically displayed and must be handled manually if needed:
 
* 62
* 63
* 64
* 73
 
If a <em>disk full</em> condition occurs, the routine will automatically attempt to validate the disk.
 
 
=== Select System Files Drive ===
 
To select the System Files drive:
 
<code>GOSUB 481</code>
 
 
=== Convert Input (I$) to Numeric Format ===
 
To convert the string stored in <strong>I$</strong> into a numeric value:
 
<code>GOSUB 610</code>
 
The resulting numeric value will be stored in variable <strong>I</strong>.
 
If <strong>I$</strong> contains non-numeric characters, the resulting value of <strong>I</strong> will be <code>0</code>.
 
 
=== Spare Commands ===
 
The Color 64 command system includes several "spare" command slots that can be assigned to custom programs or modules.
 
Refer to the following table to determine which program overlay and entry line are used by each spare command.
 
{| class="wikitable"
|-
|-
|+Spare Command Reference Chart
|+ Spare Command Reference Chart
! Command
! Command
! Loads Program
! Loads Program
! Executes Line
! Executes Line
|-
|-
| Spare 1 (in 8.10a, default for games)
| Spare 1 (v8.1a default: Games)
| √bbs.msgs
| √bbs.msgs
| 13430
| 13430
|-
|-
| Spare 2 (in 8.10a, default for User Profile)
| Spare 2 (v8.1a default: User Profile)
| √bbs.xfer
| √bbs.xfer
| 13440
| 13440
|-
|-
| Spare 3
| Spare 3
| √bbs.ov1
| √bbs.ovl
| 13450
| 13450
|-
|-
Line 100: Line 174:
|-  
|-  
| Spare 6
| Spare 6
| √bbs.ov1
| √bbs.ovl
| 13465
| 13465
|-
|-
| Spare 7
| Spare 7
| √bbs.ov1
| √bbs.ovl
| 13470
| 13470
|-
|-
| Spare 8
| Spare 8
| √bbs.ov1
| √bbs.ovl
| 13475
| 13475
|-
|-
| Spare 9
| Spare 9
| √bbs.ov1
| √bbs.ovl
| 13480
| 13480
|}
|}


As you can see, there is one spare command pointed to each program file with spare 6 through 9 all pointing to √bbs.ovl. This allows you to put all you smaller files in √bbs.ovl and save √bbs.ov2 and √bbs.ov3 for larger files (the included Mod Menu program uses √bbs.ov2).  For Color 64 v8.10a, Spare 1 and 2 commands are being utilized for Games and User Profile Editor respectively. 
As shown above, each overlay has at least one spare command entry point. 
Spare commands <strong>6 through 9</strong> all branch to <strong>√bbs.ovl</strong>, which makes it convenient to place several smaller utilities in that overlay.
 
This design allows:
 
* √bbs.ovl – multiple small utilities 
* √bbs.ov2 / √bbs.ov3 – larger programs or menus
 
In Color 64 <strong>v8.1a</strong>, Spare Commands 1 and 2 are already assigned (can be modified, if desired):
 
* Spare 1 – Games Menu
* Spare 2 – User Profile Editor


If you want to have lots of little programs in ov2 or ov3, I recommend you design a menu that is called spare 4 or spare 5, then have this command select the desired subroutine.  
If you wish to run multiple programs from a single spare command, a common approach is to implement a small menu program. For example, Spare 4 or Spare 5 can load a menu which then branches to several internal subroutines depending on the user's selection.


Next section: [[branch tables|Command Branch Tables]]
Next section: [[generic routines|Generic Routines]]


[[programming features|Programming Features]]
[[programming features|Programming Features]]

Latest revision as of 13:33, 7 March 2026

Programming Features - Miscellaneous Programming Notes

Misc Programming Notes

Rainbow Mode

If an F1 character is placed inside a quoted text string that is being sent to the user, Rainbow Mode will be enabled. In this mode, characters are displayed using the system color sequence defined in SETUP.

To disable Rainbow Mode, place an F3 character inside the quoted text.

Example: 

"{F1}Rainbow text here{F3}"


Color Sequencing

If an F5 character is placed inside a quoted text string, the cursor will advance to the next color in the color sequence defined in SETUP. This allows color cycling within printed output without explicitly specifying each color.


Border Color

If an F7 character is placed inside a quoted text string, the border and screen background will switch to black.

To restore the normal background color and uppercase mode, execute: 

GOSUB 13680


Sequential File Display

To display a sequential file located in the System Files area: 

F$="filename":GOSUB 205

This routine opens the file, sends its contents to both the screen and modem, and then closes the file.


Data Input from File

Sequential files used for data storage can be read using standard BASIC file input commands.

Example: 

INPUT#

Although machine language routines exist to perform similar functions, they are not required for most applications. Standard BASIC file I/O generally performs adequately for typical BBS modules.


Capture User Input

Color 64 provides several routines for capturing user input.

  • To input a full line typed by the user:
 GOSUB 310  
 The result is stored in the variable I$.
  • To read a single character from the modem or console:
 GOSUB 110  
 If a character was typed, it will be stored in A$.
  • To prompt for a Yes/No response:
 GOSUB 1010  
 The result (Y or N) will be returned in A$.
  • To display the standard "Are you sure?" confirmation prompt:
 GOSUB 1005


Caller Log

To store information in the caller log, use one of the following methods: 

A$="info to save":GOSUB 8004

or 

I$="info to save":GOSUB 8003

These routines append the specified information to the caller log maintained by the BBS.


Carrier Lost Check

After user input or sequential file reads, you can test the variable P to determine if the connection has been interrupted.

Possible values of P include:

  • P=255 – Carrier lost or timeout occurred
  • P=1 – Caller pressed CTRL/P to abort

It is recommended that programs include the following line after input operations: 

IF P THEN RETURN

This ensures the routine exits cleanly if the caller disconnects or aborts the operation.


Disk Error Check

To check the disk error channel after accessing a disk drive: 

GOSUB 510

If an error occurred, the message will automatically be printed to both the local screen and the caller's terminal.

The following variables will contain the error information:

  • ER – Error number
  • ER$ – Error description
  • ET – Error track
  • ES – Error sector

Some disk status codes are not automatically displayed and must be handled manually if needed:

  • 62
  • 63
  • 64
  • 73

If a disk full condition occurs, the routine will automatically attempt to validate the disk.


Select System Files Drive

To select the System Files drive: 

GOSUB 481


Convert Input (I$) to Numeric Format

To convert the string stored in I$ into a numeric value: 

GOSUB 610

The resulting numeric value will be stored in variable I.

If I$ contains non-numeric characters, the resulting value of I will be 0.


Spare Commands

The Color 64 command system includes several "spare" command slots that can be assigned to custom programs or modules.

Refer to the following table to determine which program overlay and entry line are used by each spare command.

Spare Command Reference Chart
Command Loads Program Executes Line
Spare 1 (v8.1a default: Games) √bbs.msgs 13430
Spare 2 (v8.1a default: User Profile) √bbs.xfer 13440
Spare 3 √bbs.ovl 13450
Spare 4 √bbs.ov2 13455
Spare 5 √bbs.ov3 13460
Spare 6 √bbs.ovl 13465
Spare 7 √bbs.ovl 13470
Spare 8 √bbs.ovl 13475
Spare 9 √bbs.ovl 13480

As shown above, each overlay has at least one spare command entry point. Spare commands 6 through 9 all branch to √bbs.ovl, which makes it convenient to place several smaller utilities in that overlay.

This design allows:

  • √bbs.ovl – multiple small utilities
  • √bbs.ov2 / √bbs.ov3 – larger programs or menus

In Color 64 v8.1a, Spare Commands 1 and 2 are already assigned (can be modified, if desired):

  • Spare 1 – Games Menu
  • Spare 2 – User Profile Editor

If you wish to run multiple programs from a single spare command, a common approach is to implement a small menu program. For example, Spare 4 or Spare 5 can load a menu which then branches to several internal subroutines depending on the user's selection.

Next section: Generic Routines

Programming Features

Retrieved from "https://www.color64wiki.itchybutt.org/index.php?title=Programming_notes&oldid=916"