ISRT call

The Insert (ISRT) call is used to load a database and to add one or more segments to the database. You can use ISRT to add a record to the end of a GSAM database or for an alternate PCB that is set up for IAFP processing.

Format

	Call Name	DB/DC	DBCTL	DCCTL	DB Batch	TM Batch
For Full-Function:	ISRT	X	X		X
For GSAM:	ISRT	X	X	X	X	X
For DEDB:	ISRT	X	X	X
For MSDB:	ISRT	X

Parameters

db pcb

Specifies the DB PCB for the call. This parameter is an input and output parameter.

aib

Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB:

AIBID: Eye catcher. This 8-byte field must contain DFSAIBbb.
AIBLEN: AIB lengths. This field must contain the actual length of the AIB that the application program obtained.
AIBRSNM1: Resource name. This 8-byte, left-justified field must contain the name of a DB PCB.
AIBOALEN: I/O area length. This field must contain the length of the I/O area specified in the call list.

i/o area

Specifies the I/O area. This parameter is an input parameter. When you want to add a new segment to the database, you place the new segment in this area before issuing the ISRT call. This area must be long enough to hold the longest segment that IMS returns to this area. For example, if none of the segments your program retrieves or updates is longer than 48 bytes, your I/O area should be 48 bytes.

If your program issues any path calls, the I/O area must be long enough to hold the longest concatenated segment following a path call. The segment data that this area contains is always left-justified. The I/O area points to the first byte of this area.

When you use the ISRT call with GSAM, the area named by the i/o area parameter contains the record you want to add. The area must be long enough to hold these records.

ssa

Specifies the SSA, if any, to be used in the call. This parameter is an input parameter. The SSA you supply in the call point to data areas in your program where you have defined the SSAs for the call. You can use up to 15 SSAs on the call. This parameter is required.

rsa

Specifies the area in your program where the RSA should be returned by DL/I. This output parameter is used for GSAM only and is optional. See the topic "GSAM Data Areas" in IMS Version 15.6 Application Programming for more information on RSAs.

Usage

Your program uses the ISRT call to initially load a database and to add information to an existing one. The call looks the same in either case. However, the way it is used is determined by the processing option in the PCB.

ISRT can add new occurrences of an existing segment type to a HIDAM, PHIDAM, HISAM, HDAM, PHDAM, DEDB, or MSDB database.

Restriction: New segments cannot be added to a HSAM database unless you reprocess the whole database or add the new segments to the end of the database.

Before you issue the ISRT call, build the new segment in the I/O area. The new segment fields must be in the same order and of the same length as defined for the segment. (If field sensitivity is used, they must be in the order defined for the application program's view of the segment.) The DBD defines the fields that a segment contains and the order in which they appear in the segment.

Root segment occurrence

If you are adding a root segment occurrence, IMS places it in the correct sequence in the database by using the key you supply in the I/O area. If the segment you are inserting is not a root, but you have just inserted its parent, you can insert the child segment by issuing an ISRT call with an unqualified SSA. You must build the new segment in your I/O area before you issue the ISRT call. Also, you use an unqualified SSA when you insert a root. When you are adding new segment occurrences to an existing database, the segment type must have been defined in the DBD. You can add new segment occurrences directly or sequentially after you have built them in the program's I/O area. At least one SSA is required in an ISRT call; the last (or only) SSA specifies the segment being inserted. To insert a path of segments, you can set the D command code for the highest-level segment in the path.

Insert rules

If the segment type you are inserting has a unique key field, the place where IMS adds the new segment occurrence depends on the value of its key field. If the segment does not have a key field, or if the key is not unique, you can control where the new segment occurrence is added by specifying either the FIRST, LAST, or HERE insert rule. Specify the rules on the RULES parameter of the SEGM statement of DBDGEN for this database.

The rules on the RULES parameter are as follows:

FIRST: IMS inserts the new segment occurrence before the first existing occurrence of this segment type. If this segment has a nonunique key, IMS inserts the new occurrence before all existing occurrences of that segment that have the same key field.
LAST: IMS inserts the new occurrence after the last existing occurrence of the segment type. If the segment occurrence has a nonunique key, IMS inserts the new occurrence after all existing occurrences of that segment type that have the same key.
HERE: IMS assumes you have a position on the segment type from a previous IMS call. IMS places the new occurrence before the segment occurrence that was retrieved or deleted by the last call, which is immediately before current position. If current position is not within the occurrences of the segment type being inserted, IMS adds the new occurrence before all existing occurrences of that segment type. If the segment has a nonunique key and the current position is not within the occurrences of the segment type with equal key value, IMS adds the new occurrence before all existing occurrences that have equal key fields.

You can override the insert rule of FIRST with the L command code. You can override the insert rule of HERE with either the F or L command code. This is true for HDAM and PHDAM root segments and for dependent segments in any type of database that have either nonunique keys or no keys at all.

An ISRT call must have at least one unqualified SSA for each segment that is added to the database. Unless the ISRT is a path call, the lowest-level SSA specifies the segment being inserted. This SSA must be unqualified. If you use the D command code, all the SSAs below and including the SSA containing the D command code must be unqualified.

Provide qualified SSAs for higher levels to establish the position of the segment being inserted. Qualified and unqualified SSAs can be used to specify the path to the segment, but the last SSA must be unqualified. This final SSA names the segment type to be inserted.

If you supply only one unqualified SSA for the new segment occurrence, you must be sure that current position is at the correct place in the database to insert that segment.

Mix qualified and unqualified SSA

You can mix qualified and unqualified SSAs, but the last SSA must be unqualified. If the SSAs are unqualified, IMS satisfies each unqualified SSA with the first occurrence of the segment type, assuming that the path is correct. If you leave out a SSA for one of the levels in an ISRT with multiple SSAs, IMS assumes an SSA for that level. The SSA that IMS assumes depends on current position:

If IMS has a position established at the missing level, the SSA that IMS uses is derived from that position, as reflected in the DB PCB.
If IMS does not have a position established at the missing level, IMS assumes an unqualified SSA for that level.
If IMS moves forward from a position established at a higher level, IMS assumes an unqualified SSA for that level.
If the SSA for the root level is missing, and IMS has position established on a root, IMS does not move from that root when trying to satisfy the call.

Using SSA with the ISRT call

Using SSA with ISRT is a good way to check for the parent segments of the segment you want to insert. You cannot add a segment unless its parent segments exist in the database. Instead of issuing Get calls for the parents, you can define a fully qualified set of SSAs for all the parents and issue the ISRT call for the new segment. If IMS returns a GE status code, at least one of the parents does not exist. You can then check the segment level number in the DB PCB to find out which parent is missing. If the level number in the DB PCB is 00, IMS did not find any of the segments you specified. A 01 means that IMS found only the root segment; a 02 means that the lowest-level segment that IMS found was at the second level; and so on.