ARTICLE
Shared Objects - CL_SHM_AREA
The CL_SHM_AREA class 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
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:
AUTO_BUILD
If the value is ABAP_TRUE , 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
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 , which implements the BUILD constructor
using the IF_SHM_BUILD_INSTANCE
interface to build area instance versions automatically. This
component is only filled if the area handle is bound by a change lock to
an area instance version, and is otherwise initial.
BUILD_KIND
Controls 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 , 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 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, then the area constructor is called
automatically for when a read access occurs. If the component has the
value 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. The constructor is
still called during the transition from an active version to an obsolete
or expired version, without creating an active area instance version.
CLIENT_DEPENDENT
If the value is ABAP_TRUE , the area is client-dependent. With
area instance versions of the same area, the version names and the
current client identifier in the CLIENT attribute are used to
differentiate between the versions. If the component has the value
ABAP_FALSE (default setting), then the area is not client-dependent
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 displacement, the content is serialized and is saved
persistently. 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
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 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
Specifies how many minutes an area instance version remains in the
shared memory - after a change/read lock has been released - before it
is automatically deleted. If the value is 0 (default setting), the area
instance version is not deleted automatically. Values other than 0 are
only possible if the INVALIDATE_TIME and REFRESH_TIME
components both have the value 0. With transactional areas, time
measurement begins with the first database commit after a lock is
released with the DETACH_COMMIT method.
INVALIDATE_TIME
Specifies after how many minutes an area instance version becomes
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 only possible if the IDLE_TIME and
REFRESH_TIME components both have the value 0. With transactional
areas, time measurement begins with the first database commit after a
lock is released with the DETACH_COMMIT method.
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 application server is shut down (default value). If it has the
value CL_SHM_AREA= LIFE_CONTEXT_SESSION , the area instances exist
until the current user�s last external session ends. If it has the value
CL_SHM_AREA= LIFE_CONTEXT_MODE , the area instances exist for as
long as the current main 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 corresponds to the total memory requirement for all area
instance versions. The default value is currently 0 and does not
restrict the size.
Geplant ist, den Standardwert aus der Gesamtgr��e des Shared Objects
Memory geteilt durch einen Profilparameter zu bestimmen. Wenn die
maximale Gr��e f�r bestehende Gebietsinstanzversionen kleiner als deren
Gr��e gemacht wird, sind zwar weiterhin Lese- aber keine
�nderungszugriffe mehr m�glich.
MAX_VERSION_SIZE
Specifies the maximum permitted size of an area in KB . The size
of an area corresponds to the total memory requirement for all area
instance versions. The default value is currently 0 and does not
restrict the size.
Geplant ist, den Standardwert aus der Gesamtgr��e des Shared Objects
Memory geteilt durch einen Profilparameter zu bestimmen. Wenn die
maximale Gr��e f�r bestehende Gebietsinstanzversionen kleiner als deren
Gr��e gemacht wird, sind zwar weiterhin Lese- aber keine
�nderungszugriffe mehr m�glich.
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 HAS_VERSIONS
component has the value ABAP_FALSE , MAX_VERSIONS is always
1. Otherwise, MAX_VERSIONS can be any non-negative number that is
not 1.
PROPAGATION_KIND
Legt fest, wie die Methode PROPAGATE_... der
Gebietsklasse zur Propagierung gestartet
wird. Wenn der Wert CL_SHM_AREA=>PROP_KIND_NONE
ist, steht keine Methode PROPAGATE... zur Verf�gung
(Standardeinstellung). Wenn die Komponente TRANSACTIONAL den Wert
ABAP_FALSE hat, kann nur dieser Wert enthalten sein. Wenn der
Wert CL_SHM_AREA= PROP_KIND_USER_TRIGGERED ist, muss der
Verwender die Methode PROPAGATE_... selbst aufrufen.
Wenn der Wert CL_SHM_AREA= PROP_KIND_AUTOMATIC
ist, wird die Methode PROPAGATE_... bei jeder �nderung eines der
in der internen Tabelle DEPENDENCIES der Gebietsklasse
angegebenen Elemente automatisch aufgerufen (zur Zeit nicht
implementiert).
REFRESH_TIME
Specifies 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 only possible if the IDLE_TIME and
INVALIDATE_TIME components both have the value 0. With transactional
areas, time measurement begins with the first database commit after a
lock is released with 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 the value is ABAP_TRUE , the area is transactional (default
setting). 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 value is ABAP_FALSE , then
the area is not transactional and changes become active immediately
after the DETACH_COMMIT method is executed.
INST_NAME
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
ATTACH_FOR_WRITE method of the area class .
CLIENT
Text field of type MANDT with the READ-ONLY property. In
client-dependent 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
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 to several area instances
at the same time - in other words, 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
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-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: 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 i
Sequence 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 sequence 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 occurs, the value of the column is initial
for either all rows or for the affected rows (depending on the value of
the IGNORE_ERRORS input parameter).
EXCEPTION of type REF TO cx_root
If an exception occurs, 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
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
).
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 parameter
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 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 they did before
the method was called. This means the previous locks and the statuses
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.
Caution
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 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 parameter
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 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(s) for either one or more rows
(depending on the value of the IGNORE_ERRORS input parameter) of
the EXCEPTION column of the ATTACH_TAB parameters.
DETACH_ALL_AREAS
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 no locks 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 and
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
Releases the lock on the current area handle. The area handle is then
inactive.
Exceptions
CX_SHM_WRONG_HANDLE
A change lock was active and not a read lock (exception text:
READ_HANDLE_REQUIRED )
CX_SHM_ALREADY_DETACHED
No read lock was active.
DETACH_COMMIT
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 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 ( TRANSACTIONAL component 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 (
TRANSACTIONAL component 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 during 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 for transactional areas without versioning.
It is not possible to set a new change lock for areas with or 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
A read lock was active but a change lock was not (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 again (release attempt 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 (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
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
A read lock was active but a change lock was not (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.
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 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 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
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
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.
Documentation extract taken from SAP system, � Copyright SAP AG. All rights reserved