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 → 

Shared Objects - Area Classes

An area class is generated as a subclass of class CL_SHM_AREA when an area is created using transaction SHMA. Its instances are used as area handles for the area instance versions of this area. The name of an area class is the same as the name of the area, which should therefore start with CL_.

Area classes can be displayed in Class Builder, although they cannot be changed there. The structure of an area class depends on the definition of the area in transaction SHMA. After the properties of an area have been changed, the area class is regenerated if necessary.

Static Attributes

AREA_NAME

Constant of type SHM_AREA_NAME: Contains the name of the current class or area.

Instance Attributes

ROOT

Reference variable of type REF TO area_root_class, where area_root_class is the area root class of the area. This attribute has the READ-ONLY property and is used for direct reads of the root object of an area instance version. Access using the GET_ROOT method is necessary in exceptional cases only, such as when using generic programming.

Static Methods

ATTACH_FOR_READ

Creates an area handle with a shared lock for an area instance version and returns a reference to the area handle.

Input Parameters

Name of the area instance version. The name is optional. The default value is CL_SHM_AREA=>DEFAULT_INSTANCE.
Client ID if the area is client-specific. The client ID is optional. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.

Return Code

Reference to the generated area handle, where area_class is the current area class.

Exceptions

The type of an object saved in the area instance does not match the definition of the object with the same name in the current internal session. If the time stamp for the type of the shared objects is newer than the time stamp in the internal session, the application should be restarted, to ensure the internal session also uses the current version of the type. If the time stamp of the type in the internal session is newer than the time stamp of the shared object, a new area instance version should be constructed, so that the current type is used there.
This exception is raised in the following cases:
The area instance version is already locked for reading in the same internal session.
This exception is raised in the following cases:
The value of CL_SHM_AREA=>ALL_CLIENTS was specified for the input parameter CLIENT.

The first four exception classes are subclasses of CX_SHM_ATTACH_ERROR.

ATTACH_FOR_WRITE

Creates an area handle with an exclusive lock for an area instance version and returns a reference to the area handle.

Input Parameters

Name of the area instance version. The name is optional. The default value is CL_SHM_AREA=>DEFAULT_INSTANCE.
Client ID if the area is client-specific. The client ID is optional. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.
Controls the lock mode. This information is optional. The default value is CL_SHM_AREA=>ATTACH_MODE_DEFAULT. Possible values are:
Wait time in milliseconds, if the value CL_SHM_AREA=>ATTACH_MODE_WAIT is passed for ATTACH_MODE. If a value not equal to 0 is passed for WAIT_TIME, if the value CL_SHM_AREA=>ATTACH_MODE_WAIT is not passed to ATTACH_MODE, or if a negative value is specified for WAIT_TIME, the exception CX_SHM_PARAMETER_ERROR is raised.
An attempt is made to set an exclusive lock again in the wait time. Only one program with the parameter WAIT_TIME can wait for an area instance at any one time. If a different program tries to set another exclusive lock with the parameter WAIT_TIME, this raises the exception CX_SHM_EXCLUSIVE_LOCK_ACTIVE directly (exception text LOCKED_BY_PENDING_CHANGER).
If the exclusive lock can be successfully set within the wait time, then the program flow continues. Note that there may be a delay until the waiting program can be restarted. During this delay, no other program can set an exclusive lock. This guarantees that the waiting program is given the exclusive lock next.
If the exclusive lock cannot be set successfully within the wait time, the exception CX_SHM_EXCLUSIVE_LOCK_ACTIVE is raised after the wait time (exception text:. LOCKED_BY_ACTIVE_CHANGER).

Return Code

Reference to the generated area handle, where area_class is the current area class.

Exceptions

The exclusive lock could not be set since there was already a shared lock on the area instance version and no new version could be created because this would overwrite the maximum number of possible versions.
An area instance version is already locked for changing in the same internal session. If a previous exclusive lock was released in a transactional area, but there has been no database commit yet, this raises the exception with the exception text WAITING_FOR_DB_COMMIT.
This exception is raised in the following cases:
This exception is raised if the value CL_SHM_AREA=>ATTACH_MODE_WAIT is passed for ATTACH_MODE, but the lock was deleted in transaction SHMM during a wait period.
This exception is raised in the following cases:

The first four exception classes are subclasses of CX_SHM_ATTACH_ERROR.

ATTACH_FOR_UPDATE

Creates an area handle with an update lock for an area instance version and returns a reference to the area handle.

Input Parameters

Name of the area instance version. The name is optional. The default value is CL_SHM_AREA=>DEFAULT_INSTANCE.
Client ID if the area is client-specific. The client ID is optional. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.
Controls the lock mode. This information is optional. The default value is CL_SHM_AREA=>ATTACH_MODE_DEFAULT. Possible values are:
Wait time in milliseconds, if the value CL_SHM_AREA=>ATTACH_MODE_WAIT is passed for ATTACH_MODE. If a value not equal to 0 is passed for WAIT_TIME, if the value CL_SHM_AREA=>ATTACH_MODE_WAIT is not passed to ATTACH_MODE, or if a negative value is specified for WAIT_TIME, the exception CX_SHM_PARAMETER_ERROR is raised.
An attempt is made to set an update lock again in the wait time. Only one program with the parameter WAIT_TIME can wait for an area instance at any one time. If a different program tries to set another exclusive lock with the parameter WAIT_TIME, this raises the exception CX_SHM_EXCLUSIVE_LOCK_ACTIVE directly (exception text LOCKED_BY_PENDING_CHANGER).
If the update lock can be successfully set within the wait time, then the program flow continues. Note that there may be a delay until the waiting program can be restarted. During this delay, no other program can set an exclusive lock. This guarantees that the waiting program receives the update lock next.
If the update lock cannot be set successfully within the wait time, the exception CX_SHM_EXCLUSIVE_LOCK_ACTIVE is raised after the wait time (exception text:. LOCKED_BY_ACTIVE_CHANGER).

Note

Since an active area instance version is required for setting an update lock, an area constructor called automatically is started when the ATTACH_FOR_UPDATE method is called. The following applies when using the parameter WAIT_TIME: If the area constructor can be started, there is a wait period. If the area constructor ends successfully before the end of the wait time, the update lock is set. If the area constructor ends without being able to construct an active version, the wait is terminated before the end of the wait time. If the area constructor does not end within the wait time, the exception CX_SHM_NO_ACTIVE_VERSION is raised (exception text: BUILD_NOT_FINISHED).

Return Code

Reference to the generated area handle, where area_class is the current area class.

Exceptions

The type of an object saved in the area instance does not match the definition of the object with the same name in the current program.
This exception is raised in the following cases:
The update lock could not be set since there was already a shared lock on the area instance version and no new version could be created because this would overwrite the maximum number of possible versions.
An area instance version is already locked for changing in the same internal session. If a previous exclusive lock was released in a transactional area, but there has been no database commit yet, this raises the exception with the exception text WAITING_FOR_DB_COMMIT.
This exception is raised in the following cases:
This exception is raised if the value CL_SHM_AREA=>ATTACH_MODE_WAIT is passed for ATTACH_MODE, but the lock was deleted in transaction SHMM during a wait period.
This exception is raised in the following cases:

The first six exception classes are subclasses of CX_SHM_ATTACH_ERROR.

DETACH_AREA

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

Input Parameters

Optional client ID if the area is client-specific. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.

Return Code

Possible values:

INVALIDATE_INSTANCE

For non-transactional areas, this method immediately sets the state of the active area instance version of the area instance of the name passed to obsolete. For transactional areas, this is done using the next database commit. No new locks can be set on this area instance version afterwards. Any existing shared locks are not released. How existing exclusive locks are handled depends on the input parameter TERMINATE_CHANGER.

Input Parameters

Name of the area instance version. The name is optional. The default value is the value of constant CL_SHM_AREA=>DEFAULT_INSTANCE.
Client ID if the area is client-specific. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.

Controls the handling of exclusive locks. Possible values are:

Controls cross-server invalidation. Possible values are:

Caution

Once this method is executed and ABAP_TRUE is passed to TERMINATE_CHANGER, all programs where there is still an exclusive lock for the invalidated area instance are terminated with the runtime error SYSTEM_SHM_AREA_OBSOLETE.

Return Code

Possible values in non-transactional areas:
In transactional areas, RC always has the value CL_SHM_AREA=>RC_NOTHING_TO_BE_DONE.

Exceptions

An invalid value was passed for the input parameter TERMINATE_CHANGER.

INVALIDATE_AREA

In non-transactional areas, this method immediately sets the state of all active area instance versions of the area in the current internal session to obsolete. For transactional areas this is done by the next database commit. No new locks can be set on these area instance versions afterwards. Any existing shared locks are not released. How existing exclusive locks are handled depends on the input parameter TERMINATE_CHANGER.

Input Parameters

Client ID if the area is client-specific. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.
Controls the handling of exclusive locks. Possible values are:
Controls cross-server invalidation. Possible values are:

Caution

Once this method is executed and ABAP_TRUE is passed to TERMINATE_CHANGER, all programs where there are still exclusive locks for the invalidated area instance versions are terminated with the runtime error SYSTEM_SHM_AREA_OBSOLETE.

Return Code

Possible values in non-transactional areas:
In transactional areas, RC always has the value CL_SHM_AREA=>RC_NOTHING_TO_BE_DONE.

Exceptions

An invalid value was passed for the input parameter TERMINATE_CHANGER.

FREE_INSTANCE

This method sets the state of all (active and obsolete) area instance versions of the area instance for the name passed to "expired", and all shared locks are released. No new shared locks and update locks can be set on this area instance version afterwards. How existing exclusive locks are handled depends on the input parameter TERMINATE_CHANGER. In non-transactional areas, the state of the area instance version is changed immediately; in transactional areas, the state changes after the next database commit.

Caution

After this method has been executed, all programs in which area handles still exist for the released area instance versions terminate with the runtime error SYSTEM_SHM_AREA_OBSOLETE.

Input Parameters

Name of the area instance version. The name is optional. The default value is the value of constant CL_SHM_AREA=>DEFAULT_INSTANCE.
Client ID if the area is client-specific. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.
Controls the handling of exclusive locks. Possible values are:
Controls cross-server invalidation. Possible values are:

Return Code

Possible values in non-transactional areas:
In transactional areas, RC always has the value CL_SHM_AREA=>RC_NOTHING_TO_BE_DONE.

Exceptions

An invalid value was passed for the input parameter TERMINATE_CHANGER.

FREE_AREA

This method sets the state of all (active and obsolete) area instance versions of the area to "expired", and all shared locks are released. No new locks can be set on these area instance versions afterwards. How existing exclusive locks are handled depends on the input parameter TERMINATE_CHANGER. In non-transactional areas, the change takes place immediately; in transactional areas, the change takes place after the next database commit.

Input Parameters

Client ID if the area is client-specific. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.
Controls the handling of exclusive locks. Possible values are:
Controls cross-server invalidation. Possible values are:

Return Code

In transactional areas, RC always has the value CL_SHM_AREA=>RC_NOTHING_TO_BE_DONE.

Exceptions

An invalid value was passed for the input parameter TERMINATE_CHANGER.

Caution

After this method has been executed, all programs in which area handles still exist for the released area instance versions terminate with the runtime error SYSTEM_SHM_AREA_OBSOLETE.

GET_INSTANCE_INFOS

Returns the names of all instances of the area on the current application server that are currently being built, are active, or are obsolete.

Input Parameters

Client ID if the area is client-specific. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.

Return Code

SHM_INST_INFOS is an internal table of row type SHM_INST_INFO with the following components:
An empty table is returned if there are no area instances for the area. The number of expired area instance versions is ignored.

BUILD

Calls the area constructor explicitly . The area constructor is executed in the current internal session. If the areas are client-specific, the area of the current client is built.

Input Parameters

Name of the area instance version. The name is optional. The default value is the value of constant CL_SHM_AREA=>DEFAULT_INSTANCE.

Exceptions

An error occurred when the area constructor was executed.
No area constructor class is bound to the area class.
The area class has to be generated again.

PROPAGATE_INSTANCE (obsolete)

This method is only available if the area is transactional. It has the same effect as executing the INVALIDATE_INSTANCE method and passing the value of ABAP_TRUE to the input parameter TERMINATE_CHANGER on all application servers in the current AS ABAP. This propagation takes place after the next database commit.

Caution

Do not use this method any more. Instead, use the parameter AFFECT_SERVER of the FREE_AREA, FREE_INSTANCE, INVALIDATE_AREA, and INVALIDATE_INSTANCE methods.

Input Parameters

Name of the area instance version. The name is optional. The default value is the value of constant CL_SHM_AREA=>DEFAULT_INSTANCE.
Client ID if the area is client-specific. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.
Controls whether the change in state is also performed on the current application server. Possible values are:

Exceptions

An invalid value was passed for the input parameter AFFECTING_LOCAL_SERVER.

PROPAGATE_AREA (obsolete)

This method is only available if the area is transactional. It has the same effect as executing the INVALIDATE_AREA method and passing the value of ABAP_TRUE to the input parameter TERMINATE_CHANGER on all application servers in the current AS ABAP. This propagation takes place after the next database commit.

Caution

Do not use this method any more. Instead, use the parameter AFFECT_SERVER of the FREE_AREA, FREE_INSTANCE, INVALIDATE_AREA, and INVALIDATE_INSTANCE methods.

Input Parameters

Client ID if the area is client-specific. The default value is the ID of the current client. In tenant-isolation systems, the CLIENT parameter cannot be passed in application clients.
Controls whether the change in state is also performed on the current application server. Possible values are:

Exceptions

An invalid value was passed for the input parameter AFFECTING_LOCAL_SERVER.

Instance Methods

SET_ROOT

This method defines the root object (instance of the area root class) of the area instance version. Before an exclusive lock can be released using the DETACH_COMMIT method, the root object has to be reset at least once using SET_ROOT. Updates are possible. The SET_ROOT method can only be called in area handles with exclusive locks.

Input Parameters

Exceptions

The method was called using an area handle with a shared lock or an area handle in which the DETACH_COMMIT method failed.
The reference variable passed to ROOT is initial.