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.
7.31 | 7.40 | 7.54
Structure of type SHM_PROPERTIES with the READ-ONLY property. The components in the structure contain area properties that are generally set using transaction SHMA. The components in the structure are:
Text field of type SHM_INST_NAME with the READ-ONLY property. 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.
Text field of type MANDT with the READ-ONLY property. In client-specific areas (the component CLIENT_DEPENDENT of the structure PROPERTIES has the value ABAP_TRUE), this attribute contains the current client identifier of the area instance. The attribute is initial in a cross-client area.
Enables read, write 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 exclusive locks at once.
- ATTACH_TAB of type SHM_ATTACH_TAB
- AREA_NAME of type SHM_AREA_NAME
- INST_NAME of type SHM_INST_NAME
Name of the area instance. If the area instance should be accessed with the default name, the value CL_SHM_AREA=>DEFAULT_INSTANCE must be passed.
- CLIENT of type MANDT
Client identifier for client-specific areas. If the area instance should be accessed with the current client identifier, 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: 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 for change accesses. Possible values: CL_SHM_AREA=>ATTACH_MODE_DEFAULT, CL_SHM_AREA=>ATTACH_MODE_DETACH_READER or CL_SHM_AREA=>ATTACH_MODE_WAIT.
- LEVEL of type
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 or all relevant rows (depending on the value of IGNORE_ERRORS). In addition to the exceptions of ATTACH methods for setting individual locks in the area class, the exception CX_SHM_MULTI_ATTACH_ERROR can also be raised if: A write and update lock is requested at the same time on an area instance version (exception text: DUPLICATE_CHANGE_LOCK), a lock for a client other than the current client is requested on an area instance version with automatic area building (exception text: ILLEGAL_AUTO_BUILD_CLIENT), a client identifier is specified for a cross-client area (exception text: ILLEGAL_CLIENT_FOR_AREA), in success cases, the column is initial..
- IGNORE_ERRORS of type ABAP_BOOL
- 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 HANDLE column is initialized in all rows of the ATTACH_TAB parameter. The reference in the EXCEPTION column to the corresponding exception object is set in the row where the error occurred.
- WAIT_TIME of type
For change locks with a wait time that are set with MULTI_ATTACH, the same mutual exclusions apply as to 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 exclusive lock A and an exclusive lock B, and program 2 does this in reverse order and lock A is set in program 1 and lock B is set in program 2, at least one second lock 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.
- ERROR_FLAG of type ABAP_BOOL
Releases all of the locks of the current internal session on any area instance versions of any areas, which deactivates all of the internal session's area handles. If a write or update lock is released, this rejects any changes that were made up to then to area instance versions.
- RC of type SHM_RC
- 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.
The method DETACH_ALL_AREAS does not require any input parameters for the client identifier, 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.
Releases the lock on the current area handle. The area handle is then inactive.
Releases a change lock (write 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 (root object). In addition, there must not be any 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 remains, 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), 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:
- With transactional areas with versioning, all requested read locks access the previous version.
- No read access is possible for transactional areas without versioning.
- It is not possible to set a new change lock for areas with or without versioning.
When the method DETACH_COMMIT is called, the event SHM_COMMIT_EVENT of the generated area class is triggered automatically.
No root object was assigned to the area instance version.
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.
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_COMPLETION_ERROR and CX_SHM_SECONDARY_COMMIT are subclasses of CX_SHM_DETACH_ERROR.
Releases a change lock (write 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 is available once the method has been executed. The previous version is still available for areas with versioning. With transactional areas, a new exclusive 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 triggered automatically before it is executed.
CX_SHM_EVENT_EXECUTION_FAILED is a subclass of CX_SHM_COMPLETION_ERROR, which is a subclass of CX_SHM_DETACH_ERROR.
Returns the type of the current lock for an area handle.
- LOCK_KIND of type SHM_LOCK_KIND
- CL_SHM_AREA=>LOCK_KIND_READ if the area handle holds a read lock.
- CL_SHM_AREA=>LOCK_KIND_WRITE if the area handle holds a write 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 was 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.
Returns a reference to the root object (instance of the area root class) for an area handle. The 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.
- ROOT of type
REF TO object
This event is triggered by the area handle automatically when the method DETACH_COMMIT is called.
This event is triggered by the area handle automatically when the method DETACH_ROLLBACK is called.