ABAP Keyword Documentation →  ABAP − Reference →  Creating Objects and Values →  Shared Objects →  Shared Objects - Classes and Interfaces →  Shared Objects - CL_ABAP_MEMORY_AREA 

Shared Objects - CL_SHM_AREA

The class CL_SHM_AREA is a subclass of CL_ABAP_MEMORY_AREA and the superclass of all area classes that are generated when an area is created using transaction SHMA. This class contains general attributes and methods for the corresponding area handles.

• Instance Attributes

• PROPERTIES

• INST_NAME

• CLIENT

• Static Methods

• MULTI_ATTACH

• DETACH_ALL_AREAS

• Instance Methods

• DETACH

• DETACH_COMMIT

• DETACH_ROLLBACK

• GET_LOCK_KIND

• GET_ROOT

• Instance Events

• SHM_COMMIT_EVENT

• SHM_ROLLBACK_EVENT

Other versions: 7.31 | 7.40 | 7.54

Instance Attributes

PROPERTIES

Structure of type SHM_PROPERTIES with the property READ-ONLY. The components in the structure contain area properties that are generally set using transaction SHMA. The components in the structure are as follows:

• AUTO_BUILD

If the value is ABAP_TRUE, the area instance versions of an area can be built automatically. The prerequisite for the value ABAP_TRUE is that the component AUTO_BUILD_CLASS is not initial. If the value is ABAP_FALSE, the area instance versions of an area cannot be built automatically.

• AUTO_BUILD_CLASS

Contains the name of the area constructor class that implements the constructor BUILD using the interface IF_SHM_BUILD_INSTANCE to build area instance versions automatically. This component is only filled if the area handle is bound by an change lock to an area instance version and is otherwise initial.

• BUILD_KIND

Specifies when area instance versions of the area are built automatically using the area constructor in the area constructor class. If the value is CL_SHM_AREA=>BUILD_KIND_NONE, area instance versions are not built automatically. This is always the case if the component AUTO_BUILD has the value ABAP_FALSE. If the component AUTO_BUILD has the value ABAP_TRUE, the component BUILD_KIND can have the values CL_SHM_AREA=>BUILD_KIND_DUE_TO_READ_REQUEST or CL_SHM_AREA=>BUILD_KIND_DUE_TO_INVALIDATION. If the component has the value CL_SHM_AREA=>BUILD_KIND_DUE_TO_READ_REQUEST and no active area instance versions exist, the area constructor is called automatically when a read is performed. If the component has the value CL_SHM_AREA=>BUILD_KIND_DUE_TO_INVALIDATION, the area constructor is called in the same way as when using the value CL_SHM_AREA=>BUILD_KIND_DUE_TO_READ_REQUEST. As before, the constructor is called in transitions from an active version to an obsolete or expired version, without an active area instance version being created.

• CLIENT_DEPENDENT

If the value is ABAP_TRUE, the area is client-specific. Area instance versions of the same area are distinguished using both the current client ID in the attribute CLIENT and using their names. If the component has the value ABAP_FALSE (default setting), the area is not client-specific and CLIENT is initial.

• DISPLACE_KIND

Controls whether area instance versions of the area may be displaced. If the value is CL_SHM_AREA=>DISPLACE_KIND_NONE, they are not displaceable (default setting). If the value is CL_SHM_AREA=>DISPLACE_KIND_SERIALIZABLE, they are displaceable. Before displacements, the content is serialized and is saved persistently. It is reloaded into the shared memory using a read or update on the area instance version. The prerequisite for this is that each class instantiated in the area instance has to implement the interface IF_SERIALIZABLE_OBJECT. If the component has the value CL_SHM_AREA=>DISPLACE_KIND_DISPLACABLE, the area instance versions are displaceable. Here, the content is lost in displacements (known as full displacement). Displacements take place only if no area handle is bound to an area instance version of the displaceable area instance at the same time.

• HAS_VERSIONS

If the value is ABAP_TRUE, the area supports versioning. If the value is ABAP_FALSE, there is a maximum of one single area instance version.

• IDLE_TIME

Defines how many minutes an area instance version is preserved in the shared memory (after a change lock or shared lock has been released) before it is deleted automatically. If the value is 0 (default setting), the area instance version is not deleted automatically. Values other than 0 are only possible if the components INVALIDATE_TIME and REFRESH_TIME both have the value 0. In the case of transactional areas, time measurement starts with the first database commit after a lock is released using the method DETACH_COMMIT.

• INVALIDATE_TIME

Defines the minutes until an area instance version becomes obsolete after a change lock is released. If the value is 0 (default setting), an area instance version never becomes obsolete. Values other than 0 are only possible if the components IDLE_TIME and REFRESH_TIME both have the value 0. In the case of transactional areas, time measurement starts with the first database commit after a lock is released using the method DETACH_COMMIT.

• LIFE_CONTEXT

Sets the visibility and lifetime of the area instance versions of the area. If this method has the value CL_SHM_AREA=>LIFE_CONTEXT_APPSERVER, the area instance versions exist until the AS Instance is shut down (default value). If it has the value CL_SHM_AREA=>LIFE_CONTEXT_SESSION, the area instances exist until the last ABAP session of the current user ends. If it has the value CL_SHM_AREA=>LIFE_CONTEXT_MODE, the area instances exist for as long as the current ABAP session is active. If it has the value CL_SHM_AREA=>LIFE_CONTEXT_MEMORY, the area instances exist for as long as the data exists in the ABAP memory of the current call sequence.

• MAX_AREA_SIZE

Specifies the maximum permitted size of an area in KB. The size of an area matches the total memory requirement of all area instance versions of the area. The default value is currently 0 and does not restrict the size.

• MAX_VERSION_SIZE

Specifies the maximum permitted size of an area in KB. The size of an area matches the total memory requirement of all area instance versions of the area. The default value is currently 0 and does not restrict the size.

• MAX_VERSIONS

Specifies the maximum number of area instance versions for an area instance of an area. Obsolete areas are not counted. The default value is 0 and does not restrict the size. If the component HAS_VERSIONS has the value ABAP_FALSE, MAX_VERSIONS is always 1. Otherwise, MAX_VERSIONS can be any non-negative whole number that is not 1.

• REFRESH_TIME

Defines the minutes until an area instance version is built by an automatic call of the area constructor. If the value is 0 (default setting), an area instance version is never built automatically. Values other than 0 are only possible if the components IDLE_TIME and INVALIDATE_TIME both have the value 0. In the case of transactional areas, time measurement starts with the first database commit after a lock is released using the method DETACH_COMMIT. The prerequisite is that an active version of the area instance version exists at the start of the build. If the method DETACH_COMMIT was not successful, the preceding area instance version is preserved (if areas are versioned) and the automatic rebuild raises appropriate exceptions. The area constructor can catch the exceptions CATCH CX_SHM_ERROR and CX_SHM_FAILURE itself and, for example, call the method INVALIDATE_INSTANCE of the area class to delete a preceding area instance version explicitly. If an automatic area build fails due to the failure of the method DETACH_COMMIT, no automatic rebuilds take place until the method is executed successfully.

• TRANSACTIONAL

If the value is ABAP_TRUE, the area is transactional (default setting). Any changes to the area instance versions of the area do not become active until the next database commit after the method DETACH_COMMIT is executed. If the value is ABAP_FALSE, the area is not transactional and changes become active immediately after the method DETACH_COMMIT is executed.

INST_NAME

Text field of type SHM_INST_NAME with the property READ-ONLY. This attribute contains the name of the current area instance. This attribute is set when an area instance is created using the method ATTACH_FOR_WRITE of the area class.

CLIENT

Text field of type MANDT with the property READ-ONLY. In client-specific areas (the component CLIENT_DEPENDENT of the structure PROPERTIES has the value ABAP_TRUE), this attribute contains the current client ID of the area instance. This attribute is initial in a cross-client area.

Static Methods

MULTI_ATTACH

Enables shared locks, exclusive locks, or update locks to be set at the same time on multiple area instances of one or more areas. The method MULTI_ATTACH is the only way to have change access to multiple area instances at the same time or, in other words, set multiple change locks at once.

Input/Output Parameters

• ATTACH_TAB of type SHM_ATTACH_TAB

Internal table whose rows contain information about the individually requested locks. The components of the rows are as follows:

• AREA_NAME of type SHM_AREA_NAME
  
  Area name

• INST_NAME of type SHM_INST_NAME
  
  Name of the area instance. If the area instance is accessed using the default name, the value CL_SHM_AREA=>DEFAULT_INSTANCE must be passed.

• CLIENT of type MANDT
  
  Client ID for client-specific areas. If the area instance is accessed using the current client ID, the current client must also be passed. The component must be initial in the case of cross-client areas.

• LOCK_KIND of type SHM_LOCK_KIND
  
  Access type (possible values are CL_SHM_AREA=>LOCK_KIND_READ, CL_SHM_AREA=>LOCK_KIND_WRITE, or CL_SHM_AREA=>LOCK_KIND_UPDATE).

• ATTACH_MODE of type SHM_ATTACH_MODE
  
  Behavior in case of changes (possible values are CL_SHM_AREA=>ATTACH_MODE_DEFAULT, CL_SHM_AREA=>ATTACH_MODE_DETACH_READER, or CL_SHM_AREA=>ATTACH_MODE_WAIT).

• LEVEL of type i
  
  Order in which the locks are set. Table rows with smaller values in the column are evaluated before table rows with larger values. If the values are equal, the order of the rows in the table is used as the deciding factor.

• HANDLE of type REF TO cl_shm_area
  
  This column returns a reference to an area handle for the area instance version for which the lock was requested (provided that this was successful). If an exception is raised, the value of the column is initial for either all rows or for the affected rows (depending on the value of the input parameter IGNORE_ERRORS).

• EXCEPTION of type REF TO cx_root
  
  If an exception is raised, this column returns a reference to the exception object for either one row or all relevant rows (depending on the value of IGNORE_ERRORS). In addition to the exceptions of ATTACH methods for settings individual locks in the area class, the exception CX_SHM_MULTI_ATTACH_ERROR can also be raised in the following cases: a write lock and an update lock are requested at the same time on an area instance version (the exception text here is DUPLICATE_CHANGE_LOCK), a lock for a client other than the current client is requested on an area instance version with automatic area building (the exception text here is ILLEGAL_AUTO_BUILD_CLIENT), a client ID is specified for a cross-client area (the exception text here is ILLEGAL_CLIENT_FOR_AREA). In success cases, the column is initial.

For more information about the individual components, see also the description of the parameters from the ATTACH methods for setting individual locks in the area class.

Input Parameters

• IGNORE_ERRORS of type ABAP_BOOL

Controls error handling of methods. Possible values are ABAP_TRUE and ABAP_FALSE.

• If ABAP_TRUE is passed, the system attempts to set the remaining locks following an exception when the lock was set. In the rows of the ATTACH_TAB parameter where an error occurred, the reference to the area handle in the HANDLE column is initialized and the reference in the EXCEPTION column is set to the corresponding exception object.

• If ABAP_FALSE is passed, the method is terminated following an exception while trying to set a lock. The column HANDLE is initialized in all rows of the parameter ATTACH_TAB. The reference to the corresponding exception object in the column EXCEPTION is set in the row where the error occurred.

All area instances for which an error occurred in the method MULTI_ATTACH have the same state after the method ends as they did before the method was called. This means the previous locks and the statuses remain the same.

• WAIT_TIME of the type i

Specifies the wait time in milliseconds for all rows of the parameter ATTACH_TAB where the value CL_SHM_AREA=>ATTACH_MODE_WAIT is specified in the column ATTACH_MODE. The wait time must be greater than or equal to 0 and is distributed to the relevant lock requests. If multiple change locks are set and the first lock can be set during the wait time, the remaining wait time can be used by the other locks. The time available for the remaining rows is therefore reduced by the wait time used each time a row of this type is evaluated.

Caution

In the case of change locks with a wait time that are set using MULTI_ATTACH, the same mutual exclusions apply as to the methods ATTACH_FOR_WRITE and ATTACH_FOR_UPDATE of the area class. This may prevent locks from being set in certain cases. For example, if a MULTI_ATTACH with a wait time is executed in parallel in two programs, where program 1 first sets a change lock A and then a change lock B, program 2 does this in reverse order, and then lock A is set in program 1 and lock B is set in program 2, at least one of the second locks cannot be set. If there is a lock request for the second lock (lock B in program 1 and lock A in program 2), each program has to wait for the other program’s wait time to expire.

Output Parameters

• ERROR_FLAG of type ABAP_BOOL

Specifies whether one or more exceptions were raised during the method. If ERROR_FLAG has the value ABAP_FALSE, this means all locks were set successfully. If ERROR_FLAG has the value ABAP_TRUE, not all locks could be set. The locks contain references to the exception object or objects for either one or more rows (depending on the value of the input parameter IGNORE_ERRORS) of the column EXCEPTION of the parameter ATTACH_TAB.

DETACH_ALL_AREAS

Releases all locks of the current internal session on any area instance versions of any areas. This deactivates all of the area handles of the internal session. If an exclusive lock or update lock is released, this rejects any changes that were made to area instance versions up to then.

Return Value

• RC of type SHM_RC

Possible values:

• CL_SHM_AREA=>RC_DONE if all locks were released.

• CL_SHM_AREA=>RC_NOTHING_TO_BE_DONE if no locks were released because no locks existed in the first place.

Note

The method DETACH_ALL_AREAS does not require any input parameters for the client ID, since it accesses both client-specific and cross-client area instances independently of the client. To delete all locks in a special client, the corresponding area handles must be accessed individually. These can be managed in an internal table.

Instance Methods

DETACH

Releases the lock on the current area handle. The area handle is then inactive.

Exceptions

• CX_SHM_WRONG_HANDLE

An change lock was active and not a shared lock (the exception text here is READ_HANDLE_REQUIRED)

• CX_SHM_ALREADY_DETACHED

No shared lock was active.

DETACH_COMMIT

Releases a change lock (an exclusive lock or update lock) on the current area handle and confirms the changes that were made. The area handle is then inactive. The prerequisite for this is that the current area instance version must contain an instance of the area root class (known as a root object). In addition, there must be no references from the area instance version to a different area instance of the shared objects memory or to the internal session.

If an exception is raised when the method is executed, the change lock is not released correctly. Although it is persisted, the lock cannot be released a second time using the method DETACH_COMMIT. The DETACH_ROLLBACK can be used instead.

In the case of non-transactional areas (the component TRANSACTIONAL of the structure PROPERTIES has the value ABAP_FALSE), any changes to the current area instance version become active immediately after the method DETACH_COMMIT is executed. In the case of transactional areas (the component TRANSACTIONAL of the structure PROPERTIES has the value ABAP_TRUE), the changes that are completed when the method DETACH_COMMIT is executed are not active until the next database commit. The following rules apply during the time between the completion of the method DETACH_COMMIT and the next database commit:

• In the case of transactional areas with versioning, all requested shared locks access the previous version.

• No reads are possible for transactional areas without versioning.

• It is not possible to set a new change lock for areas with versioning or for areas without versioning.

When the method DETACH_COMMIT is called, the event SHM_COMMIT_EVENT of the generated area class is raised automatically.

Exceptions

• CX_SHM_WRONG_HANDLE

A shared lock was active instead of a change lock (the exception text here is WRITE_HANDLE_REQUIRED)

• CX_SHM_ALREADY_DETACHED

No change lock was active.

• CX_SHM_COMPLETION_ERROR

Subclasses:

• CX_SHM_ROOT_OBJECT_INITIAL
  No root object was assigned to the area instance version.

• CX_SHM_EXTERNAL_REFERENCE
  There are still references from the current area instance version to a different area instance of the shared objects memory or to the internal session.

• CX_SHM_EVENT_EXECUTION_FAILED
  An exception was raised when an event handler was executed for SHM_COMMIT_EVENT. The exception raised can be read using the attribute PREVIOUS.

• CX_SHM_SECONDARY_COMMIT

An attempt was made to release a change lock again (a release had already failed previously) using DETACH_COMMIT instead of DETACH_ROLLBACK.

CX_SHM_COMPLETION_ERROR and CX_SHM_SECONDARY_COMMIT are subclasses of CX_SHM_DETACH_ERROR.

DETACH_ROLLBACK

Releases a change lock (an exclusive lock or update lock) on the current area handle and discards the changes that were made. The area handle is then inactive.

For areas without versioning, no active version of the area exists once the method has been executed. The previous version is still available for areas with versioning. In the case of transactional areas, a new change lock can be set on the relevant area instance (even before the next database commit) once the method DETACH_ROLLBACK has been executed.

When the method DETACH_ROLLBACK is called, the event SHM_ROLLBACK_EVENT is raised automatically before it is executed.

Exceptions

• CX_SHM_WRONG_HANDLE

A shared lock was active instead of a change lock (the exception text here is WRITE_HANDLE_REQUIRED).

• CX_SHM_ALREADY_DETACHED

No change lock was active.

• CX_SHM_EVENT_EXECUTION_FAILED

An exception was raised when an event handler was executed for SHM_ROLLBACK_EVENT. The exception raised can be read using the attribute PREVIOUS.

CX_SHM_EVENT_EXECUTION_FAILED is a subclass of CX_SHM_COMPLETION_ERROR, which is a subclass of CX_SHM_DETACH_ERROR.

GET_LOCK_KIND

Returns the type of the current lock for an area handle.

Return Value

• LOCK_KIND of type SHM_LOCK_KIND

Possible values:

• CL_SHM_AREA=>LOCK_KIND_READ if the area handle holds a shared lock.

• CL_SHM_AREA=>LOCK_KIND_WRITE if the area handle holds an exclusive lock.

• CL_SHM_AREA=>LOCK_KIND_UPDATE if the area handle holds an update lock.

• CL_SHM_AREA=>LOCK_KIND_COMPLETION_ERROR if the area handle holds a change lock after the method DETACH_COMMIT ended with an exception.

• CL_SHM_AREA=>LOCK_KIND_DETACHED, if the area handle does not hold any locks or if it is not bound to an area instance version.

GET_ROOT

Returns a reference to the root object (instance of the area root class) for an area handle. This method is intended for the unlikely case where multiple handles need to be handled for different areas with different area root classes. Otherwise the attribute ROOT of the area class can be accessed directly.

Return value

• ROOT of type REF TO object

Exceptions

• CX_SHM_ALREADY_DETACHED

The area handle is not bound to an area instance version.

Instance Events

SHM_COMMIT_EVENT

This event is raised by the area handle automatically when the method DETACH_COMMIT is called.

SHM_ROLLBACK_EVENT

This event is raised by the area handle automatically when the method DETACH_ROLLBACK is called.

Continue

Shared Objects - Area Classes