9.132 LOCK_OBJECT

Note: Built-In Function Rules     Usage Options

Attempts to place a lock on the specified User Object and returns an error if unsuccessful.

Arguments

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Req

Object Type.

1

20

 

 

2

A

Opt

Object Identifier 1.

1

10

 

 

3

A

Opt

Object Identifier 2.

1

10

 

 

4

A

Opt

Object Identifier 3.

1

10

 

 

5

A

Opt

Object Identifier 4.

1

10

 

 

6

A

Opt

Locking Level

FUNC = Function (Default)

JOB = Job

PERM = Permanent

3

4

 

 

 

Return Values

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Req

Return code

OK = Object was successfully locked.

IG = Lock request ignored. Object already locked by current Job.

ER = Object already has a lock present.

2

2

 

 

2

A

Opt

Job Name of Locking Job

1

10

 

 

3

A

Opt

User of Locking Job

1

10

 

 

4

A

Opt

Job Number of Locking Job

1

6

 

 

 

This Built-In Function allows the locking of User Objects. Once a User Object is locked any other attempt to lock that User Object results in an error condition and a Return Code of "ER" being returned. The exception to this is when an attempt is made to lock a User Object that is already locked by the current job. When this occurs the lock request is ignored and a Return Code of "IG" is return.

A User Object need not be a physical object on the system, it can be ANYTHING you require. User Objects are more conceptual than physical, and can represent a particular customer number or an entire LANSA partition. The only limitation is your imagination.

The word 'ALL' is reserved by the system and must not be used as an Object Identifier.

This method of locking is controlled by your application, it is NOT controlled by the operating system. Therefore system commands cannot be used to investigate the lock status of User Objects.

Some of the advantages of using LOCK_OBJECT over the LOCK(*YES) parameter of I/O commands include:

The Object Type argument is used to organize the object identifiers into groups of common attributes. For example an Object Type could be used to group customers, orders or printer names.

The Object Identifiers then specify a single object.

Current User Object locks are stored in the file DC@FOL. There exists one record in DC@FOL for each User Object lock present. The layout of DC@FOL is:

Field Name

Length

Description

FOLP#I

3A

Partition Identifier

FOLTYP

20A

Object Type

FOLID1

10A

Object Identifier 1

FOLID2

10A

Object Identifier 2

FOLID3

10A

Object Identifier 3

FOLID4

10A

Object Identifier 4

FOLLVL

4A

Lock Level

FOLMOD

10A

Process name

FOLFMT

7A

Function name

FOLJNL

10A

Locked by Job Name

FOLJ#L

6A

Locked by Job Number

FOLUSL

10A

Locked by User

FOLTDS

12S 0

Time/Date Stamp - System Format

 

The Logical Views present and their keys are:-

Logical File

Key Sequence

Use

DC@FOLV1

FOLP#I, FOLTYP, FOLID1, FOLID2, FOLID3, FOLID4.

Read Only

DC@FOLV2

Same as DC@FOLV1.

Update

DC@FOLV3

FOLLVL, FOLJ#L, FOLMOD, FOLFMT, FOLP#I, FOLTYP, FOLID1, FOLID2, FOLID3, FOLID4.

Read Only

DC@FOLV4

Same as DC@FOLV3.

Update

 

Be aware that backup and recovery of this file is a user responsibility. Any locks that are present when a backup is done will be reinstated when that backup is restored.

Should LANSA or a function crash due to error any locks that are present will be removed. But if the system were to crash, LANSA will be unable to remove the locks. Locks remaining due to a system crash become the responsibility of the user to remove.

The User Object locks are either unlocked automatically or when the UNLOCK_OBJECT Built-In Function is used.

The Locking Level used on the LOCK_OBJECT determines when the User Object would be automatically unlocked.

Examples

By using the four User Object Identifiers to build a structure to your object locking it is possible to do generic key unlocking.

DEFINE     FIELD(#RETURN)  TYPE(*CHAR) LENGTH(2)

DEFINE     FIELD(#STATE)   TYPE(*CHAR) LENGTH(3)

DEFINE     FIELD(#CUSTNO)  TYPE(*CHAR) LENGTH(6)

********** Lock Customers to be Updated

USE        BUILTIN(LOCK_OBJECT)

           WITH_ARGS('CUSTOMER' #STATE #CUSTNO '' '' 'FUNC') TO_GET(#RETURN)

********** Unlock ALL Customers for the STATE

USE        BUILTIN(UNLOCK_OBJECT) WITH_ARGS('CUSTOMER' #STATE 'ALL' '' '' 'FUNC')

           TO_GET(#RETURN)

In this example a number of User Objects relating to customers had locks placed on them. All the locked 'customers' belong to the same 'state'. When the update process is complete the locks can be removed. Rather than remove each individual lock for each customer, all the locks for a state can be removed generically by specifying 'ALL' on the second Object Identifier.

User Object locking can also be used to limit the number of concurrent users a function can have. For example, if you wish to impose a three user limit on your order entry function, then create three User Objects, each relating to a user. Then at the top of your order entry function attempt to obtain a lock on one of the User Objects. If none are available then you could display a message stating this, and exit the function. If a lock is granted then allow access to the function. Remember to unlock the User Object when exiting the function, or specify 'FUNC' as the Locking Level so the lock will be automatically removed when the function is finished. Use the following example as a guide.

DEFINE     FIELD(#RETURN)  TYPE(*CHAR) LENGTH(2)

********** Attempt lock on 1st instance

USE        BUILTIN(LOCK_OBJECT)

           WITH_ARGS('ORDER_ENTRY' 'ORDER#1' '' '' '' 'FUNC') TO_GET(#RETURN)

IF         COND('#RETURN *EQ ER')

********** Attempt lock on 2nd instance

USE        BUILTIN(LOCK_OBJECT)

           WITH_ARGS('ORDER_ENTRY' 'ORDER#2' '' '' '' 'FUNC') TO_GET(#RETURN)

IF         COND('#RETURN *EQ ER')

********** Attempt lock on 3rd instance

USE        BUILTIN(LOCK_OBJECT)

           WITH_ARGS('ORDER_ENTRY' 'ORDER#3' '' '' '' 'FUNC') TO_GET(#RETURN)

IF         COND('#RETURN *EQ ER')

********** Cannot obtain any locks

MESSAGE    MSGTXT('No Order Entry sessions are Available')

RETURN

ENDIF

ENDIF

ENDIF

 

********** Protected processing

********** Unlock ALL Order Entry locks for this Function

USE        BUILTIN(UNLOCK_OBJECT) WITH_ARGS('ORDER_ENTRY' 'ALL' '' '' '' 'FUNC') TO_GET(#RETURN)