Problem solve Get help with specific problems with your technologies, process and projects.

Allow users to see why they are locked

This service program will show you which job is locking in the update process.

It's sometimes useful for users, especially when IT department is unavailable, to be able to see by themselves...

which user/job is locking their update process.

When you know who's locking you, and where he is, a single phone call may solve your problem.

For this reason, I've created a service program, named S_DSPLOC, that when called after a record lock is encountered in an interactive program upon a file opened in update, retrieves the information related to the locking job and user and displays a lock notifying window with these info. The typical case of use for this SRVPGM is an interactive program locked in update to a master file. It should only be used when the update process may be canceled (not yet ongoing).

The resulting window shows the following information:

* Locking JOB (Device when interactive) name, and Device Description (when interactive)
* Locking user name, and user description

This additional info is available through F10:

* Locking Job Number
* Status (HELD)
* Lock (UPDATE)
* Physical File name (with the record locked)
* Relative record number locked

This SRVPGM accept three parameters and returns a status.

The Status returned may be:

0 - Ok (Window displayed with collected info) (IT'S THE NORMAL CASE)
1 - Locking not found (not locked anymore)
9 - Process failure (normally due to wrong parameters)

The three parameters to be passed are:

File_in : External Name of the file with the record locked. (10A )
Rrn_in : Relative record Number of the locked record (10i 0)
Msg_in : The particular message you want to give to the locked user..... (58A )

These parameters are transmitted by value (CONST keyword), allowing expressions to be passed as parameters and forcing compiler to accommodate mismatch in the definition between the callee and the caller (This is what happens for the RRN).

The principle is easy to understand.
When an input for update fails due to the fact that the record is still locked, the program waits for the number of seconds specified on the file's WAITRCD parameter (unless an override is in effect) before timing out on a record lock (The default value for WAITRCD is 60 seconds.) (WE WILL REDUCE THIS TIME TO 1 SECOND OR *IMMED)

To check for a record lock in RPGIV, get the record (CHAIN,READ..) specifying the 'E' extender on the opcode. You can then check the %ERROR and %STATUS built-in functions. %ERROR is set on if an error occurred. %STATUS may be checked to determine the error. %STATUS = 1218 indicates a record lock.

If you use for this file the INFDS keyword, the INFDS keyword lets you define and name a data structure to contain the feedback information associated with the file. The data structure name is specified as the parameter for INFDS. Positions 397-400 (4b 0) of this DS will contain the RRN of the last accessed record. That's what we need. You may use INFDS(feebk_Lock) (Feebk_lock is a DS defined in the P_S_DSPLOC copy provided). The retrieve RRN is called Rrn_lock.

You have caught the lock. You may call the SRVPGM to show who or what's holding the record.

The call will look like:

     C                   eval      ret_Dsp_lock = Dsp_Lock ('MYFILE   ':
     C                                                      Rrn_lock:
     C                                                      Msg_lck) 

Where - MYFILE is the name of the file with the locked record
- Msg_Lck is a standard defined message you provide to the user (that should be replaced by a file specific message.)

All the used variables in thesee three lines are defined in the P_S_DSPLOC copy. You may test the ret_Dsp_Lock variable to check the process result (0,1,9)

How to create the service program


Assume #lib is the library where you want to source and the program to be located. Assume #lib/#bind is a binding directory where you will enter S_DSPLOC SRVPGM. This bnddir is available to the caller (programs) thru *LIBL.

1. Copy the P_S_DSPLOC block (from begin to end) in a source member named #LIB/QRPGLESRC (P_S_DSPLOC)

2. Copy the DSPLOCFM block (from begin to end) in a source member named #lib/QDDSSRC (DSPLOCFM)

3. Compile the Display file DSPLOCFM source in #LIB

4. Copy the S_DSPLOC block (from begin to end) in a source member named #lib/QRPGLESRC (S_DSPLOC)

5. Compile the S_DSPLOC source with CRTRPGMOD (#LIB/S_DSPLOC), having #LIB in your *LIBL.


7. If you have no binding directory that may/can contain this SRVPGM, create one with CRTBNDDIR.

8. Update your binding directory with S_DSPLOC : WRKBNDDIR #lib/#bnddir, option 9 , option 1 (add) with OBJECT(S_DSPLOC) type(*SRVPGM) library(*libl).

Now the SRVPGM is available.

How to adapt the wait time (delay) for the required file


The program will wait for the number of seconds specified on the file's WAITRCD parameter (unless an override is in effect) before timing out on a record lock. The default value for WAITRCD is 60 seconds. If recommend one second, or *IMMED, for the file, using OVRDBF or CHGPF. If the program used file is and LF, you should adapt the WAITRCD parameter for both PF (with CHGPF) and LF (with CHGLF).

How to modify your RPGIV to use S_DSPLOC


Assume #lib/#bind is a binding directory with S_DSPLOC SRVPGM. This bnddir is available to the caller (programs) thru *LIBL.

1. Use BNDDIR(#LIB/#bind) in H statement. H BNDDIR('#LIB/#BIND')

2. Include the following copy in the top of D statements. D/COPY P_S_DSPLOC Proto fo S_UPDTAB

3. Attach the infds(feebk_lock) to your update-capable file. It will look like : FMyfile UF E K DISK infds(feebk_lock)

4. Replace your normal CHAIN (or read) for update code by something like:

     C     Key_          CHAIN(e)  Myfile                             
      ** AS400 RECORD LOCK
     C                   IF        %error                                       (B10)
     c                   if        %status(maexpl1) = 1218                      (B20) record Locked
     C                   eval      msg_lck     = 'This is a typical message...'
     C                   eval      ret_Dsp_lock = Dsp_Lock ('Myfile   ':
     C                                                      Rrn_lock:
     C                                                      Msg_lck)
     C                   GOTO      abort
     C                   endif                                                  (e20)
     C                   ENDIF                                                  (E10) 

Known limitations of this tip


* Does not support multiple member files -- limited to *first member.
* Does not support logical files based on multiple physical files.
* Does not apply to batch use (because of Display file).
* Useless when the update process can't be canceled.
* Requires at least V4R5 version of OS400 (for some API's)

Click here to view the code.

================================== MORE INFORMATION ON THIS TOPIC ==================================

The Best Web Links: tips, tutorials and more.

Ask your programming questions--or help out your peers by answering them--in our live discussion forums.

Ask the Experts yourself: Our application development gurus are waiting to answer your programming questions.

Dig Deeper on iSeries ILE programming