Builder: ONEONLY segment qualifier

SPLat/PC V8.20.2 and later will recognize the alias ONCEONLY

If your program uses NVEM it needs to include a NVEM0 directive to tell SPLat/PC where your executable code ends and your NVEM stuff (tables etc) starts. However a complete program may only contain one single NVEM0 directive. If you have several modules (*.spt source files), each containing NVEM, that can be a bit awkward to arrange.

Builder allows you to designate a segment name that will only be used once in the whole build process. If segment name appears in the .b1d file with the qualifier word ONEONLY after it. the segment code will be taken from the first .spt file to contain it and be ignored in any other files containing that segment. The code will be located in the output file according to the segment name's position in the build file (c.f. ONCEINLINE.

Example:

Consider 2 source files, that are listed in the .b1d in the same order as below:

1st file, test1.spt -

;<CODESEG>
;	...
;		do some stuff in test1.spt
;	...
;<NVEM0DIR>	NVEM0 ;in test1.spt
;<NVEM0DATA>
Table1:		NV0Byte  1,2,3,4,5

2nd file, test2.spt -

;<CODESEG>
;	...
;		do some stuff in test2.spt
;	...
;<NVEM0DIR>
			NVEM0 ;in test2.spt
;the above line will not get to the final file as it falls in
;segment NVEM0DIR of the 2nd .spt file to contain it.
;<NVEM0DATA>
Table2:		NV0Byte  99,100,11,22,33

And the .b1d file:

CODESEG
NVEM0DIR ONEONLY
NVEM0DATA
#---
test1.spt
test2.spt

This will build to the following merged file:

;	...
;		do some stuff in test1.spt
;	...

;	...
;		do some stuff in test2.spt
;	...
	NVEM0 ;in test1.spt

Table1:		NV0Byte  1,2,3,4,5

Table2:		NV0Byte  99,100,11,22,33

You can see that only one of the NVEM0 lines has been used.

Exercise: What will happen if I swap the test1.spt and test2.spt lines in the .b1d file? Explain why the new resulting file has one more empty line in it. It's OK to try the files to see what happens.