ARTICLE
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
INST_NAME of type SHM_INST_NAME
Name of the area instance version. The name is optional. The default
value is CL_SHM_AREA= DEFAULT_INSTANCE .
CLIENT of type SHM_CLIENT
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
HANDLE of type REF TO area_class .
Reference to the generated area handle, where area_class is the
current area class.
Exceptions
CX_SHM_INCONSISTENT
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.
CX_SHM_NO_ACTIVE_VERSION
This exception is raised in the following cases:
The area instance version does not exist and an automatic build is not
possible because there is no area constructor or displaced version
(exception text: NEITHER_BUILD_NOR_LOAD ).
The area instance version does not exist and the area constructor was
called (exception text: BUILD_STARTED ). The system does not wait
for the automatic area build to be terminated when the exception is
caught. If this exception is raised twice in succession with this
exception text, the area constructor was not ended correctly.
The area instance version does not exist although the area constructor
is already being executed (exception text: BUILD_NOT_FINISHED ).
The area instance version is not available and a displaced version was
started (exception text: LOAD_STARTED ).
The area instance version does not exist but a displaced version is
already being loaded (exception text: LOAD_NOT_FINISHED ).
CX_SHM_READ_LOCK_ACTIVE
The area instance version is already locked for reading in the same
internal session.
CX_SHM_EXCLUSIVE_LOCK_ACTIVE
This exception is raised in the following cases:
The area instance does not support versioning and is already locked
against changes (exception text: LOCKED_BY_ACTIVE_CHANGER ).
The area instance does not support versioning and a user is waiting for
an exclusive lock (exception text: LOCKED_BY_PENDING_CHANGER ).
The area instance is transactional, does not support versioning, and an
exclusive lock was released, but the database commit has not yet taken
place (exception text: WAITING_FOR_DB_COMMIT ).
CX_SHM_PARAMETER_ERROR
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
INST_NAME of type SHM_INST_NAME
Name of the area instance version. The name is optional. The default
value is CL_SHM_AREA= DEFAULT_INSTANCE .
CLIENT of type SHM_CLIENT
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 .
ATTACH_MODE of type SHM_ATTACH_MODE
Controls the lock mode. This information is optional. The default value
is CL_SHM_AREA= ATTACH_MODE_DEFAULT . Possible values are:
CL_SHM_AREA= ATTACH_MODE_DEFAULT
If there are shared locks on the area instance of the specified name,
these are not released. For areas with versioning, the system attempts
to create a new version. In the case of areas without versioning, the
exception CX_SHM_VERSION_LIMIT_EXCEEDED is raised.
CL_SHM_AREA= ATTACH_MODE_DETACH_READER
For areas with versioning, if there are shared locks on all area
instance versions of the specified name, the shared locks on the oldest
version are released. This deactivates them so that a new version can be
created. All shared locks are released for areas without versioning.
CL_SHM_AREA= ATTACH_MODE_WAIT
If the exclusive lock cannot be set, the program waits for the time
specified in the WAIT_TIME parameter and tries to set the lock
again before the exception CX_SHM_VERSION_LIMIT_EXCEEDED is
raised. For an area without versioning, no further shared locks can be
set on the area instance during the wait time. It is still possible to
set shared locks for an area with versioning.
WAIT_TIME of type i
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
HANDLE of type REF TO area_class .
Reference to the generated area handle, where area_class is the
current area class.
Exceptions
CX_SHM_VERSION_LIMIT_EXCEEDED
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.
CX_SHM_CHANGE_LOCK_ACTIVE
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
.
CX_SHM_EXCLUSIVE_LOCK_ACTIVE
This exception is raised in the following cases:
The area instance is already locked for changes in a different internal
session (exception text: LOCKED_BY_ACTIVE_CHANGER ).
A user in a different internal session is waiting for an exclusive lock
(exception text: LOCKED_BY_PENDING_CHANGER ).
The area instance is transactional and an exclusive lock was released in
a different internal session, but the database commit has not yet taken
place (exception text: WAITING_FOR_DB_COMMIT ).
CX_SHM_PENDING_LOCK_REMOVED
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.
CX_SHM_PARAMETER_ERROR
This exception is raised in the following cases:
An invalid value was passed for the input parameter ATTACH_MODE .
A negative number was passed for the input parameter WAIT_TIME .
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_UPDATE
Creates an area handle with an update lock for an area instance version
and returns a reference to the area handle.
Input Parameters
INST_NAME of type SHM_INST_NAME
Name of the area instance version. The name is optional. The default
value is CL_SHM_AREA= DEFAULT_INSTANCE .
CLIENT of type SHM_CLIENT
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 .
ATTACH_MODE of type SHM_ATTACH_MODE
Controls the lock mode. This information is optional. The default value
is CL_SHM_AREA= ATTACH_MODE_DEFAULT . Possible values are:
CL_SHM_AREA= ATTACH_MODE_DEFAULT
If there are shared locks on the area instance of the specified name,
these are not released. For areas with versioning, the system attempts
to create a new version. In the case of areas without versioning, the
exception CX_SHM_VERSION_LIMIT_EXCEEDED is raised.
CL_SHM_AREA= ATTACH_MODE_DETACH_READER
For areas with versioning, if there are shared locks on all area
instance versions of the specified name, the shared locks on the oldest
version are released. This deactivates them so that a new version can be
created. All shared locks are released for areas without versioning.
CL_SHM_AREA= ATTACH_MODE_WAIT
If the update lock cannot be set, the program waits for the time
specified in the WAIT_TIME parameter and tries to set the lock
again before the exception CX_SHM_VERSION_LIMIT_EXCEEDED is
raised. For an area without versioning, no further shared locks can be
set on the area instance during the wait time. It is still possible to
set shared locks for an area with versioning.
WAIT_TIME of type i
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
HANDLE of type REF TO area_class .
Reference to the generated area handle, where area_class is the
current area class.
Exceptions
CX_SHM_INCONSISTENT
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.
CX_SHM_NO_ACTIVE_VERSION
This exception is raised in the following cases:
The area instance version does not exist and an automatic build is not
possible because an area constructor or a displaced version does not
exist (exception text: NEITHER_BUILD_NOR_LOAD ).
The area instance version does not exist and the area constructor was
called (exception text: BUILD_STARTED ).
The area instance version does not exist although the area constructor
is already being executed (exception text: BUILD_NOT_FINISHED ).
The area instance version is not available and a displaced version was
started (exception text: LOAD_STARTED ).
The area instance version does not exist but a displaced version is
already being loaded (exception text: LOAD_NOT_FINISHED ).
CX_SHM_VERSION_LIMIT_EXCEEDED
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.
CX_SHM_CHANGE_LOCK_ACTIVE
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
.
CX_SHM_EXCLUSIVE_LOCK_ACTIVE
This exception is raised in the following cases:
The area instance is already locked for changes in a different internal
session (exception text: LOCKED_BY_ACTIVE_CHANGER ).
A user in a different internal session is waiting for an exclusive lock
(exception text: LOCKED_BY_PENDING_CHANGER ).
The area instance is transactional and an exclusive lock was released in
a different internal session, but the database commit has not yet taken
place (exception text: WAITING_FOR_DB_COMMIT ).
CX_SHM_PENDING_LOCK_REMOVED
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.
CX_SHM_PARAMETER_ERROR
This exception is raised in the following cases:
An invalid value was passed for the input parameter ATTACH_MODE .
A negative number was passed for the input parameter WAIT_TIME .
The value of CL_SHM_AREA= ALL_CLIENTS was specified for the input
parameter CLIENT .
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
CLIENT of type SHM_CLIENT
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
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 current session.
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
INST_NAME of type SHM_INST_NAME
Name of the area instance version. The name is optional. The default
value is the value of constant CL_SHM_AREA= DEFAULT_INSTANCE .
CLIENT of type SHM_CLIENT
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 .
TERMINATE_CHANGER of type ABAP_BOOL
Controls the handling of exclusive locks. Possible values are:
ABAP_TRUE (existing exclusive locks are released (default
setting)).
ABAP_FALSE (existing exclusive locks are not released).
AFFECT_SERVER of type SHM_AFFECT_SERVER (for transactional
areas only)
Controls cross-server invalidation. Possible values are:
CL_SHM_AREA= AFFECT_LOCAL_SERVER (only the area instance versions
of the current application server are invalidated (default setting)).
CL_SHM_AREA= AFFECT_ALL_SERVERS (the area instance versions of
all application servers are invalidated).
CL_SHM_AREA= AFFECT_ALL_SERVERS_BUT_LOCAL (the area instance
versions of all application servers are invalidated, apart from the
current application server). This enables changes to be made to areas of
the current application server directly, without the database having to
create the entire area again.
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
RC of type SHM_RC
Possible values in non-transactional areas:
CL_SHM_AREA= RC_DONE if the active area instance version was set
to obsolete. If the value ABAP_TRUE was passed to
TERMINATE_CHANGER (even if an exclusive lock was released).
CL_SHM_AREA= RC_NOTHING_TO_BE_DONE if no active area instance
version is available and (if the value ABAP_TRUE was passed to
TERMINATE_CHANGER ) if no exclusive lock exists .
CL_SHM_AREA= RC_INSTANCE_NAME_NOT_FOUND if no area instance of
the specified name exists.
In transactional areas, RC always has the value
CL_SHM_AREA= RC_NOTHING_TO_BE_DONE .
Exceptions
CX_SHM_PARAMETER_ERROR
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 of type SHM_CLIENT
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 .
TERMINATE_CHANGER of type ABAP_BOOL
Controls the handling of exclusive locks. Possible values are:
ABAP_TRUE (existing exclusive locks are released (default
setting)).
ABAP_FALSE (existing exclusive locks are not released).
AFFECT_SERVER of type SHM_AFFECT_SERVER (for transactional
areas only)
Controls cross-server invalidation. Possible values are:
CL_SHM_AREA= AFFECT_LOCAL_SERVER (only the area instance versions
of the current application server are invalidated (default setting)).
CL_SHM_AREA= AFFECT_ALL_SERVERS (the area instance versions of
all application servers are invalidated).
CL_SHM_AREA= AFFECT_ALL_SERVERS_BUT_LOCAL (the area instance
versions of all application servers are invalidated, apart from the
current application server). This enables changes to be made to areas of
the current application server directly, without the database having to
create the entire area again.
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
RC of type SHM_RC
Possible values in non-transactional areas:
CL_SHM_AREA= RC_DONE if at least one active area instance version
was set to obsolete. If the value ABAP_TRUE was passed to
TERMINATE_CHANGER (even if one or more exclusive locks were
released).
CL_SHM_AREA= RC_NOTHING_TO_BE_DONE if no active area instance
version exists and (if the value ABAP_TRUE was passed to
TERMINATE_CHANGER ) if no exclusive lock exists.
In transactional areas, RC always has the value
CL_SHM_AREA= RC_NOTHING_TO_BE_DONE .
Exceptions
CX_SHM_PARAMETER_ERROR
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
INST_NAME of type SHM_INST_NAME
Name of the area instance version. The name is optional. The default
value is the value of constant CL_SHM_AREA= DEFAULT_INSTANCE .
CLIENT of type SHM_CLIENT
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 .
TERMINATE_CHANGER of type ABAP_BOOL
Controls the handling of exclusive locks. Possible values are:
ABAP_TRUE (existing exclusive locks are released (default
setting)).
ABAP_FALSE (existing exclusive locks are not released).
AFFECT_SERVER of type SHM_AFFECT_SERVER (for transactional
areas only)
Controls cross-server invalidation. Possible values are:
CL_SHM_AREA= AFFECT_LOCAL_SERVER (only the area instance versions
of the current application server are invalidated (default setting)).
CL_SHM_AREA= AFFECT_ALL_SERVERS (the area instance versions of
all application servers are invalidated).
CL_SHM_AREA= AFFECT_ALL_SERVERS_BUT_LOCAL (the area instance
versions of all application servers are invalidated, apart from the
current application server). This enables changes to be made to areas of
the current application server directly, without the database having to
create the entire area again.
Return Code
RC of type SHM_RC
Possible values in non-transactional areas:
CL_SHM_AREA= RC_DONE if an active or an obsolete area instance
version was set to expired. If the value ABAP_TRUE was passed to
TERMINATE_CHANGER (even if an exclusive lock was released).
CL_SHM_AREA= RC_NOTHING_TO_BE_DONE , if no active or obsolete area
instance versions exist and (if the value ABAP_TRUE was passed to
TERMINATE_CHANGER ) if no exclusive lock exists.
CL_SHM_AREA= RC_INSTANCE_NAME_NOT_FOUND if no area instance of
the specified name exists.
In transactional areas, RC always has the value
CL_SHM_AREA= RC_NOTHING_TO_BE_DONE .
Exceptions
CX_SHM_PARAMETER_ERROR
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 of type SHM_CLIENT
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 .
TERMINATE_CHANGER of type ABAP_BOOL
Controls the handling of exclusive locks. Possible values are:
ABAP_TRUE (existing exclusive locks are released (default
setting)).
ABAP_FALSE (existing exclusive locks are not released).
AFFECT_SERVER of type SHM_AFFECT_SERVER (for transactional
areas only)
Controls cross-server invalidation. Possible values are:
CL_SHM_AREA= AFFECT_LOCAL_SERVER (only the area instance versions
of the current application server are invalidated (default setting)).
CL_SHM_AREA= AFFECT_ALL_SERVERS (the area instance versions of
all application servers are invalidated).
CL_SHM_AREA= AFFECT_ALL_SERVERS_BUT_LOCAL (the area instance
versions of all application servers are invalidated, apart from the
current application server). This enables changes to be made to areas of
the current application server directly, without the database having to
create the entire area again.
Return Code
RC of type SHM_RC
Possible values in non-transactional areas:
CL_SHM_AREA= RC_DONE if at least one active or obsolete area
instance version was set to "expired". If the value ABAP_TRUE was
passed to TERMINATE_CHANGER (even if one or more exclusive locks
were released).
CL_SHM_AREA= RC_NOTHING_TO_BE_DONE if no active or obsolete area
instance versions exist and (if the value ABAP_TRUE was passed to
TERMINATE_CHANGER ) if no exclusive lock exists.
In transactional areas, RC always has the value
CL_SHM_AREA= RC_NOTHING_TO_BE_DONE .
Exceptions
CX_SHM_PARAMETER_ERROR
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 of type SHM_CLIENT
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
INFOS of type SHM_INST_INFOS
SHM_INST_INFOS is an internal table of row type SHM_INST_INFO
with the following components:
CLIENT of type MANDT . The client ID if areas are
client-specific. Initial if areas are cross-client.
NAME of type SHM_INST_NAME (area name). This name is
CL_SHM_AREA= DFAULT_INSTANCE for areas with the default name.
VERSIONS_IN_BUILD of type SHM_VERS_CNT . The number of area
instance versions that are currently being built. Possible values are 0
or 1.
VERSIONS_ACTIVE of type SHM_VERS_CNT . The number of
currently active area instance versions. Possible values are 0 or 1.
VERSIONS_OBSOLETE of type SHM_VERS_CNT . The number of
obsolete area instance versions. Possible values range from 0 to the
maximum number of area instance versions (component MAX_VERSIONS
of the PROPERTIES attribute of the CL_SHM_AREA class).
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
INST_NAME of type SHM_INST_NAME
Name of the area instance version. The name is optional. The default
value is the value of constant CL_SHM_AREA= DEFAULT_INSTANCE .
Exceptions
CX_SHM_BUILD_FAILED
An error occurred when the area constructor was executed.
CX_SHMA_NOT_CONFIGURED
No area constructor class is bound to the area class.
CX_SHMA_INCONSISTENT
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
INST_NAME of type SHM_INST_NAME
Name of the area instance version. The name is optional. The default
value is the value of constant CL_SHM_AREA= DEFAULT_INSTANCE .
CLIENT of type SHM_CLIENT
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 .
AFFECTING_LOCAL_SERVER of type ABAP_BOOL
Controls whether the change in state is also performed on the current
application server. Possible values are:
ABAP_TRUE . The active area instance version is set to obsolete on
the current application server. This setting can be used if the content
of the area instance is to be changed using the area constructor, after
the database content has been changed.
ABAP_FALSE . The active area instance version is not set to
obsolete on the current application server (default setting). This means
that a new version can remain on an application server while only the
current versions on other servers are invalidated.
Exceptions
CX_SHM_PARAMETER_ERROR
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 of type SHM_CLIENT
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 .
AFFECTING_LOCAL_SERVER of type ABAP_BOOL
Controls whether the change in state is also performed on the current
application server. Possible values are:
ABAP_TRUE . The active area instance versions are set to obsolete
on the current application server.
ABAP_FALSE . The active area instance versions are not set to
obsolete on the current application server (default setting).
Exceptions
CX_SHM_PARAMETER_ERROR
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
REF TO of type area_root_class , where
area_root_class is the area
root class of the area.
Exceptions
CX_SHM_WRONG_HANDLE
The method was called using an area handle with a shared lock or an area
handle in which the DETACH_COMMIT method failed.
CX_SHM_INITIAL_REFERENCE
The reference variable passed to ROOT is initial.
Documentation extract taken from SAP system, � Copyright SAP AG. All rights reserved