Processing Fast Path DEDBs with subset pointer command codes

Subset pointers and the command codes you use with them are optimization tools that significantly improve the efficiency of your program when you need to process long segment chains.

Subset pointers are a means of dividing a chain of segment occurrences under the same parent into two or more groups or subsets. You can define as many as eight subset pointers for any segment type. You then define the subset pointers from within an application program. Each subset pointer points to the start of a new subset. For example, in the following topic, suppose you define one subset pointer that divides the last three segment occurrences from the first four. Your program can then refer to that subset pointer through command codes and directly retrieve the last three segment occurrences.

Chain of segments in order from B1 through B7. Subset pointer points to B5

You can use subset pointers at any level of the database hierarchy, except at the root level. If you try to use subset pointers at the root level, they are ignored.

The following figures show some of the ways you can set subset pointers. Subset pointers are independent of one another, which means that you can set one or more pointers to any segment in the chain. For example, you can set more than one subset pointer to a segment, as shown in the following figure.

Chain of segments in order from B1 through B7. Subset pointers P3 and P5 both point to segment B3

You can also define a one-to-one relationship between the pointers and the segments, as shown in the following figure.

Chain of segments B1 to B7. Segments pointers P1 to P6 are attached to segments B1 to B6 respectively. B7 does not have a segment pointer.

The following figure shows how the use of subset pointers divides a chain of segment occurrences under the same parent into subsets. Each subset ends with the last segment in the entire chain. For example, the last segment in the subset that is defined by subset pointer 1 is B7.

Chain of segments in order from B1 through B7. Subset pointer P1 points to segment B3. Subset pointer P2 points to segment B5

Before you use subset pointers

For your program to use subset pointers, the pointers must be defined in the DBD for the DEDB and in your program's PSB:

In the DBD, you specify the number of pointers for a segment chain. You can specify as many as eight pointers for any segment chain.
In the PSB, you specify which pointers your program is to use. Define this on the SENSEG statement. (Each pointer is defined as an integer from 1 to 8.) Also, indicate on the SENSEG statement whether your program can set the pointers it uses. If your program has read sensitivity, it cannot set pointers but can only retrieve segments using subset pointers that are already set. If your program has update sensitivity, it can also update subset pointers by using the S, W, M, and Z command codes.

After the pointers are defined in the DBD and the PSB, an application program can set the pointers to segments in a chain. When an application program finishes executing, the subset pointers used by that program remain as they were set by the program; they are not reset.

Designating subset pointers

To use subset pointers in your program, you must know the numbers for the pointers as they were defined in the PSB. When you use the subset pointer command codes, specify the number of each subset pointer you want to use followed by the command code. For example, you use R3 to indicate that you want to retrieve the first segment occurrence in the subset defined by subset pointer 3. No default exists, so if you do not include a number between 1 and 8, IMS considers your SSA invalid and returns an AJ status code.

Subset pointer command codes

To take advantage of subsets, application programs use five command codes. The R command code retrieves the first segment in a subset. The following 4 command codes, which are explained in the topic "DEDB command codes for DL/I" in IMS Version 15.5 Application Programming APIs, redefine subsets by modifying the subset pointers:

Z: Sets a subset pointer to 0.
M: Sets a subset pointer to the segment following the current segment.
S: Unconditionally sets a subset pointer to the current segment.
W: Conditionally sets a subset pointer to the current segment.

Before your program can set a subset pointer, it must establish a position in the database. A call must be fully satisfied before a subset pointer is set. The segment a pointer is set to depends on your current position at the completion of the call. If a call to retrieve a segment is not completely satisfied and a position is not established, the subset pointers remain as they were before the call was made. You can use subset pointer command codes in either an unqualified SSA or a qualified SSA. To use a command code in a call with an unqualified SSA, use the command code along with the number of the subset pointer you want, after the segment name. This is shown in the following figure.

Table 1. Unqualified SSA with subset pointer command code
Seg Name	*	Cmd Code	Ssptr.	b
8	1	Variable	Variable	1

To use a subset pointer command code with a qualified SSA, use the command code and subset pointer number immediately before the left parenthesis of the qualification statement, as shown in the following figure.

Table 2. Qualified SSA with subset pointer command code
Seg Name	*	Cmd Code	Ssptr.	(	Fld Name	R.O.	Fld Value	)
8	1	Variable	Variable	1	8	2	Variable	1

Inserting segments in a subset

When you use the R command code to insert an unkeyed segment in a subset, the new segment is inserted before the first segment occurrence in the subset. However, the subset pointer is not automatically set to the new segment occurrence.

For example, the following call inserts a new B segment occurrence in front of segment B5, but does not set subset pointer 1 to point to the new B segment occurrence:

ISRT   Abbbbbbb
(Akeybbbb=bA1)
Bbbbbbbb
*R1

To set subset pointer 1 to the new segment, you use the S command code along with the R command code, as shown in the following example:

ISRT   Abbbbbbb
(Akeybbbb=bA1)
 Bbbbbbbb
*R1S1

If the subset does not exist (subset pointer 1 is set to 0), the segment is added to the end of the segment chain.

Deleting the segment pointed to by a subset pointer

If you delete the segment pointed to by a subset pointer, the subset pointer points to the next segment occurrence in the chain. If the segment you delete is the last segment in the chain, the subset pointer is set to 0.

Combining command codes

You can use the S, M, and W command codes with other command codes, and you can combine subset pointer command codes with each other, as long as they do not conflict. For example, you can use R and S together, but you cannot use S and Z together because their functions conflict. If you combine command codes that conflict, IMS returns an AJ status code to your program.

You can use one R command code for each SSA and one update command code (Z, M, S, or W) for each subset pointer.