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

attr/copy - Copy attribute values

CONTENTS

Synopsis
Description
Indirect Addressing
Encoded Values
Exporting Values
Error Handling
Examples
See Also
Author

attr/copy write, ![object], attribute
attr/copy write, (![object], attribute)
attr/copy write, (readval)

attr/xcopy write, ![object], attribute
attr/xcopy write, (![object], attribute)
attr/xcopy write, (readval)

attr/export write, ![object], attribute
attr/export write, ![object], attribute, #size
attr/export write, (![object], attribute)
attr/export write, (![object], attribute, #size)
attr/export write, (readval)
attr/export write, (readval, #size)

attr/export write, xvalue
attr/export write, xvalue, #size

In the first synopsis form, copies the value from the specified attribute assigned to the named object, storing the result as a new string structure (PSUNIT_TYPE_STRING) in the write register. This is a new memory structure that can be released using reg/clr.

The attribute argument may be the text name of the attribute, or a register pointing to the attribute definition obtained using attr/load (the register will hold the type PSUNIT_TYPE_ATTRDEF).

Note that it is not possible to read an attribute value without taking a unique copy, and it is therefore imperative that if the new string structure returned is no longer required it is cleaned up with the reg/clr instruction.

If the attribute has more than one value associated with it, a NULL will be returned in the write argument instead. In this case, you must use the indirect addressing forms to read the attribute values.

If your intention is to read attribute values so that they may be written to other attributes or objects, consider using the attr/direct or obj/clone instructions instead, which may be more suited to your needs and will be a generally more efficient way of copying attributes around.

To convert an XVALUE into a new byte string, use reg/copy instead. If the XVALUE is required in binary format, use attr/export as described in EXPORTING VALUES below.

In the second and third synopsis forms, the attr/copy instruction can be used with indirect addressing to copy multiple values from an object attribute.

First a read structure is initialised when the second argument is the object to read and the third argument is the attribute identified by text name or register of type PSUNIT_TYPE_ATTRDEF. The write register will now hold an attribute value read structure (type PSUNIT_TYPE_READVAL).

The read structure is then given as the readval argument in successive calls. Each call to attr/copy with readval will return the next value in the write register, as a unique byte string copy (type PSUNIT_TYPE_STRING). Note that when the string copy is no longer required, it must be released using the reg/clr instruction.

Finally use reg/clr to clear the read value structure and release memory associated with it.

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

The attr/xcopy instructions are identical to their attr/copy counterparts except that the resulting data will be an encoded attribute value represented by the type PSUNIT_TYPE_XVALUE, rather than a byte string representation.

The attr/export instructions are identical to their attr/copy counterparts except that the resulting data will be exported in binary format to a PSUNIT_TYPE_STRING. Binary data exported in this way is suitable for subsequent re-importing with attr/import.

The optional size argument fixes the size of the exported data in bytes and may be a register of type PSUNIT_TYPE_RAWIDX or a psInteger stored inside a PSUNIT_TYPE_XVALUE. If the exported data would have been more than size bytes then a runtime error is generated. If the data would have been less than size bytes it is padded appropriately. The way the data is padded suits the type of data encoding, for example a psString is padded at the end with null bytes whereas a psIndex and psInteger is always exported as big endian and padded at the front with null bytes. The psInteger type will also have an extra byte prepended indicating the sign of the number, where 0 is a positive integer and 255 is a negative integer.

In the last two synopsis forms the encoded attribute value contained within the supplied xvalue will be exported to a byte string representation.

A runtime error is generated if a named attribute does not exist in the schema or is not assigned to the object, a referenced object does not exist in the nexus, an argument provided is the wrong type or if attr/export is used and the length of the exported data would exceed the number of bytes specified in the size argument.

The following demonstrates iterating attribute values. This example assumes that the current context object contains multiple "author" values:

.main   % Initialise the read structure attr/copy P0, (PCTX, [author]) .loop   % Read the next value attr/copy P1, (P0) % Exit loop if no values remain reg/jmpeq &[.loop_end], P1, NULL % Dump the value obj/dump P1 % Release the byte string! reg/clr P1 % Continue next iteration local/jmp &[.loop] .loop_end   % Release the read structure and return reg/clr P0 func/rtn

pal_commands(5), pal_registers(5), pal_indices(5), ps_attributes(5), attr_def(5), attr_index(5), attr_direct(5), attr_import(5), obj_clone(5), attr_load(5), reg_clr(5), reg_copy(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2018 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.