ABAP Keyword Documentation →  ABAP − Reference →  Creating Objects and Values →  Shared Objects →  Shared Objects - Area Instance Versions 

Shared Objects - Area Handles

Other versions: 7.31 | 7.40 | 7.54

Creating Area Handles

Area handles are instances of the area class of an area. An individual area handle is created using one of the following static methods from the area class (this sets an associated area lock):

• ATTACH_FOR_WRITE

• ATTACH_FOR_UPDATE

• ATTACH_FOR_READ

The method MULTI_ATTACH also exists and is used to create multiple area handles at once. These methods return a reference to any new area handle created. Each area handle is bound to exactly one area instance version. This area instance version has a certain state, depending on the method used.

Binding an area handle to an area instance version has the same effect as setting one of the following area locks on the area instance:

• ATTACH_FOR_WRITE and ATTACH_FOR_UPDATE both create an exclusive lock

• ATTACH_FOR_READ creates a shared lock

Creating Area Instance Versions

The method ATTACH_FOR_WRITE creates a new area instance version if the existing locks permit this. Specifying a name makes it possible to create multiple area instances of an area, each with its own versioning. If no name is specified, the content of constant CL_SHM_AREA=>DEFAULT_INSTANCE is used as the default value. It is advisable to always work with explicit and unique names. Until the binding is removed, changes can be performed in the current internal session on the bound area instance version.

Changing Area Instance Versions

The method ATTACH_FOR_UPDATE does one of the following (if permitted by existing locks):

• In areas with versioning, it creates a new version as a copy of the active area instance version.

• In areas without versioning,it binds the area handle to an existing active area instance version.

When a name is specified, an area instance is selected. If no name is specified, the content of the constant CL_SHM_AREA=>DEFAULT_INSTANCE is used as the default value. Until the binding is removed, changes can be performed on the bound area instance version in the current internal session.

Reading Area Instance Versions

The method ATTACH_FOR_READ binds the area handle to an existing area instance version if existing locks allow this. When a name is specified, an area instance is selected. If no name is specified, the content of the constant CL_SHM_AREA=>DEFAULT_INSTANCE is used as the default value. Until the binding is removed, reads can be performed on the bound area instance version in the current internal session.

Detaching Area Handles

The following instance methods of the area class remove the binding of an individual area handle:

• DETACH removes a shared lock.

• DETACH_COMMIT removes an exclusive lock and confirms the changes that were made.

• DETACH_ROLLBACK removes an exclusive lock without confirming the changes that were made.

Two other static methods, DETACH_AREA and DETACH_ALL_AREAS, are used to remove multiple bindings at once. Once the binding between an area handle and the area instance version is removed, the area handle is inactive and can no longer be used. Removing a binding also removes the corresponding area lock and might change the state of the relevant area instance version.

Additional Methods

The methods of the area handles specified above are normally used when working with shared objects. Additional methods also exist for special applications. Transaction SHMM provides a program-independent user interface for these methods.

• Invalidating versions

The methods INVALIDATE_INSTANCE or INVALIDATE_AREA can be used to set one or more active area instance versions to "obsolete". This prevents new shared locks from being set for this version, although existing shared locks continue to exist.

• Deleting versions

The methods FREE_INSTANCE or FREE_AREA can be used to set one or more active or obsolete area instance versions to "expired". This removes all shared locks and no new shared locks can be set on these versions.

• Information about area instances

The method GET_INSTANCE_INFOS returns information about all area instances of an AS Instance in an internal table.

• Information about area handles

The methods GET_LOCK_KIND, IS_VALID, IS_ACTIVE_VERSION, IS_SHARED, HAS_ACTIVE_PROPERTIES, and GET_DETACH_INFO provide information about locks and the state of an area handle.

• Explicit call of the area constructor

The method BUILD can be used to call the area constructor of an area explicitly in the current internal session. This method is a standardized mechanism for building area instances.