ISRT command

The Insert (ISRT) command is used to add one or more segments to the database.

Format

Read syntax diagramSkip visual syntax diagramEXECDLIINSERTISRTUSING PCB( expression)AB
A For each parent segment (optional)
Read syntax diagramSkip visual syntax diagramVARIABLEFIRSTLASTCURRENTSEGMENT( name)SEGMENT(( area))SEGLENGTH( expression)FROM( area)1MOVENEXT( data_value)GETFIRST( data_value)SET( data_value)SETCOND( data_value)SETZERO( data_value)WHERE( qualification statement)FIELDLENGTH( expression)2KEYS( area)KEYLENGTH( expression)3
B For the object segment (required)
Read syntax diagramSkip visual syntax diagramVARIABLEFIRSTLASTSEGLENGTH( expression)OFFSET( expression)MOVENEXT( data_value)GETFIRST( data_value)SET( data_value)SETCOND( data_value)SETZERO( data_value)SEGMENT( name)SEGMENT(( area))FROM( area)
Notes:
  • 1 Specify FROM on parent segments for a path command.
  • 2 If you use multiple qualification statements, specify a length for each, using FIELDLENGTH. For example: FIELDLENGTH(24,8)
  • 3 You can use either the Keys option or the Where option, but not both on one segment level.

Options

USING PCB(expression)
Specifies the DB PCB you want to use for the command. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number.
VARIABLE
Indicates that a segment is variable-length.
FIRST
Specifies that you want to retrieve the first segment occurrence of a segment type, or that you want to insert a segment as the first occurrence. Use FIRST to insert a segment as a first occurrence of a segment type.
LAST
Specifies that you want to retrieve the last segment occurrence of a segment type, or that you want to insert a segment as the last segment occurrence. Use LAST to insert a segment as the last occurrence of a segment type.
CURRENT
Qualifies the command, and specifies that you want to use the level of and levels above the current position as qualifications for this segment. Use CURRENT to insert a segment based on your current position.
SEGMENT(name), SEGMENT((area))
Qualifies the command, specifying the name of the segment type or the area in the program containing the name of the segment type that you want to retrieve, insert, delete, or replace.

You must include at least a SEGMENT option for each segment you want to add to the database. Unless ISRT is a path command, the lowest level SEGMENT option specifies the segment being inserted. You cannot use a WHERE or KEYS option for this level.

If a segment has a unique key, DL/I inserts the segment in its key sequence. (If the segment does not have a key, or has a nonunique key, DL/I inserts it according to the value specified for the RULES parameter during DBDGEN.

If you specify a SEGMENT option for only the lowest level segment, and do not qualify the parent segments with SEGMENT, WHERE, or KEYS options, you must make sure that the current position is at the correct place in the database to insert the segment. The SEGMENT option that DL/I assumes depends on your current position in the database record:

  • If DL/I has a position established at the missing level, DL/I uses the segment on which position is established.
  • If DL/I does not have a position established at the missing level, DL/I uses the first occurrence at that level.
  • If DL/I moves forward from a position established at a higher level, DL/I uses the first occurrence at the missing level that falls within the new path.
  • If you leave out a SEGMENT option for the root level, and DL/I has position established on a root, DL/I does not move from that root when trying to satisfy the command.

It is good practice to always provide qualifications for higher levels to establish the position of the segment being inserted.

If you are inserting a root segment, you need only specify a SEGMENT option. DL/I determines the correct place for its insertion in the database by the key taken from the I/O area. If the segment you are inserting is not a root segment, but you have just inserted its immediate parent, the segment can be inserted as soon as it is built in the I/O area just by using a SEGMENT option for it in the ISRT command. You need not code the parent level segments to establish your position.

When you specify multiple parent segments, you can mix segments with and without the WHERE option. If you include only SEGMENT options on parent segments, DL/I uses the first occurrence of each segment type to satisfy the command.

SEGLENGTH(expression)
Specifies the length of the I/O area from which the segment is obtained. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (It is required in COBOL programs for any SEGMENT level that specifies the INTO or FROM option.)

Requirement: The value specified for SEGLENGTH must be greater than or equal to the length of the longest segment that can be processed by this call.

FROM(area)
Specifies an area containing the segment to be added, replaced, or deleted. Use FROM to insert one or more segments with one command.
MOVENEXT(data_value)
Specifies a subset pointer to be moved to the next segment occurrence after your current segment.
GETFIRST(data_value)
Specifies that you want the search to start with the first segment occurrence in a subset.
SET(data_value)
Specifies unconditionally setting a subset pointer to the current segment.
SETCOND(data_value)
Specifies conditionally setting a subset pointer to the current segment.
SETZERO(data_value)
Specifies setting a subset pointer to zero.
WHERE(qualification statement)
Qualifies the command, specifying the segment occurrence. Its argument is one or more qualification statements, each of which compares the value of a field in a segment to a value you supply. Each qualification statement consists of:
  • The name of a field in a segment
  • The relational operator, which indicates how you want the two values compared
  • The name of a data area in your program containing the value that is compared against the value of the field

WHERE establishes position on the parents of a segment when you are inserting that segment. You can do this by specifying a qualification of WHERE or KEYS for the higher level SEGMENT options.

When you specify multiple parent segments, you can mix segments with and without the WHERE option. If you include only SEGMENT options on parent segments, DL/I uses the first occurrence of each segment type to satisfy the command.

FIELDLENGTH(expression)
Specifies the length of the field value in a WHERE option.
KEYS(area)
Qualifies the command with the segment's concatenated key. You can use either KEYS or WHERE for a segment level, but not both.

KEYs can be used to qualify a parent segment. Instead of using WHERE, you can specify KEYS and use the concatenated key of the segment as qualification. You can use the KEYS option once for each command, immediately after the highest level SEGMENT option.

Area specifies an area in your program containing the segment's concatenated key.

KEYLENGTH(expression)
Specifies the length of the concatenated key when you use the KEYS option. It can be any expression in the host language that converts to the integer data type; if it is a variable, it must be declared as a binary halfword value. For IBM® COBOL (or VS COBOL II), PL/I, or assembler language, KEYLENGTH is optional. For COBOL programs that are not compiled with the IBM COBOL for MVS & VM (or VS COBOL II) compiler, you must specify KEYLENGTH with the KEYS option.

Usage

To add new segments to an existing database, use the ISRT command. When you issue the ISRT command, DL/I takes the data from the I/O area you have named in the FROM option and adds the segment to the database. (The initial loading of a database requires using the LOAD command, instead of the ISRT command.)

You can use ISRT to add new occurrences of an existing segment type to a HIDAM, HISAM, or HDAM database. For an HSAM database, you can add new segments only by reprocessing the whole database or by adding the new segments to the end of the database.

Before you can issue the ISRT command to add a segment to the database, your program must build the segment to be inserted in an I/O area. If the segment has a key, you must place the correct key in the correct location in the I/O area. If field sensitivity is used, the fields must be in the order defined by the PSB for the application's view of the segment.

If you are adding a root segment occurrence, DL/I 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 insert request qualified with only the segment name. You must build the new segment in your I/O area before you issue the ISRT request. You also qualify insert requests with the segment name when you add a new root segment occurrence. 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.

If the segment type you are inserting has a unique key field, the location where DL/I 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 for the database.

Examples

Example 1

Add information to the record for Chris Edwards about his visit to the clinic on February 1, 1993. His patient number is 02345. He had a sore throat.

Explanation: First, build the ILLNESS segment in your program's I/O area. Your I/O area for the ILLNESS segment looks like this: 
19930201SORETHROAT
Use the command to add this new segment occurrence to the database is: 
EXEC DLI ISRT
     SEGMENT(PATIENT) WHERE (PATNO=PATNO1)
     SEGMENT(ILLNESS) FROM(ILLAREA);
Example 2

Add information about the treatment to the record for Chris Edwards, and add information about the illness.

Explanation: You build the TREATMNT segment in a segment I/O area. The TREATMNT segment includes the date, the medication, amount of medication, and the doctor's name: 
19930201MYOCINbbb
0001TRIEBbbbbb
&b
The following command adds both the ILLNESS segment and the TREATMNT segment to the database: 
EXEC DLI ISRT
     SEGMENT(PATIENT) WHERE (PATNO=PATNO1)
     SEGMENT(ILLNESS) FROM(ILLAREA)
     SEGMENT(TREATMNT) FROM(TRETAREA);
Example 3
EXEC DLI ISRT
     SEGMENT(ILLNESS) KEYS(CONKEY)
     SEGMENT(TREATMNT) FROM(TRETAREA);

Explanation: Using this command is the same as having a WHERE option qualified on the key field for the ILLNESS and PATIENT segments.

Restrictions

Restrictions the ISRT command:

  • You cannot issue the ISRT command until you have built a new segment in the I/O area.
  • You must specify at least one SEGMENT option for each segment being added to the database.
  • When inserting a segment, you must have position established on the parents of the segment.
  • If you specify a SEGMENT option for only the lowest level segment, and do not qualify the parent segments with SEGMENT, WHERE, or KEYS options, be sure that current position is at the correct place in the database to insert the segment.
  • If you use a FROM option for a segment, you cannot qualify the segment by using the WHERE or KEYS option; DL/I uses the key field value specified in the I/O area as qualification.
  • You must use a separate I/O area for each segment type you want to add.
  • You cannot mix SEGMENT options with and without the FROM option. When you use a FROM option for a parent segment, you must use a FROM option for each dependent segment. (You can begin the path at any level, but you must not leave out any levels.)
  • You can only use the FIRST option with segments that have either no keys or have a nonunique key with HERE specified on the RULES operand of the SEGM statement in the DBD.
  • You can only use the LAST option when the segment has no key or a nonunique key, and the INSERT rule for the segment is either FIRST or HERE.