Spectrum ROM: Routine at 2C02

The address of this routine is found in the parameter table.

This routine establishes new arrays in the variables area. The routine starts by searching the existing variables area to determine whether there is an existing array with the same name. If such an array is found then it is 'reclaimed' before the new array is established.

A new array will have all its elements set to zero if it is a numeric array, or to 'spaces' if it is an array of strings.

The address of this routine is found in the parameter table. This routine establishes new arrays in the variables area. The routine starts by searching the existing variables area to determine whether there is an existing array with the same name. If such an array is found then it is 'reclaimed' before the new array is established. A new array will have all its elements set to zero if it is a numeric array, or to 'spaces' if it is an array of strings.
DIM	2C02	CALL LOOK_VARS	Search the variables area.
D_RPORT_C	2C05	JP NZ,REPORT_C	Give report C as there has been an error.
	2C08	CALL SYNTAX_Z	Jump forward if in 'run time'.
	2C0B	JR NZ,D_RUN	Jump forward if in 'run time'.
	2C0D	RES 6,C	Test the syntax for string arrays as if they were numeric.
	2C0F	CALL STK_VAR	Check the syntax of the parenthesised expression.
	2C12	CALL CHECK_END	Move on to consider the next statement as the syntax was satisfactory.
An 'existing array' is reclaimed.
D_RUN	2C15	JR C,D_LETTER	Jump forward if there is no 'existing array'.
	2C17	PUSH BC	Save the discriminator byte.
	2C18	CALL NEXT_ONE	Find the start of the next variable.
	2C1B	CALL RECLAIM_2	Reclaim the 'existing array'.
	2C1E	POP BC	Restore the discriminator byte.
The initial parameters of the new array are found.
D_LETTER	2C1F	SET 7,C	Set bit 7 in the discriminator byte.
	2C21	LD B,$00	Make the dimension counter zero.
	2C23	PUSH BC	Save the counter and the discriminator byte.
	2C24	LD HL,$0001	The HL register pair is to hold the size of the elements in the array: '1' for a string array, '5' for a numeric array.
	2C27	BIT 6,C
	2C29	JR NZ,D_SIZE
	2C2B	LD L,$05
D_SIZE	2C2D	EX DE,HL	Element size to DE.
The following loop is accessed for each dimension that is specified in the parenthesised expression of the DIM statement. The total number of bytes required for the elements of the array is built up in the DE register pair.
D_NO_LOOP	2C2E	RST $20	Advance CH-ADD on each pass.
	2C2F	LD H,$FF	Set a 'limit value'.
	2C31	CALL INT_EXP1	Evaluate a parameter.
	2C34	JP C,REPORT_3	Give an error if 'out of range'.
	2C37	POP HL	Fetch the dimension counter and the discriminator byte.
	2C38	PUSH BC	Save the parameter on each pass through the loop.
	2C39	INC H	Increase the dimension counter on each pass also.
	2C3A	PUSH HL	Restack the dimension counter and the discriminator byte.
	2C3B	LD H,B	The parameter is moved to the HL register pair.
	2C3C	LD L,C	The parameter is moved to the HL register pair.
	2C3D	CALL GET_HLxDE	The byte total is built up in HL and then transferred to DE.
	2C40	EX DE,HL
	2C41	RST $18	Get the present character and go around the loop again if there is another dimension.
	2C42	CP ","
	2C44	JR Z,D_NO_LOOP
At this point the DE register pair indicates the number of bytes required for the elements of the new array and the size of each dimension is stacked, on the machine stack. Now check that there is indeed a closing bracket to the parenthesised expression.
	2C46	CP ")"	Is it a ')'?
	2C48	JR NZ,D_RPORT_C	Jump back if not so.
	2C4A	RST $20	Advance CH-ADD past it.
Allowance is now made for the dimension sizes.
	2C4B	POP BC	Fetch the dimension counter and the discriminator byte.
	2C4C	LD A,C	Pass the discriminator byte to the A register for later.
	2C4D	LD L,B	Move the counter to L.
	2C4E	LD H,$00	Clear the H register.
	2C50	INC HL	Increase the dimension counter by two and double the result and form the correct overall length for the variable by adding the element byte total.
	2C51	INC HL
	2C52	ADD HL,HL
	2C53	ADD HL,DE
	2C54	JP C,REPORT_4	Give the report 'Out of memory' if required.
	2C57	PUSH DE	Save the element byte total.
	2C58	PUSH BC	Save the dimension counter and the discriminator byte.
	2C59	PUSH HL	Save the overall length also.
	2C5A	LD B,H	Move the overall length to BC.
	2C5B	LD C,L	Move the overall length to BC.
The required amount of room is made available for the new array at the end of the variables area.
	2C5C	LD HL,($5C59)	Make the HL register pair point to the '+80-byte' (E-LINE-1).
	2C5F	DEC HL
	2C60	CALL MAKE_ROOM	The room is made available.
	2C63	INC HL	HL is made to point to the first new location.
The parameters are now entered.
	2C64	LD (HL),A	The letter, suitably marked, is entered first.
	2C65	POP BC	The overall length is fetched and decreased by '3'.
	2C66	DEC BC
	2C67	DEC BC
	2C68	DEC BC
	2C69	INC HL	Advance HL.
	2C6A	LD (HL),C	Enter the low length.
	2C6B	INC HL	Advance HL.
	2C6C	LD (HL),B	Enter the high length.
	2C6D	POP BC	Fetch the dimension counter.
	2C6E	LD A,B	Move it to the A register.
	2C6F	INC HL	Advance HL.
	2C70	LD (HL),A	Enter the dimension count.
The elements of the new array are now 'cleared'.
	2C71	LD H,D	HL is made to point to the last location of the array and DE to the location before that one.
	2C72	LD L,E
	2C73	DEC DE
	2C74	LD (HL),$00	Enter a zero into the last location but overwrite it with 'space' if dealing with an array of strings.
	2C76	BIT 6,C
	2C78	JR Z,DIM_CLEAR
	2C7A	LD (HL)," "
DIM_CLEAR	2C7C	POP BC	Fetch the element byte total.
	2C7D	LDDR	Clear the array + one extra location.
The 'dimension sizes' are now entered.
DIM_SIZES	2C7F	POP BC	Get a dimension size.
	2C80	LD (HL),B	Enter the high byte.
	2C81	DEC HL	Back one.
	2C82	LD (HL),C	Enter the low byte.
	2C83	DEC HL	Back one.
	2C84	DEC A	Decrease the dimension counter.
	2C85	JR NZ,DIM_SIZES	Repeat the operation until all the dimensions have been considered; then return.
	2C87	RET