qdosmsq:traps:trap_1:lthg

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
qdosmsq:traps:trap_1:lthg [2010/09/20 16:11]
george.gwilt TH_CHECK and a fuller explanation of linkage block added
qdosmsq:traps:trap_1:lthg [2010/11/06 11:20] (current)
george.gwilt Added links to other thing Traps
Line 1: Line 1:
 +====== SMS_LTHG ======
 +
 +This trap links in a new Thing.
 +
 +^Call Parameters^^Return Parameters^^
 +|D0.B|$26|D0.L|Error code.|
 +|A1.L|Address of Thing linkage |A0.L|Preserved.|
 +
 +===== Errors =====
 +
 +|ERR_EX|Name already exists.|
 +
 +
 +
 +===== Notes =====
 +  * None of the "Thing" Traps work with Qdos or SMSQE. However, if the HOTKEY system v 2.03 and beyond is available vectors are provided to enable the thing system to be used. SMSQE contains an appropriate  HOTKEY system. See below.
 +  * All registers not shown above are not used on entry and are preserved on exit.
 +  * The linkage block, shown below, should have TH_THING, TH_FREE, TH_FFREE, TH_REMOV, TH_VERID, TH_NSHAR and TH_NAME filled in.
 +  * The space for the linkage block should be in the common heap and should be the first, or only, item in that allocated space.
 +=== Thing Linkage Block ===
 +^Name^Address^Length^Item^
 +|TH_NXTTH|$00|long|pointer to next linkage block|
 +|TH_USAGE|$04|long|usage list|
 +|TH_FRFRE|$08|long|code to force remove a Thing|
 +|TH_FRZAP|$0C|long|code when Thing owner is removed|
 +|TH_THING|$10|long|pointer to Thing itself|
 +|TH_USE|$14|long|code to use the Thing or 0|
 +|TH_FREE|$18|long|code to free the Thing or 0|
 +|TH_FFREE|$1C|long|code to force free the Thing or 0|
 +|TH_REMOV|$20|long|code to tidy up before removing a Thing or 0|
 +|TH_NSHAR|$24|byte|set if Thing not shareable|
 +|TH_CHECK|$25|byte|check byte of name - set by LTHG|
 +|TH_VERID|$26|long|version ID eg "1.03"|
 +|TH_NAME|$2A|string|name of Thing|
 +=== THING Thing ===
 +The Thing called THING allows, via HOTKEY (v 2.03 +), use of things.
 +The THING thing is:
 +^Name^Address^Length^Item^
 +|THH_FLAG|$00|long|"THG%"|
 +|THH_TYPE|$04|long|-1|
 +|THH_ENTR|$08|long|address of TH_ENTRY routine|
 +|THH_EXEC|$0C|long|address of TH_EXEC routine|
 +=== TH_ENTRY ===
 +This vector gives the same result as the Trap #1 thing routines with codes $26 to $2C. The parameters to be used are exactly as for the Traps. The routines, apart from this one, are:
 +  *[[rthg|SMS_RTHG]]
 +  *[[uthg|SMS_UTHG]]
 +  *[[fthg|SMS_FTHG]]
 +  *[[zthg|SMS_ZTHG]]
 +  *[[nthg|SMS_NTHG]]
 +  *[[nthu|SMS_NTHU]]
 +=== TH_EXEC ===
 +The vector TH_EXEC allows an executable thing to be called. At entry D0 holds the owner ID, 0 or -1. The MSW of D2 contains the priority of the job to be executed and the LSW the timeout. A0 points to the thing name and A1 to the parameter string.
 +
 +
 +
 +
 +
 +===== Examples =====
 +The first example shows how to get one of the vectors.
 +
 +<code>
 +* Routine to get Thing Vector to A4
 +
 +; On entry D0.W = 8 for THH_ENTR and $0C for THH_EXEC.
 +; On a successful exit A4 contains the vector.
 +
 +vecr reg d1-3/d7/a0
 +gu_thvec
 + movem.l vecr,-(sp) ; Save registers
 + move.w d0,d3 ; Keep parameter in D3
 + moveq #mt_inf,d0 ; Get address . .
 + trap #1 ; . . of SYS_VARS
 + move sr,d7 ; Keep condition codes
 + trap #0 ; To supervisor mode
 + move.l sv_thingl(a0),d1 ; address of Thing list . .
 + beq not_there ---->
 + movea.l d1,a0 ; . . to A0
 +thvec_lp
 + move.l (a0),d1 ; Last linkage block? . .
 + beq found ; . . yes
 + movea.l d1,a0 ; try the . .
 + bra thvec_lp ; . . next one
 +*
 +not_there
 +  moveq #-7,d0 ; ERROR Not found
 + bra th_rt
 +*
 +found movea.l $10(a0),a0 ; Pointer to THING Thing
 + cmpi.l #-1,4(a0) ; THING? . .
 + bne not_there ----> ; . . NO!
 + movea.l (a0,d3.w),a4 ; Get the vector to A4
 +th_rt move d7,sr ; Back to user mode
 + movem.l (sp)+,vecr ; Replace registers
 + tst.l d0 ; Set condition codes
 + rts
 +</code>
 +
 +The second example shows an executable program being linked in. Note that the routine SMS_LTHG assumes that the linkage block is the first item in a block of allocated space and places the address of the linkage block 12 bytes earlier than its start assuming it to be the header of allocated space. To allow that to happen sixteen zero bytes are placed at PSEUDO just before that linkage block.
 +<code>
 +
 +SET_THING
 + LEA TLINK,A1 ; address of linkage block
 + LEA N_THING,A0 ; address of Thing itself
 + MOVE.L A0,$10(A1) ; set address of Thing in linkage
 + MOVEQ #8,D0 ; THH_ENTR
 + BSR GU_THVEC ; Get the vector
 + BNE OOPS_1 ---->
 + MOVEQ #$SMS_LTHG,D0 ; $26
 + JSR (A4) ; Link in the Thing
 + TST.L D0
 +OOPS_1 RTS
 +; This is the NET_PEEK Thing
 +
 +N_THING DC.L "THG%",1 ; Type is 1 = executable code
 + DC.L HEADZ-N_THING ; -> Start of header
 + DC.L PRS-HEADZ ; Size of header
 + DC.L D_SPACE ; Data space
 + DC.L STARTA-N_THING ; -> Start of program
 +
 +; This is the linkage block
 +
 +PSEUDO  DC.L    0,0,0,        ; pseudo allocated space header
 +
 +TLINK DCB.W 19,0 ; All zero until . .
 + DC.L "1.00" ; . . Version
 + DC.W    8 ; Length of name
 + DC.B    "NET_PEEK" ; name
 + DS.W 0 ; To even boundary
 +
 +
 +</code>
 +
  
  • qdosmsq/traps/trap_1/lthg.txt
  • Last modified: 2010/11/06 11:20
  • by george.gwilt