
Forms		Concurrency

Concurrency

Overview

This is intended for users who are using a database concurrently with other users. The concurrent environment is controlled by a program called MASTER. To use SirForms with concurrency, specify the name of the MASTER process on the MST = parameter at start-up. In concurrent mode, multiple users can simultaneously enter data and read data from the same database.

A form that has been designed for single user running, runs without alteration in concurrent mode. The defaults provide a reasonable concurrent user environment. If you specify particular features such as locking, which only have meaning in a multiple user environment, these specifications can be left in the form for single user operation and have no effect. The same form definition can run interchangeably in both environments.

When using a form, it appears the same whether or not you are using concurrency. While a database is under MASTER's control, that database can only be updated through MASTER. It cannot be updated through the non-concurrent products. The non-concurrent products can read the database, but they cannot update it.

There may be a number of MASTER programs on a system, and the one to use is specified through the MST= parameter on the execution statement.

When a MASTER starts, it does not use any databases, and once the last user has stopped using a database, MASTER releases it. MASTER could be on a system for hours or days doing no work and taking virtually no resources, waiting for a request from a user program to attach to a particular database.

When using a concurrent product through MASTER, information is at the latest possible level. If you use a non-concurrent product in read-only mode while the database is still controlled by MASTER, information is as per the last "Permanent Update" before the process connected to the database.

Prefix

MASTER is a separate process from an

SirForms

session and MASTER may use a different default directory. The database to access may not be in the MASTER default directory. It is advisable to specify a full prefix in order that MASTER is able to find the database you wish to access. Specify the directory either with the PREFIX parameter on the execution statement or with the PREFIX sub-clause on the DATABASE clause of the FORM command. It is safest if all forms which accesses a database have the PREFIX specified to avoid any problems when using the form from different directories. If a form uses multiple databases in multiple directories, then the prefix information must be specified in the form, not on the execution statement parameters. For example:

SirForms/ FRM=MYFORM.frm / MST='sirnt.SIR2002.com.au' / PREFIX='C:\SIR2002\'

Locking

When multiple users are updating the same database at the same time, MASTER uses locks when updating a record to prevent other users from simultaneously updating the same record. Locks apply to individual instances of a record. They do not apply to the database as a whole or to all records of one type.

Locks can be specified on the CALL or ROOT commands in the form definition. During a session, the user can change the lock types specified in the form, provided they have LOCKCHANGE permission. Current lock types are displayed in the status area. The lock types are:

Lock Type	Command	Requests	Allows Other
CONCURRENT READ	CR	Read access	Readers Writers
CONCURRENT WRITE	CW	Read and write access	Readers Writers
PROTECTED READ	PR	Read access	Readers No writers
PROTECTED WRITE	PW	Read and write	Readers No writers
EXCLUSIVE	EX	Read and write access	No

Concurrent Read allows read-only access to the record. Other users can still access the record for read and write.

Concurrent Write allows both read and write access, while also allowing other users both read and write access. (It is strongly recommended NOT to use this lock type as updates could be lost.

Protected Read allows read-only access to the record. Other users can read the data, but no writers are allowed.

Protected Write allows read and write access. Other users can read the data but no writers are allowed.

Exclusive establishes read and write access to the record. No other users can access the record.

Changing Locks

Operators with LOCKCHANGE permission can use the LOCK and UNLOCK commands to change the lock types during a session. The user enters the command LOCK and a lock type. Lock types entered with the LOCK command remain in effect while the screen is being used: they do not affect the form definition. If a lock is changed, any other locks on the requested record are scanned for compatibility. Specify NOLOCKCHANGE on the ACTIVITIES clause on the FORM to revoke permission to make lock changes.

The following table shows the allowable changes:

Current Locks refer to the locks held on a case or a record by other users at the time the lock change is requested. New Lock Request refers to the lock type entered with the LOCK command. For example, if a user requests a Concurrent Write (CW) lock on a record, the request is granted if there are no other locks or the other locks currently granted are Concurrent Read (CR) or Concurrent Write (CW). The request is denied if there is a Protected Read (PR), Protected Write (PW), or an Exclusive (EX) lock established for the record. If a lock request cannot be granted, a message is displayed.

		Current Locks
		CR	CW	PR	PW	EX
New Lock Request	CR	YES	YES	YES	YES	NO
	CW	YES	YES	NO	NO	NO
	PR	YES	NO	YES	NO	NO
	PW	YES	NO	NO	NO	NO
	EX	NO	NO	NO	NO	NO

LOCK

LOCK lock_type or

LOCK [CIR lock_type] [RECORD lock_type] [ROW
lock_type]

Specify locks in a form definition with the LOCK clause. There are four places to do this:

the ROOT clause of the FORM command;

the CALL command;

the LOOKUP command;

the LOOKUP clause of the FIELD command.

Specification of lock types is optional. The default lock type for the root screen is Exclusive (EX). For called screens, the default lock type is the same as that of the calling screen. The default for the LOOKUP command and clause is Concurrent Read (CR).

Added to the ROOT clause, the LOCK option sets the default concurrency mode for the entire form. All screens use the default lock type. For example, to set a lock type of Concurrent Read (CR) for all the data accessed with a form, specify:

form COMPANY ..... root MAINMENU lock CR
Specifying LOCK and a lock type sets the lock types for both the CIR and the associated record. Lock types can be specified separately for the CIR, the record or a table row. For a separate lock type for the CIR and for records, specify:

form COMPANY ..... root MAINMENU lock CIR PR RECORD EX
On the CALL command, the LOCK clause specifies the lock type to apply to the records on the called screen. The lock type specified on the CALL command overrides the lock established with the ROOT clause. The lock set on the CALL applies to all instances of that record type displayed on the screen. For example, to set a lock type of Protected Write (PW) for a called screen named OCCUP, specify:

CALL OCCUP .... lock PW
The LOCK clause on the LOOKUP command (or the LOCK option to the LOOKUP clause of the FIELD command) sets the lock type for the records accessed by the LOOKUP. The lock type specified on the LOOKUP command or clause overrides the lock established with the ROOT clause. There is no reason to have any lock type other than "CR" on a LOOKUP.

Establishing a Set of Lock Types

Selecting appropriate lock types for an application depends on the type of work being done.

Read Only

ACTIVITIES NOWRITE
NOLOCKCHANGE

Protected Read

PR

READ

DATABASE

FORM

MASTER

Read & Write

Concurrent Read

CR

Protected Write

PW

Exclusive

EX

Locking can be at the case-level or at the record-level. When a case-level lock is required, specify the keyword LOCK and a lock type to lock both the CIR and the records for a case. Specify separate lock types for the CIR and records for general access to the case, but a more restricted access to the records.

If you lock at the case level, only one user at a time can access any of the records for a case, regardless of the record types involved.

Master Messages

The following messages may occur during a concurrent session:

Message Explanation

98 Waiting for locked case. Another user has locked the CIR and the record. If the likelihood is good that the other user will release the case, you may decide to wait. If not, issue a break. Issuing a break causes Message 99 to be displayed.

99 Next case is locked, enter ABORT, LOCK or WAIT. This message is displayed after a break is issued in response to Message 98. You can ABORT the process, change your lock request, or continue waiting.

100 Waiting for locked record. Another user has locked the record. If the likelihood is good that the other user will release the record soon, you may decide to wait. If not, issue a break. Issuing a break causes Message 101 to be displayed.

101 Next record is locked, enter ABORT, LOCK or WAIT. This message is displayed after a break is issued in response to Message 100. You can ABORT the process, change your lock request, or continue waiting.

123 No permission to change LOCK status for record or CIR. LOCKCHANGE permission has been revoked. See whoever created your form.

150 Illegal lock type specified. Most probably, a misspelled lock type. Check the spelling of the lock type and reenter the command with the proper spelling.

Message	Explanation
98	Waiting for locked case. Another user has locked the CIR and the record. If the likelihood is good that the other user will release the case, you may decide to wait. If not, issue a break. Issuing a break causes Message 99 to be displayed.
99	Next case is locked, enter `ABORT, LOCK` or `WAIT`. This message is displayed after a break is issued in response to Message 98. You can `ABORT` the process, change your lock request, or continue waiting.
100	Waiting for locked record. Another user has locked the record. If the likelihood is good that the other user will release the record soon, you may decide to wait. If not, issue a break. Issuing a break causes Message 101 to be displayed.
101	Next record is locked, enter `ABORT, LOCK` or `WAIT`. This message is displayed after a break is issued in response to Message 100. You can `ABORT` the process, change your lock request, or continue waiting.
123	No permission to change `LOCK` status for record or CIR. `LOCKCHANGE` permission has been revoked. See whoever created your form.
150	Illegal lock type specified. Most probably, a misspelled lock type. Check the spelling of the lock type and reenter the command with the proper spelling.