Specifying segment search arguments using the SSAList interface

Creating an unqualified SSAList

This example returns a Path that consists of all fields in the segment DOCTOR:

SSAList ssaList = pcb.getSSAList("HOSPITAL","DOCTOR");
Path path = ssaList.getPathForRetrieveReplace();
pcb.getUnique(path, ssaList, false);  

In the previous example, the ssaList represents all segments along the hierarchic path from the topmost segment (HOSPITAL) to the lowest segment (DOCTOR). The ssaList will look like this:

HOSPITALb
WARDbbbbb
PATIENTbb
ILLNESSbb
TREATMNTb
DOCTORbbb

Creating a qualified SSAList

An SSAList can be qualified to filter the segments on the hierarchic path to be retrieved or updated. The general steps to create a qualified SSAList are:

1. Obtain an unqualified SSAList from the PCB using the getSSAList method.
2. Use the addInititalQualification method to specify the initial search criteria for a segment on the SSAList returned from a getSSAList method. For each segment represented in the SSAList, you can make one call to specify an initial qualification for that segment. The segment can be referenced by name or by using the 1-based offset of the SSA representing that segment within the SSAList. If you use more than one addInitialQualification statement for a segment, an exception will be thrown. The relational operator (relationalOp) parameter in the addInitialQualification method indicates the conditional criteria that the segment must meet in order to be qualified. Valid relational operators are:
   • EQUALS
   • GREATER_OR_EQUAL
   • GREATER_THAN
   • LESS_OR_EQUAL
   • LESS_THAN
   • NOT_EQUAL
3. To specify additional search criteria, use the appendQualification method. For each segment, you can make multiple calls to the appendQualification method to add more than one qualification statement. The Boolean operator (booleanOp) parameter in the appendQualification method indicates how this qualification is logically connected to the previous qualification. Valid Boolean operators are:
   • AND
   • OR
   • INDEPENDENT_AND
4. You can also qualify a SSAList by setting DL/I command codes and lock classes. The supported DL/I command codes include:
   • CC_A: The A command code (clear positioning).
   • CC_C: The C command code (concatenated key). Use the addConcatenatedKey method to add a concatenated key to a segment.
   • CC_D: The D command code (path call)
   • CC_F: The F command code (first occurrence)
   • CC_G: The G command code (prevent randomization).
   • CC_L: The L command code (last occurrence)
   • CC_N: The N command code (path call ignore)
   • CC_O: The O command code (contain field names or segment position and length).
   • CC_P: The P command code (set parentage)
   • CC_U: The U command code (maintain position at this level)
   • CC_V: The V command code (maintain position at this level and all superior levels)
   You can use a lock class to prevent another program from updating a segment until your program reaches a commit point. Use the addLockClass method to add a lock class to a segment. The supported lock class letters are A to J. The behavior of a lock class is the same as using a Q command code with that lock class letter.

The following code example demonstrates how to specify and use a qualified SSAList with a single initial qualification statement to retrieve data:

SSAList ssaList = pcb.getSSAList("HOSPITAL","DOCTOR");
ssaList.addInitialQualification("PATIENT","PATNAME",SSAList.EQUALS,"ANDREA SMITH");
ssaList.markFieldForRetrieval("ILLNESS","ILLNAME",true);
ssaList.markFieldForRetrieval("TREATMNT","TREATMNT",true);
Path path = ssaList.getPathForRetrieveReplace();
pcb.getUnique(path, ssaList, false); 

For the code example above, the ssaList will look like this:

HOSPITALb
WARDbbbbb
PATIENTb(PATNAMEbEQANDREAbSMITHbbbbb)
ILLNESSb*D
TREATMNT*D 

The code example above retrieves the following information for all records where PATNAME is "ANDREA SMITH":

• The ILLNAME field in the ILLNESS segment.
• The TREATMNT field in the TREATMNT segment.
• All fields in the DOCTOR segment (by default, IMS returns all fields in the lowest level segment specified by the SSAList).

The following code example demonstrates how to specify a qualified SSAList with a multiple qualification statements to retrieve data:

SSAList ssaList = pcb.getSSAList("HOSPITAL","WARD");
ssaList.addInitialQualification("WARD","NURCOUNT",SSAList.GREATER_THAN,4);
ssaList.appendQualification("WARD",SSAList.AND,"DOCCOUNT",SSAList.GREATER_THAN, 2);

For the code example above, the ssaList will look like this:

HOSPITALb
WARDbbbb(NURCOUNTGT4&DOCCOUNTGT2;)

The following example shows how to specify a qualified SSAList with the command code CC_L (which means "last occurence") to find the most recently admitted patient in the "SANTA TERESA" hospital:

SSAList ssaList = pcb.getSSAList("HOSPITAL","PATIENT");
ssaList.addInitialQualification
   ("HOSPITAL","HOSPNAME",SSAList.EQUALS,"SANTA TERESA");
ssaList.addCommandCode("PATIENT",SSAList.CC_L);  
Path path = ssaList.getPathForRetrieveReplace();
pcb.getUnique(path,ssaList,false);

For the code example above, the ssaList will look like this:

HOSPITAL(HOSPNAMEEQSANTAbTERESAbbbbb)
WARDbbbbb
PATIENTb*L