OEM Manual Adaption

2. Language Reference Differences

Several elements of the BASIC language may be different or not included in your implementation. Some of these statements are listed below.

Read these sections closely and make the appropriate changes required for your specific implementation. A look at each statement and function alphabetically folows:

CIRCLE

The default value aspect ratio depends on particular screen hardware.

CLEAR

In some versions, CLEAR supports the ability to further control video memory with the videomemory parameter. The following is the enhanced syntax for the compiler:

CLEAR [,[location] [,[stack] [,videomemory]]]

The videomemory parameter tells BASIC to ensure there is enough room for videomemory number of bytes for display memory. This allocates space for graphic modes that require large amounts of display memory, or for additional pages (each of which might be displayed on the screen). The videomemory parameter is not supported on most machines.

COLOR

Colors are display-hardware dependent.

LOCATE

Note that the meanings of the LOCATE argument, can vary according to your implementation. Specifically, the largest row number and column number will vary according to the particular machine. Also, whether the cursor blinks, and the speed at which it blinks, depends on the particular machine.

In addition, the start and stop options are not implemented on some machines. If they are available, the range will vary according to the particular machine.

LPRINT

Support for LPRINT depends on the lineprinters supported.

NOISE

Multiple voices require hardware support found only in certain machines. If you attempt to execute the NOISE statement on anything but a machine without this hardware support you will get an "Advanced feature error" message.

PALETTE

The range of colors for this statement depend on screen hardware.

PCOPY

If PCOPY is executed on a machine that does not support multiple screen pages, an "Advanced Feature Error" message results.

PEN ON

On some machines, the pen should not be used in the border area of the screen. Any values returned while the pen is in that area will be inaccurate.

PLAY Statement

The number of notes can be played in the background at one time varies according to the particular machine.

PSET

The largest row number will vary according to the particular machine.

RND Function

The actual algorithm and random values for this function may vary with implementation.

SCREEN Statement

The options for this statement are display-hardware dependent.

SHELL

Some versions of BASIC will not allow the user to SHELL to another copy of BASIC. BASIC, when run as a child process, will recognize this before initialization and return to the parent copy of BASIC after issuing the message: "You cannot Shell to BASIC".
This restriction is provided as an implementation option for cases where it is necessary to protect the integrity of the BASIC parent. BASIC will produce a child program when it uses the SHELL statement. It is not possible for BASIC to totally protect itself from its children.

When a SHELL statement is executed, many things may be going on. For example, files may be open and devices may be in use.
The following guidelines will help to prevent child processes from harming the BASIC envirionment.

• 1. Hardware
  
  It is recommended that the state of all hardware be preserved during a SHELL command. The implementation interface provides a way for performing this task. However, it may be necessary to request that BASIC users refrain from using certain devices within child processes which are executed using the BASIC SHELL command. Specific areas of concern are:
  
  Screen Device
     While useful information may be displayed by child processes, some children can damage existing screen mode
     parameters. This problem is further complicated by Screen Editor issues.
  
  Interrupt Vectors
     Save and restore interrupt vectors the child intends to use. It seems reasonable to expect the child process to perform this
     task.
  
  Other Hardware
     Many devices are placed in a specific state by BASIC. Such devices may include an Interrupt Controller, Counter    Timers, DMA Controller, I/O Latch, and UARTS. These devices may be used by the child process without the user    being aware of any limitations. This is a serious consideration which must be addressed with other GW-BASIC    machine-specific considerations.
  
  The File System
  

  ---

     Warning
  
       Any child process which alters any open file in the BASIC parent shows poor programming technique, and may have
       unpredictable effects. If it is necessary to update such files, they should be closed in the parent before using SHELL,      then re-opened upon return to the BASIC parent.
  

  ---

  
  Memory Management
  
     a. Before BASIC shells to COMMAND, it will try to free any memory it is not then using, with one exception: when the BASIC interpreter is run with the /M: switch. When the /M: switch is set, BASIC assumes that the user intended to load something in the top of BASIC's memory block. This prevents BASIC from compressing the workspace before doing the SHELL. For this reason SHELL may fail with an "Out of memory" error when using the /M: switch.
  
     A better method is to load machine language subroutines before BASIC is run. This can be accomplished by placing code at the end of machine language subroutines that allows them to exit to DOS and stay resident. For example:
  
  

  
  
  CSEG SEGMENT CODE
  ;Machine language subroutine
  
  
  RET
  ;Last instruction
  
  
  START::
  
  
  INT 27H
  ;Terminate, stay resident
  
  
  CSEG ENDS
  
  
  END START
  
  
  
  

     Be sure to "load" these subroutines before BASIC by running them. The AUTOEXEC.BAT file is very useful for this
     purpose.
  
     b. A child should never "Terminate and stay resident". Doing so may not leave BASIC enough room to expand its
     workspace to the original size. If BASIC cannot restore the workspace, all files are closed, the error message "SHELL
     can't continue" is printed, and BASIC exits to DOS.
  
  

  ---

   Note
  
     There is no restriction in the machine-independent portion of BASIC which prohibits GW-BASIC from running as a child of GW-BASIC. However, complications which arise from this configuration may lead to a decision by the OEM that this capability should not be implemented.

  ---

SOUND

Multiple voices require hardware support found only in certain machines. If you attempt to execute a program with multiple voices on a machine without such support, you will get an "Advanced feature error" message.