CL_SHM_AREA 

Common superclass of all area classes for area handles of area instance versions in the shared memory. This class contains general attributes and methods for area handles.

 

Instance Attributes

 

PROPERTIES

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 of the structure are:

AUTO_BUILD	If this component has the value of constant ABAP_TRUE, then the area instance versions of an area can be built automatically. The prerequisite for the ABAP_TRUE value is that the AUTO_BUILD_CLASS component is not initial. If it has the value ABAP_FALSE, then area instance versions cannot be built automatically.
AUTO_BUILD_CLASS	This component contains the name of the <area_constructor> area constructor class, which implements the BUILD constructor using the IF_SHM_BUILD_INSTANCE interface to build area instance versions automatically. This component is filled only if the area handle is bound by a change lock to an area instance version, and is otherwise initial.
BUILD_KIND	This component controls when area instance versions of the area should be built automatically using the area constructor in the <area_constructor> class: if it has the value of constant CL_SHM_AREA=>BUILD_KIND_NONE, then area instance versions are not built automatically. This is always the case if the AUTO_BUILD component has the value ABAP_FALSE. If the AUTO_BUILD component has the value of ABAP_TRUE, then the BUILD_KIND component can have the value of constants CL_SHM_AREA=>BUILD_KIND_DUE_TO_READ_REQUEST or CL_SHM_AREA=>BUILD_KIND_DUE_TO_INVALIDATION. If it has the value CL_SHM_AREA=>BUILD_KIND_DUE_TO_READ_REQUEST and no active area instance version is available, then the area constructor is called automatically for a read access. If it has the value of constant CL_SHM_AREA=>BUILD_KIND_DUE_TO_INVALIDATION, the area constructor is called in the same way as with the CL_SHM_AREA=>BUILD_KIND_DUE_TO_READ_REQUEST value. Furthermore, it is called during the transition from an active version to an obsolete or expired version, without creating an active area instance version.
CLIENT_DEPENDENT	If this component has the value of constant ABAP_TRUE, the area is client-dependent. Are instance versions of the same area are differentiated by their name as well as by the current client identifier in the CLIENT attribute. If the component has the value ABAP_FALSE (default setting), then the area is not client-dependent and CLIENT is initial.
DISPLACE_KIND	This component controls whether area instance versions of the area may be displaced. It is has the value of constant CL_SHM_AREA=>DISPLACE_KIND_NONE, they are not displaceable (default setting). If it has the value of constant CL_SHM_AREA=>DISPLACE_KIND_SERIALIZABLE (from Release 7.0), they are displaceable. The content is serialized and is stored persistent. It is reloaded into the shared memory with a read or update access to the area instance version. The prerequisite for this is that each class instantiated in the area instance has to implement the IF_SERIALIZABLE_OBJECT interface. If the component has the value of constant CL_SHM_AREA=>DISPLACE_KIND_DISPLACABLE, the area instance versions are displaceable, and the content is lost with a displacement (complete displacement). Displacement takes place as long as no area handle is bound to an area instance version of the displaceable area instance at the same time.
HAS_VERSIONS	If this component has the value of constant ABAP_TRUE, then the area supports versioning. If it has the value ABAP_FALSE, there is a maximum of one single area instance version.
IDLE_TIME	This component determines how many minutes an area instance version remains in the shared memory once a change or read lock has been released, until it is automatically deleted. If the value is 0 (default setting), the area instance version is not deleted automatically. Values other than 0 are possible only if the INVALIDATE_TIME and REFRESH_TIME components both have the value 0. With transactional areas, the time measurement begins with the first database commit after a lock was released using the DETACH_COMMIT method.
INVALIDATE_TIME	This component determines after how many minutes an area instance version is obsolete after a change lock has been released. If the value is 0 (default setting), an area instance version never becomes obsolete. Values other than 0 are possible only if the IDLE_TIME and REFRESH_TIME components both have the value 0. With transactional areas, the time measurement begins with the first database commit after a lock was released using the DETACH_COMMIT method.
LIFE_CONTEXT	This component determines the visibility and lifetime of the area instance versions of the area. If it has the value of constant CL_SHM_AREA=>LIFE_CONTEXT_APPSERVER, the area instance versions exist until the application server is shut down (default value). If it has the value of constant CL_SHM_AREA=>LIFE_CONTEXT_SESSION (from Release 7.0), the area instances exist until the current user’s last external session ends. If it has the value of constant CL_SHM_AREA=>LIFE_CONTEXT_MODE (from Release 7.0), the area instances exist as long as the current user’s external session. If it has the value of constant CL_SHM_AREA=>LIFE_CONTEXT_MEMORY (from Release 7.0), the area instances exist as long as the data in the ABAP memory of the current call sequence.
MAX_AREA_SIZE	This component specifies the maximum permitted size of an area in KB. The size of an area corresponds to the total of the memory requirement of all of the area’s area instance versions (from Release 7.0). The default value is currently 0 and does not restrict the size. It is planned that the default value will be determined from the total size of the shared objects memory using a profile parameter. If the maximum size of existing area instance versions is less than their size, then read accesses are still possible, although change accesses are not.
MAX_VERSION_SIZE	This component specifies the maximum permitted size of an area instance version in KB. The default value is 0 and does not restrict the size. If it is greater than 0, the value of the MAX_VERSION_SIZE component must be less than or equal to the value of the MAX_AREA_SIZE component.
MAX_VERSIONS	This component specifies the maximum number of area instance versions of the area’s area instance. Obsolete areas are not counted. The default value is 0 and does not restrict the size. If the HAS_VERSIONS component has the value of constant ABAP_FALSE, MAX_VERSIONS is always 1. Otherwise, MAX_VERSIONS can be any non-negative number that is not 1.
PROPAGATION_KIND	This component determines how the PROPAGATE_.. method of the <area> area class is started for propagation. If it has the value of constant CL_SHM_AREA=>PROP_KIND_NONE, no PROPAGATE method is available (default setting). If the TRANSACTIONAL component has the value ABAP_FALSE, then only this value can be specified. If the component has the value of constant CL_SHM_AREA=>PROP_KIND_USER_TRIGGERED, the user must call the PROPAGATE_... method him or herself. If it has the value of constant CL_SHM_AREA=>PROP_KIND_AUTOMATIC, the PROPAGATE_... method is called automatically each time one of the elements specified in the internal table DEPENDENCIES of the <area> area class is changed (this is not currently implemented).
REFRESH_TIME	This component determines after how many minutes an area instance version is built by the 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 possible only if the IDLE_TIME and INVALIDATE_TIME components both have the value 0. With transactional areas, the time measurement begins with the first database commit after a lock was released using the DETACH_COMMIT method. The prerequisite is that an active version of the area instance version is present at the start of the build.
TRANSACTIONAL	If this component has the value of constant ABAP_TRUE (default setting), the area is transactional. Changes to the area instance versions of the area do not become active until after the DETACH_COMMIT method is executed with the next database commit. If the component has the value of constant ABAP_FALSE, then the area is not transactional and changes become active immediately after the DETACH_COMMIT method is executed.

The values of the component are usually set using the administration transaction, SHMA.

 

INST_NAME

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

 

CLIENT

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

 

Static Methods

 

MULTI_ATTACH

This method enables read, write or update locks to be set at the same time on several area instances of one or more areas. The MULTI_ATTACH method is the only way to have change access several area instances at the same time, that is, to set several 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:

¡        AREA_NAME of type SHM_AREA_NAME

Name of the area

¡        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 of constant CL_SHM_AREA=>DEFAULT_INSTANCE must be passed.

¡        CLIENT of type MANDT

Client identifier for client-dependent 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 with client-independent areas.

¡        LOCK_KIND of type SHM_LOCK_KIND

Access type. Possible values are those of constants 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 with change accesses. Possible values are those of constants CL_SHM_AREA=>ATTACH_MODE_DEFAULT, CL_SHM_AREA=>ATTACH_MODE_DETACH_READER or CL_SHM_AREA=>ATTACH_MODE_WAIT.

¡        LEVEL of type i

Sequence in which the locks are set. Table rows with smaller values in the LEVEL column are evaluated before table rows with larger values. When the values in LEVEL are equal, the sequence of the rows in the table counts.

¡        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). In the case of an exception, the value of the column is initial depending on the value of the IGNORE_ERRORS input parameter for all rows, or the relevant rows.

¡        EXCEPTION of type REF TO CX_ROOT

In the case of an exception, this column returns a reference to the exception object depending on the value of the IGNORE_ERRORS for one or all relevant rows. In addition to the exceptions of the ATTACH methods for setting individual locks in the <area> area class, the CX_SHM_MULTI_ATTACH_ERROR exception can also occur 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 client-independent area (exception text: ILLEGAL_CLIENT_FOR_AREA).

If this is successful, 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> area class.

Input Parameter

·        IGNORE_ERRORS of type ABAP_BOOL

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

If the value of ABAP_TRUE is passed, an attempt is made to set the remaining locks following an exception as 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 the value of ABAP_FALSE is passed, the method is terminated following an exception when a lock was set. 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.

All area instances for which an error occurred in the MULTI_ATTACH method have the same state after the method ends as before the method was called. That is, the previous locks and the state remain the same.

·        WAIT_TIME of type i

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

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 area class, which 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 change lock A and then a change 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, then 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), then each program has to wait for the other program’s wait time to expire.

Output Parameters

·        ERROR_FLAG of type ABAP_BOOL

Specifies whether the method resulted in one or more exceptions during the method. If ERROR_FLAG has the value of constant ABAP_FALSE, all locks could be set successfully.

If ERROR_FLAG has the value of constant ABAP_TRUE, not all locks could be set. Depending on the value of the IGNORE_ERRORS input parameter, they contain references to the exception object(s) for one or more rows of the EXCEPTION column of the ATTACH_TAB parameters.

 

DETACH_ALL_AREAS

This method releases all of the current internal session’s locks on any area instance versions of any areas, thereby deactivating 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.

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 none existed in the first place.

Note

The DETACH_ALL_AREAS method does not require any input parameters for the client identifier since it accesses both client-dependent as well as client-independent area instances independently of the client. In order to delete all locks on a special client, you have to access the corresponding area handles individually. These can be managed in an internal table.

 

Instance Methods

 

DETACH

This method releases the lock on the current area handle. The area handle is then inactive.

Exceptions

·        CX_SHM_WRONG_HANDLE

No read lock was active, but a change lock was (exception text: READ_HANDLE_REQUIRED)

·        CX_SHM_ALREADY_DETACHED

No read lock was active.

Both exception classes inherit from CX_DYNAMIC_CHECK.

 

DETACH_COMMIT

This method 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 has to contain an instance of the area root class (root object). Furthermore, 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 occurs 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 DETACH_COMMIT method. The DETACH_ROLLBACK can be used instead.

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

·        With transactional areas with versioning, all requested read locks access the previous version.

·        No read access is possible with transactional areas without versioning.

·        It is not possible to set a new change lock, either with areas with versioning or with areas without versioning.

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

Exceptions

·        CX_SHM_WRONG_HANDLE

No change lock was active, but a read lock was (exception text: 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 occurred when an event handler was executed for SHM_COMMIT_EVENT. The exception that occurred can be accessed using the PREVIOUS attribute.

·        CX_SHM_SECONDARY_COMMIT

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

All exception classes inherit from CX_DYNAMIC_CHECK. CX_SHM_COMPLETION_ERROR and CX_SHM_SECONDARY_COMMIT are subclasses of CX_SHM_DETACH_ERROR.

 

DETACH_ROLLBACK

This method releases a change lock (write or update lock) of the current area handle and rejects the changes that were made. The area handle is then inactive.

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

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

Exceptions

·        CX_SHM_WRONG_HANDLE

No change lock was active, but a read lock was (exception text: WRITE_HANDLE_REQUIRED)

·        CX_SHM_ALREADY_DETACHED

No change lock was active.

·        CX_SHM_EVENT_EXECUTION_FAILED

An exception occurred when an event handler was executed for SHM_ROLLBACK_EVENT. The exception that occurred can be accessed using the PREVIOUS attribute.

All exception classes inherit from CX_DYNAMIC_CHECK. 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

This method 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 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, once the DETACH_COMMIT method 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.

GET_ROOT

This method 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 that you have to work generically with several handles for different areas with different area root classes. Otherwise the ROOT attribute of the <area> 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 triggered by the area handle automatically when the DETACH_COMMIT method is called.

 

SHM_ROLLBACK_EVENT

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