www.cpcalive.com

                                                                                                                                                                                                                      
* CpcAlive V1.07h *
* ENGLISH
DOCUMENTATION *
CpcAlive is an Amstrad CPC computer emulator.
CpcAlive is a free software.
 Its vocation is to integrate into the Dos system the softwares developed on the CPC system.

                                                                                                                                                                                                                       

I - CpcAlive Initializations:

Create a CpcAlive
directory on your hard disk and decompress the file CpcAliveV1.07h.zip in this directory.
You can now launch CpcAlive.
If you launch CpcAlive starting from a Dos window and  you obtain an "Ems error" message, close the window, click on the MsDos icon with right mouse bouton and select "Proprieties","Memory","EMS Memory>AUTO".

Notes:
    - Amstrad roms ares copyrighted, you cannot thus normally use CpcAlive only if you have a
n Amstrad Cpc 6128 computer in a position to function.
    - colors PAPER and PEN 1 were modified with initialization for
ergonomic reason  (less tiring for eyes).


II - CpcAlive commands syntax:

CpcAlive [input_file[:X]] [command] [Cpc command] [>output_file]
or
! [input_file[:X]] [command] [Cpc command] [>output_file]

- 1 - [input_file[:X]]
~~~~~~~~~~~~~~~~~~~~~~~

input_file =      virtual diskette with format DSK     (see chapter - 1a -)
              or     Cpc rom file                                  (see chapter - 1b -)
              or     intel hex file                                   (see chapter - 1c -)
              or     command file                                 (see chapter - 1d -)
              or     text document                                (see chapter - 1e -)

X           =      see chapters 1a, 1b and 1c

Syntax from the Cpc Basic Interpreter:

All input files commands are also available from the Cpc basic interpreter with instruction:
|INPUT,"input_file[:X]"[,@er%]

The
error return parameter @er% is facultatif. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
1 = error in the parameters
2 = way not found
(don't forget initialize er% at the program beginning or before the command)

         ex:    10 er%=0
                 20 |INPUT,"Disc.dsk",@er%
                 30 if er%<>0 then PRINT"ERROR":STOP

It is possible to put several file name at the continuation, it is enough to separate them by a space character. In this case, the error code er% will relate to the last file mentioned.


- 1a - Loading virtual diskettes files (.DSK
) -
Make follow the file name of the
":A" or ":B" markers to choose the Cpc drive destination.(drive A by defect)

example starting from the Dos command line:

! disc.dsk:A

This command launch the emulator and load the virtual diskette "disc.dsk" in drive A.
note: no space betwen the file name and the marker.


- 1b - Loading  Cpc roms files -
Make follow the file name by the ":R" marker

example starting from the Dos command line:

! XRom.rom:R

If
the rom number place must be fixed, change the 'R' character by the rom number place.
This number can be written into decimal, hexadecimal or binary.

example starting from the Dos command line:
-decimal:          ! XRom.rom:10
-hexadecimal:  
! XRom.rom:0Ah     or     ! XRom.rom:&A
-binary:           
! XRom.rom:1010b  or     ! XRom.rom:&X1010

All these cammands make the same thing, they launch the emulator and load rom XRom.rom with the number 10.

CAUTION:
The other roms numbers used by the Cpc system are:
- 0 for BASIC rom
- 7 for DISC rom
The maximum value is 15.

Particular case:
The value 080h or 128 indicates to the emulator that it must load the bios rom.

note: Roms loading with 
|INPUT command will be reconize by the Cpc system only after a Cpc reboot, for example by a CALL 0 or by pressing on [CTRL][F10] keys in the same time.

- 1c - Loading intel hex files  -

Loading in rom:
Make follow the file name by ":X" marker where X represent the rom recipient
number.

example starting from the Dos command line:

!  hex.obj:10     for loading in rom number 10

notes:  - same remarks as for roms files
           - if the rom does not exist, CpcAlive create it.

Loading in ram:
Make follow the file name by ":X" marker where X represents
the ram recipient configuration type. The valid hexadecimal values for loading in RAM are:
0C0h, 0C1h, 0C2h, 0C3h, 0C4h, 0C5h, 0C6h and 0C7h

Table showing
ram blocks positioning in foncion of the configuration type:

                type      blocks positions
                0C0h          0,1,2,3
                0C1h          0,1,2,7
                0C2h          4,5,6,7
                0C3h          0,3,2,7
                0C4h          0,4,2,3
                0C5h          0,5,2,3
                0C6h          0,6,2,3
                0C7h          0,7,2,3

note: - By defect, the loading is done in RAM with
0C0h configuration.


- 1d - Loading command files

These files are intended, as their name indicates it, to command the emulator from a file. This file must start with
"CDE:" sequence without guillemets (header). A good example is the ROM.INI file which is a command file  intended for the emulator initialization. It is from this one that for example the Cpc roms are loaded. Each line is interpreted like commands starting from the Dos command line. Note the separator ';' for comments.

Internal orders available are detailed in chapter 2 except the two following orders which do not have no interest starting from
the Dos command line.

EndCde:         indicate the end of a command file.
Keyboard:      going from the COMMAND mode to the KEYBOARD mode.
                     After this order, the file will not be interpreted any more like a command file
                     but like a text file  (see chapter - 1e -)
                     (!do not use this command in the ROM.INI file.)

exemple 1:
CDE:
CpuSlow        ; speed selection
...                  ; etc... (see chapter 2 for the various orders available)
EndCde          ; close the command file

exemple 2:
CDE:
CpuSlow        ; speed selection
...                  ; etc... (see chapter 2 for the various orders available)
Keyboard       ; swap in keyboard mode
                     ;
(starting from here each character is transmitted directly to the Cpc keyboard manager)
PRINT"ok "
...

note: no "EndCde" here because after the
"Keyboard" order, the file is interpreted like a text file. (automatic Stop at file end and it is not possible to return in "command" mode - see below).


- 1e - Loading text files (KeyBoard simulation)

If the file type is not recognized by CpcAlive as being one of files detailed higher, CpcAlive considers that it is a text file. CpcAlive treats these files simply. Each character of the document is read and sent to the Cpc keyboard manager. You can thus transmit by this function a BASIC file in text format or pilot a software running into the emulator.

example starting from the Dos command line:
! exemple.bas

This order load the text named "exemple.bas" through the Cpc keyboard manager. This file must be in text format. In this example it must be in the CpcAlive directory or a path
directory. If the file does not exist, the chain "exemple.bas" will be transmitted to the Cpc keyboard manager and will probably emerge on a "Syntax error" message.

example starting from the Cpc BASIC interpreter:
mode 2
10 |Input,"FILE_ID.DIZ"
20 line input a$:if a$="" then |STOP:end else goto 20
run

This example load the document "FILE_ID.DIZ" until it meet one blank line. The order |STOP close the file.

note: A
text file opening close definitively the text file previously open if there were one.


- 2 - [command]
~~~~~~~~~~~~~~~
The intern emulator
valid orders starting from the Dos system command line (or from a CpcAlive command file - see chapter II paragraph - 1d -) are:

CpuFast                    ; maximum speed
CpuSlow                   ; normal speed (speed of the Cpc computer)
Sleep                        ;
emulator sleeping state [F11]
Exit                          ; to leave emulator [CTRL][F12]
ROM=X                   ; select ROM X
RAM=X                   ; select RAM X type
:LLAAAA00DDDD   ; intel hex line
                                ; for information: LL=block size, AAAA=
Starting adress, 00 always 00, DDDD=datas

example starting from the Dos command line:
! ROM=0 :01C38000FF CpuSlow

Select the BASIC rom and poke 255 in 0C380h adress (WIDTH 255) and select slow speed.
(Don't forget spaces between commands.)

notes:
- orders owe beings separated by a space.
- the crc normally present in intel hex standard is not obligatory here.
- poked in RAM blocks 0,1,2 ou 3 before the Cpc system
initialization is useless because this blocks are cleared with starting (except 0BE00h to 0BFFFh addresses). For poked in RAM from the Dos command line, the system could be launched and put in sleeping mode previously.
- CpcAlive forces the "WIDTH 255" with initialization in ROM.INI file.


- 3 - [Cpc command] = Cpc command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Cpc orders must always be placed at the last of the command line.

ex: ! PRINT"ok"
Launch the emulator and places the order PRINT"ok" through the Cpc keaboard manager.

Particular case:
The '|' character is a Dos command. CpcAlive uses thus a substitution character which is the '§' than you can obtained with the [ALT][245] keyboard sequence from the Dos command line. (If you obtain another character than '§' on your screen it is not important. The most important is the [ALT][245] keyboard sequence to obtain the ascii character number 245 in the Dos command line)

ex: ! §DISC
Launch the emulator and place the order |DISC in Cpc keyboard manager.

Note:
There are other reserved characters by Dos like ' < ' or ' > ' which can't be used for Cpc commands from the Dos command line. For more information read the Dos system documentation.

- 4 - [>output_file]
~~~~~~~~~~~~~~~~~~~~~
By defect the Cpc printing output is done in file CPC.PRN located in CpcAlive directory.
This order redirects this exit towards the output_file. The equivalent order starting from the Cpc interpreter is as follows:

|OUTPUT, "output_file"[,@er% ]

The error return parameter @er% is facultatif. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
1 = error in the parameters
3 = way not found
4 = no more handle available
5 = refused access
(don't forget to initialize er% at the beginning of the program or before the order)

example starting from the Dos command line:
! PRINT#8, "OK"                 register word "OK" in the file
Cpc.prn
! PRINT#8, "OK">test.prn    register word" OK "in the file test.prn

note: Only one character ' > ' before output_file indicates to the Dos system that if the output_file
name already exists, this file will be recreate virgin before receiving datas. (the old one output_file with the same name being delete without notice... warning).
Two characters ' > > ' before output_file indicates to the Dos system that it must preserve the file and put new datas to be followed. (There does not exist at time equivalent order starting from the Cpc BASIC interpreter)

example starting from the Dos command line:
! PRINT#8, "OK1":§Exit>test.prn         register word "OK1"in the file test.prn
! PRINT#8, "OK2":§Exit>>test.prn       register word "OK2"follow in the file test.prn

The result in the file test.prn gives:
OK1
OK2

A small program which redirect the CATalogue output towards the output file:
10 POKE &BB5C,PEEK(&BD2D):POKE &BB5B,PEEK(&BD2C)
20 CAT
30 CALL &BD37:|DISC
RUN

III - Commands  from the Cpc basic interpreter:

[CTRL][F10]             = réinit System Cpc (CALL 0)
|CpuFast                    = maximum speed
|CpuSlow                   = normal speed (speed of the Cpc computer)
|Sleep                        = emulator in sleeping mode [F11]
|Exit                          = to leave emulator [ CTRL][F12 ]
|INPUT, "[file_name[:X]]"[,@er% ]
                                 = see chapter II paragraph - 1 -
|STOP                       = see chapter II paragraph - 1e -
|GO, "chain"[,@er% ] = see chapter IV
|OUTPUT, "output_file"[,@er% ]
                                = see chapter II paragraph - 4 -
|OUTASCDOS          = see chapter V
|OUTASCWIN          = see chapter V
|OUTASCOFF           = see chapter V
|PRINT, "chains"       = output character string towards output_file.
                                   (Order equivalent to the order PRINT#8,"chains";)
|LPRINT, "chains"     = output character string towards output_file followed by a carriadge return.
                                   (Order equivalent to the order PRINT#8,"chains")
|OBMP, "nom_de_fichier"[,@er% ]
                                = manufactures a file image of the Cpc screen (
BMP format).
                                    - Mode 0 and Mode 1 only
                                    - see |OUTPUT command for
error codes significance.
|INK,PEN,R,G,B       = change PEN color. Letters R,G,B représents Red,Green and Blue values (0 to 255)
                                   ex: |INK,0,0,255,0 (change PAPER color)
                                   ex: |INK,1,255,0,0 (change PEN 1 color)
|INKRESTORE         = restore originals Cpc inks.



IV- ":D" Marker

The
":D" marker (D like 'D'atas) following the file name indicates to the emulator that it must transmit the value of each byte of the file through the Cpc keyboard manager in decimal format.This function as been developed to easily treat datas from a file with the Cpc BASIC interpreter.

Here, a small program whose function is reading some bytes of ROM.INI file and print them in hexadecimal format.
10 mode 2:window#0,1,80,2,25:window#1,1,80,1,1
20 |Input,"ROM.INI:D"
30 for i=0 to 100
40 input#1,a:Print hex$(a,2)" ";
50 next i
60 |STOP
run

The order |GO, "chain"[,@er% ] move the file pointer.
In this case, "chains" represent the value of displacement compared to the beginning of the file. The error return parameter @er% is facultatif. If it is put, the significance of the values recovered in the variable er% are:
0 = ok
1 = error
(don't forget to initialize er% at the program beginning or before the command)

example starting from the Cpc BASIC interpreter:
|GO,"&100"

Moves the file pointer to the position &100. The maximum value is &FFFFFFFF and can be write in decimal.


V -
ACCENTUED CHARACTERS

See French documentation

VI - UTILITY SOFTWARES

Only one utility software in that time: CreaDisc.bas create a virgin virtual diskette. (data formatted)

Order starting from the Dos command line:
! CreaDisc.bas>
diskette_name

Developer souls call
If  you have the idea to develop some freewares utilities or little demonstrations for CpcAlive, I would be enjoy to include them in next version. You can post them here: cpcalive@aol.com
You'ld be informed about new versions of CpcAlive. Thank you

VII - CPCALIVE
EVOLUTION

V1.07h   05/2005    - 262144 colors
                             - Adding |INK,PEN,R,G,B and |INKRESTORE orders
V1.07g   04/2005    - Adding .PIF files for Win9X DosBox configuration.
V1.07    04/2005     - Adding .PIF files for WinXP DosBox configuration.
V1.01 to V1.06       - corrections
V1.0      12/2004     - first diffusion

END