DB-MODIFY

Targets:

IMS DB
SQL
VSAM Batch
VSAM Online

IMS DB

Syntax:

DB-MODIFY
... REC|REF recordname1 [FROM dataarea]
... [VIEW|PCB pcbname]
        .
        .
        .
... REC|REF recordnameN [FROM dataarea]
... [VIEW|PCB pcbname]

Syntax Rules:

Use REF only when DB-MODIFY is preceeded by a DB-OBTAIN path call, meaning more than one record was obtained by the call and placed into the I/O area.
Use REF with DB-MODIFY to specify higher-level segments that you do not want to modify.

General Rules:

The record must be retrieved and held by a DB-OBTAIN or DB-PROCESS call before it can be modified.
To modify records obtained by a path call DB-OBTAIN, specify every segment obtained in the path. To specify that a segment is not modified, code REF.
If a preceding DB-OBTAIN specifies the REF parameter, meaning that the record is referenced but not placed into the I/O area, DB-MODIFY ignores the record.
Use the CCODE keyword to include additional IMS command codes. See the topic IMS command codes for a list of valid CCODEs.

Parameters:

REC `recordname`	IMS segment to process.
REF `recordname`	Specify an IMS segment to reference. The program uses the referenced segment for navigating the database.
FROM `dataarea`	Alternate I/O area where program deletes, modifies, or adds a record. Code FROM when a record is obtained from an I/O area other than the default I/O area, such as by DB-OBTAIN INTO.
PCB `pcbname`	Specify the PCB used when the PSB contains multiple PCBs for the same database. Code PCB when a record is obtained from the default PCB.
VIEW `pcbname`	Specify the PCB used when the PSB contains multiple PCBs for the same database. Code VIEW when a record is not obtained from the default PCB.

Examples:

Modify only RECORD-C.

DB-OBTAIN REC RECORD-A WHERE KEY-A = VALUE-A
... REC RECORD-B WHERE KEY-B = VALUE-B
... REC RECORD-C WHERE KEY-C = VALUE-C HOLD
DB-MODIFY REF RECORD-A
... REF RECORD-B
... REC RECORD-C

The following examples assume that the following DB-OBTAIN path call precedes the DB-MODIFY.

$DB-OBTAIN ("REC SEG1, REC SEG2, REC SEG3")

To modify all records retrieved in the path:

$DB-MODIFY ("REC SEG1, REC SEG2, REC SEG3")

To modify just SEG2:

$DB-MODIFY ("REF SEG1, REC SEG2")

To modify just SEG3:

$DB-MODIFY ("REF SEG1, REF SEG2, REC SEG3")

The following example assumes that the following DB-OBTAIN call precedes the DB-MODIFY. This DB-OBTAIN is not a path call and places only SEG3 into the I/O area; therefore, DB-MODIFY ignores SEG1 and SEG2:

$DB-OBTAIN ("REF SEG1, REF SEG2, REC SEG3")

To modify SEG3 only:

$DB-MODIFY ("REC SEG3")

The following examples assume that the following DB-OBTAIN path call precedes the DB-MODIFY. This DB-OBTAIN places only SEG2 and SEG3 into the I/O area; therefore, DB-MODIFY ignores SEG1:

$DB-OBTAIN ("REF SEG1, REC SEG2, REC SEG3")

To modify SEG3 only:

$DB-MODIFY ("REF SEG2, REC SEG3")

To modify SEG2 only:

$DB-MODIFY ("REC SEG2")

SQL

DB-MODIFY updates row contents in a table or cursor set as follows:

All rows in a table
Specific rows in a table
Specific columns in a table
Specific columns of a specific row
Cursor set rows

Syntax:

DB-MODIFY REC copylibname-REC
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... [FROM dataname]
... [WHERE column1 operator [:]altvalue
        .
        .
        .
... AND|OR columnN operator [:]altvalue]
... [END[WHERE]]]
... [WHERE CURRENT [OF] cursorname]
... [QUERYNO number]
... [WITH [CS|RS|RR]]

Parameters:

REC `copylib`-REC	Specify the 01-level name of the COBOL row layout in the DCLGEN or copybook information. Cannot be the same as any cursor names or DB-PROCESS-ID names.
`column1` [(`altvalue`)]	`Altvalue` can be a literal, column name, host variable, or one of the following expressions: NEXT VALUE FOR `sequencename` PREVIOUS VALUE FOR `sequencename` If you name an alternate host variable for a specific column, do not code FROM, which names an entire alternate host structure. See also the information on Host variables in the General Rules section of the Help topic Database Calls.
FROM `dataname`	Move alternate data structure to the host variable structure name. Data moves prior to the actual SQL call via MOVE statement.
WHERE column operator	Not valid for cursor processing. `Column` is the column on which to qualify the selection. `Operator` can be =, ^=, >, <, >=, <=, native SQL predicates (such as LIKE and BETWEEN).
[:]`altvalue`	Alternate value; when used with WHERE, AND , or OR, it can be a literal or a column name.
END[WHERE]	Terminate a WHERE clause. Required if you code WHERE before FROM.
WHERE CURRENT [OF] `cursorname`	Valid for cursor processing only. Act upon the row retrieved from `cursorname`.
QUERYNO `number`	Specifies the number to be used for this SQL statement in EXPLAIN output and trace records.
WITH	Specifies the isolation level at which the statement is executed.
	CS	Cursor stability
	RS	Read stability
	RR	Repeatable read

Example:

Update specific columns of specific rows using selection criteria and alternate data from different areas for each column.

DB-MODIFY REC D2TAB-REC
... PM_UNIT_BASE_PRICE (25.99)
... PM_UNITS (:WS-UNITS)
... WHERE PM_PART_SHORT_DESC = 'WIDGET'
... AND PM_COLOR = 'RED'
... AND PM_UNIT_BASE_PRICE < 50

VSAM Batch

Syntax:

DB-MODIFY REC recordname [FROM dataarea]

General Rule:

Before modifying a record, retrieve it with a DB-OBTAIN or DB-PROCESS call.

Parameters:

REC `recordname`	COBOL record to process.
FROM `dataarea`	Alternate I/O area where program deletes, modifies, or adds a record. Required for a record obtained from an I/O area other than the default I/O area, such as by DB-OBTAIN INTO

Example:

Hold CUST-RECORD for modification; specify an alternate storage area to contain the data that updates the record.

DB-OBTAIN REC CUST-RECORD
... WHERE CUST-NUMBER = SCREEN-CUST-NUMBER
IF  OK-ON-REC
    DB-MODIFY REC CUST-RECORD
    ... FROM CUST-RECORD-UPDATE-AREA

VSAM Online

Syntax:

DB-MODIFY REC recordname [FROM dataarea]
... [SYSID systemname] [DDN ddname]

General Rule:

Before modifying a record, retrieve it with a DB-OBTAIN or DB-PROCESS call.

Parameters:

DDN `ddname`	Specify file `ddname`; can be a literal or data name defined as PIC X(8). Supply a value to the name option of CICS DATASET.
FROM `dataarea`	Alternate I/O area where program deletes, modifies, or adds a record. Required for a record obtained from an I/O area other than the default I/O area, such as by DB-OBTAIN INTO
REC `recordname`	COBOL record or IMS segment to process.
SYSID `systemname`	Remote system name (maximum 4 characters); can be a literal region name or a Working-Storage field.

Example:

Hold CUST-RECORD for modification; specify an alternate storage area to contain the data that updates the record.

DB-OBTAIN REC CUST-RECORD
... WHERE CUST-NUMBER = SCREEN-CUST-NUMBER
... HOLD
IF  OK-ON-REC
    DB-MODIFY REC CUST-RECORD
    ... FROM CUST-RECORD-UPDATE-AREA