Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

reg/load() - Iterate a data segment

CONTENTS

Synopsis
Description
Indirect Addressing
Examples
See Also
Author

reg/load write, (&[~dataptr])
reg/load write, (readseg)
reg/load write, (readseg, #index)

reg/load write, (&[~dataptr], #index)

A data segment, created using the PAL data entry macros, stores its data in the order in which the arguments were provided to those macros. Each data entry argument can be extracted, in sequence, using the reg/load indirect addressing functionality.

First a data segment read structure is initialised. Then successive calls can be made to read consecutive data values or specific index positions. Finally use reg/clr to clear the read structure and release memory associated with it.

In the first synopsis form above a data segment read structure is initialised. This structure describes the position within a data segment and is returned in the write argument (type PSUNIT_TYPE_READSEG).

In the second synopsis form, returns in the write argument the next data item in the segment. The readseg argument is a pointer to an initialised data segment read structure.

In the third synopsis form, a specific data entry value can be requested using the raw index number index. The first data item in the segment is identified by #0, the next is #1 and so on. Note that reading values backwards in a data segment is inefficient and should be avoided if possible.

In the fourth synopsis form an index is supplied with a dataptr. No data segment read structure is required, instead a single lookup is performed. This form is only efficient if only a single data item is being read, as a new read structure will be created and destroyed silently in the background in order to serve the request.

If an attempt is made to read beyond the end of a data segment, a NULL value is returned in the write argument.

Using parentheses ( ) with the reg/load instruction invokes the indirect addressing behaviour described above when the initialisation command is provided with a pointer to a data segment.

See the reg_load(5) manual page for a description of other functionality available with this command.

The following example dumps the data values provided in a data segment.

~data   EQUS {[text item 1], [text item 2]} EQUB {1, 3, 5, 7, 9} EQUS {[text item 3], [text item 4]} .main   % Initialise a data segment read structure reg/load P0, (&[~data]) .loop   % Read next data item reg/load P1, (P0) % Break out of loop if end of data reached reg/jmpeq &[.loop_end], P1, NULL % Debug item and continue loop obj/dump P1 local/jmp &[.loop] .loop_end   % Tidy up and exit reg/clr P0 func/rtn

pal_commands(5), pal_registers(5), pal_indices(5), pal_macros(5), reg_load(5), reg_clr(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2009 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.