So why shall I use this SUBs instead of simply coding my offset symbols as CONSTs with the offsets given as literals? Because if you add/remove entries in your structure or changing the size of an existing entry, then you must manually adjust all following offsets too. This is annoying and may cause errors by miscalculations. With these SUBs you can do any required changes and all following offsets are adjusted automatically.
Example of usage: (a simple structure) -------------------------------------- DefSTRUCTURE MyStruct&, 0& DefULONG ms_1stLong& DefULONG ms_2ndLong& DefBYTE ms_SignedByte& ALIGNWORD DefUWORD ms_UnsignedWord& DefLABEL MyStruct_SizeOf& and again with explaination: ---------------------------- DefSTRUCTURE MyStruct&, 0& 'this SUB does init a structure type, optional with start offset 'set the variable MyStruct& = zero (always) 'init the offset counter to given start offset (here zero) DefULONG ms_1stLong& 'this SUB creates a 4-byte entry 'set the variable ms_1stLong& = offset counter (is zero from the init above) 'increment the offset counter by 4 for the next entry DefULONG ms_2ndLong& 'the same SUB again to create another 4-byte entry 'set the variable ms_2ndLong& = offset counter (now 4 from last increment) 'increment the offset counter by 4 for the next entry DefBYTE ms_SignedByte& 'this SUB creates a 1-byte entry 'set the variable ms_SignedByte& = offset counter (now 8 from last increment) 'increment the offset counter by 1 for the next entry 'offset counter is now 9, which would be Ok for another BYTE entry, but is not a nice value for WORD, LONG etc. entries ALIGNWORD 'this SUB aligns the offset counter to (next) WORD boundary (here 10) 'if the offset counter is already on such a boundary, then this SUB does nothing, otherwise the next boundary will be calculated DefUWORD ms_UnsignedWord& 'this SUB creates a 2-byte entry 'set the variable ms_UnsignedWord& = offset counter (now 10 from alignment) 'increment the offset counter by 2 for the next entry DefLABEL MyStruct_SizeOf& '(here) this SUB is used to finish the actual structure 'set the variable MyStruct_SizeOf& = offset counter (now 12 from last increment, this is the size required for this structure, use it to allocate storage space via the FUNCTIONs in memory.bm) 'this SUB does not increment the offset counter
Another Example: (a structure incorporating the structure MyStruct& twice (at the beginning and in the middle), also it shall have a union) ----------------------------------------------------------------------------- DefSTRUCTURE BigStruct&, MyStruct_SizeOf& DefLONG bs_SigLong& DefLABEL bs_UniEnt1& DefWORD bs_UniEnt2& DefWORD bs_SigWord& DefSTRUCT bs_MyStruct&, MyStruct_SizeOf& DefULONG bs_USigLong1& DefULONG bs_USigLong2& DefLABEL BigStruct_SizeOf& and once again with explaination: --------------------------------- DefSTRUCTURE BigStruct&, MyStruct_SizeOf& 'again this SUB does init the structure, here with a start offset, which is the size required for the structure MyStruct& defined above) 'set the variable BigStruct& = zero (always) 'init the offset counter to given start offset (here MyStruct_SizeOf& (12)) 'so now we have space for MyStruct& at the beginning of BigStruct& DefLONG bs_SigLong& 'this SUB creates a 4-byte entry again 'set the variable bs_SigLong& = offset counter (is 12 from the init above) 'increment the offset counter by 4 for the next entry DefLABEL bs_UniEnt1& '(here) this SUB is used to define the first label of a union 'set the variable bs_UniEnt1& = offset counter (now 16 from last increment) 'this SUB does not increment the offset counter DefWORD bs_UniEnt2& 'this SUB creates a 2-byte entry again 'set the variable bs_UniEnt2& = offset counter (still 16, as DefLABEL didn't increment) 'increment the offset counter by 2 for the next entry 'so now bs_UniEnt1& and bs_UniEnt2& have the same offset (union), as the last union entry was defined as a WORD, this size is also mandatory for the first union entry DefWORD bs_SigWord& 'this SUB creates another 2-byte entry 'set the variable bs_SigWord& = offset counter (now 18 from last increment) 'increment the offset counter by 2 for the next entry DefSTRUCT bs_MyStruct&, MyStruct_SizeOf& 'this SUB is used to incorporate another complete structure 'set the variable bs_MyStruct& = offset counter (now 20 from last increment) 'increment the offset counter by the size of the incorporated structure (12) 'so now we have space for MyStruct& in the middle of BigStruct& DefULONG bs_USigLong1& 'this SUB creates a 4-byte entry again 'set the variable bs_USigLong1& = offset counter (now 32 from last DefSTRUCT increment) 'increment the offset counter by 4 for the next entry DefULONG bs_USigLong2& 'the same SUB again to create another 4-byte entry 'set the variable bs_USigLong2& = offset counter (now 36 from last increment) 'increment the offset counter by 4 for the next entry DefLABEL BigStruct_SizeOf& '(here) the SUB DefLABEL is used again to finish the actual structure 'set the variable BigStruct_SizeOf& = offset counter (now 40 from last increment, this is the size required for this structure, use it to allocate storage space via the FUNCTIONs in memory.bm) 'this SUB does not increment the offset counter To access the entries in the first incorporated MyStruct& you would simply use the defined ms_... offsets itself or BigStruct& + ms_..., the entries in the second MyStruct& you can access using bs_MyStruct& + ms_... as offsets. For an overview of all available DefXXX SUBs just take a look into types.bm, you will quickly see how easy the system works and then you can also add types for your own needs. Back to Types Overview