Accessing dynamic arrays with the Universal Drivers using the DBArrayElementSet class

The IMS Universal DL/I driver enables accesses and updates to dynamic arrays with the DBArrayElementSet class.

A dynamic array is an array in which the number of repeating array elements can vary from one instance of a segment type to another. It is defined by coding FIELD statements in the input control statements of the DBD Generation utility. To access dynamic arrays through IMS Universal DL/I driver, use the DBArrayElementSet class, which supports creating, receiving, and updating data structures that represent DBArray objects.

Accessing Dynamic Arrays is supported in IMS Universal DL/I driver after Universal Drivers build 15122 or higher.

The following example demonstrates how a DBArrayElementSet object accesses and updates a dynamic array that has 15 repeating occurrences.
ssaList = pcb.getSSAList("HOSPITAL");
ssaList.addInitialQualification(1, "HOSPCODE", SSAList.EQUALS, "R1210010000A");
path = ssaList.getPathForRetrieveReplace();
pcb.getUnique(path, ssaList, true);
DBArray dbArray = path.getArray("DYNAMICARRAY");
DBArrayElementSet dbArrayElementSet = dbArray.getElements();
dbArrayElementSet.absolute(0);

dbArrayElementSet.prepareElementToAdd();
dbArrayElementSet.setString("DYNAMICFIELD1", "RR");
dbArrayElementSet.setString("DYNAMICFIELD2", "RRRR");
dbArrayElementSet.setString("DYNAMICFIELD3", "DDDD");
dbArrayElementSet.addElement();
dbArrayElementSet.setString("DYNAMICFIELD1", "XX");
dbArrayElementSet.setString("DYNAMICFIELD2", "VVVV");
dbArrayElementSet.setString("DYNAMICFIELD3", "ZZZZ");
dbArrayElementSet.addElement();
dbArrayElementSet.absolute(17);
dbArrayElementSet.setString("DYNAMICFIELD1", "SS");
dbArrayElementSet.setString("DYNAMICFIELD2", "SSSS");
dbArrayElementSet.setString("DYNAMICFIELD3", "DDDD");
dbArrayElementSet.addElement();
dbArrayElementSet.setString("DYNAMICFIELD1", "XX");
dbArrayElementSet.setString("DYNAMICFIELD2", "VVVV");
dbArrayElementSet.setString("DYNAMICFIELD3", "ZZZZ");
dbArrayElementSet.addElement();

path.setInt("OCCURSFIELD", 19);
path.setArray("DYNAMICARRAY", dbArray);
pcb.replace(path);
In this example, the array field is named DYNAMICARRAY and contains three elements named DYNAMICFIELD1, DYNAMICFIELD2, DYNAMICFIELD3. The array field has a DEPENDSON field for setting the number of occurrences of an element with the name OCCURSFIELD. Four more occurrences are added to the array structure, making the total occurrence number 19. A replace (REPL) call is made to update the path.
You might find the following notes helpful when using the previous example:
  • The prepareElementToAdd() function moves the DBArrayElementSet object to an insert row buffer that can be used to set the array's fields. Your current cursor's position will be stored. You will remain on the insert row buffer until the moveToCurrentElement() function is called that restores your cursor's position.
    Note: Only dynamic arrays can use the prepareElementToAdd() function.
  • You can move the DBArrayElementSet object's cursor by calling the following functions:
    • previous()
    • next()
    • last()
    • first()
    • beforeFirst()
    • afterLast()
    • absolute(int position)
    • relative(int position)
    Moving the cursor's position cancels any pending data on the insert row buffer that is not added by the addElement() function.
  • You can use setters such as setString(), setInt(), and so on to complete the following tasks:
    • Updating the array field value at the current cursor position
    • Adding the array field value into the insert row buffer if the array field value is initialized
  • You can use getters such as getString(), getInt(), and so on to complete the following tasks:
    • Retrieving the array field value at the current cursor position
    • Retrieving the array field value from the insert row buffer if the array field value is initialized
  • The DEPENDSON field must always be set into the path object when you add or update a DBArrayElementSet object and must reflect the total number of elements.