Q command code

Use the Q command code if you want to prevent another program from updating a segment until your program reaches a commit point. The Q command code tells IMS that your application program needs to work with a segment and that no other tasks can be allowed to modify the segment until the program has finished.

This means that you can retrieve segments using the Q command code, then retrieve them again later, knowing that they have not been altered by another program. (You should be aware, however, that reserving segments for the exclusive use of your program can affect system performance.)

You can use the Q command code in batch programs in a data-sharing environment and in CICS® and IMS online programs. IMS ignores Q in non-data sharing batch programs.

Limiting the number of database calls

For full function, before you use the Q command code in your program, you must specify a MAXQ value during PSBGEN. This establishes the maximum number of database calls (with Q command codes) that you can make between sync points.

Related reading: For information on PSBGEN, see IMS Version 15.4 System Utilities.

Fast Path does not support the MAXQ parameter. Consequently in Fast Path, you can issue as many database calls with Q command codes as you want.

Using segment lock class

For full function, when you use the Q command code to retrieve a segment, you specify the letter Q followed by a letter (A-J), designating the lock class of that segment (for example, QA). If the lock class is not a letter (A-J), IMS returns the status code GL.

Fast Path supports the Q command code alone, without a letter designating the lock class. However, for consistency between Fast Path and full function, Fast Path treats the Q command code as a 2-byte string, where the second byte must be a letter (A-J). If the second byte is not a letter (A-J), IMS returns the status code AJ.

For example, suppose a customer wants to place an order for items 1, 2, and 3, but only if 50 item 1's, 75 item 2's, and 100 item 3's are available. Before placing this order, the program must examine all three item segments to determine whether an adequate number of each item is available. You do not want other application programs to change any of the segments until your program has determined this and, if possible, placed the order.

To process this request for full function, your program uses the Q command code when it issues the Get calls for the item segments. When you use the Q command code in the SSA, you assign a lock class immediately following the command code in the SSA.

GU    PART X
      ITEM 1    *QA
GU    PART X
      ITEM 2    *QA
GU    PART X
      ITEM 3    *QA

Exception: For Fast Path, the second byte of the lock class is not interpreted as lock class 'A'.

After retrieving the item segments, your program can examine them to determine whether an adequate number of each item are on hand to place the order. Assume 100 of each item are on hand. Your program then places the order and updates the database accordingly. To update the segment, your program issues a GHU call for each segment and follows it immediately with a REPL call:

GHU   ITEM 1
REPL  ITEM 1 with the value 50
GHU   ITEM 2
REPL  ITEM 2 with the value 25
GHU   ITEM 3
REPL  ITEM 3 with the value 0

Using the DEQ call with the Q command code

When you use the Q command code and the DEQ call, you reserve and release segments.

For full function, to issue a DEQ call against an I/O PCB to release a segment, you place the letter designating the segment's lock class in the first byte of an I/O area. Then, you issue the DEQ call with the name of the I/O area that contains the letter.

A DEDB DEQ call is issued against a DEDB PCB. Because Fast Path does not support lock class, a DEDB DEQ call does not require that a lock class be specified in the I/O area.

Restriction: The EXEC DL/I interface does not support DEDB DEQ calls, because EXEC DL/I disallows a PCB for DEQ calls.

Retrieving segments with full-function DEQ calls

The DEQ call releases all segments that are retrieved using the Q command code, except:

Segments modified by your program, until your program reaches a commit point
Segments required to keep your position in the hierarchy, until your program moves to another database record
A class of segments that has been locked again as another class

If your program only reads segments, it can release them by issuing a DEQ call. If your program does not issue a DEQ call, IMS releases the reserved segments when your program reaches a commit point. By releasing them with a DEQ call before your program reaches a commit point, you make them available to other programs more quickly.

Retrieving buffers with Fast Path DEQ calls

DEQ calls cause Fast Path to release a buffer that satisfies one of the conditions:

The buffer has not been modified, or the buffer does not protect a valid root position.
The buffer has been protected by a Q command code.

Fast Path returns an FW status code when no buffers can be released for a DEQ call.

Any CI locking or segment-level locking performed with a Q command code is protected from other application programs until a DEQ call is issued or a commit point is reached.

Considerations for root and dependent segments (full function only)

If you use the Q command code on a root segment, other programs in which the PCB does not have update capability can access the database record. Programs in which the PCB has update capability cannot access any of the segments in that database record. If you use the Q command code on a dependent segment, other programs can read the segment using one of the Get calls without the hold. If your program accesses shared databases, and if any of the segments in that block are reserved with the Q command code, application programs in other IMS systems cannot update anything in that block. The Q command code does not hold segments from one step of a conversation to another.

Related Reading: For more information on the relationship between the Q command code and the DEQ call, see the topic "Reserving Segments for the Exclusive Use of Your Program" in IMS Version 15.4 Application Programming.