REPL command

The Replace (REPL) command is used to replace a segment, usually to change the values of one or more of its fields.

Format

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.
SEGMENT(name): Qualifies the command, specifying the name of the segment type you want to retrieve, insert, delete, or replace.
SEGMENT((area)): Is a reference to an area in your program containing the name of the segment type. You can specify an area instead of specifying the name of the segment in 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.
OFFSET(expression): Specifies the offset to the destination parent. It 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. You use OFFSET when you process concatenated segments in logical relationships. It is required whenever the destination parent is a variable length segment.
FROM(area): Specifies an I/O area containing the segment to be added, replaced or deleted. You can replace more than the segment by including the FROM option after the corresponding SEGMENT option for each segment you want to replace. Including FROM options for one or more parent segments is called a path command.
The argument following FROM identifies an I/O area that you have defined in your program. You must use a separate I/O area for each segment type you want to replace.
MOVENEXT(data_value): Specifies a subset pointer to be moved to the next segment occurrence after your current segment.
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.

Usage

You must qualify the REPL command with at least one SEGMENT and FROM option, which together indicate the retrieved segments you want replaced.

If the Get command that preceded the REPL command was a path command, and you do not want to replace all of the retrieved segments or the PSB does not have replace sensitivity for all of the retrieved segments, you can indicate which of the segments are not to be replaced by omitting the SEGMENT option.

If your program attempts to do a path replace of a segment where it does not have replace sensitivity, the data for the segment in the I/O area for the REPL command must be the same as the segment returned on the preceding GET command. If the data changes in this situation, the transaction is abended and no data is changed as a result of the Replace command.

Notice that the rules for a REPL path command differ from the rules for an ISRT path command. You cannot skip segment levels to be inserted with an ISRT command, as you can with a REPL command.

To update information in a segment, you can use the REPL command. The REPL command replaces data in a segment with data you supply in your application program. First, you must retrieve the segment into an I/O area. You then modify the information in the I/O area and replace the segment with the REPL command. For your program to successfully replace a segment, that segment must already have been defined as replace-sensitive in the PCB by specifying PROCOPT=A or PROCOPT=R on the SENSEG statement in the PCB.

You cannot issue any commands using the same PCB between a Get command and the REPL command, and you can issue only one REPL command for each Get command.

Examples

Example 1

EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA);
EXEC DLI REPL SEGMENT(PATIENT) FROM(PATAREA);

Explanation: This example shows that you cannot issue any commands using the same PCB between the Get command and the REPL command, and you can issue only one REPL command for each Get command. If you issue this commands and wanted to modify information in the segment again, you must first reissue the GU command, before reissuing the REPL command.

Example 2

We have received a payment for $65.00 from a patient whose ID is 08642. Update the patient's billing record and payment record with this information, and print a current bill for the patient.

Explanation: The four parts to satisfying this processing request are:

Retrieve the BILLING and PAYMENT segments for the patient.
Calculate the new values for these segments by subtracting $65.00 from the value in the BILLING segment, and adding $65.00 to the value in the PAYMENT segment.
Replace the values in the BILLING and PAYMENT segments with the new values.
Print a bill for the patient, showing the patient's name, number, address, the current amount of the bill, and the amount of the payments to date.

To retrieve the BILLING and PAYMENT segments, issue a GU command. Because you also need the PATIENT segment when you print the bill, you can include INTO following the SEGMENT options for the PATIENT segment and for the BILLING segment:

EXEC DLI GU
     SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1)
     SEGMENT(BILLING) INTO(BILLAREA)
     SEGMENT(PAYMENT) INTO(PAYAREA);

After you have calculated the current bill and payment, you can print the bill, then replace the billing and payment segments in the database. Before issuing the REPL command, you must change the segments in the I/O area.

Because you have not changed the PATIENT segment, you do not need to replace it when you replace the BILLING and PAYMENT segments. To indicate to DL/I that you do not want to replace the PATIENT segment, you do not specify the SEGMENT option for the PATIENT segment in the REPL command.

EXEC DLI REPL
     SEGMENT(BILLING) FROM(BILLAREA)
     SEGMENT(PAYMENT) FROM(PAYAREA);

This command tells DL/I to replace the BILLING and PAYMENT segments, but not to replace the PATIENT segment.

These two examples are called path commands. You use a path REPL command to replace more than one segment with one command.

Example 3

Steve Arons, patient number 10250, has moved to a new address in this town. His new address is 4638 Brooks Drive, Lakeside, California. Update the database with his new address.

Explanation: You need to retrieve the PATIENT segment for Steve Arons and replace the address portion of the segment. To retrieve the PATIENT segment, you can use this GU command (assuming PATNO1 contains 10250):

EXEC DLI GU
     SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1);

Since you are not replacing the first two fields of the PATIENT segment (PATNO and NAME), you do not have to change them in the I/O area. Place the new address in the I/O area following the PATNO and NAME fields. Then you issue the REPL command:

EXEC DLI REPL
     SEGMENT(PATIENT) FROM(PATAREA);

Example 4

EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA)
     WHERE (PATNO=PATNO1)
     SEGMENT(ILLNESS) INTO(ILLAREA)
     SEGMENT(TREATMNT) INTO(TRETAREA);
EXEC DLI REPL SEGMENT(PATIENT) FROM(PATAREA)
     SEGMENT(TREATMNT) FROM(TRETAREA);

Explanation: This example assumes that you want to replace the PATIENT and TREATMNT segments for patient number 10401, but you do not want to change the ILLNESS segment. To do this issue this command (assuming PATNO1 contains 10401).

Restrictions

Restrictions for the REPL command:

You cannot issue any commands using the same PCB between the Get command and the REPL command.
You can issue only one REPL command for each Get command.
To modify information in a segment, you must first reissue the GU command before reissuing the REPL command.
You must qualify the REPL command with at least one SEGMENT option and one FROM option.
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.