1C:Enterprise 8.3. Developer Guide. Contents
WORK WITH DATA
9.1. OBJECT LOCKS
As it works with object data (catalogs, documents, account, etc.), the 1C:Enterprise system provides two types of object locks: pessimistic and optimistic. These allow you to modify entire objects with multiple simultaneous users.
9.1.1. Pessimistic Lock
A pessimistic lock of database objects prevents other sessions or this session from modifying the object data until the lock is released (automatically or using the 1C:Enterprise script methods).
Generally, pessimistic locks are used by 1C:Enterprise to lock objects edited in a form. At the same time the developer can enable this feature using the 1C:Enterprise script.
In 1C:Enterprise, pessimistic locks are applied with the help of application object form extensions. As soon as the user starts modifying an object in a form, the form extension enables a pessimistic lock. If another user attempts to edit this object while the lock is active, a message appears explaining that the object could not be locked. When the user who edited the object closes the object form, the form extension releases the pessimistic lock.
If you want to apply the standard form behavior to the non-standard object form, you can use the form's LockFormDataForEdit() method to enable a pessimistic lock and the UnlockFormDataForEdit() method to release the lock.
The developer can enable a pessimistic lock using the global context LockDataForEdit() method. Two options of pessimistic lock are available:
Form ID is specified. In this case a lock is active while the form exists; the lock is automatically released when the form is closed or the session is terminated. You can also release the lock using the global context UnlockDa- taForEdit() method with the form ID specified when setting the lock;
No form ID is specified. In this case the applied lock is not associated with any form. It is automatically released when a session is terminated or control return from the server or transaction is complete (if the lock was placed on the transaction). You can also release the lock using the global context UnlockDataForEdit() method without specifying the form ID.
Please note, however, that locking an object does not guarantee it cannot be updated or removed from the database. Therefore, to ensure the locked object cannot be modified, another session must attempt to lock it, too, before the modification operation. An attempt to lock a previously locked database object raises an exception that can be processed using Try … Except … EndTry.
&AtServer
Function SampleModification()
ProductRef = Catalogs.Goods.FindByCode("000000001");
Try
LockDataForEdit(ProductRef);
// Object data can be modified
// ...
ProductObject = ProductRef.GetObject();
ProductObject.Description = "New description";
ProductObject.Write();
Return True;
Except
// Object data cannot be modified
Message = New UserMessage;
Message.Text = "Object data already locked";
Message.Message();
Return False;
EndTry;
EndFunctionPlease remember that concurrent attempts to lock an object with form ID and without it are incompatible.
ProductRef = Catalogs.Nomenclature.FindByCode(1); LockDataForEdit(ProductRef); Try LockDataForEdit(ProductRef, , FormID); Except // exception due to lock incompatibility EndTry;
The developer can release a pessimistic lock using the global context UnlockDataForEdit() method.
9.1.2. Pessimistic Lock and Transactions
Object lock operations affect other object lock operations only and have no effect on data operations or transactions.
An attempt to lock a previously locked database object raises an exception that can be processed and does not result in an automatic transaction rollback. If execution of the LockDataForEdit() method within the transaction raises an exception, it can be processed using Try … Except … EndTry and does not require a transaction rollback.
Object locks enabled in the course of a transaction are released when the transaction is complete if no form ID is specified for the lock.
9.1.3. Optimistic Lock
An optimistic lock prevents an object from being written to the database if the object was modified in the database after it had been read.
Technically, an optimistic lock is a check performed before the object is written to the database.
When an object of the 1C:Enterprise script reads data from the database, it also reads the version of the object stored in the database.
If the object data in the database has been modified (e.g., by another user) before the current user updates the data (sets a pessimistic lock), it changes the object version number stored in the database. When the user attempts to write the object, the object version in memory is checked against the version in the database. Since the versions do not match, a warning appears explaining that the object version has changed or the object has been removed, i.e. an optimistic lock is enabled.
The optimistic lock guarantees that the user's changes do not overwrite the changes made by other sessions or other application objects of the same session.
9.2. TRANSACTIONS
Regardless of the selected 1C:Enterprise version (file mode version or client/server mode), the system works with information stored in the database through transactions.
A transaction is a sequence of data manipulation operations that is atomic in terms of its impact on the database. Transactions are "all-or-nothing" in nature; they transition the database from one status to another in its entirety. If one of the transaction actions cannot be completed for some reason or the system has encountered an error, the database returns to its pre-transaction status (the transaction is rolled back).
Transactions can be used either by the 1C:Enterprise or by the developer as he/she creates modules.
1C:Enterprise invokes transactions implicitly every time database information is modified. Thus, all event handlers located in object and record set modules and related to database data modification are called within a transaction. The following types of objects are also read in transactions: ExchangePlanObject, DocumentObject, CatalogObject, ChartOfCharacteristicTypesObject, ChartOfAccountTypesObject, ChartOfAccountsObject, BusinessPro- cessObject, TaskObject, SequenceRecordSet, InformationRe- gisterRecordSet, AccumulationRegisterRecordSet, AccountingRegisterRecordSet, CalculationRegisterRecordSet, RecalculationRecordSet. In the managed transaction lock mode (see page 1-515), a shared lock is applied based on the recordset recorder value and filter values for the independent information register recordset.
Additionally the developer can work with transactions explicitly. In this case global context procedures BeginTransaction(), CommitTransaction() and RollbackTransaction() are used.
9.2.1. Explicit Calls to Transactions
The BeginTransaction() procedure can be used to open a transaction. All subsequent changes to database information made by other operators can be either committed in their entirety or rolled back.
All changes can be committed using the CommitTransaction() procedure.
To cancel all changes made to an open transaction, use the RollbackTransaction() procedure. The CommitTransaction() method is used to accept all applied changes. To cancel all changes applied in an opened transaction you can use the RollbackTransaction() method. If the number of BeginTransaction() method calls exceeds the number of CommitTransaction() method or RollbackTransaction() method calls, the system implicitly calls the RollbackTransaction() method in the following cases:
When 1C:Enterprise script execution is finished (event handler, external connection, automation server).
When control is transferred from the server to the client.
If the number of CommitTransaction() method or RollbackTransaction() method calls exceeds the number of BeginTransaction() method calls, an exception will be generated for every excessive call of CommitTransaction() or RollbackTransaction().
Therefore, a general layout of use of transactions can look like the following:
BeginTransaction(); // A sequence of operators … Try // A sequence of executed operators … Except RollbackTransaction(); EndTry; // A sequence of executed operators … CommitTransaction();
As you apply this procedure, please remember that errors you encounter when you work with the database can be processed by the system in different ways.
Generally, all database errors fall into one of two categories:
Non-recoverable errors
Recoverable errors
Non-recoverable errors can disturb normal operation of 1C:Enterprise system, e.g. by corrupting data. A non-recoverable error always results in 1C:Enterprise termination.
If a non-recoverable error occurs in the course of a transaction, all changes made within this transaction are rolled back by the system.
Recoverable errors do not cause major breakdowns in 1C:Enterprise operation. In case of a recoverable error the system can continue functioning. The operation that caused the error is aborted and an exception is raised; the latter can be captured and processed using Try … Except … EndTry.
If a recoverable error occurs in the course of a transaction, the system does not automatically abort the transaction, allowing the developer to resolve the issue.
The nature of the error defines the issue resolution scenario.
If the error is not related to the database, the transaction can be continued and the module operation does not have to be terminated. If necessary, the developer can cancel the transaction or, on the contrary, carry it on if the error does not interfere with the transaction's atomic nature.
If, however, the exception is due to a database error, the system registers the error state of the transaction and continuing or committing the transaction becomes impossible. The only database operation available to the developer in this case is a transaction rollback. The developer can re-try the transaction later.
A sample code that uses this approach to writing data to the database can look like the following.
// Abort write attempts flag Written = False; // Write attempts in a loop While Not Written Do Try BeginTransaction(); Data.Write(); CommitTransaction(); // If the transaction is successfully committed, abort write attempts Written = True; Except // In case of failure abort the current transaction and // start the next attempt in a new transaction RollbackTransaction(); EndTry; EndDo;
9.2.2. Nested Transaction Call
You can invoke BeginTransaction(), CommitTransaction() and RollbackTransaction() procedures within a running transaction. For example, you can use the following call procedure:
BeginTransaction(); … // Nested transaction call BeginTransaction(); … CommitTransaction(); … // Nested transaction call BeginTransaction(); … CommitTransaction(); … CommitTransaction();
However, calls of this type do not start a new transaction within the current transaction.
IMPORTANT!
1C:Enterprise does not support nested transactions.
It means the only active transaction is always the top-level transaction. All transactions invoked within the open transaction belong to this transaction rather than become nested transactions. Therefore, a rollback of a nested transaction ultimately rolls back the entire top-level transaction rather than the nested transaction only. At the same time commitment of a nested transaction is ignored.
9.2.3. Impact of Transactions on Program Objects
In the most general case, program objects used in 1C:Enterprise are completely transparent to database transactions. In other words, you can invoke database transactions when various program object methods are executed; however, actions involved in a database transaction rollback generally have no impact on the corresponding program objects.
It means that when database transactions are rolled back the developer is responsible for making changes to the corresponding program objects (if required). This can be achieved by re-reading all object data or changing certain attributes of the program object (e.g., if required for interface display purposes).
This rule has exceptions. Due to a very special application nature of 1C:Enterprise program objects, a rollback of database changes can, in some cases, affect property values of the corresponding program objects. It happens in the following cases:
When a transaction is rolled back, the document posted flag recovers the pretransaction value;
If an object is created and written in a transaction, the transaction rollback clears the reference value;
If an object is created outside the transaction and is written using its autogenerated code/number, the transaction rollback clears the code/number.
9.3. MANAGED LOCKS
9.3.1. General Information on Locks
Ideally, in any DBMS transactions should isolate changes made to the database. In other words, multiple transactions that modify data concurrently should be independent.
The simplest solution to this issue is execution of transactions in a sequence. It means every subsequent transaction is executed after the previous transaction has completed.
However, in practice, using this approach in multi-user systems significantly reduces the system performance. Therefore, mechanisms that support concurrent execution of multiple transactions are used.
To make concurrent transactions possible, transactions are isolated at several levels. At the lowest level transactions can affect each other a lot. At the top level they are entirely isolated.
Thus, greater isolation of transactions means more overhead and slow system performance.
Transactions can be isolated using locks placed on the data used in transactions. The level of isolation defines the lock types applied to various database objects and the lock duration.
In 1C:Enterprise, you can work with data in one of two modes:
In a transaction
Outside a transaction
When you work with data outside the transaction, you are only allowed to read the data. This approach ensures maximum speed and concurrency of data read operations. Therefore, any data read operation outside the transaction is unreliable. It means a read operation of this type can return obsolete data or uncommitted changes made by another transaction, i.e. it does not account for data locks set by other transactions.
When you work with data within a transaction, you can perform any data read and modification operations.
You should follow the following rules:
Data read operations must be reproducible, i.e. any subsequent data read operation with the same selection criterion must return the same result;
The read operation result must contain the most recent data. It means no other transaction can change the data read by the current transaction until the latter is completed;
The read operation result must not include uncommitted changes of database data.
9.3.2. Managed Locks
1C:Enterprise allows interacting with the database in two modes within a transaction: automatic lock mode and managed lock mode.
The basic difference between these two modes is described below. The auto-lock mode does not require the developer to manage locks within transactions in any way in order to ensure the aforementioned rules of working with data in transactions are followed. These rules are followed by the 1C:Enterprise platform by applying certain levels of transaction isolation in a particular DBMS. This mode is the easiest for the developer; however, in certain cases (e.g., when many users work with the system concurrently and actively) the transaction isolation level applied by the DBMS cannot ensure sufficient concurrency of work which leads to multiple lock collisions.
If you select the managed lock mode, 1C:Enterprise uses a much lower level of DBMS transaction isolation, thus improving concurrency of application user operations. However, unlike the auto-lock mode, this transaction isolation mode cannot ensure rules for working with data in transactions are met (e.g., reproducibility of data read operations in a transaction is not guaranteed). Therefore, in the managed lock mode, the developer has to manage locks applied within transactions.
A summary of differences between the auto-lock and managed lock modes is provided in the table below:
|
|
Lock Type |
Transaction Isolation Level |
|
Auto-locks |
|
|
|
File Database |
Tables |
Serializable |
|
MS SQL Server |
Records |
Repeatable Read or Serializable |
|
IBM DB2 |
Records |
Repeatable Read or Serializable |
|
PostgreSQL |
Tables |
Serializable |
|
Oracle Database |
Tables |
Serializable |
|
Managed Locks |
|
|
|
File Database |
Tables |
Serializable |
|
MS SQL Server 2000 |
Records |
Read Committed |
|
MS SQL Server 2005 and later |
Records |
Read Committed Snapshot |
|
IBM DB2 |
Records |
Read Committed |
|
PostgreSQL |
Records |
Read Committed |
|
Oracle Database |
Records |
Read Committed |
NOTE
It is recommended to develop applications in the managed lock mode to get the most of your DBMS. Application automatic mode is used for compatibility with previous application versions and it is not recommended for production operation.
The system behavior during irresponsive reading (e.g. when dynamic lists are used or reports are made) also varies depending on the given lock mode. The table below provides a summary of the differences of irresponsive reading in different (automatic or managed) lock modes.
|
|
Reading outside the transaction |
|
Automatic Lock |
|
|
File database |
"Dirty" reading |
|
MS SQL Server |
"Dirty" reading |
|
IBM DB2 |
"Dirty" reading |
|
PostgreSQL |
Consistent reading |
|
Oracle Database |
Consistent reading |
|
Managed Lock |
|
File database "Dirty" reading
MS SQL Server 2000 "Dirty" reading
MS SQL Server 2005 and later Consistent reading
IBM DB2 "Dirty" reading
PostgreSQL Consistent reading
Oracle Database Consistent reading
9.3.3. Setting Lock Mode in Configuration
Configuration has the Data lock control mode property. Each configuration object also has the Data lock control mode property.
The data lock control mode for the entire configuration can be set to Automatic, Managed (used by default for new configurations) and Automatic and managed. Automatic and Managed enable the respective lock control mode for all the configuration objects, regardless of their values. Automatic and managed means that a particular configuration object will use the mode selected in its Data lock control mode property: Automatic or Managed.
It is important to note that the data lock control mode specified for a metadata object is set for the transactions initiated by 1C:Enterprise when it works with the object data (e.g., when it modifies the object data).
If, however, an object write operation is performed within a developer-initiated transaction (BeginTransaction() method), the data lock control mode is defined by the LockMode parameter of the BeginTransaction() method rather than by the metadata object's Data lock control mode property.
By default, the LockMode parameter is set to DataLockControlMode.Automatic; therefore, if you want to use the managed lock mode in an explicit transaction, select the DataLockControlMode.Managed value.
9.3.4. Work with Managed Locks Through
1C:Enterprise Script
To manage locks within transactions, you can use the 1C:Enterprise script DataLock object. You can create an instance of this object in the wizard and use it to describe the required lock namespaces and modes. You can set all the locks you have created using the Lock() method of the DataLock object. If this method is executed in a transaction (explicit or implicit), locks are set and auto-released when the transaction is completed. If the Lock() method is executed outside a transaction or inside a transaction in automatic lock management mode, an exception will be thrown.
The DataLock object is a collection of data lock items, each describing locks of a single lock namespace. Lock namespaces are defined in the 1C:Enterprise platform and match the structure of configuration application objects. Each lock namespace has fields defined in the platform and available for analysis when locks are set.
The following lock namespace names and field names are valid.
Lock
Namespace Name Lock
Namespace Field Name
|
Catalog.<Name> Ref; <field name> Document.<Name> Ref; <field name> ExchangePlan.<Name> Ref; <field name> ChartOfAccounts.<Name> Ref; <field name> BusinessProcess.<Name> Ref; <field name> Task.<Name> Ref; <field name> ChartOfCalculationTypes.<Name> Ref; <field name> ChartOfCharacteristicTypes.<Name> Ref; <field name> InformationRegister.<Name>.RecordSet – Recorder only for an information register that is subordinate to |
|
|
|
a recorder |
|
|
|
InformationRegister.<Name> |
Period, if any; <Dimension name> |
|
|
AccumulationRegister.<Name>.RecordSet |
Recorder |
|
|
AccumulationRegister.<Name> |
Period; <Dimension name> |
|
|
AccountingRegister.<Name>.RecordSet |
Recorder |
|
|
AccountingRegister.<Name> |
Period; <Dimension name> |
|
|
|
<RecordType> – |
Accountin- |
|
gRecordType system enumeration value; Account; ExtDimensions<N>; <Extra dimension types> |
||
|
CalculationRegister.<Name>.RecordSet |
Recorder |
|
|
CalculationRegister.<Name> |
RegistrationPeriod; ActionPeriod; <Dimension name> |
|
|
Recalculation.<Name>.RecordSet |
RecalculationObject |
|
|
Sequence.<Name>.RecordSet |
Recorder |
|
|
Sequence.<Name> Constant.<Name> |
<Dimension name> |
|
Where <field name> – is a name of the field that can be used to set a managed lock. A list of valid fields (that can be used to set a managed lock) shall be set in the Data lock fields property for the following objects:
catalogs
documents
charts of characteristic types
charts of accounts
charts of calculation types
exchange plans
business processes
tasks
We recommend that you do not set locks by attributes (and common attributes) of the following types: an unlimited length string, value storage, type description. This concerns the following objects: catalogs, documents, charts of characteristic types, charts of calculation types, charts of accounts, business processes, tasks, and exchange plans. Locks by Predefined and PredefinedDataName fields cannot be set in catalogs, charts of characteristic types, charts of calculation types, and charts of accounts.
If a managed transaction lock is set to the AccountingRegister.<Name> space and an external dimension value is set by a reference to a characteristics, the characteristics should be one of the external dimensions of this account in the chart of accounts. If no external dimension for the account is set, an error will be thrown.
In each lock namespace, you can set any number of criteria for the fields used to select records to be locked. The criteria can specify that the field value must match the selected value or must fall within the selected range.
You can use two methods to set the criteria:
Specify the field name and value explicitly (use the SetValue() method of the DataLockItem object);
Specify the data source that contains the required values (use the DataSource property of the DataLockItem object).
When you specify the field value explicitly, the SetValue() method receives the field name and value as its parameters:
Lock = New DataLock;
LockItem = Lock.Add( "Catalog.Shop");
LockItem.SetValue("Code", 100);
LockItem.Mode = DataLockMode.Exclusive;
Lock.Lock();
Lock = New DataLock;
LockItem = Lock.Add("AccumulationRegister.ProductsInStock");
LockItem.SetValue("Quality", Catalogs.Quality.FindByCode("1"));Please keep in mind that a single register record can be locked twice: first, you can lock the record and then you can lock the set that owns this record.
When an object for which the field lock is available is deleted or changed, locking is performed by the Reference field and by all fields specified in the Data lock fields property. If an object is changed, it is locked by "old" field values (which existed before writing) and by "new" values (which are included in the object to be written).
You can also pass the 1C:Enterprise script Range object as a value; this object is created in the wizard and defines the upper and lower limits of the range (the limit values are also included in the range).
If you use a data source, specify a value for the DataSource property and then use the UseFromDataSource() method to map the lock namespace fields with the data source fields:
Lock = New DataLock;
LockItem = Lock.Add("AccumulationRegister.GoodsInStock");
LockItem.DataSource = DocumentObject.Returnables;
LockItem.UseFromDataSource("Nomenclature", "Nomenclature");
LockItem.UseFromDataSource("Warehouse", "Warehouse");You can use the following as a data source:
query result
tabular section
record set
value table
Therefore, when you map fields, the following items are used as source field names:
Query result column names
Tabular section attribute names
Dimension names
Value table column names
The Range object can also serve as a data source field value.
You can set one of two lock modes for each lock item:
Shared mode
Exclusive mode
To set the lock mode, use the Mode property of the DataLockItem object.
Below is a table of managed lock compatibility:
|
|
Shared lock |
Exclusive lock |
|
Shared lock |
+ |
- |
|
Exclusive lock |
- |
- |
In the shared lock mode, the locked data cannot be modified by another transaction until the current transaction is completed.
In the exclusive lock mode, the locked data cannot be modified by another transaction until the current transaction is completed and cannot be read by another transaction placing a shared lock on the same data.
Considering compatibility of actions within a transaction, you should remember that in addition to explicit managed locks set by the user, 1C:Enterprise can also set implicit managed exclusive locks as it writes data within the transaction. When you read object data from the database (retrieve the object or follow a link), transactional object lock is not applied. If you need the lock, you should use the 1C:Enterprise script to set it before calling the object.
Below is a table of compatibility for actions performed within a transaction when the managed lock mode is used.
|
Lock |
Mode |
NL |
|
SL |
|
EL |
|
|
R |
W |
R |
W |
R |
W |
||
|
NL |
R |
+ |
+ |
+ |
+ |
+ |
+ |
|
W |
+ |
- |
- |
- |
- |
- |
|
|
SL |
R |
+ |
- |
+ |
- |
- |
- |
|
W |
+ |
- |
- |
- |
- |
- |
|
|
EL |
R |
+ |
- |
- |
- |
- |
- |
|
W |
+ |
- |
- |
- |
- |
- |
Where:
R – read
W – write
NL – no lock
SL – shared lock
EL – exclusive lock
9.3.5. Automatic and Managed Mode: Features
The Automatic and managed lock control mode is used to resolve issues related to concurrent use of some configuration objects.
Assume you have a large configuration that is hard to transition to the managed lock mode all at once. However, a couple of documents always stick out when multiple users work with them simultaneously. In this case you can set the Automatic and managed mode for the entire configuration and then select the Managed mode for the documents and the configuration objects that are affected when the documents are written. Thus, you can set up the managed lock mode for the documents, while the rest of the configuration will still function in the automatic lock control mode.
When you work in the Automatic and managed lock control mode, you should be aware of two peculiarities:
Regardless of the mode specified for the current transaction, the system applies managed locks;
The lock control mode is defined by the top-level transaction. In other words, if by the time you initiate a transaction another transaction has been started, the new transaction can only run in the mode specified for the running transaction.
Review the above peculiarities in more detail.
The first peculiarity is that the system places additional managed locks on the data written in a transaction, even if the transaction already uses the automatic lock control mode. It means transactions that run in the managed lock mode can conflict with transactions executed in the automatic lock control mode.
The second peculiarity is that the lock control mode specified for a metadata object in the configuration or explicitly set at the transaction start (in the BeginTransaction() method parameter) is only a recommended mode. The actual lock control mode for a transaction depends on whether this transaction call is the first or another transaction has already been initiated in the current 1C:Enterprise session.
For example, if you want to manage locks as you write register record sets and post a document, the managed lock mode has to be placed on both the register and the document, since register record sets will be written in a transaction opened when you write the document.
Four combinations of lock control modes are valid in a transaction, as demonstrated in the table below:
|
Existing Transaction Mode |
New Transaction Mode |
Result |
|
Automatic |
Automatic |
The new transaction runs in the automatic mode |
|
Automatic |
Managed |
The new transaction runs in the automatic mode |
|
Managed |
Automatic |
An exception is raised |
|
Managed |
Managed |
The new transaction runs in the managed mode |
9.3.6. Working with multiple managed locks
It should be remembered that if over 100,000 locks are applied to one scope, lock escalation may occur. Lock escalation means that the whole space is locked. Should independent separators be used, then escalation is applied to one set of separator values:
The whole space is only blocked within the separator values.
Escalation does not impact sessions with other separator values.
9.3.7. Configuration Modification When Switching to Managed Lock Mode
When you switch to the managed lock mode partially or completely, you have to refine the application. It means you have to find code blocks that require managed locks and set the managed data lock mode in these blocks. You can use one of two methods:
Use the DataLock object;
Use the LockForUpdate property for accumulation and accounting register record sets. The required managed lock is auto-set by the platform if the register record set to be written has this property set to True.
9.3.7.1. Identification of Code Blocks to Be Refined
Managed locks are required for code blocks that meet one of the following conditions:
Data that are being read needs to be modified later;
A consistent collection of data (included in multiple objects) is being read and data consistency has to be preserved. In this case the collection data have to be locked once or in a sequence as its individual items are being read. If a data item is read once, is not logically associated with other data items and will not be modified in the same transaction, you do not have to lock it;
It is important to ensure the data are not modified until the transaction is completed. For example, some data read within the transaction can be read again and it is important to preserve it intact.
A typical example of such an operation is a request to obtain product balances in the document posting module.
9.3.7.2. Managed Lock Mode Selection
The lock mode for the operations described above should be selected based on the following prerequisites:
Exclusive lock mode should be placed on the data that are to be modified within the same transaction. It prevents lock collisions;
Shared lock mode should be placed on the data that are read-only and are not modified, but require a lock.
9.3.7.3. Sample Configuration Refinement
Below is an example of setting managed locks in the record set module of the GoodsInStock accumulation register.
First, create a managed lock:
Lock = New DataLock;
Then analyze the query text generated in the module and create the required locks.
Exclusive Lock for GoodsInStock Register
When you run the record set module, a query is generated; it contains the following fragment:
// … LEFT JOIN AccumulationRegister.GoodsInStock.Balance(, Nomenclature IN (SELECT DISTINCT Nomenclature FROM Document.GoodserviceSales.Goods WHERE Ref = &DocumentRef)) // …
In this case the following locks are required:
LockGoodsInStock1 = Lock.Add("AccumulationRegister.GoodsInStock");
LockGoodsInStock1.Mode =
DataLockMode.Exclusive;
LockGoodsInStock1.DataSource = DocumentObject.Goods;
LockGoodsInStock1.UseFromDataSource("Nomenclature", "Nomenclature");
LockGoodsInStock1.UseFromDataSource("NomenclatureCharacteristic","NomenclatureCharacteristic");
LockGoodsInStock1.UseFromDataSource("Warehouse", "Warehouse");Shared Lock for GoodsInReserveInStock Register
When you run the module, a query is generated; it contains the following fragment:
// … LEFT JOIN AccumulationRegister.GoodsInReserveInStock.Balance(, Nomenclature IN (SELECT DISTINCT Nomenclature FROM Document.GoodserviceSales.Goods WHERE Ref = &DocumentRef)) // …
In this case the following locks are required:
LockGoodsInReserveInStock1 = Lock.Add("AccumulationRegister.GoodsInReserveInStock");
LockGoodsInReserveInStock1.Mode = DataLockMode.Shared;
LockGoodsInReserveInStock1.DataSource = DocumentObject.Goods;
LockGoodsInReserveInStock1.UseFromDataSource("Nomenclature", Nomenclature");
LockGoodsInReserveInStock1.UseFromDataSource("NomenclatureCharacteristic","NomenclatureCharacteristic");
LockGoodsInReserveInStock1.UseFromDataSource("Warehouse", "Warehouse");Shared Lock for GoodsToBeTransferredFromWarehouse Register
When you run the module, a query is generated; it contains the following fragment:
// … LEFT JOIN AccumulationRegister.GoodsToBeTransferredFromWarehouse.Balance(, Nomenclature IN (SELECT DISTINCT Nomenclature FROM Document.GoodserviceSales.Goods WHERE Ref = &DocumentRef)) // …
In this case the following locks are required:
LockGoodsToBeTransferredFromWarehouse1 = Lock.Add("AccumulationRegister.GoodsToBeTransferredFromWarehouse");
LockGoodsToBeTransferredFromWarehouse1.Mode = DataLockMode.Shared;
LockGoodsToBeTransferredFromWarehouse1.DataSource = DocumentObject.Goods;
LockGoodsToBeTransferredFromWarehouse1.UseFromDataSource("Nomenclature", "Nomenclature");
LockGoodsToBeTransferredFromWarehouse1.UseFromDataSource(
"NomenclatureCharacteristic","NomenclatureCharacteristic");
LockGoodsToBeTransferredFromWarehouse1.UseFromDataSource("Warehouse", "Warehouse");Locks for Returnables Tabular Section Exclusive Lock for GoodsInStock Register
When you run the module, a query is generated; it contains the following fragment:
// … LEFT JOIN AccumulationRegister.GoodsInStock.Balance(, Nomenclature IN (SELECT DISTINCT Document.GoodserviceSales.Returnables.Nomenclature FROM Document.GoodserviceSales.Returnables WHERE Document.GoodserviceSales.Returnables.Ref = &DocumentRef) AND Quality = &New) // …
In this case the following locks are required:
|
LockGoodsInStock2 = Lock.Add("AccumulationRegister.GoodsInStock"); |
|
|
|
|
|
|
|
LockGoodsInStock2.Mode = DataLockMode.Exclusive; |
|
|
|
|
|
|
|
LockGoodsInStock2.DataSource = DocumentObject.Returnables; |
|
|
|
|
|
|
|
LockGoodsInStock2.UseFromDataSource("Nomenclature", "Nomenclature"); |
|
|
|
LockGoodsInStock2.UseFromDataSource("Warehouse", "Warehouse"); |
|
|
|
LockGoodsInStock2.SetValue("Quality", Catalogs.Quality.FindByCode("1")); |
Locks for Returnables Tabular Section Shared Lock for GoodsInReserveInStock Register
When you run the module, a query is generated; it contains the following fragment:
|
// … |
|
|
|
LEFT JOIN |
|
|
|
AccumulationRegister.GoodsInReserveInStock.Balance(, |
|
|
|
Nomenclature IN (SELECT DISTINCT |
|
|
|
Document.GoodserviceSales.Returnables.Nomenclature |
|
|
|
FROM |
|
|
|
Document.GoodserviceSales.Returnables |
|
|
|
WHERE |
|
|
|
Document.GoodserviceSales.Returnables.Ref = &DocumentRef)) AS Reserves |
|
|
|
// … |
In this case the following locks are required:
|
LockGoodsInReserveInStock2 = Lock.Add("AccumulationRegister.GoodsInReserveInStock"); |
|
|
|
|
|
|
|
LockGoodsInReserveInStock2.Mode = DataLockMode.Shared; |
|
|
|
|
|
|
|
LockGoodsInReserveInStock2.DataSource = DocumentObject.Returnables; |
|
|
|
LockGoodsInReserveInStock2.UseFromDataSource("Nomenclature", "Nomenclature"); |
|
|
|
LockGoodsInReserveInStock2.UseFromDataSource("Warehouse", "Warehouse"); |
Locks for Returnables Tabular Section Shared Lock for GoodsToBeTransferredFromWarehouse Register
When you run the module, a query is generated; it contains the following fragment:
// … LEFT JOIN AccumulationRegister.GoodsToBeTransferredFromWarehouse.Balance(, Nomenclature IN (SELECT DISTINCT Document.GoodserviceSales.Returnables.Nomenclature FROM Document.GoodserviceSales.Returnables WHERE Document.GoodserviceSales.Returnables.Ref = &DocumentRef)) AS GoodsToBeTransferred // …
In this case the following locks are required:
LockGoodsToBeTransferredFromWarehouse2 = Lock.
Add("AccumulationRegister.GoodsToBeTransferredFromWarehouse");
LockGoodsToBeTransferredFromWarehouse2.Mode = DataLockMode.Shared;
LockGoodsToBeTransferredFromWarehouse2.DataSource = DocumentObject.Returnables;
LockGoodsToBeTransferredFromWarehouse2.UseFromDataSource("Nomenclature", "Nomenclature");
LockGoodsToBeTransferredFromWarehouse2.UseFromDataSource("Warehouse", "Warehouse");After all the required locks are created, you must lock the data listed above:
Lock.Lock(); // … followed by the previous module text
9.4. EXCLUSIVE MODE
Exclusive mode is a special database access mode when only one session can be used for working with a database. The exclusive mode can be used when major changes agreed to need to be implemented in an infobase that cannot be executed at the transaction level. The impact of other sessions on the results of changes should be limited. Some script methods (the DeleteObjects() method) and using Designer need to be performed in exclusive mode.
To set or release the exclusive mode, use the SetExclusiveMode() global context method. To check whether the exclusive mode is set, use the ExclusiveMode() method. It is not possible to change the exclusive mode status if a transaction (explicit or implicit) is active.
If the exclusive mode is set, no new sessions can be created with this infobase. Moreover, the exclusive mode cannot be set if multiple sessions work with an infobase. The exclusive mode does not support setting managed locks (and any attempts to set them are ignored).
When working in the exclusive mode, you should always bear the following in mind: if a background task is launched from the session that set the exclusive mode, the background task launched "takes away" the exclusive mode from the parent session. During a background task, the parent session cannot change any data in an infobase. The exclusive mode will return to the parent session when the launched background task is completed.