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

obj/commit - Commit object edit buffer to nexus

CONTENTS

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

obj/commit ![target], [name], buffer
obj/commit ![target], buffer
obj/commit [name], buffer
obj/commit buffer

obj/commit ![target], [name]
obj/commit [name]

obj/commitref write, ![target], [name], buffer
obj/commitref write, ![target], buffer
obj/commitref write, [name], buffer
obj/commitref write, buffer

obj/commitref write, ![target], [name]
obj/commitref write, [name]

Commits the add, delete and modify commands in an object edit buffer against a new or existing node in the nexus. The object edit buffer will have been previously created by obj_def(5), obj_edit(5) or obj_clone(5).

If this is a new node, the commands in the object edit buffer will be processed in the order that they appear. They are amalgamated into a single add node operation.

If this is an existing node, the add commands are performed against the target node first, followed by the delete commands and finally the modify commands. For each of the command types add, delete and modify, classes are processed first, then attributes, each of these in an undefined order. This approach is fixed and cannot be changed.

In the fifth and sixth synopsis forms, where no object edit buffer has been provided, creates a new empty node with no classes or attributes specified.

The obj/commit instruction takes the following arguments:

![target]
	An object reference (or register containing an object reference) identifying an existing node in the nexus. If supplied with the name argument (the first synopsis form above), this is used as the relative path under which the object will be created (instead of the default of PCTX). If supplied without the name argument (the second synopsis form), this identifies the object to which the changes will be committed.
[name]	The name of the node to commit the changes to. If the node does not already exist, it will be created. Unlike error/def, func/def and var/def, this must be a single nodename and cannot be a dot-path. If dots are found in the node name, they will become a part of the name. If supplied with the ![target] argument (the first synopsis form), the node will be created under the path provided by target. If supplied without the ![target] argument (the third synopsis form), the node will be created relative to PCTX.
buffer	An object edit buffer previously initialised by obj/def, obj/clone or obj/edit. If omitted an empty node will be created if it does not already exist.

If neither the ![target] nor [name] arguments are supplied (the fourth synopsis form), then the buffer is committed back to the originating object. This form is only legal if the edit buffer was created using obj/edit (see obj_edit(5)).

Upon a successful commit, the register containing the edit buffer will be cleared (PSUNIT_TYPE_NULL).

The obj/commitref instruction is identical to obj/commit except that a pointer to the new or modified node will be stored in the write register.

When adding attributes, if the attribute already exists an attempt will be made to insert an additional value. This requires that the attribute permits multiple values (defined by the schema). If this value is already assigned to the attribute, the request will be silently discarded.

When removing attributes, if only an attribute name has been supplied (via the attr/del instruction), then the entire attribute will be removed from the object regardless of how many values might be assigned to it. If an attribute name and value has been supplied (via the attr/mvdel instruction), then only that value will be removed. The attribute will remain associated with the object if it has additional values.

When modifying attributes, if only an attribute name and new value has been supplied (via the attr/mod instruction), then the entire attribute will be replaced with the new value overwriting all values that might already be assigned to it. If the attr/mvmod instruction was used then only the specified value will be replaced.

A runtime error is generated if an object referenced in a read argument does not exist, or is the wrong type.

An error will also occur if the commit operation 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.

Note that requests to remove classes or attributes, or modify attributes, that are defined in the schema but not assigned to the object will be silently discarded.

If used to create a new node, this instruction is fully atomic. The node will exist if no errors occurred creating it, otherwise it will not exist.

When modifying an existing node, this instruction is partially atomic. The add commands are processed atomically. If any add command fails then no changes are made to the target object. However, once the add commands have been processed, they will not be rolled back in the event of any further errors.

The del commands are processed next, and are not atomic. If the second del command fails there is no attempt to roll back the first delete.

The mod commands are processed atomically. If any mod command fails then none of the modify operations will result in the target object. However, no previous add or del commands will be rolled back in the event of a mod failure.

pal_commands(5), pal_registers(5), pal_indices(5), obj_def(5), obj_clone(5), obj_edit(5), obj_clear(5), class_add(5), class_del(5), attr_add(5), attr_del(5), attr_mod(5), attr_mvadd(5), attr_mvdel(5), attr_mvmod(5), error_def(5), func_def(5), var_def(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.