DBG_SELECT

Enable Select debugging

The DBG_SELECT environment variable turns on debugging for the Select class.

Value

One of the following:

1 = Log optimization details.

2 = Log optimization details and add display of the Select opcode stream to the log.

Discussion

When it’s enabled, two events cause Select debugging to output information: the creation of a Select object and the destruction of the AlphaEnumerator created from a Select object.

DBG_SELECT logging includes implicit and explicit key selection, including each key in the table, which keys have been referenced, which key was chosen, and why that key was chosen.

DBG_SELECT should never be used on multiple threads at the same time.

Setting location

The environment. DBG_SELECT can be reset by the SETLOG routine, and the runtime interprets the new setting.

Used by

Runtime

See also

DBG_SELECT_FILE environment variable

Examples

On Windows,

set DBG_SELECT=1

The logged content might look something like this:

[Select debugging at MAIN$APMAIN:93]
Where(D(7:5).EQ.23)
Optimized key: 2 
Head key length: 5
  Key range: 7:5
Tail exit condition: (7:5)EQ
[Select debugging at MAIN$APMAIN:120]
Where(Keynum(1).AND.A(1:2).EQ."90".AND.A(3:4).EQ."0097".AND.D(15:1).EQ.0.AND.D(21:1).EQ.1)
Optimized key: 1 
Head key length: 6
  Key segment ranges: (1:2) (3:4)
Tail exit conditions: (1:2)EQ (3:4)EQ
[Select debugging at MAIN$APMAIN:120]
Optimization effectiveness: 98%
Total rows fetched: 13871 out of 487055
[Select debugging at MAIN$APMAIN:93]
Optimization effectiveness: 100%
Total rows fetched: 1 out of 11049

The first part of the output (the first two sections) shows each Select that was executed, the module and line number of that Select, the query string, whether the Select is optimized, which key will be used for optimization, the key length to be used plus the key range (which can be matched back to fields in the query string) when Head optimization is used, and the exit conditions when Tail optimization is used. (The exit condition reflects the field(s) and comparison operator(s) being used to continue enumerating. When the comparison result is false, the exit condition has been met, thus terminating any further I/O.)

In the example,

“Where(D(7:5).EQ.23)” shows what the Select knows about the query string specified at line 93 in APMAIN. The specified field is decimal, starts at position 7 in the specified record and is 5 bytes long, and is being compared for equality against the value of 23. Field designations such as 7:5, when used below to describe optimization, can be further qualified by referring back here to the query string.
“Optimized key: 2” shows that the key that will be used for optimization is #2. If no key could be used for optimization, you’d see something like “Non-optimized key: 0”.
“Head key length: 5” shows the Select will perform head optimization. Rather than starting from the beginning of the file, the Select will use the first 5 bytes of key 2 to position directly to the first match using the target value “00023”.
“Key range: 7:5” refers to the field position and length of the optimized key.
The second Select at line 120 found a segmented key for optimization.
“Key segment ranges: (1:2) (3:4)” refers to the field positions and lengths of the optimized key segments. In this case, the Select will use the first 6 bytes (2+4) of the optimized key to position directly to the first match using the target value “900097”. Follow key segments (1:2) and (3:4) back to the query string to find the target type and value. If head optimization cannot be used, these entries will not be displayed.
“Tail exit condition: (7:5) EQ” shows the Select will perform tail optimization. Rather than unconditionally checking every record until End of File, the Select has constructed a condition past which no further I/O is necessary. When the field (7:5) retrieved from the file and compared using the EQ operator against the target value 23 is no longer true, exit the selection loop. Notice the second select at line 120 shows “Tail exit condition: (1:2)EQ (3:4)EQ”. This time 2 fields (1:2) and (3:4) will both be compared using the EQ operator against the target value “900097”, and then exit on a false condition. In both cases, you can find the target type and value by matching against the field designations in the query string. If tail optimization cannot be used, these entries will not be displayed.

The second part of the output (the last two sections) shows the result any optimization may have had on the file itself, post operation. Optimization effectiveness shows a percentage of rows/records checked vs. the total number of rows/records in the file. The higher the percentage, the better the optimization. Optimization effectiveness is not supported on OpenVMS or to an OpenVMS server. The “Total rows fetched” (supported on all systems) shows the total number of rows/records that were read. OpenVMS users can figure out the effectiveness of the optimization using this number and the number of records in their file. Note that if an AlphaEnumerator wasn’t created or was never used, this information will be suppressed.