add considerations for DL/I

When you use the add statement in the context of DL/I, the statement adds a segment or set of segments to a hierarchical database.

You can also use the add statement to place multiple segments into a DL/I database from a dynamic array of DLISegment records.

The add statement generates a DL/I ISRT statement. In DL/I, this insert takes place at the current position in the database. You control this positioning in one of the following ways:

Explicitly set keys in your EGL program (see "Example" in this topic).
Use a get statement (see get considerations for DL/I).
Create qualified SSAs through the #dli directive (see #dli directive).

To add a dynamic array of DLISegment records to your database, do the following:

If the dynamic array of DLISegment records is not an array of root segments, establish position in the database for the parent segment under which you want to insert the records.
Issue the add statement and specify the name of the dynamic array of DLISegment records. The key value in each record of the array determines the logical position at which the new segment is added to the database.

Syntax

DLISegmentVariable: Name of the DLISegment variable.
usingPCB pcbName: Option to specify the name of a PCB, as defined in your PSB record, to use instead of the default PCB.
with #dli{ dliStatement }: Option to make an explicit DL/I ISRT call; see #dli directive. Leave no space between #dli and the left brace.
DLIDynamicArray: Name of a dynamic array that is composed of DLISegment records.

Path calls

DL/I also supports the use of path calls on add statements. When you use path calls, you can add parent segments for all segment levels between the lowest level segment you are adding and the root. In the following example, DL/I adds a new customer and location at the same time that it adds a new order:

add myCustomer, myLocation, myOrder;

EGL generates the following pseudo-DL/I code from this statement:

ISRT STSCCST*D (STQCCNO = :myCustomer.customerNo) 
     STSCLOC (STQCLNO = :myLocation.locationNo) 
     STPCORD

Example

The following example adds an order to the customer database:

// define DLI Segment records using the hostVarQualifier property
Record CustomerRecord type DLISegment
{ segmentName="STSCCST", keyItem="customerNo", hostVarQualifier="myCustomer" }
...
end
Record LocationRecord type DLISegment
{ segmentName="STSCLOC", keyItem="locationNo", hostVarQualifier="myLocation" }
...
end
Record OrderRecord type DLISegment
{ segmentName="STPCORD", keyItem="orderDateNo", hostVarQualifier="myOrder" }
...
end

	//create variables for the records
	myCustomer CustomerRecord;
	myLocation LocationRecord;
	myOrder    OrderRecord;

	//build a segment search parameter
	myCustomer.customerNo = "005001";
	myLocation.locationNo = "000022";

	//fill the fields in the order record
	fillOrder(myOrder);
	
	//add the new order record
	try
		add myOrder;
		onException(dex DLIException)
			myErrorHandler(dex);
	end

This add statement generates the following pseudo-DL/I code:

ISRT STSCCST (STQCCNO = :myCustomer.customerNo) 
     STSCLOC (STQCLNO = :myLocation.locationNo) 
     STPCORD

Qualified segment search parameters (SSAs) for customer and location identify the parent segments for the new order segment. DL/I adds the new order segment in a position that is determined by the keyItem field for that segment, the orderDateNo (STQCODN).

Error considerations

To capture "soft" I/O errors like "noRecordFound", use a set-values block to set the throwNrfEofExceptions program property to YES. In the onException block, test for the errors with the "is" or the "not" operator:

	if (myOrder is unique)
		...
	end

Possible runtime errors include the following:

unique if an order segment already exists with the specified key (no duplicates allowed)
duplicate if an order segment exists with the same key, but duplicates are allowed