Andy Pennell's books.

A place to discuss general QL issues.
Derek_Stewart
Font of All Knowledge
Posts: 3900
Joined: Mon Dec 20, 2010 11:40 am
Location: Sunny Runcorn, Cheshire, UK

Re: Andy Pennell's books.

Post by Derek_Stewart »

Peter wrote:Many thanks Derek, looks like a lot of work.
Is ISBN 0-946408-649-6 on the back cover correct? On my paper version it is ISBN 0-946408-69-6
HI Peter,

Sorry, I made a error in the number.


Regards,

Derek
User avatar
pjw
QL Wafer Drive
Posts: 1280
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Re: Andy Pennell's books.

Post by pjw »

Looks great, Derek! Well done - and thank you!


Per
dont be happy. worry
- ?
Martin_Head
Aurora
Posts: 846
Joined: Tue Dec 17, 2013 1:17 pm

Re: Andy Pennell's books.

Post by Martin_Head »

Derek_Stewart wrote:HI,

Since I have had no comment from Andrew Pennell, with regards, to my efforts to to convert the QDOS-Companion from paper to electronic book, I have uploaded the LibreOffice ODT file and a PDF file to Github:

https://github.com/SinclairQL/QDOS-Companion

I would be grateful is someone can proof read the book and correct any errors from the original paper book.

Update of the book to cover later version of QDOS, can be done by the Github Fork process.
I have had a quick look through my copy of the book. And here is a list of my pencilled in comments/corrections.
Please confirm they are correct before using them.

Code: Select all

Page 6
SV.MDSTA, 0 = No pending operations

$28100	SV.FSDEF
$28140	SV.FSLST	long	Pointer to list of channel definitions
$28180	SV.STABC
$28480	SV.STACK
------------------------------------
Page 16
MT.ALLOC	On exit, don't trust the zero flag. Do a TST.L D0
------------------------------------
Page 35
Channels	I have a reference to page 155
------------------------------------
Page 41
FS.ACCES is byte sized
------------------------------------
Page 42
MS.MNAME	10 bytes of medium name + 2 byte random number
------------------------------------
Page 43
IO.OPEN		D2,D3 and A1 not preserved
------------------------------------
Page 58
$3A should be $3C
------------------------------------
Page 68
NET.TYPE	EOF = -1
------------------------------------
Page 106
MD.SELET
	$2B64(1.02) = AH
	$2370(1.03) = JM
	$2C56(1.10) = JS
	$2CD2(1.13) = MG
------------------------------------
Page 108
MD.DSEL
	$2B5E(1.02) = AH
	$2B6A(1.03) = JM
	$2C50(1.10) = JS
	$2CCC(1.13) = MG
------------------------------------
Page 136
CN.FTOD		A1 on exit  (old A1 + 6 or A1 + 2) 
------------------------------------
Page 137
CN.ITOBB	A1 on exit  (old A1 + 1 or + 2 or + 4)
------------------------------------
Page 153
CA.GTINT	Action: Last parameter on bottom of stack, and first on the top
------------------------------------
Page 157
BP.ABSIO	next trap #2, or #3
------------------------------------
Page 173
IO.NAME		D7 may be trashed
------------------------------------
Page 175
Channel Close	Entry A1 points to the Physical Definition block
------------------------------------
Page 184
Channel Open	A6 points to the base of the System Variables
------------------------------------
Page 185
Format		A1 Pointer to medium name
		D1 Number of medium to format e.g 3 = FLP3_
		A4 Pointer to Physical Definition Block
		A6 Pointer to System variables


Derek_Stewart
Font of All Knowledge
Posts: 3900
Joined: Mon Dec 20, 2010 11:40 am
Location: Sunny Runcorn, Cheshire, UK

Re: Andy Pennell's books.

Post by Derek_Stewart »

Hi,

I can make some updates to the Github file.

What is the validation process for the changes?

I do have some soldering jobs to do as well, so changes may not happen straight away.


Regards,

Derek
User avatar
janbredenbeek
Super Gold Card
Posts: 628
Joined: Wed Jan 21, 2015 4:54 pm
Location: Hilversum, The Netherlands

Re: Andy Pennell's books.

Post by janbredenbeek »

Some more corrections I have annotated:

Page 19, MT.CJOB:
On QDOS <1.1(AH,JM), when D2 = 0 then D1 may not be -1. Better avoid this by allocating a few bytes of code for a JMP instruction and $4AFB + job name. Also, if A1 <> 0 then on exit A0 = A1.

Page 98: A polled list routine MUST preserve register A5 (at least on QDOS ROMs).

Page 132:
RI.NINT and RI.NLINT round floating point value to nearest integer (not INT).
RI.INT does INT operation, not truncate.
RI.LINT should really be named RI.FLOAT?
(Compare with other QDOS documentation).


martyn_hill
Aurora
Posts: 908
Joined: Sat Oct 25, 2014 9:53 am

Re: Andy Pennell's books.

Post by martyn_hill »

Hi Derek!

Great effort, thank you. I do hope Mr Pennel and his Publisher are OK with it!

I'd like to offer the following set of corrections/additions to the NET Driver description on pages 68/69:

Code: Select all

CHAPTER 5 - Device Drivers

Device NET — the network

The network used in the QL and the ZX Spectrum is a simple two wire connection, allowing up to 64 machines to be interconnected. Data is sent over the net in ‘packets’ of up to 255 bytes of data, preceeded by an 8 byte header.

Before explaining the format, it is useful to examine the channel definition block format:

$18 NET.HEDR
$18 NET.DEST Byte destination station number (equivalent to nciris on the spectrum)
$19 NET.SELF Byte this station number
$1A NET.BLKL Byte LSB of data block number
$1B NET.BLKH Byte MSB of data block number (these are in reverse order because of the way words are stored for the z80 on the spectrum)
$1C NET.TYPE Byte packet type: *See below
$1D NET.NBYT Byte number of bytes in data block
$1E NET.DCHK Byte data checksum
$1F NET.HCHK Byte header checksum
$20 NET.DATA 255 bytes data block
$11F NET.RPNT Byte pointer to current position in data block
$120 NET.END End of channel definition block

The protocol acts in the following way. The sender listens to the network to wait until it isn’t being used by anyone else, and when the network is free, the sender transmits a SCOUT bit-pattern followed immediately by the eight bytes of header, from NET.HDR/DEST to NET.HCHK inclusive down the cable serially at a high rate. Unless the sender is broadcasting (i.e. sending to any listening machines, NET.DEST=$00), it tests to see if the receiving station transmits a byte of acknowledgement, which is always a '$01'.

If the acknowledgement byte is not received, then the sender repeats the whole process until successful or until it times out. If the sender was broadcasting, no checks are made for the acknowledgement, and the sender continues with the data packet. In either case, the next data packet is sent (which may not necessarily be the full 255 bytes) and another acknowledgement tested-for (again, unless broadcasting) — if it is not found then the whole process is re-tried. Network channels are single direction channels, the direction determined by the name, though any number of channels of input or output can be open at once.

* The direction is stored in NET.TYPE at $1C(a0) as:

$FE or $FF: output channel
$00 or $01: input channel (data or EOF packet)

On the wire however, NET.TYPE is always either $00 (normal data) or $01 (EOF packet)

Open routine:

After checking the parameters in the name, $120 bytes are claimed from the common heap for the channel definition. The host station number is then copied from SV.NETNR to NET.SELF, the destination copied from the device specifier to NET.DEST, NET.TYPE set to suit the direction ($FE/$FF or $00), and a return made.

Close routine:

If the channel is set for output, then NET.TYPE is set to show ‘EOF packet’, and NET.RPNT copied to NET.NBYT. The routine then waits for any microdrives that are turning to stop, so that the timing will not be upset by them. This final packet (typically less than the full 255 bytes) will then try to be sent, but if the attempt fails then it will be tried a further 1399 times, when the QL will give up (though the calling job will not know it was unsuccessful, as the routine does not cause an error return). If the transmission was successful (or unsuccessful 1400 times), the routine finishes by reclaiming the channel definition area from the common heap. If instead the channel was an input channel, the only action taken is for the definition block to be reclaimed.

For general I/O, the simple serial handler (SERIO) is used as follows.

The ‘pending input’ tests to see if the channel is an output channel, and if it is then the error return ‘bad parameter’ is made. Otherwise, if the current buffer is exhausted, then an attempt is made to read the next packet from the net, and the process repeats if successful. If the buffer is not empty, then NET.RPNT is compared with NET.NBYT, and, if it was an ‘EOF’ packet AND there are no more bytes to be read from the buffer an ‘EOF’ return is made.

For the ‘receive a byte’ routine, the ‘pending input’ routine is called and, if there was no error, the appropriate byte is read from the buffer and NET.RPNT incremented.

The ‘send byte’ routine checks that the channel is an output channel (otherwise ‘bad parameter’ occurs), and if so then NET.RPNT is incremented. If NET.RPNT reaches 256 (ie there is no room in the buffer) then the byte’s value is saved, NET.TYPE is temporarily set to $00 (i.e. not EOF), the packet is transmitted, and the byte value restored. In either case, the byte is placed in the appropriate position within the buffer, and then NET.RPNT updated. Finally, NET.TYPE is restored to $FF to maintain the 'output channel' status.

There is no trap to set the QL’s station number, and this is done simply by writing a byte of suitable value into SV.NETNR at $28037, between 1 and 64 inclusive.


Martin_Head
Aurora
Posts: 846
Joined: Tue Dec 17, 2013 1:17 pm

Re: Andy Pennell's books.

Post by Martin_Head »

I was wondering about if Toolkit II enhancements should be included in the book.

I left out a couple of things in my list, like Rename and Truncate. And the format of a level 2 file header.


User avatar
pjw
QL Wafer Drive
Posts: 1280
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Re: Andy Pennell's books.

Post by pjw »

It seems unfair to saddle Derek with all this! I thought the whole point of GitHub was that many different people could work on the same project without FUBAR. Cant everyone sort out their own corrections?
BTW1: Some of these corrections are going to mess up any page references! That should be taken into consideration. I dont know if Libre Office caters for "live" page references like M$ Orifice does..

BTW2: I only skimmed through the first few pages: P13 Supervisor stack: should be $28480 to $28180 (which, correctly, = $300)


Per
dont be happy. worry
- ?
Derek_Stewart
Font of All Knowledge
Posts: 3900
Joined: Mon Dec 20, 2010 11:40 am
Location: Sunny Runcorn, Cheshire, UK

Re: Andy Pennell's books.

Post by Derek_Stewart »

Hi,

Up to now, I do have a little spare time to update all the amendments to the book.

I just have work out how to use Github.

All the page references are generated by the use of linked Tables, Indexes so the amendments should change the TOC/Index references automatically.

The Trap and Vector Tables are Hyperlinked to the actual page, but the page number in the table is not linked. I tried to make a Index Table, but the resulting Index can only be sorted by Page Number, not Alphabetically sorted.

I do not have a licence to use Microsoft Office, so I only use Open Source software.

I will add the amendments entered and see where we go from there.


Regards,

Derek
martyn_hill
Aurora
Posts: 908
Joined: Sat Oct 25, 2014 9:53 am

Re: Andy Pennell's books.

Post by martyn_hill »

Hi Per and Derek!
pjw wrote:It seems unfair to saddle Derek with all this!
Quite right - I'm sure when Derek first solicited corrections/edits, he didn't foresee the additional effort involved!

@Derek - I'm happy to figure out how to submit changes via GitHub rather than leaning on your time and goodwill!

Fortunately, the page refs shouldn't change for the Net Driver edits I proposed...

Since validated those edits across JM, JS and Minerva.


Post Reply