HLI: Locking behavior of HLI calls

Overview

This topic describes Model 204 resource locking and record locking for application programmers who are using the Host Language Interface facility. Refer to the descriptions of locking behavior for HLI calls when you are coding your host language program.

Refer specifically to information about the record locking behavior of multiple cursor IFSTRT thread calls if you are using multiple cursor features in your HLI program for the first time.

For more information about record locking, also see Record level locking and concurrency control.

See HLI: Function summary for a description of the HLI function calls shown in the examples.

Locking facility

Model 204 controls user access to file resources with a facility called resource locking. Record locking prevents conflicting, simultaneous use of records when several users have access to the same files or groups and protects against the concurrent updating of certain data by different users.

With locking, Model 204 allows a particular resource or record to be shared between users or locks access to a resource or record so that it can be used exclusively by a user.

Locking at the thread level

Model 204 locks resources and records for HLI processing at the thread level (for an IFSTRT thread and for an IFDIAL thread).

A resource or record that is shared by more than one thread is locked by each thread whether those threads are used in the same host language program, such as in a multithreaded IFAM4 job, or in different host language programs, for example, in two different IFAM2 jobs.

Enqueuing actions

For HLI functions that lock resources or records, if enqueuing actions are successful, Model 204 locks the resource or record in either of the following modes:

Mode	Description
SHR	In share mode, a lock allows one or more users to perform retrieval functions on a file, record set, or record. Any number of users can have shared control of a file, record set, or record concurrently.
EXC	In exclusive mode, a lock allows a single user to update a file, record set, or record. An exclusive lock is not compatible with other exclusive locks nor with any shared locks. See EXC lock on the current record for information about different types of exclusive locks on records.

Most HLI functions automatically enqueue on the resources or records to which they refer.

For example, retrieval functions, such as IFFIND or IFFAC, enqueue in SHR mode, which allows simultaneous retrievals of records by different users but prohibits updating of those same records concurrently by other users. File maintenance functions such as IFPUT or IFUPDT enqueue in EXC mode, which locks out all other references.

In addition to the automatic enqueuing facilities, you can explicitly enqueue or dequeue on resources and records in your host language application program. See HLI locking functions for a listing of HLI functions and enqueuing actions.

Getting control of a resource or a record

If control of a resource or record cannot be gained, Model 204 either immediately returns control to the application program with a function completion code (RETCODE) of 3 or waits a certain number of seconds.

If a wait occurs, Model 204 then attempts enqueuing again and if the resource or record is still unavailable, returns control to the application program with a function completion code of 3.

For all functions except IFCHKPT, a completion return code of 3 indicates that control of the resource or record could not be obtained. For calls that enqueue on a resource or record, code your host language program to test for a return code of 3 and, if desirable, to reissue the call.

See Record locking conflicts for a coding example that uses the Model 204 return code to test for locking conflicts.

Specifying wait time within system limits

You can specify a wait time for any of the following enqueuing calls: IFOPENX, IFFNDX, IFGETX, IFMOREX, IFENQL, and IFENQ.

Attention: Although there is no restriction on the wait time you can specify, setting the time to a very large number might exceed the system's wait-time limit; if the system's time limit is exceeded, a program ABEND occurs.

See Locking functions for more information about wait times for HLI calls. Check with your Model 204 system administrator for information about system wait times.

Releasing a resource or record

With HLI functions that dequeue (release) locks on resources or records, dequeuing actions are performed immediately; there is no wait time.

Locking behavior of IFSTRT calls

The remaining sections describe the locking behavior of HLI calls that are issued on an IFSTRT thread.

Guidelines to avoid locking conflicts

Design your HLI application to enqueue on the fewest possible resources or records, as needed. Release resources or records as often as possible, when they are no longer needed.

Code your HLI application to use a record locking strategy that avoids logical inconsistencies, but that allows resources or records to be shared. This guideline applies in particular to HLI jobs running in IFAM2 (which supports multiple users) and to multithreaded IFAM4 applications (where conflicts can occur between threads in the same HLI job).

File locking

A file is a resource. Model 204 enqueues a file when an HLI application issues a call to open a file, with IFOPEN or IFOPENX. IFOPEN enqueues a file in SHR mode, while IFOPENX enqueues a file in EXC mode.

Attention: IFOPENX locks out all other Model 204 users and threads from accessing a file. In IFAM2, IFOPENX prevents any SOUL request or other HLI application from processing against the opened file.

Read-only file access in IFAM2 and IFAM4

For certain HLI applications that use IFSTRT threads, the IFSTRT thread type might determine the type of file access. For IFAM2 and IFAM4 jobs, the following IFSTRT thread types are available:

Thread type	Allows...
0	Read-only access (regardless of password used)
1	Updates (password privileges determine type of access)
2	Multiple-cursor functionality (password determines access)

In IFAM2 and IFAM4, a read-only IFSTRT thread allows SHR access to a file. You can use a password that allows either read-only or update privileges, but you cannot issue calls that perform update operations.

For example, if you set the IFSTRT thread indicator to read-only (THRD_IND is 0), Model 204 rejects a call at execution time that attempts to perform an update operation such as IFPUT and returns an error completion code (RETCODE) of 40.

Note: To update files in an IFAM2 or IFAM4 job, you must issue IFSTRT with thread update privileges (THRD_IND is 1 or 2) and you must enter file or group passwords that have update privileges.

Using a password with update privileges

HLI application programs that share the same copy of the HLI Model 204 service program, such as in IFAM2, can share files regardless of password privileges.

Operating system enqueuing

Between HLI applications that use different copies of Model 204, a file resource might be locked. If an HLI application opens a file using a password that allows updating privileges, an attempt to open that file by any other HLI application that uses a different copy of Model 204 is unsuccessful.

The following table summarizes file locking behavior between HLI applications. Each HLI application listed on the left opens a file using a password with update privileges. The HLI applications listed on the right are locked from accessing the open file.

Open file w/ update privileges:	File resource is locked to...
IFAM1	Other IFAM1; IFAM2; IFAM4
IFAM2	IFAM1; IFAM4
IFAM4	IFAM1; IFAM2; other IFAM4

Model 204 performs either of the following actions depending on which type of HLI job attempts to open a locked file.

If the file resource is locked to...	Then Model 204 issues...
IFAM1 application	WAITING FOR ACCESS message and the IFAM1 application waits for the file.
IFAM2 or IFAM4 application	FILE IS IN USE message and returns an IFOPEN completion code of 260 (an error).

In IFAM1 and IFAM4, the same file can be defined (DISP=SHR) in different HLI jobs. Model 204 performs resource locking at the operating-system level to control access to files that are shared by more than one copy of the HLI Model 204 service program in IFAM1 and IFAM4.

Note that enqueuing at the operating-system level is distinct from file-level enqueuing with IFOPEN and IFOPENX.

See Resource locking for more information about file resource locking at the operating-system level.

Record locking on found sets

Model 204 adheres to a specific set of rules for record locking behavior. The record locking behavior of the following HLI functions, which create found sets, is described in the following sections:

HLI function	Equivalent SOUL command
IFFAC	FIND AND COUNT
IFFIND	FIND
IFFDV	FIND VALUES
IFFNDX	FIND EXCLUSIVE
IFFWOL	FIND WITHOUT LOCKS

The record locking behavior of the IFDSET function, which deletes a found set, is described in IFDSET locks a record set in EXC mode.

IFFAC and IFFIND lock in SHR mode

Both the IFFAC (FIND AND COUNT) and IFFIND (FIND) functions immediately lock the set of found records in SHR mode. If the locking is successful, none of the records in the found set can be updated by another user or thread until the records are released.

On a single cursor IFSTRT thread, an IFFIND that is executed in a loop releases the old found set as soon as the function is reexecuted. The final set selected by the IFFIND remains locked (in SHR mode) until the end of the transaction. Also, on a single cursor IFSTRT thread, each record is removed from the found set and the SHR lock released as it is processed by IFGET.

On a multiple cursor IFSTRT thread, records are held until explicitly released by a call to IFRELR or IFRELA, or until the entire transaction has been completed.

Note: When updating records after using IFFIND, you are moving from a SHR lock to an EXC lock, and the update fails, if any other user has obtained a SHR lock on the records. This is likely to occur in a busy system.

IFFDV locks a value set

The IFFDV (FIND ALL VALUES) function operates in the following manner, depending on the field attribute:

If the field has the FRV attribute, the value set is locked in EXC mode until all values are collected. The EXC lock is released after all values are found.
If the field has the ORDERED attribute, no locking is performed.

IFFNDX locks in EXC mode

The IFFNDX (FIND EXCLUSIVE) function enqueues in EXC mode to lock a set of records.

You can use IFFNDX to lock a record set for loop processing. However, when using IFFNDX, concurrence is reduced, because records are exclusively locked; none of the records in the found set can be retrieved or updated by another user or thread. Records found using IFFNDX are held in EXC status until they are released.

Issue IFRELR, IFRELA, or IFCMTR to explicitly release records locked in EXC mode by IFFNDX.

Note the following considerations when using IFFNDX:

Because IFFNDX fails if any of the records that it needs are locked in SHR or EXC mode by other users, it has a good chance of failing in busy systems.
To update a large set of records without locking the entire set, place the records to be updated on a list and then issue the IFUPDT on each record as you update it.
IFFNDX guarantees that subsequent record updates succeed, because the records are already exclusively locked.

In the following example, a host language application exclusively locks two record sets. The first IFFNDX prevents access to TOTAL PREMIUM in the CLIENTS file while the corresponding VEHICLE PREMIUMs in the VEHICLES file are being changed. The application updates both files. This example shows HLI processing on a multiple cursor IFSTRT thread.

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 DIR PIC 9(5) COMP SYNC VALUE "1". 01 WK-VARS COMP SYNC. 05 FIND-SWITCH PIC 9 VALUE ZERO. 05 SET-SWITCH PIC 9 VALUE ZERO. 05 VPREM-AMT PIC 9(6) VALUE ZERO. 05 TOTAL-PREM-AMT PIC 9(7) VALUE ZERO. 05 VTOT-UPDATES PIC 9(5) VALUE ZERO. 05 CTOT-UPDATES PIC 9(5) VALUE ZERO. 01 CLIENT-FILE-INFO. 05 CLIENT-FILE-NAME PIC X(8) VALUE "CLIENTS;". 05 CLIENT-FILE-PASSW PIC X(9) VALUE "CUPDATES;". 01 VEHICLE-FILE-INFO. 05 VEHICLE-FILE-NAME PIC X(9) VALUE "VEHICLES;". 05 VEHICLE-FILE-PASSW PIC X(9) VALUE 'VUPDATES;". 01 FINDX-CLIENTS. 05 FXSPEC-CLIENTS PIC X(38) VALUE "IN CLIENTS FD;POLICY NO=100015;RECTYPE=POLICYHOLDER;". 05 WAIT-TIME PIC 99 VALUE 30. 05 FXNAME-CLIENTS PIC X(7) VALUE "FXCLIENTS;". 05 END-CALL PIC X(4) VALUE "END;". 01 FINDX-VEHICLES. 05 FXSPEC-VEHICLES PIC X(20) VALUE "IN VEHICLES FD;OWNER POLICY=100015;". 05 WAIT-TIME PIC 99 VALUE 30. 05 FXNAME-VEHICLES PIC X(7) VALUE "FXVEHICLES;". 05 END-CALL PIC X(4) VALUE "END;". 01 COUNT-VARS. 05 COUNT PIC 9(5). 05 CLIENT-COUNT PIC 9(5) VALUE ZERO. 05 VEHICLE-COUNT PIC 9(5) VALUE ZERO. 01 VCURSOR-PARMS. 05 VCURSPEC PIC X(14) VALUE "IN FXVEHICLES;". 05 VCURNAME PIC X(8) VALUE "VCURSOR;". 01 CCURSOR-PARMS. 05 CCURSPEC PIC X(13) VALUE "IN FXCLIENTS;". 05 CCURNAME PIC X(8) VALUE "CCURSOR;". 01 VEHICLE-REC. 05 OWNER-POLICY-NO PIC 9(5) VALUE ZERO. 05 VEHICLE-ID-NO PIC 9(2) VALUE ZERO. 05 VEHICLE-PREMIUM-AMT PIC ((6) VALUE ZERO. 01 CLIENT-REC. 05 CLIENT-POLICY-NO PIC (5) VALUE ZERO. 05 CLIENT-TYPE PIC X(15) VALUE SPACES. 05 CLIENT-PREMIUM-TOTAL PIC 9(7) VALUE ZERO. 01 VDATA-SPEC PIC X(55) VALUE "EDIT(OWNER POLICY,VIN,VEHICLE PREMIUM)(A(5),A(2),A(6));". 01 CDATA-SPEC PIC X(55) VALUE "EDIT(POLICY NO,RECTYPE,TOTAL PREMIUM)(A(5),A(15),A(7));". . . . PROCEDURE DIVISION. CALL "IFSTRT"... * * OPEN DATA FILES * PERFORM OPEN-FILES UNTIL RETCODE IS NOT EQUAL TO ZERO OR SET-SWITCH IS NOT EQUAL TO ZERO. IF RETCODE IS NOT EQUAL TO ZERO THEN GO TO ERROR-RTN. * * FIND RECORDS TO BE UPDATED * PERFORM FIND-RTN UNTIL RETCODE IS NOT EQUAL TO ZERO OR FIND-SWITCH IS NOT EQUAL TO ZERO. IF RETCODE IS NOT EQUAL TO ZERO THEN GO TO ERROR-RTN. * * UPDATE VEHICLES FILE * PERFORM VEHICLES-UPDATE UNTIL RETCODE IS NOT EQUAL TO ZERO OR VEHICLE-COUNT IS EQUAL TO ZERO. DISPLAY "TOTAL VEHICLE RECORDS UPDATED IS " VTOT-UPDATES. IF RETCODE IS NOT EQUAL TO ZERO THEN GO TO ERROR-RTN. * MOVE ZERO TO SET-SWITCH. PERFORM CURSOR-RTN UNTIL RETCODE IS NOT EQUAL TO ZERO OR SET-SWITCH IS NOT EQUAL TO ZERO. IF RETCODE IS NOT EQUAL TO ZERO THEN GO TO ERROR-RTN. * * UPDATE CLIENTS FILE * PERFORM CLIENTS-UPDATE UNTIL RETCODE IS NOT EQUAL TO ZERO OR CLIENT-COUNT IS EQUAL TO ZERO. DISPLAY "TOTAL CLIENT RECORDS UPDATED IS " CTOT-UPDATES. IF RETCODE IS NOT EQUAL TO ZERO THEN GO TO ERROR-RTN. * MOVE ZERO TO SET-SWITCH. PERFORM END-UPDATES UNTIL RETCODE IS NOT EQUAL TO ZERO OR SET-SWITCH IS NOT EQUAL TO ZERO. IF RETCODE IS NOT EQUAL TO ZERO THEN GO TO ERROR-RTN. PERFORM END-JOB-RTN. * * SUBROUTINE TO OPEN VEHICLES AND CLIENTS FILES * OPEN-FILES. CALL "IFOPEN" USING RETCODE,CLIENT-FILE-INFO. CALL "IFOPEN" USING RETCODE,VEHICLE-FILE-INFO. MOVE 1 TO SET-SWITCH. * SUBROUTINE TO FIND RELATED RECORDS IN BOTH FILES * HOLDS FILES EXCLUSIVELY * FIND-RTN. CALL "IFFNDX" USING RETCODE,FXSPEC-CLIENTS,WAIT-TIME, FXNAME-CLIENTS,END-CALL. CALL "IFCOUNT" USING RETCODE,COUNT,FXNAME-CLIENTS. MOVE COUNT TO CLIENT-COUNT. DISPLAY "TOTAL CLIENT RECORDS FOUND IS " CLIENT-COUNT. CALL "IFFNDX" USING RETCODE,FXSPEC-VEHICLES,WAIT-TIME, FXNAME-VEHICLES,END-CALL. CALL "IFCOUNT" USING RETCODE,COUNT,FXNAME-VEHICLES. MOVE COUNT TO VEHICLE-COUNT. DISPLAY "TOTAL VEHICLE RECORD FOUND IS " VEHICLE-COUNT. CALL "IFOCUR" USING RETCODE,VCURSPEC,VCURNAME. MOVE 1 TO FIND-SWITCH. CURSOR-RTN. CALL "IFCCUR" USING RETCODE,VCURSOR. CALL "IFOCUR" USING RETCODE,CCURSPEC,CCURNAME. MOVE "1" TO SET-SWITCH. * * SUBROUTINE TO UPDATE PREMIUM AMOUNT IN VEHICLES RECORDS * VEHICLES-UPDATE. CALL "IFFTCH" USING RETCODE,VEHICLE-REC,DIR,VCURNAME, VDATA-SPEC. MOVE VEHICLE-PREMIUM-AMT TO VPREM-AMT. ADD 100 TO VPREM-AMT. ADD VPREM-AMT TO TOTAL-PREM-AMT. MOVE VPREM-AMT TO VEHICLE-PREMIUM-AMT. CALL "IFUPDT" USING RETCODE,VEHICLE-REC,VCURNAME, VDATA-SPEC. CALL "IFCMMT" USING RETCODE. MOVE ZEROS TO VEHICLE-REC. ADD 1 TO VTOT-UPDATES. SUBTRACT 1 FROM VEHICLE-COUNT. * * SUBROUTINE TO UPDATE TOTAL PREMIUM/RELATED CLIENTS RECORD * CLIENTS-UPDATE. CALL "IFFTCH" USING RETCODE,CLIENT-REC,DIR,CCURNAME, CDATA-SPEC. MOVE TOTAL-PREM-AMT TO CLIENT-PREMIUM-TOTAL. CALL "IFUPDT" USING RETCODE,CLIENT-REC,CCURNAME,CDATA-SPEC. CALL "IFCMMT" USING RETCODE. * MOVE ZEROS TO CLIENT-POLICY-NO. MOVE SPACES TO CLIENT-TYPE. MOVE ZEROS TO CLIENT-PREMIUM-TOTAL. ADD 1 TO CTOT-UPDATES. SUBTRACT 1 FROM CLIENT-COUNT. * * SUBROUTINE TO END THE PROCESSING LOOP * END-UPDATES. CALL "IFCCUR" USING RETCODE,CCURSOR. CALL "IFRELA" USING RETCODE. MOVE "1" TO SET-SWITCH. * * TO HERE FOR ERROR-RTN AND END-JOB-RTN . . .

IFFWOL does not lock records

The IFFWOL (FIND WITHOUT LOCKS) function executes an IFFIND without obtaining any record locks.

The found set of records is indistinguishable from a list, except that the record set is referenced with "IN label" syntax.

Caution when using IFFWOL

You can use the IFFWOL function to solve specific performance problems. However, use IFFWOL with caution to avoid logical inconsistencies.

When using IFFWOL, design your application to take into account the following usage issues:

The logical integrity of data is at risk when:
- Another user is in the middle of changing values that are related.
- Another user deletes or changes the field that caused the record to be found.
The thread that issues IFFWOL might encounter data that is temporarily physically inconsistent. Because the thread does not hold any locks and cannot prevent other threads from updating, updates can occur while the IFFWOL thread is examining the record.
The following error conditions can occur when this happens:
- SICK RECORD messages are sent when extension records get deleted. In this case, the record is not really sick; it just temporarily appears that way to Model 204.
- NONEXISTENT RECORD messages are sent when entire records get deleted.

When to use IFFWOL

An advantage to using IFFWOL over any of the other find functions (which lock records) is that IFFWOL never fails. Examples of appropriate use of the IFFWOL function include:

When there is one user or thread at a time per record, for example, scratch records or bank teller applications, where an account is usually modified by one teller at a time.
Report programs in a heavy update environment.

Examples of inappropriate uses of the IFFWOL function include:

Report program in a heavy delete environment. In this case, IFFWOL results in many NONEXISTENT RECORD messages.
Retrievals in which the selection criteria can be changed by other users.
Reuse record number (RRN) files, with the possible exception of scratch files keyed on the user ID.

IFDSET locks a record set in EXC mode

The IFDSET (DELETE SET) function temporarily locks the set of records to be deleted in EXC mode before deletion occurs. The locking does not succeed, if any other user or thread has access to any of the records either in SHR or EXC mode.

Note: Once a record has been deleted, the EXC lock on the record is released, because the record no longer exists in the file.

SHR lock on the current record

The following retrieval functions lock the current record in SHR mode:

HLI function	Equivalent SOUL command
IFFRN	FOR RECORD NUMBER
IFOCC, IFCTO	COUNT OCCURRENCES
IFGET	GET
IFMORE	MORE

EXC lock on the current record

Two of the HLI retrieval calls, IFGETX and IFMOREX, and all the file updating calls enqueue in EXC mode and lock the current record with a SRE (single record enqueue) lock. Model 204 applies the SRE lock regardless of whether the record set is being held in SHR or EXC mode, or is unlocked.

Model 204 enqueues with the SRE lock on records from transaction back out (TBO) and non-TBO files alike. For TBO files with the LPU option set, Model 204 applies an additional EXC lock on updated records.

Single record enqueue (SRE) locks

The following retrieval calls lock the current record in EXC mode with a SRE lock:

IFGETX (GET EXCLUSIVE)
IFMOREX (MORE EXCLUSIVE)

The following updating calls lock the current record in EXC mode with a SRE lock before modifying the record:

IFDALL (DELETE ALL)
IFDREC (DELETE RECORD)
IFDVAL (DELETE VALUE)
IFPUT (PUT)
IFUPDT (UPDATE)

The following calls, if successful, lock the newly created record in EXC mode with an SRE lock:

IFBREC (BEGIN RECORD)
IFSTOR (STORE RECORD)

On a single cursor IFSTRT thread, Model 204 holds the SRE lock on the current record until the HLI thread enqueues on another record.

On a multiple cursor IFSTRT thread, Model 204 holds the SRE lock on a cursor's current record until the HLI program issues a call to IFRELA or IFCMTR to release locks, or until the cursor position is modified by one of the following calls.

Call	Function
IFFTCH	Moves the cursor to the next logical record in the set.
IFFRN	Points to specified a record number.
IFSTOR	Changes the cursor position to the newly created record.
IFCCUR	Closes the cursor.

Note: When using these functions inside a processing loop in the host language program, the current record remains locked until it passes through the loop unless it has been released (as described above) or deleted. If the record has been deleted, the EXC lock on the record is released, because the record no longer exists in the file.

Lock pending updates (LPU) locks

Model 204 provides a special file facility for TBO files called lock pending updates (LPU), which prevents updated records in one transaction from being used by other applications until the transaction ends.

When processing records from a TBO file with the LPU option set, the first updating call locks the current record in EXC mode with an additional LPU lock and adds the record to a set of updated locked records, called the pending update pool.

The following updating calls lock the current record in a pending update pool with the additional EXC lock:

IFDALL
IFDVAL
IFDREC
IFPUT
IFSTOR
IFUPDT

Model 204 locks the record in the pending update pool with the additional EXC lock until the transaction is committed. The record is locked until the end of the transaction when the entire pending update pool is released. See IFCMMT releases LPU locks for information about using IFCMMT to release LPU locks.

Note: Lock pending updates is an option of the FOPT parameter, which is enabled or disabled on a file by file basis. Using files that have the LPU option set ensures logical file consistency.

See IFFNDX locks in EXC mode for a description of IFFNDX locking behavior. See the FOPT parameter and File integrity and recovery for more information about the FOPT parameter.

Record locking: sample processing loops

The following coding sequence shows HLI processing against a TBO file (the LPU option is set). The program creates a found set with a SHR lock and updates records.

Call	Locking behavior
1. IFFIND or IFFAC	Enqueues SHR lock on found record set
2. Loop: IFFTCH IFUPDT End loop	Dequeues previous SRE lock (if any) Enqueues current record with SRE lock (EXC-1) Enqueues current record with LPU lock (EXC-2)
3. IFCMMT	Releases all SRE and LPU locks (EXC-1, EXC-2 locks)
4. IFRELR	Releases SHR lock on record set

The following coding sequence shows HLI processing against a TBO file (the LPU option is set). The program creates a found set with an EXC lock and updates records.

Call	Locking behavior
1. IFFNDX	Enqueues EXC lock on found record set
2. Loop: IFFTCH IFUPDT End loop	Dequeues previous SRE lock (if any) Enqueues current record with SRE lock (EXC-1) Enqueues current record with LPU lock (EXC-2)
3. IFCMMT	Releases all SRE and LPU locks (EXC-1, EXC-2 locks)
4. IFRELR	Releases EXC lock on record set

Releasing record locks

The following functions allow you to explicitly remove certain types of record locks:

HLI function	Equivalent SOUL command
IFRELA	RELEASE ALL RECORDS
IFRELR	RELEASE RECORDS
IFCMMT	COMMIT
IFCMTR	COMMIT RELEASE

The record locks released by each function are described in the following sections.

Refer to the Rocket Model 204 Host Language Interface Reference Manual for a detailed description of the HLI functions and their syntax. See HLI: Transactions for more information about managing transactions.

IFRELA releases all locks

IFRELA (RELEASE ALL RECORDS) empties all record sets and terminates all locks held by the thread. IFRELA also performs the following actions:

Releases all SHR and EXC locks placed on records
Clears all lists and the results of all IFSORT functions
Sets the current record number to -1

Note: Use IFRELA with caution. After IFRELA is processed in a host language program, no records are available for processing. Issue a call to IFRELA at the end of a logical phase.

IFRELR releases a record set lock

IFRELR (RELEASE RECORDS) empties the records in a single found set and terminates the lock on those records. You can use IFRELR to release the SHR lock placed on records by IFFIND or IFFAC and the EXC lock placed on a record set by IFFNDX.

You can also use IFRELR to release IFSORT records in the scratch file.

When IFRELR refers to an IFSORT sorted set, the CCATEMP space, which was occupied by the temporary sorted record copies, is released.

Note: Sorted records released in this manner are no longer available to the host language program. However, the original found set or list from which the sorted set was built is not affected.

IFCMMT releases LPU locks

If the host language program is processing against a TBO file, IFCMMT (COMMIT) releases the LPU exclusive lock on updated records. IFCMMT also releases a single record enqueue (SRE) on the current record if one exists, for example, as a result of a call to IFUPDT or IFPUT. IFCMMT ends the current transaction and dequeues checkpoints.

When updating records, you can minimize record locking conflicts by issuing frequent calls to IFCMMT.

A call to IFCMMT inside a loop that processes each record ends the current update unit each time the loop is processed. This results in several short update units instead of one long update unit and is especially useful for minimizing conflicts on an LPU file where all updated records are enqueued in EXC mode until the update unit ends. Record set locks obtained by IFFIND, IFFAC, and IFFNDX are not affected by IFCMMT.

Example of using IFCMMT

The following COBOL example shows the call to IFCMMT issued inside a record processing loop. The program finds and prints a count of all records whose last name is NELSON. The MONTH field of each record in the found set is changed to November (value is NOV).

In this example, the following conditions apply:

IFSTRT starts a multiple cursor thread that allows updating
IFOPEN uses a password that allows updating privileges
IFUPDT enqueues the current record in EXC mode
IFCMMT releases the LPU lock on the current record

WORKING-STORAGE SECTION. 01 COUNTERS. 05 0FIND-TOT PIC 9(5) VALUE ZERO. 05 UPDATE-TOT PIC 9(5) VALUE ZERO. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 DIR PIC 9 COMP SYNC VALUE "1". 01 FIND-CRITERIA. 05 FDSPEC PIC X (13) VALUE "LNAME=NELSON;". 05 COUNT PIC 9(5) COMP SYNC. 05 FDLNAME PIC X(8) VALUE "FDLNAME;". 05 END-CALL PIC X(4) VALUE "END;". 01 CURSOR-PARMS. 05 CURSPEC PIC X(11) VALUE "IN FDLNAME;". 05 CURNAME PIC X(8) VALUE "CRLNAME;". 01 DATA-SPEC PIC X(74) VALUE "EDIT(FNAME,LNAME,ADDRESS,YEAR,MONTH,DAY) (A(10),A(20),A(40),A(2),A(3),A(2));". 01 WORK-REC. 05 FIRST-NAME PIC X(10). 05 LAST-NAME PIC X(20). 05 ADDRESS PIC X(40). 05 DATE-YEAR PIC X(2). 05 DATE-MONTH PIC X(3). 05 DATE-DAY PIC X(2). 01 WORK-VAL. 05 MONTH1 PIC X(3) VALUE "JAN". . . . 05 MNTH11 PIC X(3) VALUE "NOV". . . . PROCEDURE DIVISION. . . . CALL "IFSTRT" ... CALL "IFOPEN" ... . . . * FIND AND COUNT RECORDS WHOSE LAST NAME IS NELSON * CALL "IFFAC" USING RETCODE,FDSPEC,COUNT,FDLNAME,END-CALL. MOVE COUNT TO FIND-TOT DISPLAY "TOTAL RECORDS FOUND IS " FIND-TOT IF RETCODE IS NOT EQUAL TO ZERO THEN GO TO END-RTN * ELSE * UPDATE NELSON RECORDS * CALL "IFOCUR" USING RETCODE,CURSPEC,CURNAME. PERFORM UPDATE-RTN UNTIL RETCODE IS NOT EQUAL TO ZERO OR FIND-TOT IS EQUAL TO ZERO IF RETCODE IS NOT EQUAL TO ZERO THEN GO TO END-RTN ELSE * * PRINT THE UPDATE TOTAL * CALL "IFCCUR" USING RETCODE,CURNAME DISPLAY "TOTAL RECORDS UPDATED IS " UPDATE-TOT. * GO TO END-RTN. * * SUBROUTINE TO CHANGE MONTH TO NOV AND UPDATE FILE COMMITS THE UPDATE UNIT * UPDATE-RTN. CALL "IFFTCH" USING RETCODE,WORK-REC,DIR,CURNAME,DATA-SPEC. MOVE MNTH11 TO DATE-MONTH. CALL "IFUPDT" USING RETCODE,WORK-REC,CURNAME,DATA-SPEC. CALL "IFCMMT" USING RETCODE. ADD 1 TO UPDATE-TOT. SUBTRACT 1 FROM FIND-TOT. * * SUBROUTINE TO END THE TRANSACTION * END-RTN. IF RETCODE IS EQUAL TO ZERO THEN NEXT SENTENCE ELSE PERFORM ERROR-RTN. CALL "IFCLOSE"... CALL "IFFNSH"... . . .

IFCMTR releases all locks and ends a transaction

The IFCMTR (COMMIT RELEASE) function performs all the operations of both IFCMMT and IFRELA.

Note: After IFCMTR is processed, there is no current record. To avoid confusing results, Technical Support recommends that you issue a call to IFCMTR at the end of a logical processing step.

Locking functions

The following table summarizes the following enqueuing and dequeuing actions for the HLI functions that lock:

Files or groups
Record sets
Individual records
Arbitrary resources

Codes used in the table

The HLI locking functions table uses the following codes:

Code

Meaning

Thread:

mc

st

Multiple cursor IFSTRT thread

Single cursor IFSTRT thread

Action:

ENQ

DEQ

Enqueues resource

Dequeues resource

Note: Some HLI functions enqueue or dequeue only, while others first dequeue and then enqueue. Those functions that perform both operations in this manner only when used on a single cursor IFSTRT thread. On a multiple cursor IFSTRT thread, except for IFFRN, an HLI function either enqueues or dequeues.

Mode:

SHR

EXC

Shares lock on resource

Exclusive lock on resource (for individual records, SRE or LPU lock

Times:

n

0

User-specified number of times to try enqueuing

No wait

Note: Except for IFOPENX and IFENQ, which is wait time in seconds, Times is the number of times to attempt enqueuing on the resource before returning a completion code (RETCODE) of 3 to the HLI application. If times is greater than zero, Model 204 waits for three seconds (or 10 seconds for IFOPEN) before the next attempt.
The total number of times to try equates to a total wait time in seconds, where:
IFOPEN total wait time is the total number of tries multiplied by 10 seconds.

For all other calls that specify a wait time except IFOPEN:
total wait time is the total number of tries multiplied by 3 seconds.

HLI locking functions
HLI function	Thread	Action	Mode	Times	Resource
Locking files or groups
IFCLOSE	mc, st	DEQ	--	0	All previously enqueued: Records Record sets and lists Files
IFDELF	mc, st	ENQ	EXC	0	Specified file
IFDFLD	mc, st	ENQ	EXC	0	Specified file
IFNFLD	mc, st	ENQ	EXC	0	Specified file
IFRFLD	mc, st	ENQ	EXC	0	Specified file
IFOPEN	st	1. DEQ	--	0	All previously enqueued: Records Record sets and lists
IFOPEN	mc, st	2. ENQ	SHR	2	Specified file or group Note: The wait time is 10 seconds each time.
IFOPENX	st	1. DEQ	--	0	All previously enqueued: Records Record sets and lists
IFOPENX	mc, st	2. ENQ	EXC	`n`	Specified file or files Note: `n` is a user-specified wait time in seconds.
Locking record sets
IFBOUT	mc, st	DEQ	--	0	LPU locks SRE exclusive locks
IFCMMT	mc, st	DEQ	--	0	LPU locks SRE exclusive locks
IFCMTR	mc, st	DEQ	--	0	Records held in EXC lock, previously updated Record sets and lists, previously enqueued (EXC or SHR)
IFDEQL	st	DEQ	--	0	Record set on a specified list, previously enqueued
IFDSET	mc, st	ENQ	EXC	0	Record set
IFENQL	st	ENQ	SHR/EXC	`n`	Record set on a specified list
IFFAC IFFACE	mc, st	ENQ	SHR	0	New record set
IFFIND IFFINDE	st	1. DEQ	--	0	Previously enqueued: Record Record set
IFFIND IFFINDE	mc, st	2. ENQ	SHR	0	New record set
IFFNDX IFFNDXE	st	DEQ	--	0	Previously enqueued: Record Record set
IFRELA	mc	DEQ	--	0	All record sets and lists previously enqueued (SHR or EXC)
IFRELR	mc	DEQ	--	0	Specified record set or list, previously enqueued
IFSKEY IFSKYE	st	DEQ	--	0	Previously enqueued: Record Record set
IFSORT IFSRTE	st	DEQ	--	0	Previously enqueued: Record Record set
Locking individual records
IFBREC	st	1. DEQ	--	0	Record previously enqueued
IFBREC		2. ENQ	EXC	0	New record
IFCCUR	mc	DEQ	--	0	Record previously enqueued
IFCTO IFCTOE	st	1. DEQ	--	0	Record previously enqueued
IFCTO IFCTOE		2. ENQ	SHR	0	Current record
IFDALL	st	1. DEQ	--	0	Record previously enqueued
	mc, st	2. ENQ	EXC	10	Current record (SRE lock)
		3. ENQ	EXC	0	Current record in LPU pending update pool
IFDREC	st	1. DEQ	--	0	Record previously enqueued
	mc, st	2. ENQ	EXC	10	Current record (SRE lock)
		3. ENQ	EXC	0	Current record in LPU pending update pool
IFDVAL	st	1. DEQ	--	0	Record previously enqueued
	mc, st	2. ENQ	EXC	10	Current record (SRE lock)
		3. ENQ	EXC	0	Current record in LPU pending update pool
IFFRN IFFRNE	mc	1. DEQ	--	0	Record previously enqueued
IFFRN IFFRNE		2. ENQ	SHR	0	Current record
IFFTCH IFFTCHE	mc	DEQ	--	0	Record previously enqueued
IFGET IFGETE	st	1. DEQ	--	0	Record previously enqueued
IFGET IFGETE		2. ENQ	SHR	0	Next logical record
IFGETX IFGETXE	st	1. DEQ	--	0	Record previously enqueued
IFGETX IFGETXE		2. ENQ	EXC	`n`	Next logical record
IFMORE IFMOREE	st	1. DEQ	--	0	Record previously enqueued
IFMORE IFMOREE		2. ENQ	SHR	0	Current record
IFMOREX IFMORXE	st	1. DEQ	--	0	Record previously enqueued
IFMOREX IFMORXE		2. ENQ	EXC	`n`	Current record
IFOCC IFOCCE	mc	ENQ	SHR	0	Current record
IFPUT IFPUTE	st	1. DEQ	--	0	Record previously enqueued
		2. ENQ	EXC	10	Current record (SRE lock)
		3. ENQ	EXC	0	Current record in LPU pending update pool
IFSTOR	mc	1. DEQ	--	0	Record previously enqueued
		2. ENQ	EXC	0	New record (SRE lock)
		3. ENQ	EXC	0	New record in LPU pending update pool
IFUPDT IFUPDTE	mc	1. DEQ	EXC	10	Current record (SRE lock)
IFUPDT IFUPDTE		2. ENQ	EXC	0	Current record in LPU pending update pool
Locking arbitrary resources
IFDEQ	mc, st	DEQ	--	0	Resource previously enqueued by IFENQ
IFENQ	mc, st	1. DEQ	--	0	User-specified source
IFENQ		2. ENQ	SHR/EXC	`n`	Note: `n` is a user-specified wait time in seconds.