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

attr/mod - Modify attribute directly or via edit buffer

CONTENTS

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

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

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

In the first synopsis form, performs a direct edit, modifying the attribute assigned to the specified object, replacing it with the given value.

In the second synopsis form, inserts attribute modify 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 will be modified with the specified values.

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 modify, or a PSUNIT_TYPE_ATTRDEF register returned by the attr/load instruction.

The value is an argument containing the new data to assign to the attribute. Any old data assigned to the attribute will be removed. 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.

All attribute values will be overwritten regardless of how many values may be assigned to it. To replace specific attribute values in a multi-valued attribute, use the attr/mvmod instruction instead (see attr_mvmod(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, if a referenced object does not exist in the nexus, or if the attribute to be modified has not previously been assigned to the object.

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 modified, and any one of the modify operations fail, then none of the attributes will be modified.

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/mod, 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 modifying multiple attributes in a nexus object:

.main   % Edit an existing node obj/def P0, ![BookStore] % Modify a list of attributes attr/mod 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_add(5), attr_del(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.