A noob's guide to QL machine code

[Peter]

qlzip, qltools, mdvtool (I think), sQLux, Q-Emulator, QPC2 all support that to recreate the exe info inside QDOS.

Are you sure? Q-Emulator supporting the XTcc trailer would be new to me.
I had to write a program to translate from XTcc trailer to Q-Emulator header.

[XorA]

qlzip, qltools, mdvtool (I think), sQLux, Q-Emulator, QPC2 all support that to recreate the exe info inside QDOS.

Are you sure? Q-Emulator supporting the XTcc trailer would be new to me.
I had to write a program to translate from XTcc trailer to Q-Emulator header.

no!

[tofro]

What does "support" mean, after all, does anyone know?

Does it mean a proper header is re-created when a file containing an XTcc signature is copied to a QDOS file system? Or does it just create the data space when such a file is EXECed?

[stevepoole]

Hi Folks,
Here's one example of a 4-colour stipple , (out of 4012 max).

[Derek_Stewart]

Hi,

I think I will personally adopt the XTcc trailer method for storing executables programmes on non-QL filesystem.

The transfer of the executable file by the emulator into a QL file system container strips off the header or trailer.

SMSQmulator seems to allow both method, but not at same time.

There man sybe an issue with Spectrum Next QL core which the people who write the system may adopt a different method.

With all the said, back on topic, I will try to write assembler using vasm, rmac and run them on a QL or Q68

[NormanDunbar]

On the subject of XTcc trailers, in one of my eMagazines, I provided a utility to be run, in the QL or emulator, if required, to set a files executable bit and datasoce Suze to that in the trailer.

Might be useful to someone. I'm pretty sure the source code was included with the release.

Cheers,
Norm

[Derek_Stewart]

On the subject of XTcc trailers, in one of my eMagazines, I provided a utility to be run, in the QL or emulator, if required, to set a files executable bit and datasoce Suze to that in the trailer.

Might be useful to someone. I'm pretty sure the source code was included with the release.

Cheers,
Norm

I re--read Volume 6 of your excellent Assembly Language Magazine, concerning XTcc trailers.

An obvious question is if a programme ( or program ?) is written and cross compiled and a XTcc trailer is added. A QL emulator or QLTOOLs restores the executable header based on the XTcc trailer. What does QDOS/SMSQ/E call the Job?

[NormanDunbar]

An obvious question is if a programme ( or program ?) is written and cross compiled and a XTcc trailer is added. A QL emulator or QLTOOLs restores the executable header based on the XTcc trailer. What does QDOS/SMSQ/E call the Job?

I was taught that "programme" is what you watch on TV, while "program" is software.

To get to your real question, I honestly don't know! It's up to the programmer. All my utility does is open the file, check if it is executable, reads to the file size minus eight, reads the xtcc trailer, then sets the dataspace to the xtcc value and writes the header before closing the file.

It doesn't change whatever is in the job's actual code, so QDOS/SMSQ will call it what the programmer defined it as in the source code. The source should define a job header:

Code: Select all

Start
        jmp.l    jobStart
        dc.w    $4AFB
        dc.w    6
        dc.b    "My Job"
        
JobStart
        ....        

HTH

Cheers,
Norm.

[dilwyn]

Here's a small SuperBASIC program to restore executable file header for a program without one, where the program contains an XTcc file header. Shows how relatively easy it is to do.
The program asks for the filename of the headerless program, loads it into memory, check the first four of the trailing 8 bytes at the end for an XTcc field, followed by a long word dataspace value and then SEXEC's the program with a new filename to create a version with executable header. It can overwrite the original if you wish (with the usual TK2 "Overwrite Y/N?" prompt.
If the file has no XTcc field it will just tell you "No XTcc field found" and go back to the beginning to ask you to enter another filename.
Just press ENTER with nothing entered to quit.
No error trapping, to keep it simple.
Needs Toolkit 2 - uses ALCHP/RECHP/FLEN/FTYP/REPORT extensions. Should run in SuperBASIC or SBASIC (SBASIC includes those extensions).
EDIT: Just remembered Norman put a similar program on here a few years ago, probably much better than my humble effort - viewtopic.php?f=3&t=2606

Code: Select all

100 REMark XTcc field dataspace restorer
110 CLS : CLS #0
120 REPeat program
130   PRINT \'RESTORE DATASPACE TO FILE WITH XTcc FIELD'
140   INPUT  'Filename of program without executable header'\'> ';ip$
150   IF ip$ = '' THEN EXIT program
160   IF FTYP(\ip$) = 1 THEN
170     REMark existing file type
180     PRINT'Already an executable.'
190     PAUSE 100 : NEXT program
200   END IF
210   fl = FLEN(\ip$) : REMark file length
220   IF fl <= 8 THEN
230     PRINT'Not loaded.'
240     IF fl < 0 THEN REPORT #1,fl
250     PAUSE 100 : NEXT program
260   END IF
270   base = ALCHP(fl)
280   IF base < 0 THEN
290     REPORT #1,base
300     PAUSE 100 : NEXT program
310   END IF
320   LBYTES ip$,base
330   field = base+fl-8 : REMark if XTcc field at end of file
340   IF PEEK(field)=CODE("X") AND PEEK(field+1)=CODE("T") AND PEEK(field+2)=CODE("c") AND PEEK(field+3)=CODE('c') THEN
350     REMark XTcc field found
360     xtcc = PEEK_L(field+4)
370     PRINT'XTcc field value:';xtcc
380     INPUT"Save as filename > ";op$
390     IF op$ = '' THEN
400       REMark remove the evidence
410       RECHP base : NEXT program
420     END IF
430     SEXEC op$,base,fl,xtcc
440     PRINT op$!'saved.'
450     RECHP base : NEXT program
460   ELSE
470     PRINT'No XTcc field found.'
480   END IF
490   PRINT"Not saved." : RECHP base : PAUSE 100
500 END REPeat program
510 PRINT #0,'Program Finished.'
520 STOP

[dilwyn]

Taking things a little step further, here's a short SuperBASIC program to remove the native file format header from QemuLator files (and probably other emulator native files which use this format, but that's untested).

Appendix II of the QemuLator manual says that executable programs saved on a Windows native file format hard disk puts a preamble of 30 or 44 bytes at the start of the file, to hold the QDOS file header parts that Windows cannot store.

No idea if this applies to Mac versions of QemuLator sorry - never used it.

A preamble of 30 bytes indicates a standard QL executable program (i.e. something you can start with EXEC or similar commands). A preamble of 44 byte length indicates that this is an executable program, but with microdrive sector information (e.g. for protected MDV programs). My program does not try to handle this.

The reason I wrote this was that people keep sending me zipped programs which were zipped in Windows from the QemuLator directories direct using something like WinZip or 7-zip, rather than copying them to QDOS media such as floppy discs in the emulator first to automatically strip away these headers before zipping on QL. What happens when people then try to execute them is that they give the dreaded "bad parameter" error when they try to EXEC it, which is a dead giveaway for "no executable file header".

You can usually tell by viewing the file - it will have something like "]!QDOS File Header" (without the quotes) right at the beginning. Note that QPC2 versions 5 and later are special in this respect. They understand QemuLator file headers and all this is often unnecessary if QPC2 copies them to QDOS format media such as floppy discs, when it might remove the header by itself. But if I didn't spot this when the software was sent to me for my website (and QPC2 v5 and later which I use tends to hide it from us) the program goes on the website and is unusable by any system other than ones which understand QemuLator headered files.

If you have a QemuLator format executable and run it through this program, it'll turn it back into a QL format executable.

My program deqemu_bas needs Toolkit 2 - ALCHP, RECHP, FLEN, FTYP and REPORT. If the REPORT command causes problems on an early QDOS ROM version (I suspect it might on version AH or JM), replace it with something like PRINT"Oops, error occurred."

This is no different to other programs that do this, just that it's written in BASIC so that you can see how it works and adapt to your own needs (or fix any bugs I left in it, apologies if I did!).

Code: Select all

100 REMark DeQemu_bas (Remove QemuLator native header)
110 CLS : CLS #0
120 REPeat program
130   PRINT \'DE-QEMULATE EXECUTABLE FILE'
140   INPUT  'Filename QemuLator native program'\'> ';ip$
150   IF ip$ = ''THEN EXIT program
160   :
170   fl = FLEN(\ip$) : REMark file length
180   IF fl < 30 THEN
190     PRINT'Not loaded - unsuitable file.'
200     PAUSE 100 : NEXT program
210   END IF
220   :
230   base = ALCHP(fl)
240   IF base < 0 THEN
250     REPORT #1,base
260     PAUSE 100 : NEXT program
270   END IF
280   LBYTES ip$,base
290   :
300   qemu$ = ''
310   FOR a=base TO base+17:qemu$=qemu$&CHR$(PEEK(a))
320   IF NOT (qemu$ = ']!QDOS File Header') THEN
330     PRINT'Not a QemuLator native file.'
340     RECHP base : PAUSE 100 : NEXT program
350   END IF
360   :
370   IF PEEK(base+21) <> 1 THEN
380     PRINT'Not an executable file.'
390     RECHP base : PAUSE 100 : NEXT program
400   END IF
410   :
420   IF PEEK(base+19) = 44 THEN
430     PRINT 'Program contains microdrive sector header.'
440     PRINT 'Unsuitable for conversion without loss of this data.'
450     RECHP base : PAUSE 100 : NEXT program
460   END IF
470   :
480   INPUT 'Save as filename > ';op$
490   IF op$ = '' THEN RECHP base : NEXT program
500   :
510   dspace = PEEK_L(base+22) : REMark get dataspace
520   PRINT'Program length=';fl-30;' Dataspace=';dspace
530   SEXEC op$,base+30,fl-30,dspace
540   PRINT op$!"saved."
550   RECHP base
560 END REPeat program
570 PRINT'Program finished.'