{
{ Permits a user to perform a series of updates to an AAM file, and yet
{ retain the power, until the series is complete, to undo all the updates
{ in the series that have been done so far.  Such a series of updates is
{ called a parcel.  Parcels, at the AAM level, may only be used when the
{ NOS/VE file attribute LOGGING_OPTIONS includes AMC$ENABLE_PARCELS.
{
{ AMP$BEGIN_FILE_PARCEL initiates a parcel, which concerns a specified
{ instance of FSP$OPEN_FILE.  All updates to that instance of open that
{ occur after the BEGIN and before a corresponding parcel COMMIT or ABORT
{ constitute a parcel.  An update during a parcel has the effect of locking
{ the updated record so that no other instance of open can access it until
{ the parcel is terminated.  If the update is a delete, then it is the key
{ rather than the vanished record that is locked, and no other instance of
{ open can insert a record with the same key.  If the parcel is terminated
{ by a COMMIT, the locks are removed and the updates become final.  If the
{ parcel is terminated by an ABORT, the updates are undone and then the
{ locks are removed.  The instance of open that is doing the parcel can
{ access the locked records during the parcel, and it sees them in their
{ updated forms.
{
{ During the operation of a parcel, there is additional processing for each
{ alternate key reference.  Any alternate key reference which accesses a
{ record modified by the parcel, will cause the accessing instance of open
{ to wait for access until the parcel has terminated because the primary
{ key will remain locked for the life of the parcel.  Other references to
{ alternate key values which access records that have not been modified,
{ will complete without interference.  Alternate key values which are
{ deleted or which disappear because of a replace appear to any other
{ instance of open to exist until the end of the parcel.  Another way to
{ describe this behavior is to say that any deletion of a key, primary or
{ alternate, will be deferred until the end of the parcel, but updates will
{ be done immediately.  Other instances of open will see any modified
{ records and all associated primary and alternate keys as locked records,
{ and the parcel user sees them in their updated state.
{
{ If one user updates a record as part of a parcel, and a second user,
{ wanting to read the record, causes expiration of the first user's lock on
{ it, then the second user must abort the first user's parcel.  The
{ processing to expire the lock and abort the parcel will be handled by AAM
{ in a manner that is transparent to the second user.  If the second user
{ had only read permission, this would be impossible.  So if a file has
{ AMC$ENABLE_PARCELS, every concurrent OPEN of that file must have
{ permission that includes MODIFY.  If not, an error diagnostic will be
{ issued and the OPEN will fail.
{
{ Note that in AAM, MODIFY permission alone does not allow changing data
{ records; its purpose is usually to allow statistics to be kept up to
{ date.  Opening with just READ permission is permitted only if the share
{ mode is either READ or NONE.  This will allow the utilities to process
{ files with AMC$ENABLE_PARCELS without any special handling.
{
{ The owner of a parcel must be aware that the parcel could be aborted by a
{ concurrent user at any point in the processing.  When this happens, the
{ next request within the parcel will return a status indicating the abort
{ by the system.  The parcel owner must issue either an
{ AMP$ABORT_FILE_PARCEL request or FSP$CLOSE_FILE request to clear this
{ error indicator.  No further updates can be done on the instance of open
{ having the aborted parcel until the parcel is aborted by the user.
{
{ The parcel feature requires a kind of logging to make it work.  But this
{ is logically separate from the kind of logging that can make recovery
{ possible.  If there is a hardware or software crash in the middle of a
{ parcel, the existence of the parcel does not, of itself, make recovery
{ any more possible.
{
{ A parcel is a set of operations on a file, which may be committed or
{ aborted as a unit.  This allows proper recovery, and the grouping of a
{ set of requests with integrity of the group, without regard to
{ concurrency.  A request late in the parcel will reflect changes made
{ earlier in the parcel.  Aborting the parcel is always allowed because the
{ changes are protected by locks.
{
{ Changes to the file are made immediately, just as if there were no
{ parcel, but the primary keys are locked automatically, so that other
{ users will usually be forced to wait until the parcel is committed or
{ aborted.  The only exceptions are skip and rewind operations, which count
{ records as they exist at the moment, regardless of locks.
{
{ FIFO ordering will not be maintained for alternate keys when parcels are
{ in effect.
{
{ There is a set of AAM requests which are not allowed within the
{ boundaries of a file parcel.  This list includes the following:
{   AMP$ABANDON_KEY_DEFINITIONS   AMP$APPLY_KEY_DEFINITIONS
{   AMP$CREATE_KEY_DEFINITION     AMP$CREATE_NESTED_FILE
{   AMP$DELETE_KEY_DEFINITION     AMP$DELETE_NESTED_FILE
{   AMP$LOCK_FILE                 AMP$UNLOCK_FILE
{   AMP$UNLOCK_KEY                AMP$GET_NEXT_PRIMARY_KEY_LIST
{   AMP$GET_PRIMARY_KEY_COUNT     AMP$BEGIN_QUIET_PERIOD
{   AMP$END_QUIET_PERIOD
{ If any of these requests are issued within a parcel, a diagnostic will be
{ issued and the parcel will be aborted.  If an FSP$CLOSE_FILE is issued
{ within a parcel, the parcel will be aborted and the file will be closed.
{
{ The user may establish explicit locks within the parcel, and they will be
{ automatically unlocked at parcel termination.  Explicit unlocks
{ (AMP$UNLOCK_KEY and AMP$UNLOCK_FILE) cannot be done in the middle of a
{ parcel.
{
{ Key selection and nested file selection are both allowed during a parcel.
{ If a parcel is successfully committed, the key selection, file position,
{ and the nested file in effect at the end of the parcel will remain.  If a
{ parcel is aborted, the nested file selection, the key selection, and the
{ file position will be reset to the values in effect when the parcel was
{ initiated.
{
{ If a file has one instance of open with an active parcel and another
{ instance of open without a parcel, the open without the parcel will not
{ be able to get access to the file to change key definitions or nested
{ file definitions until the parcel terminates.
{
{ Since the modified records are locked out from any other file user,
{ parcels on highly concurrent files should be kept as short as possible to
{ minimize waiting by the other users.
{
{ Parcels that alter a large number of records should not be attempted
{ during periods of high activity on a file.  When one is attempted, it is
{ recommended that the user lock the file before beginning the parcel.
{ This makes locking the individual records unnecessary, and avoids the
{ problem of generating too many locks.  The parcel will function the same,
{ that is, it may be committed or aborted and the records will be handled
{ accordingly.
{
{ The file parcel facility is also designed to serve as a resource manager
{ for the general parcel capability (Available at 1.5.1).  Some optional
{ parameter values are provided for the AMP$BEGIN_FILE_PARCEL and
{ AMP$COMMIT_FILE_PARCEL procedures for when they are used within a general
{ parcel.
{
{ For any given file_identifier, there can be at most one parcel in
{ progress.  This is true whether the parcel is a portion of a general
{ parcel or an individual file parcel.
{
{
{       AMP$BEGIN_FILE_PARCEL (FILE_IDENTIFIER, GENERAL_COMMIT, STATUS)
{
{ FILE_IDENTIFIER: (input) This parameter specifies the file access
{       identifier established when the file was opened.
{
{ GENERAL_COMMIT: (input) Boolean variant record.  When not used within
{       a general parcel (1.5.1), the value must be FALSE.
{
{ STATUS: (output) This parameter specifies the request status.
{       CONDITION:  aae$parcel_in_progress,
{                   aae$parcel_not_allowed,
{                   aae$not_while_file_locked,
{                   aae$too_many_parcels,
{                   aae$space_not_available.
{       IDENTIFIER: amc$access_method_id.
{
