Record Selection Tests

You can issue any FOCUS report request through the IMS/DB Interface. However, those requests whose record selection criteria can be applied at the IMS level (with qualified SSAs on .KEY, .IMS, .HKY, or .SKY fields) result in many fewer DL/I calls and I/O operations than non-optimized requests. They can achieve performance improvements measured in orders of magnitude.

Note: Since IMS does not support the concept of missing data, FOCUS considers all fields not missing.

This section includes sample requests with their corresponding FSTRACE4 results. When you allocate FSTRACE4 as described in Tracing Interface Processing, you get a dump of the SSA buffer set-up for each request. For example, the following is a selection test on the SEQFIELD search field in the PATINFO segment of the PATDB01 database (see Sample File Descriptions):

IF SEQFIELD EQ '100000' OR '100001'

It produces the following FSTRACE4 results:

  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604DE2 C5D8C6C9      *PATINFO *-(SEQFI*
 C5D3C47E 40F1F0F0 F0F0F04E E2C5D8C6      *ELD= 100000+SEQF*
 C9C5D3C4 7E40F1F0 F0F0F0F1 5D40          *IELD= 100001)   *

Note:

• The dump has a left side and a right side. The left side shows the hexadecimal values in the memory locations. The right side, delimited by *'s, contains the corresponding alphanumeric characters.

Since not all hexadecimal values represent printable alphanumeric characters, those parts of the dump that correspond to non-printable characters display as blanks on the right side. In particular, if a comparison value in an SSA is a packed number, it displays as blank on the right-hand side of the dump. In this example, the comparison values are alphanumeric and, therefore, they display.

• The logical operator AND is represented by an asterisk (*) in the SSA, and the logical operator OR is represented by a plus sign (+).
• The field names in the SSA are the IMS names for the fields; the Interface finds these names in the Master File as ALIAS values.
• The SSA always includes the segment name, PATINFO in this case. What distinguishes an optimized request from a non-optimized request is whether the SSA is qualified; a qualified SSA includes the selection test from the request, as in the previous example. An unqualified SSA contains the segment name with no selection criteria.
• If you access the Interface in the DBCTL environment, the trace includes additional statistics. Tracing Interface Processing, contains a detailed description of trace facilities.

Whenever possible, the Interface translates screening conditions from the FOCUS request into qualified SSAs. However, not all FOCUS screening conditions can be translated into SSAs. Such conditions are still applied, but by FOCUS, not by IMS. In those cases, the Interface retrieves the data sequentially and passes it to FOCUS for screening.

Access Method Restrictions

Some IMS access methods are limited in their ability to apply certain screening conditions. These restrictions can affect request optimization. The following considerations apply to specific access methods:

• Since HDAM databases are stored randomly and accessed directly, IMS cannot retrieve their records in root key sequence. Therefore, with an HDAM database, the Interface can only optimize equality conditions on the root key:

KEY EQ value

You can build a secondary index on the root key and use it to optimize sequential (range) processing. Auto Index Selection, contains an example.

Note: The NE condition is not optimized.

• With HIDAM databases, the Interface optimizes LIKE tests with a mask by translating the LIKE into a range condition. See Partial Key and Multi-Segment Requests, for an example.
• To take advantage of efficiencies available by limiting processing to one area of a Fast Path DEDB database, the PSB must limit access to that area.

Rules for Constructing SSAs From FOCUS IF Tests

In order for the Interface to translate a FOCUS IF test into a qualified SSA, the following conditions must exist:

• The field tested must be an IMS key field, search field, or a secondary index.
• The test relation must be one of the relations described in this section.
• The tested field cannot be a floating point numeric or zoned field.

Note: In order for the Interface to optimize selection tests on zoned key fields, you must describe the USAGE format of these fields as alphanumeric or packed in the Master File.

• The ACTUAL and USAGE formats of the tested field must be basically the same, so no format conversion is required. For example, extending with leading zeros or padding with trailing blanks is not a format conversion, but shifting the implied decimal point in a packed field is.
• In an HDAM database, record selection tests must use the EQ relation on the root key, with no value masking, or you must have a secondary index on the root key.

The Interface can translate the following test relations to qualified SSAs:

• Comparison of a field to a list of values:

field relation value1 OR value2 ... OR valuen

See Complex Screening Conditions, for a discussion of SSA generation when comparing a field to a list of values.

• IS, EQ
• IS-NOT, NE
• IS-FROM, FROM, GE
• LIKE
• NOT LIKE
• TO, LE
• FROM...TO

The Interface treats the FROM...TO relation as a pair of relations. For example:

IF field GE . . . AND IF field LE . . .

The Interface also translates a search on a partial key (the high-order portion of a key) to a range condition and optimizes it (see Partial Key and Multi-Segment Requests, for an example).

• NOT-FROM...TO
• IS-MORE-THAN, EXCEEDS, GT
• IS-LESS-THAN, LT

Note: The Interface does not optimize the relations INCLUDES, EXCLUDES, CONTAINS, and OMITS.

Complex Screening Conditions

The general form for a complex screening condition is:

field1 relation1 value1 OR field2 relation2 value2  OR ...

If the fields are search or sequence fields, the Interface can optimize the screening test subject to certain conditions. The Interface either constructs a single SSA or multiple SSAs, depending on the characteristics of the segment and the type of relation used.

Note: Using the AND operator between logical conditions in a selection test is equivalent to using multiple IF statements without the AND operator. The Interface constructs a qualified SSA that incorporates the AND operation in either case.

This section describes the following:

• The SSA buffer, and how the Interface processes SSAs that do not fit into the buffer.
• Conditions under which the Interface constructs a single SSA.
• Conditions under which the Interface constructs multiple SSAs.

The SSA Buffer

Once the Interface constructs an SSA, it must place it in the SSA buffer in order to submit it in a DL/I call. If the SSA is too long to fit into the buffer, the Interface makes the following choices between the individual screening conditions within the SSA:

• Tests on key fields take precedence over all other tests.
• The Interface gives precedence to remaining tests based on their order in the query. It retains earlier tests and eliminates later tests from the SSA, so you can influence the conditions included in the SSA by carefully constructing your screening conditions.

If an SSA does not fit into the SSA buffer, no error is generated. The selection tests omitted from the SSA are applied, but they are not optimized; that is, FOCUS applies them, not IMS.

Note: The number of conditions that fit into the SSA buffer is not fixed; it varies depending on the lengths of the values in the comparisons and on the relations used in the comparisons.

Constructing a Single SSA

The Interface constructs a single SSA that incorporates the entire complex logical condition if any of the following is true:

• The segment has no key.
• There is a key, but the request does not include a screening condition that references it.
• There is a record selection test on the key that specifies the EQ relation or a single range.

If the entire SSA fits into the SSA buffer, the Interface submits it in the DL/I call. If the SSA is too long to fit into the SSA buffer, the Interface makes the choices described in the previous section, The SSA Buffer.

The following example illustrates SSA generation when there is no equality test on the key field, but there are tests on a search field:

TABLE FILE PATINFO
PRINT SSN SEQFIELD LAST_NAME
IF SEQFIELD EQ '100000' OR '100005'
IF LAST_NAME EQ 'BORRERO' OR 'JONES'
END

These selection criteria produce the following trace:

  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604DE2 C5D8C6C9      *PATINFO *-(SEQFI*
 C5D3C47E 40F1F0F0 F0F0F05C D3D5C1D4      *ELD= 100000*LNAM*
 C5404040 7E40C2D6 D9D9C5D9 D6404040      *E   = BORRERO   *
 40404EE2 C5D8C6C9 C5D3C47E 40F1F0F0      *  +SEQFIELD= 100*
 F0F0F05C D3D5C1D4 C5404040 7E40D1D6      *000*LNAME   = JO*
 D5C5E240 40404040 40404EE2 C5D8C6C9      *NES       +SEQFI*
 C5D3C47E 40F1F0F0 F0F0F55C D3D5C1D4      *ELD= 100005*LNAM*
 C5404040 7E40C2D6 D9D9C5D9 D6404040      *E   = BORRERO   *
 40404EE2 C5D8C6C9 C5D3C47E 40F1F0F0      *  +SEQFIELD= 100*
 F0F0F55C D3D5C1D4 C5404040 7E40D1D6      *005*LNAME   = JO*
 D5C5E240 40404040 40405D40               *NES       )     *

The trace shows that the Interface generates one SSA, incorporating the following selection criteria:

(SEQFIELD EQ 100000 AND LNAME EQ BORRERO
 OR SEQFIELD EQ 100000 AND LNAME EQ JONES
 OR SEQFIELD EQ 100005 AND LNAME EQ BORRERO
 OR SEQFIELD EQ 100005 AND LNAME EQ JONES)

If this SSA did not fit into the SSA buffer, the Interface would retain as much of it as possible in a qualified call, after which FOCUS would apply the remaining tests to the returned segments.

The request produces the following report:

  PAGE     1


  SSN        SEQFIELD  LAST_NAME
  ---        --------  ---------
  197548684  100005    JONES

Constructing Multiple SSAs

This section describes how the Interface handles SSA generation when the condition in the FOCUS request compares a key field to a list of values. The key can be unique or non-unique. The form of such a condition is

IF key EQ value1 OR value2 OR value3 ... 

IF key IS (filename)

or

WHERE key IN (value1, value2, ... ,valuen)

where:

key

Is a key field or secondary index.

value1...valuen

Are the comparison values.

filename

Indicates that the comparison values are stored in a sequential file allocated to DDNAME file name. The file can contain up to 4000 bytes of data; for an 8-byte key, this is enough space for 500 values.

With this kind of screening condition, the Interface constructs a separate SSA for each value in the list, in ascending sort sequence, and transmits each one in turn to IMS:

(key EQ value1)
  .
  .
  .
(key EQ valuen)

The Interface first issues a DL/I call containing only the first SSA. If IMS locates a segment that satisfies the condition in the SSA, the Interface returns the segment to FOCUS. Otherwise, the Interface issues a DL/I call that incorporates only the second SSA. It continues until IMS either locates a segment that satisfies one of the SSAs or exhausts the list of values.

In the following example, the Interface constructs three SSAs:

TABLE FILE PATINFO
PRINT SSN SEQFIELD LAST_NAME
IF SSN EQ '197548682' OR '197548685' OR '197548691'
END

The FSTRACE4 results show the three separate SSAs generated:

  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604DE2 E2D54040      *PATINFO *-(SSN  *
 4040407E 40F1F9F7 F5F4F8F6 F8F25D40      *   = 197548682) *
  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604DE2 E2D54040      *PATINFO *-(SSN  *
 4040407E 40F1F9F7 F5F4F8F6 F8F55D40      *   = 197548685) *
  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604DE2 E2D54040      *PATINFO *-(SSN  *
 4040407E 40F1F9F7 F5F4F8F6 F9F15D40      *   = 197548691) *

The following is the resulting report:

  PAGE     1


  SSN        SEQFIELD  LAST_NAME
  ---        --------  ---------
  197548682  100003    SALEH
  197548685  100006    JACA
  197548691  100012    BOYCE

The next request illustrates an equality test on the key field and an additional test on a search field:

TABLE FILE PATINFO
PRINT SSN SEQFIELD LAST_NAME
IF SSN EQ '197548679' OR '197548682' OR '197548685'
IF SEQFIELD GT '100000'
END

The request produces multiple SSAs, as illustrated in the following trace:

  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604DE2 E2D54040      *PATINFO *-(SSN  *
 4040407E 40F1F9F7 F5F4F8F6 F7F95CE2      *   = 197548679*S*
 C5D8C6C9 C5D3C46E 40F1F0F0 F0F0F05D      *EQFIELD> 100000)*
 40                                       *                *
  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604DE2 E2D54040      *PATINFO *-(SSN  *
 4040407E 40F1F9F7 F5F4F8F6 F8F25CE2      *   = 197548682*S*
 C5D8C6C9 C5D3C46E 40F1F0F0 F0F0F05D      *EQFIELD> 100000)*
 40                                       *                *
  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604DE2 E2D54040      *PATINFO *-(SSN  *
 4040407E 40F1F9F7 F5F4F8F6 F8F55CE2      *   = 197548685*S*
 C5D8C6C9 C5D3C46E 40F1F0F0 F0F0F05D      *EQFIELD> 100000)*
 40                                       *                *

The Interface constructs three SSAs and applies them one at a time:

 (SSN EQ 197548679 AND SEQFIELD GT 100000)
 (SSN EQ 197548682 AND SEQFIELD GT 100000)
 (SSN EQ 197548685 AND SEQFIELD GT 100000)

The following report is produced:

  PAGE     1


  SSN        SEQFIELD  LAST_NAME
  ---        --------  ---------
  197548682  100003    SALEH
  197548685  100006    JACA

If the SSA generated by combining the conditions in all the IF statements is too long to fit into the SSA buffer, the Interface retains as much of it as possible in a qualified call by applying the rules described in the previous section, The SSA Buffer.

Sequentially Accessed Root Segments

If the root segment is the target of the SSA generated by a request, and if it has a unique key, the Interface assumes that IMS will use an index or randomizing scheme to locate the segment without an exhaustive search of the root segment chain. Therefore, the Interface retrieves the segment with qualified GET UNIQUE calls.

Even if the assumption that there is an index or randomizing scheme for IMS to use is not valid, as with HSAM databases, each call starts its search at the first record in the database. In this situation, it is preferable to describe the root segment as having no key (SEGTYPE=S0), and not to describe any field's alias with the .KEY suffix. This technique causes the Interface to issue qualified GET NEXT calls that access the roots sequentially and maintain their position in the database from one call to the next.

WHERE Tests

When the Interface constructs DL/I calls, it looks only at IF selection tests, not WHERE tests. However, prior to constructing DL/I calls, it examines WHERE selection tests and, when possible, translates them to equivalent IF statements. Therefore, WHERE tests that can be expressed as IF tests are subject to the same optimization rules as IF tests.

For example, if field1 and field2 are search or sequence fields, the Interface optimizes the following WHERE test:

WHERE field1 relation1 value1 AND field2 relation2 value2

It is equivalent to the following:

IF field1 relation1 value1
IF field2 relation2 value2

The Interface can also optimize the following WHERE conditions:

• WHERE tests that use the AND operator between adjacent parts of a key.
• WHERE tests that compare an IMS field to a list of values, as described in Constructing Multiple SSAs in Section Complex Screening Conditions, Complex Screening Conditions.

The Interface optimizes the following request:

TABLE FILE PATINFO
PRINT SSN SEQFIELD LAST_NAME
WHERE SSN EQ '197548679' AND SEQFIELD EQ '100000'
END

The trace shows the qualified SSA that the request generates:

  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604DE2 E2D54040      *PATINFO *-(SSN  *
 4040407E 40F1F9F7 F5F4F8F6 F7F95CE2      *   = 197548679*S*
 C5D8C6C9 C5D3C47E 40F1F0F0 F0F0F05D      *EQFIELD= 100000)*
 40                                       *                *

The report follows:

  PAGE     1


  SSN        SEQFIELD  LAST_NAME
  ---        --------  ---------
  197548679  100000    ROSANO

The Interface cannot optimize the following types of WHERE tests:

WHERE field1 relation field2
WHERE field1 relation1 value1 OR field2 relation2 value2

For example, the Interface does not optimize the next request:

TABLE FILE PATINFO
PRINT SSN SEQFIELD LAST_NAME
WHERE SSN EQ '197548679' OR SEQFIELD EQ '100000'
END

The resulting SSA is not qualified; it includes the segment name, but no selection criteria:

  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604040               *PATINFO *-      *

FOCUS retrieves all records from the segment, applies the selection criteria, and produces the following report:

  PAGE     1


  SSN        SEQFIELD  LAST_NAME
  ---        --------  ---------
  197548679  100000    ROSANO

Partial Key and Multi-Segment Requests

This section illustrates SSAs for requests that select on a partial key and requests that access values from multiple segments.

Selection on a Partial Key

The Interface can optimize record selection on a partial key unless the database is an HDAM database. The partial key must be the high-order (leftmost) portion of the key. To search on a partial key, use a mask as the comparison value in the relation. The syntax is

{IF|WHERE} field EQ 'xxx$*'

{IF|WHERE} field LIKE 'xxx%'

where:

field

Is a valid field name.

xxx

Are any number of characters that constitute the leftmost portion of the key. You must enclose the masking characters between single quotation marks.

$* or %

The Interface translates the condition to a range using GE and LE. Consider the following request:

DYNAM ALLOC FILE FSTRACE4 DA *
TABLE FILE PATINFO
PRINT SSN SEQFIELD LAST_NAME
WHERE SSN EQ '1975486$*'
END

The FSTRACE4 results show that the Interface translated the selection test to a range condition:

  set up SSA-Q:
 D7C1E3C9 D5C6D640 5C604DE2 E2D54040      *PATINFO *-(SSN  *
 4040406E 7EF1F9F7 F5F4F8F6 00005CE2      *   >=1975486  *S*
 E2D54040 4040404C 7EF1F9F7 F5F4F8F6      *SN     <=1975486*
 FFFF5D40                                 *::)             *

To define the range of values, the Interface appends the lowest hexadecimal value (00) and the highest hexadecimal value (FF) to 1975486 (00 and FF are not alphanumeric representations of numbers; therefore they do not print on the right side of the dump).

The first few lines of the resulting report follow:

  PAGE     1


  SSN        SEQFIELD  LAST_NAME
  ---        --------  ---------
  197548679  100000    ROSANO
  197548681  100002    BORRERO
  197548682  100003    SALEH
  197548683  100004    SALGADO
  197548684  100005    JONES
  197548685  100006    JACA
  197548686  100007    PENA
  197548687  100008    FREEMAN
     .
     .
     .

Multi-Segment Requests

When a request requires access to multiple segments, the Interface constructs one SSA for each segment. (DL/I Calls, explains the rules for accessing multiple segments.) If the selection criteria for a particular segment can be optimized, its corresponding SSA is qualified.

The following request includes an equality test on PARTKEY, the root key of the DI21PART database, but it contains no selection criteria for the STANKEY field in the STANINFO segment:

TABLE FILE DI21PART
PRINT PARTKEY STANKEY
IF PARTKEY EQ '02AN960C10'
END

The SSA for the root segment, PARTROOT, is qualified, but the SSA for the STANINFO segment is not qualified:

  set up SSA-Q:
 D7C1D9E3 D9D6D6E3 5C604DD7 C1D9E3D2      *PARTROOT*-(PARTK*
 C5E8407E 40F0F2C1 D5F9F6F0 C3F1F040      *EY = 02AN960C10 *
 40404040 40405D40                        *      )         *
  set up SSA-Q:
 E2E3C1D5 C9D5C6D6 5C604040               *STANINFO*-      *

The request produces the following report:

  PAGE     1


  PARTKEY            STANKEY
  -------            -------
  02AN960C10         02

The next request includes a not-equal condition on PARTKEY, the root key of the DI21PART database; it has no selection criteria for STANKEY:

TABLE FILE DI21PART
PRINT PARTKEY STANKEY
IF PARTKEY NE '02AN960C10'
END

The following is the SSA for both the PARTROOT and STANINFO segments:

 
  set up SSA-Q:
  D7C1D9E3 D9D6D6E3 5C604DD7 C1D9E3D2      *PARTROOT*-(PARTK* 
 C5E8405F 7EF0F2C1 D5F9F6F0 C3F1F040      *EY ¬=02AN960C10 * 
 40404040 40405D40                        *      )         * 
  set up SSA-Q:
 E2E3C1D5 C9D5C6D6 5C604040               *STANINFO*-      *

FOCUS applies the selection criteria to produce the desired report. The first several lines in the report follow:

  PAGE     1


  PARTKEY            STANKEY
  -------            -------
  02CK05CW181K       02
  02CSR13G104KL      02
  02JAN1N976B        02
  02MS16995-28       02
  02N51P3003F000     02
  02RC07GF273J       02
  02TPART01          02
  02106B1293P009     02
  02250236-001       02
    .
    .
    .

It is important to consider how qualified SSAs on lower level segments of a database may affect performance:

• IMS retrieves lower level segments sequentially (after possibly locating the appropriate root segment via an index or hash code).
• If the Interface passes a qualified SSA on a lower level segment to IMS without a qualified SSA on the root segment, IMS does not return data or a return code to the Interface until it either finds an appropriate segment or exhausts the entire database.
• Depending on the size of the database, the Interface could wait an extremely long time between calls without any way to interrupt the process.

These facts make it advantageous to screen on the root segment, where an index or hash code makes retrieval efficient. One technique for preventing an exhaustive search of the database is to define fields in low level segments in the Master File as non-search fields. This approach forces control to return to FOCUS after retrieval of each segment instance, giving you the opportunity to limit processing with a READLIMIT test. For information on READLIMIT, see Search Limits.

Auto Index Selection

When the Master File and FOCPSB define secondary indexes for a database, the Interface analyzes each request to determine the most efficient entry point into the database. For information on creating a Master File and FOCPSB for use with a database that has secondary indexes, refer to IMS Overview and Mapping Concepts, and Chapter 3, Creating FOCUS Descriptions.

The Interface scans each request to determine if fields used in record selection tests are key fields, secondary indexes, or the high-order (leftmost) parts of either. Depending on the request criteria, the Interface selects the appropriate PCB for the most efficient access to the data. The PATINFO Master File describes a secondary index named IXADMD on the ADMIT_DATE field.

In the following request, the field referenced in the IF condition is the field associated with the secondary index called IXADMD:

TABLE FILE PATINFO
PRINT LAST_NAME SALARY ADMIT_DATE
IF ADMIT_DATE EQ '19920925'
END

The trace shows that the Interface generates a qualified SSA using the IXADMD index:

  set up SSA-Q:                                                
 D7C1E3C9 D5C6D640 5C604DC9 E7C1C4D4      *PATINFO *-(IXADM*    
 C440407E 40F1F9F9 F2F0F9F2 F55D40        *D  = 19920925)  *    

If a request includes record selection tests on more than one field, or if a field participates in more than one type of index, the Interface uses the following order of precedence in choosing which PCB to use:

1. .KEY field (primary index).

If a field in a record selection test is both a .KEY field and the high-order portion of a secondary index, the Interface accesses the database via the primary index on the .KEY field.

However, if the database is an HDAM database, and if the request includes a range test on a field that is both an .HKY field and a .SKY field, the Interface accesses the database through the secondary index on the .SKY field. (Recall that only equality conditions on .HKY fields generate qualified SSAs.)

2. .SKY field (secondary index).

3. .IMS field (search field).

The following example demonstrates how secondary indexes and the Auto Index Selection feature affect SSA generation. The following Master File, AIHDAM, describes an HDAM database. This Master File does not describe a secondary index on the key field (the DBD, PSB, and FOCPSB do include a secondary index description; see Sample File Descriptions):

FILE=AIHDAM   ,SUFFIX=IMS   ,$ 
SEGNAME=LANGUAGE ,SEGTYPE=S1 ,$ 
 FIELD=EMPLOYEE_ID6  ,ALIAS=EMPL6.HKY   ,I9 ,I4  ,$ 
 FIELD=LANGUAGE      ,ALIAS=LANG6.IMS   ,A15,A15 ,$ 

A range test on the key field generates an unqualified SSA:

TABLE FILE AIHDAM
 > PRINT *
 > WHERE EMPLOYEE_ID6 FROM 5248 TO 6393
 > END                                                                

  set up SSA-Q:                                                      
 D3C1D5C7 E4C1C7C5 5C604040               *LANGUAGE*-      *          

Following is the same Master File, edited to describe the secondary index on the key field:

FILE=AIHDAM   ,SUFFIX=IMS   ,$    
SEGNAME=LANGUAGE ,SEGTYPE=S1 ,$   
 FIELD=EMPLOYEE_ID6  ,ALIAS=EMPL6.HKY   ,I9 ,I4   ,$  
 FIELD=LANGUAGE      ,ALIAS=LANG6.IMS   ,A15,A15  ,$  
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$ 
$$           SECONDARY INDEX DESCRIPTION           $$ 
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
GROUP=EMPLIX         ,ALIAS=IXEMP6.SKY  ,I9 ,I4   ,$  
 FIELD=EMPLY6        ,ALIAS=EMPLOYEE_ID6,I9 ,I4   ,$  

Now, the Interface can use the Auto Index Selection feature on the same request to generate a qualified SSA:

>  > TABLE FILE AIHDAM                                       
> PRINT *                                                    
> WHERE EMPLOYEE_ID6 FROM 5248 TO 6393                       
> END                                                        

  set up SSA-Q:                                              
 D3C1D5C7 E4C1C7C5 5C604DC9 E7C5D4D7      *LANGUAGE*-(IXEMP*  
 F640406E 7E000014 805CC9E7 C5D4D7F6      *6  >=   Ø*IXEMP6*  
 40404C7E 000018F9 5D40                   *  <=   9)       *  

Search Limits

There are two search limit tests available through the Interface.

• READLIMIT limits the number of records searched in a file.
• RECORDLIMIT stops a search after finding a specified number of records that pass all screening criteria.

When reporting against an IMS database, you may want to halt the retrieval after reading part of the database when any of the following conditions exists:

• You are testing a new Master File. A few records are adequate to determine whether the description is correct.
• You are testing a new report format.
• You need to generate a trace for debugging purposes.
• The Database Administrator wants to limit segment search and retrieval for very large IMS databases.

The syntax is

IF {READLIMT|RECORDLIMIT} EQ n

where:

n

Is a number greater than 0.

The Database Administrator can supply this screening condition directly in the Master File, in which case you cannot override it. If you include a READLIMIT or RECORDLIMIT test in a request, and the Database Administrator also includes one in the Master File, FOCUS uses the smaller value. (Refer to the FOCUS for IBM Mainframe Users Manual for additional information on READLIMIT and RECORDLIMIT.)

FOCUS, not IMS, applies READLIMIT and RECORDLIMIT tests. Therefore, because IMS always searches as much of the database as necessary to locate an appropriate segment, the READLIMIT setting has no effect on retrieval in an optimized request.

To illustrate this point, the next examples reference fields from the PATINFO Master File (see Sample File Descriptions). The database contains the following values:

SEQFIELD	FIRST_NAME	LAST_NAME
100000	ANDRE	ROSANO
100001	LARRY	LOVELACE
100002	JOHN	BORRERO
100003	JAMAL	SALEH

Consider this request:

TABLE FILE PATINFO
PRINT FNAME
IF READLIMIT EQ 1
END

Since the field FNAME is not qualified, FOCUS applies the READLIMIT condition and locates the following value for FNAME in its one read:

ANDRE

The next request includes a screening condition on FNAME, an IMS search field. The Interface passes the screening condition to IMS in a qualified SSA, and IMS searches for a segment that passes the test, unaware of the READLIMIT condition:

TABLE FILE PATINFO
PRINT FNAME
IF FNAME GT 'JAMES'
IF READLIMIT EQ 2
END

The report contains the following values for FNAME:

LARRY
JOHN

FOCUS considers the retrieval of a qualified segment a single read, even though IMS may read many segments to locate each one that it returns to FOCUS. In the previous example, IMS had to read three records in order to locate the two records that it returned to FOCUS.

In the next example, the requested value does not exist in the database but, because FNAME is qualified by an optimized screening condition, IMS searches the entire database trying to locate it:

TABLE FILE PATINFO
PRINT FNAME
IF FNAME GT 'TOMMY'
IF READLIMIT IS 1
END

To prevent this situation, the user should be aware of the valid range of values contained in the database when IMS search fields are part of a Master File.