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

attr/add - Add attribute to object or edit buffer

CONTENTS

Synopsis
Description
Multi-value Attributes
List Sequences
Error Handling
Atomicity
Examples
See Also
Author

attr/add ![object], attribute, value <, attribute, value ... >

attr/add buffer, attribute, value <, attribute, value ... >

In the first synopsis form, performs a direct edit, assigning attribute and value to the specified object.

In the second synopsis form, inserts attribute add instructions to an object edit buffer. When the buffer is committed against a nexus object using obj/commit, the instructions are processed and the specified list of attributes and values will be assigned to the object.

The object edit buffer identified by the buffer argument will have been previously initialised by obj/def, obj/clone or obj/edit.

One or more pairs of attribute and value arguments may be provided.

The attribute is either a text argument containing the name of the object attribute to add, or a PSUNIT_TYPE_ATTRDEF register returned by the attr/load instruction.

The value is an argument containing the data to add to the attribute. If value is a register containing the type PSUNIT_TYPE_STRING, PSUNIT_TYPE_XVALUE or PSUNIT_TYPE_LIST and the instruction does not generate an error, then the register will be cleared as the data is now referenced elsewhere.

If value is encoded data (PSUNIT_TYPE_XVALUE) and the data encoding is not of an appropriate syntax to be stored directly in the selected attribute, then it will be re-encoded as a byte string before processing.

To add multiple values to a single attribute, it is more efficient to use the attr/mvadd instruction instead (see attr_mvadd(5)).

If value is a list sequence provided via @[ ... ] notation and the list contained registers of type PSUNIT_TYPE_STRING or PSUNIT_TYPE_XVALUE, then upon successful completion of this instruction the source registers will be cleared as the data is now referenced elsewhere.

A runtime error is generated if an argument is of the wrong type, if a named attribute does not exist in the schema, or if a referenced object does not exist in the nexus.

An error will also occur if a direct edit would break the schema. At this time schema checking is limited to testing for the SINGLE-VALUE parameter, i.e. if an attempt is made to add a second value to an attribute that does not permit multiple values.

This instruction is atomic. If multiple attributes are being added, and any one of the add operations fail, then none of the attributes will be added.

This atomicity does not extend to stack operations, so if you used the PULL register to pull an item off the program stack, it won’t be pushed back onto the stack in the event of an error. This has the potential of leaving your stack in an unknown state if an error occurs. You can alleviate this problem by using stack/lock prior to attr/add, and stack/flush in the error handler.

This atomicity also does not extend to virtual attributes, which are not possible to roll back in the event of an error. Furthermore if multiple virtual attributes are provided in a single instruction, and more than one of them suffers an error condition, only the first of those errors will be reported.

The following demonstrates the use of an edit buffer for adding multiple attributes to a nexus object:

.main   % Edit an existing node obj/edit P0, ![BookStore] % Add a list of attributes attr/add P0, [name], [Oliver Twist], [author], [Charles Dickens] % Commit changes obj/commit P0

pal_commands(5), pal_registers(5), pal_indices(5), obj_def(5), obj_clone(5), obj_edit(5), obj_commit(5), attr_del(5), attr_mod(5), attr_mvadd(5), attr_mvdel(5), attr_mvmod(5), attr_load(5), ps_attributes(5), stack_lock(5), stack_flush(5),
PROSE Assembly Language at prose.sourceforge.net.

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