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. During this process, a corresponding area lock is set:

• ATTACH_FOR_WRITE

• ATTACH_FOR_UPDATE

• ATTACH_FOR_READ

There is also a MULTI_ATTACH method for creating multiple area handles at once. The methods return a reference to the area handle that is created. Each area handle is bound to exactly one area instance version. This area instance version has a certain state, depending on the method.

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 create an exclusive lock

• ATTACH_FOR_READ creates a shared lock

Creating Area Instance Versions

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. We recommend always working 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

Method ATTACH_FOR_UPDATE is created if existing locks allow this,

• Creates a new version as a copy of the active area instance version, in the case of areas with versioning, or

• Binds the area handle to an existing active area instance version in the case of areas without versioning.

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

Reading Area Instance Versions

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

Deactivating Area Handles

The following instance methods of the area class removes the binding of individual area handles:

• DETACH removes a shared lock.

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

• DETACH_ROLLBACK removes an exclusive lock without confirming the changes that have been 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 has been 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 area handles listed above are normally used when working with shared objects. There are also additional methods for special applications. Transaction SHMM provides a program-independent user interface for these methods.

• Invalidating Versions

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

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

Method GET_INSTANCE_INFOS returns information about all of the area instances of an application server 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.