Chapter 5: Database Calls

This chapter describes APS database calls.

Coding Calls

Observe the following when coding database calls:

Code the command using COBOL indentation.
Arguments can be one of the following:
- Variable
- 1- to 7-digit number
- Literal string delimited by single or double quotes
Separate each command component with a space, unless indicated otherwise in the syntax.
Some arguments are positional. Code positional arguments in the order shown in the syntax for each command.
To omit a positional argument, code an asterisk (*) in its place (unless it is the last argument).
A command can be continued on as many as 101 subsequent lines by coding an ellipsis followed by a space. Break a command for continuation at any blank space, but do not break a parameter.

Comments:

Code anywhere in your program:

-KYWD-   12-*----20---*--
 /*     commentline

Code in Procedure Division only:

-KYWD-  12-*----20---*----
        /*commentline

Continuation is an ellipsis followed by a space (... ) and must continue on the immediate subsequent line.

IDMS DB

DB-BIND

Format 1:
```
DB-BIND REC [recordname]
```

Format 2:

DB-BIND RUN-UNIT
... SUBSCHEMA name|NODENAME name|DBNAME name

DB-CLOSE

DB-CLOSE ALL

DB-ERASE

DB-ERASE REC recordname [PERM|SELECT|ALL]

DB-GET

DB-GET REC [recordname]

DB-MODIFY

DB-MODIFY REC recordname

DB-OBTAIN

Format 1, based on a CALC key or an indexed or sorted set:

DB-OBTAIN REC|REF recordname WHERE keyname = value [NEXT]
... [HOLD] [EXCLUSIVE]

Format 2, where the most recently retrieved occurrence of a record type is current of run unit:
```
DB-OBTAIN REC|REF recordname CURRENT [HOLD] [EXCLUSIVE]
```
Format 3, where the most recently retrieved occurrence of any record in the set is current of run unit:
```
DB-OBTAIN REC|REF IDMSREC SET setname| AREA areaname CURRENT
... [HOLD] [EXCLUSIVE]
```

Format 4, based on database address:

DB-OBTAIN REC|REF IDMSREC|recordname
... WHERE DBKEY = value [HOLD] [EXCLUSIVE]

Format 5, where the set owner is obtained when the record is unknown:
```
DB-OBTAIN REC|REF IDMSREC
... SET setname OWNER [HOLD] [EXCLUSIVE]
```

Format 6, based on a CALC key or an indexed or sorted set, using a valid operator:

DB-OBTAIN [REF recordname1] REC|REF recordname2
... WHERE sortkey operator value
... [SET setname [RESET]]|[RESET] [HOLD] [EXCLUSIVE]

Format 7, based on position within set:

DB-OBTAIN [REF recordname1] REC|REF recordname2
... [SET setname]
... [WHERE SEQUENCE = number|FIRST|LAST|PREV|NEXT]
... [HOLD] [EXCLUSIVE]

Format 8, based on position within the set when the record is unknown:

DB-OBTAIN REC|REF IDMSREC SET setname|AREA areaname
... [WHERE SEQUENCE = number|FIRST|LAST|PREV|NEXT]
... [HOLD] [EXCLUSIVE]

Format 9, based on position within the area:

DB-OBTAIN REC|REF recordname [AREA areaname]
... [WHERE SEQUENCE = number|FIRST|LAST|PREV|NEXT]
... [HOLD] [EXCLUSIVE]

DB-OPEN

DB-OPEN [ALL] [MODE usagemode] [AREA areaname]

DB-PROCESS

DB-PROCESS [REF recordname] REC recordname
... [DB-PROCESS-ID name]
... [WHERE keyname operator value]
... [SET setname|AREA areaname] [RESET]
... [HOLD] [EXCLUSIVE]
        Controlled logic block

DB-STORE

DB-STORE REC recordname

Error Handling Flags

Use the following 88-level flags for error handling after executing an IDMS call:

Flag	Status Code	Explanation
AB-ON-REC	0001 through 0306 0308 through 0325 0327 through 0625 1206 through 9999	Any error other than those listed.
DUP-ON-REC	0705 0805,1205	Duplicate key.
END-ON-REC	0307	End of set, area, or index reached.
NTF-ON-REC	0326 0626	Record not found.
OK-ON-REC	0000	Successful operation.
POS-ON-REC	All values of AB-ON-REC whose last 2 bytes are: 06 13	Positioning error.
VIO-ON-REC	All values of AB-ON-REC whose last 2 bytes are: 01 02 08 09 10 14 15 23 31	An update would violate rules.

IDM-COMMIT

IDM-COMMIT [ALL]

IDM-CONNECT

IDM-CONNECT REC [recordname] TO setname

IDM-DISCONNECT

IDM-DISONNECT REC [recordname] FROM setname

IDM-IF

IDM-IF SET setname [EMPTY|NOT EMPTY]
... [MEMBER|NOT MEMBER] paragraphname

IDM-PROTOCOL

-KYWD-  12--*--20---*----30----*---40---*----
 SYEN   IDM-PROTCOL programmode location

IDM-RETURN

IDM-RETURN dataname FROM indexsetname
... [CURRENCY [FIRST|LAST|NEXT|PRIOR]]
... [USING keyfiel] [KEY INTO keyfield]

IDM-ROLLBACK

IDM-ROLLBACK [CONTINUE]

IMS DB

DB-ERASE

Format 1:

DB-ERASE REC segment [FROM dataarea] 
... [VIEW pcbname|PCB pcbname]

Format 2, records obtained by path calls:

DB-ERASE REC|REF segment1 [FROM dataarea]
... VIEW pcbname|PCB pcbname]
... REC|REF segment2 [FROM dataarea]
... VIEW pcbname|PCB pcbname]
  .
  .
... REC segmentN [FROM dataarea]
... VIEW pcbname|PCB pcbname]

DB-MODIFY

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

DB-OBTAIN

Format 1, unqualified:
```
DB-OBTAIN REC recordname [HOLD] [RESET]
```

Format 2, qualified:

DB-OBTAIN REC recordname
... WHERE fieldname1 operator value
... [AND|OR fieldname2 operator value [FIRST|LAST] 
... [INTO dataarea]
  .
  .
... [AND|OR fieldnameN operator value] [FIRST|LAST]
... [INTO dataarea] [HOLD]]] [RESET]

Format 3, qualified on secondary index values:

DB-OBTAIN REC recordname
... WHERE fieldname operator (value1 [ ... valueN]) 
... [INTO dataarea]
... [FIRST|LAST] [HOLD] [RESET]

Format 4, qualified compound retrieval:

DB-OBTAIN REF segmentname1 WHERE fieldname1 operator value
... REC|REF segmentname2 WHERE fieldname2 operator value
  .
  .
... [REC segmentnameN WHERE fieldnameN operator value 
... [FIRST|LAST] [HOLD]] [RESET]

Format 5, retrieve next segment:

DB-OBTAIN NEXT[REC] INTO dataarea 
...VIEW pcbname|PCB pcbname [HOLD] [RESET]

Format 6, retrieve segment specified in program at run time:

MOVE 'segmentname' TO segmentname
DB-OBTAIN IMSREC segmentname FROM dataarea 
... VIEW pcbname|PCB pcbname

Format 7, retrieve dependent of current record:

DB-OBTAIN REF recordname1 CURRENT
... REC recordname2 [WHERE fieldname operator value]

Format 8, retrieve segment from PSB with multiple PCBs:

DB-OBTAIN REC recordname
... [WHERE fieldname operator value] VIEW pcbname|PCB pcbname

Format 9, retrieve qualified or subscripted field:

DB-OBTAIN REC recordname
... WHERE keyname operator fieldname OF dataarea|SUB (number)

Format 10, retrieve dependent record via concatenated key:
```
DB-OBTAIN REC recordname CKEYED dataname
```

DB-PROCESS

Format 1, key-qualified:

DB-PROCESS REC recordname
... [WHERE keyname operator value [SUB value] [OF dataarea]]
... [DB-PROCESS-ID name] [INTO dataarea]
... [HOLD] [RESET] [VIEW pcbname|PCB pcbname]
        Controlled logic block

Format 2, unqualified:

DB-PROCESS REC recordname
... [DB-PROCESS-ID name] [INTO dataarea]
... [HOLD][RESET] [VIEW pcbname|PCB pcbname]
        Controlled logic block

DB-STORE

DB-STORE [REC|REF recordname1] [FROM dataarea]
... [VIEW pcbname|PCB pcbname]
... [WHERE fieldname operator value] [REC|REF recordname2]
... [FROM dataarea] [VIEW pcbname|PCB pcbname]
... [WHERE fieldname operator value] 
... [SUB number] [OF dataarea]
  .
  .
... REC recordnameN [FROM dataarea] 
... [VIEW pcbname|PCB pcbname]
... [WHERE fieldname operator value] [SUB number] [OF dataarea]

Error Handling Fields

IMS provides the following error fields that show how far your call was processed prior to failure:

IM-DB-PCB-SEGLEV	Lowest level in the database for which the requested segment was found.
IM-DB-PCB-SEGNAME	8-character IMS name for the lowest-level segment located.
IM-DB-PCB-KEY-FEED-BACK	Concatenated key information for the path from the root-level to the lowest-level segment found.
IM-DB-PCB-KEY-KFBLEN	Length of data in the IM-DB-PCB-KEY-FEED-BACK field.

Error Handling Flags

Use the following 88-level flags for error handling after executing an IMS DB call:

Flag	Status Code	Explanation
AB-ON-REC	Any not listed below	For any error code not listed below.
DUP-ON-REC	I NI LB	The DB-STORE failed; the new segment would have created a duplicate for a key or sequence field defined as unique.
END-ON-REC	GB	End of database reached.
NTF-ON-REC	GE GB	Requested record not found.
OK-ON-REC	2 spaces, GA GD GK	Everything is OK.
POS-ON-REC	DJ LC LD LE	Positioning error; requested positioning not established.
RTY-ON-REC	GG	Requested record not available. Retry.
VIO-ON-REC	AM DA DX RX IX	An update would violate rules.

Generation Field

IMS provides a field to control program generation:

&IM-SUPPRESS-DB-CALL

Prevent generation of DB calls; set field to YES in APS CNTL file APSDBDC.

GSAM Calls

IM-CLSE view
IM-OPEN view
IM-OPEN-INP view
IM-OPEN-OUT view
IM-OPEN-OUTA view
IM-OPEN-OUTM view
IM-GN pcbname [ssa1 [...ssa15]]
IM-GU pcbname ssa1 [...ssa15]
IM-ISRT pcbname [ssa1 [...ssa15]]

$IM-FLD

$IM-FLD MSDBview fsaname [rootssa]

$IM-FSA

$IM-FSA fsaname segment
... field1[/picture/] operator operand1
... [field2[/picture/] operator operand2]
  .
  .
 ... [field10[/picture/[ operator operand10]]

$IM-POS

$IM-POS DEDBview [SSA]

System Service Calls

IM-CHKP pcbname checkpointID
... [length1 dataarea1 [... length7 dataarea7]]
 
IM-XRST pcbname
... [length1 area1 [... length7 area7]]
... [checkpointID maxiolength]
IM-CHKP-OSVS pcbname checkpointID
IM-DEQ pcbname deqcharacter
IM-GSCD pcbname
IM-LOG pcbname logcode loglength message
IM-ROLB pcbname [msgarea]
IM-ROLL
IM-STAT-DBAS-FULL pcbname
IM-STAT-DBAS-UNFORMATED pcbname
IM-STAT-DBAS-SUMMARY pcbname
IM-STAT-VBAS-FULL pcbname
IM-STAT-VBAS-UNFORMATED pcbname
IM-STAT-VBAS-SUMMARY pcbname

SQL

Built-In Functions

For DB-DECLARE:

DB-DECLARE cursorname [correlname1.]copylibname-REC
... function1[(](expression)[,resultfield[,Y][)]]
... function2[(](expression)[,resultfield[,Y][)]]
  .
  .
... functionN[(](expression)[,resultfield[,Y][)]]
... WHERE ...

For DB-OBTAIN:

DB-OBTAIN REC [correlname1.]copylibname-REC
... function1[(](expression)[,resultfield[,Y][)]]
... function2[(](expression)[,resultfield[,Y][)]]
  .
  .
... functionN[(](expression)[,resultfield[,Y][)]]
... WHERE ...

For DB-PROCESS:

DB-PROCESS REC [correlname1.]copylibname-REC 
... [DB-PROCESS-ID name]
... function1[(](expression)[,resultfield[,Y][)]]
... function2[(](expression)[,resultfield[,Y][)]]
  .
  .
... functionN[(](expression)[,resultfield[,Y][)]]
... WHERE ...

DB-CLOSE

DB-CLOSE CUR[SOR] cursorname

DB-COMMIT

DB-COMMIT [HOLD]

DB-DECLARE

Format 1, unqualified, select all columns:

DB-DECLARE cursorname copylibname-REC
... [FETCH ONLY] [WITH HOLD] [OPTIMIZE number] [UPDATE|ORDER]
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]

Format 2, qualified, select all columns:

DB-DECLARE cursorname copylibname-REC
... [FETCH ONLY] [WITH HOLD] [OPTIMIZE number]
... WHERE column operator [[:]altvalue]|column
... [AND|OR column operator [[:]altvalue]|column] 
... [UPDATE|ORDER] column1 [ASC|DESC] 
... [...columnN [ASC|DESC]]]

Format 3, select specific columns:

DB-DECLARE cursorname copylibname-REC [DISTINCT]
... [FETCH ONLY] [WITH HOLD] [OPTIMIZE number]
... column1 [(altvalue)] [... columnN [(altvalue)]]
... [WHERE column operator [[:]altvalue]|column
... [AND|OR correlname.]column operator [[:]altvalue]|column]
   .
   .
... [AND|OR correlname.]column operator [[:]altvalue]|column]]
... [UPDATE|ORDER col1 [ASC|DESC] [...columnN [ASC|DESC]]]

Format 4, join columns from two or more tables:

DB-DECLARE cursorname correlname.copylibname-REC [DISTINCT]
... [FETCH ONLY] [WITH HOLD] [OPTIMIZE number]
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... [correlname.copylibname-REC
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
  .
  .
... [WHERE correlname.column operator [:]altvalue|correlname.column
... [AND|OR correlname.column operator [:]altvalue|correlname.column]
  .
  .
... [AND|OR correlname.column operator [:]altvalue|correlname.column]]
... [ORDER column1 [ASC|DESC] [...columnN [ASC|DESC]]]

Format 5, specify a Union

DB-DECLARE cursorname copylibname-REC [DISTINCT]
... [FETCH ONLY] [WITH HOLD] [OPTIMIZE number]
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... [WHERE column operator [[:]altvalue]|column
... [AND|OR column operator [[:]altvalue]|column]
  .
  .
... [AND|OR column operator [[:]altvalue|]column]] UNION [ALL]
DB-OBTAIN REC copylibname-REC
  .
  .
... [ORDER column1 [ASC|DESC] [...columnN [ASC|DESC]]]

DB-ERASE

Format 1:

DB-ERASE REC copylibname-REC [WHERE column operator [:]altvalue
... [AND|OR column operator [:]altvalue
  .
  .
... AND|OR column operator [:]altvalue]]

Format 2:

DB-ERASE REC copylibname-REC [WHERE CURRENT [OF] cursorname]

DB-FETCH

DB-FETCH CUR[SOR] cursorname [INTO dataname]

DB-MODIFY

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]

DB-OBTAIN

Format 1, qualified, select all columns:

DB-OBTAIN REC copylibname-REC
... WHERE column operator [:]altvalue|column
... [AND|OR column operator [:]altvalue|column]
   .
   .
... [AND|OR column operator [:]altvalue|column] [INTO dataname]

Format 2, unqualified, select all columns:

DB-OBTAIN REC copylibname-REC [INTO dataname]

Format 3, join all columns from two tables:

DB-OBTAIN REC correlname1.copylibname-REC
... REC correlnameN.copylibname-REC
... [WHERE correlname.column operator [:]altvalue|correlname.column
... [AND|OR correlname.column operator [:]altvalue|correlname.column]
   .
   .
... [AND|OR correlname.column operator [:]altvalue|correlname.column]]

Format 4, select specific columns:

DB-OBTAIN REC copylibname-REC [DISTINCT]
... column1 [(altvalue)] [... columnN [(altvalue)]]
... [WHERE [correlname.]column operator [:]altvalue|column]

DB-OPEN

DB-OPEN CUR[SOR] cursorname

DB-PROCESS

Format 1, unqualified, select all columns:

DB-PROCESS REC copylibname-REC
... [DB-PROCESS-ID name] [DB-LOOP-MAX=number]
... [FETCH ONLY] [WITH HOLD] [OPTIMIZE number]
... [UPDATE|ORDER col1 [ASC|DESC] [...columnN [ASC|DESC]]]
... [INTO dataname]
        Controlled logic block

Format 2, qualified, select all columns:

DB-PROCESS REC copylibname-REC [DB-PROCESS-ID name]
... [FETCH ONLY] [WITH HOLD] [OPTIMIZE number]
... WHERE column operator [[:]]altvalue]|column
... [AND|OR column operator [[:]altvalue]|column]
  .
  .
... [AND|OR column operator [[:]altvalue]|column]
... [DB-LOOP-MAX=number]
... [UPDATE|ORDER col1 [ASC|DESC] [...columnN [ASC|DESC]]]
... [INTO dataname]
        Controlled logic block

Format 3, select specific columns:

DB-PROCESS REC copylibname-REC
... [FETCH ONLY] [WITH HOLD] [OPTIMIZE number]
... [DB-PROCESS-ID name] [DISTINCT]
... column1 [(altvalue)] [... columnN [(altvalue)]]
... WHERE column operator [[:]altvalue]|column
... [AND|OR column operator [[:]altvalue]|column]
  .
  .
... [AND|OR col operator [[:]altvalue]|col] [DB-LOOP-MAX=number]
... [UPDATE|ORDER column1 [ASC|DESC] [...columnN [ASC|DESC]]]
        Controlled logic block

Format 4, join columns from two or more tables:

DB-PROCESS REC correlname.copylibname-REC
... [DB-PROCESS-ID name] [DISTINCT]
... [FETCH ONLY] [WITH HOLD] [OPTIMIZE number]
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... REC correlname.copylibname-REC
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
  .
  .
... [WHERE correlname.column operator [[:]altvalue]|correlname.column
... [AND|OR correlname.column operator [[:]altvalue]|correlname.column]
  .
  .
... [AND|OR correlname.column operator [[:]altvalue]|correlname.column]
... [DB-LOOP-MAX=number]
... [ORDER column1 [ASC|DESC] [...columnN [ASC|DESC]]]
        Controlled logic block

Format 5, specifying a UNION:

DB-PROCESS REC copylibname-REC
... [DB-PROCESS-ID name] [DISTINCT]
... [FETCH ONLY] [WITH HOLD] [OPTIMIZE number]
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... [WHERE column operator [[:]altvalue]|column
... [AND|OR column operator [[:]altvalue]|column]
  .
  .
... [AND|OR column operator [[:]altvalue]|column]]
... [DB-LOOP-MAX=number] UNION [ALL]
DB-OBTAIN REC copylibname-REC
  .
  .
... [ORDER column1 [ASC|DESC] [...columnN [ASC|DESC]]]
        Controlled logic block

DB-ROLLBACK

DB-ROLLBACK

DB-STORE

Format 1:

DB-STORE REC copylibname-REC
... [column1 [(altvalue)] [... columnN [(altvalue)]]] [FROM dataname]

Format 2:

DB-STORE REC copylibname-REC
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... [DB-OBTAIN REC copylibname-REC column1 [... columnN]
... WHERE column1 operator [:]altvalue
... [AND|OR column2 operator [:]altvalue]]
  .
  .
... [AND|OR columnN operator [:]altvalue] ]

Error Handling Flags

Use the following 88-level flags for error handling after executing SQL calls:

Flag	Meaning
AB-ON-REC	Any error not listed in this table.
DB2-DEADLOCK	DB-PROCESS calls check this status to ensure the cursor is not already closed before closing it. SQL closes the cursor if the database is locked.
DUP-ON-REC	DB-STORE failed because the row already exists; duplicates are not allowed.
END-ON-REC	End of table or cursor set reached.
NTF-ON-REC	Requested row not found.
OK-ON-REC	Operation successful.
RI-ON-REC	Referential Integrity check successful (corresponds to SQLCODE -532 to -530).

Error Handling Field

Use the following generated field to indicate whether the associated host variable has been assigned a null value:

01  IND-cursorname|IND-recorename
    05  IND-column

Joins

With DB-DECLARE:

DB-DECLARE cursorname correlname1.copylibname-REC [DISTINCT]
... [column1 [... columnN]]|[NONE]
  .
... correlnameN.copylibname-REC [column1 [... columnN]]|[NONE]
  .
... [WHERE correlname.column1 operator [:]value|correlname.column2
... [AND|OR correlname.column3 operator [:]value|correlname.column4
  .
... AND|OR correlname.columnN operator [:]value|correlnameN]]
... [ORDER column1 [ASC|DESC] [...columnN [ASC]]]

With DB-OBTAIN:

DB-OBTAIN REC correlname1.copylibname-REC [DISTINCT]
... [column1 [... columnN]]|[NONE]
  .
  .
  .
... REC correlnameN.copylibname-REC [column1 [... columnN]]|[NONE]
... [WHERE correlname.column1 operator [:]value|correlname.column2
... [AND|OR correlname.column3 operator [:]value|correlname.column4
  .
  .
  .
... AND|OR correlname.columnN operator [:]value|correlname.columnN]]

With DB-PROCESS:

DB-PROCESS REC correlname1.copylibname-REC
... [DB-PROCESS-ID name] [DISTINCT]
... [column1 [... columnN]]|[NONE]
  .
  .
  .
... REC correlnameN.copylibname-REC
... [column1 [... columnN]]|[NONE]
 
... [WHERE correlname.column1 operator [:]value|correlname.column2
... [AND|OR correlname.column3 operator [:]value|correlname.column4
  .
  .
  .
... AND|OR correlname.columnN operator [:]value|correlname.columnN]]
 
... [DB-LOOP-MAX=number]
... [ORDER column1 [ASC|DESC] [...columnN [ASC|DESC]]]
        Controlled logic block

Special Registers

Use the following special registers in DB-DECLARE, DB-OBTAIN, and DB-PROCESS calls:

CURRENT DATE
CURRENT TIME
CURRENT TIMESTAMP
CURRENT TIMEZONE

UNION

With DB-DECLARE:

DB-DECLARE cursorname [correlname1.]copylibname-REC
  .
  .
  .
... UNION [ALL]
DB-OBTAIN REC copylibname-REC
  .
  .
  .
... [ORDER column1 [ASC|DESC] [...columnN [ASC|DESC]]]

With DB-PROCESS:

DB-PROCESS REC [correlname1.]copylibname-REC
  .
  .
  .
... UNION [ALL]
DB-OBTAIN REC copylibname-REC 
  .
  .
  .
... [ORDER column1 [ASC|DESC] [...columnN [ASC|DESC]]]

VSAM Batch

DB-CLOSE

Format 1:

DB-CLOSE FILE filename1 [ ... filenameN]

Format 2:
```
DB-CLOSE FILE ALL
```

DB-ERASE

Format 1, key-qualified:

DB-ERASE REC recordname
 ... WHERE primarykeyname = value [SUB value] [OF dataarea]

Format 2, unqualified:

DB-ERASE REC recordname

DB-MODIFY

DB-MODIFY REC recordname [FROM dataarea]

DB-OBTAIN

Format 1, sequential:

DB-OBTAIN REC recordname [VIEW keyname] [INTO dataarea] [RESET]

Format 2, direct:

DB-OBTAIN REC recordname WHERE keyname operator value [SUB value]
... [OF dataarea] [INTO dataarea]

Format 3, positional:

DB-OBTAIN REC recordname WHERE keyname operator value [SUB value]
... [OF dataarea]

DB-OPEN

Format 1:

DB-OPEN FILE filename ...[filenameN] MODE option

Format 2:
```
DB-OPEN FILE ALL MODE option
```

DB-PROCESS

Format 1, qualified:

DB-PROCESS REC recordname WHERE keyname operator value
...[DB-PROCESS-ID name] [SUB value] [OF dataarea] [INTO dataarea]
        Controlled logic block

Format 2, unqualified:

DB-PROCESS REC recordname [VIEW keyname]
... [DB-PROCESS-ID name] [INTO dataarea] [RESET]
        Controlled logic block

DB-STORE

DB-STORE REC recordname [FROM dataarea]

Error Handling Flags

Use the following 88-level flags for error handling after executing SQL calls:

Flag	Status Code	Explanation
OK-ON-REC	00	Successful operation.
DUP-ON-REC	02	Duplicate key; duplicates allowed.
END-ON-REC	10	End of file.
INV-ON-REC	20 21 22 23 24	Invalid key condition.
IVD-ON-REC	22	Duplicate key; not allowed.
NTF-ON-REC	23	Record not found.
AB-ON-REC	30 34 90 91 92 93 94 95 96 97	Abnormal condition.

Fields

Use APS-defined data fields and S-COBOL flags in your program.

Name	Associated Calls	Description
APS-END-PROCESS	DB-PROCESS	Flag that terminates a DB-PROCESS loop.
ddname-RRN	DB-OBTAIN DB-PROCESS DB-ERASE DB STORE	Field that controls relative record number (RRN) of a retrieved or stored RRDS file record; generates value for the RELATIVE KEY clause of the SELECT statement.
RESET-OBTAIN	DB-OBTAIN DB-PROCESS	Flag that resets browse to beginning of file. Example: TRUE RESET-OBTAIN

Name

Associated Calls

Description

APS-END-PROCESS

DB-PROCESS

Flag that terminates a DB-PROCESS loop.

ddname-RRN

DB-OBTAIN
DB-PROCESS
DB-ERASE
DB STORE

Field that controls relative record number (RRN) of a retrieved or stored RRDS file record; generates value for the RELATIVE KEY clause of the SELECT statement.

RESET-OBTAIN

DB-OBTAIN
DB-PROCESS

Flag that resets browse to beginning of file.
Example: TRUE RESET-OBTAIN

VSAM Online

DB-ERASE

Format 1, key-qualified:

DB-ERASE REC recordname WHERE primarykeyname = value
... [SUB value] [OF dataarea] [KLEN value]
... [SYSID systemname] [DDN ddname]

Format 2, unqualified:
```
DB-ERASE REC recordname
```

DB-FREE

DB-FREE REC recordname|ALL [VIEW keyname] [ENDBR] [UNLOCK]
... [REQID number] [SYSID systemname] [DDN ddname]

DB-MODIFY

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

DB-OBTAIN

Format 1, sequential:

DB-OBTAIN REC recordname [VIEW keyname] [INTO dataarea]
... [HOLD] [PREV] [REQID number] [RESET]
... [SYSID systemname] [DDN ddname]

Format 2, direct:

DB-OBTAIN REC recordname WHERE keyname operator value
... [SUB value] [OF dataarea] [INTO dataarea] [KLEN value] [HOLD]
... [REQID number] [SYSID systemname] [DDN ddname]

Format 3, positional:

DB-OBTAIN REF recordname WHERE keyname operator value
... [SUB value] [OF dataarea] [KLEN value] [RESETBR]
... [REQID number] [SYSID systemname] [DDN ddname]

DB-PROCESS

Format 1, key-qualified:

DB-PROCESS REC recordname WHERE keyname operator value
... [DB-PROCESS-ID name] [SUB value] [OF dataarea]
... [INTO dataarea] [KLEN value] [HOLD] [PREV]
... [REQID number] [SYSID systemname] [DDN ddname]
        Controlled logic block

Format 2, unqualified:

DB-PROCESS REC recordname [DB-PROCESS-ID name] [INTO dataarea]
... [HOLD] [PREV] [RESET] [REQID number] [SYSID systemname]
... [VIEW keyname] [DDN ddname]
        Controlled logic block

DB-STORE

DB-STORE REC recname [FROM dataarea] [SYSID systemname] [DDN ddname]

Error Handling Flags

Use the following 88-level flags for error handling after executing VSAM online calls:

VSAM Flag	EIBRCODE Flag	ISI-Errors/ ExceptioDnal Condition	Explanation
AB-ON-REC	DSIDERR ILLOGIC IOERR LENGERR NOSPACE NOTOPEN SYSIDERR	DSIDERR ILLOGIC IOERR LENGERR NOSPACE NOTOPEN SYSIDERR	Abnormal condition.
DUP-ON-REC	DUPKEY	DUPKEY	Duplicate key; allowed.
END-ON-REC	ENDFILE	ENDFILE	End of file.
INV-ON-REC	NOTFND DUPREC	NOTFND DUPREC	Invalid key condition.
IRQ-ON-REC	INVREQ	INVREQ	Invalid request.
IVD-ON-REC	DUPREC	DUPREC	Duplicate key; not allowed.
NTF-ON-REC	NOTFND	NOTFND	Record not found.
OK-ON-REC	N/A	N/A	Successful operation.

Fields

Use APS-defined data fields and S-COBOL flags in your program.

Name	Associated Calls	Description
APS-shortrecname-VAR	DB-OBTAIN DB-STORE DB-MODIFY DB-PROCESS DB-ERASE	Field that contains actual record length after a successful record retrieval (direct or sequential for DB-OBTAIN and DB-PROCESS). Supplies value to dataarea in CICS LENGTH option. Shortrecname comes from the subschema definition; it is the REC card SHORT keyword.
APS-END-PROCESS	DB-PROCESS	Flag that terminates DB-PROCESS loop.
APS-VSAM-NUMREC	DB-ERASE	Field that contains number of records deleted after key-qualified ERASE with partial key length specified.
ddname-APS-KEYnumber	DB-OBTAIN DB-PROCESS	Field that contains APS-generated key name for use in skip-sequential processing. Ddname is the subschema file.
ddname-RBA	DB-OBTAIN DB-PROCESS DB-STORE	Field that contains relative byte address (RBA) of a retrieved, stored ESDS file record; supplies value to CICS RIDFLD option.
ddname-RRN	DB-OBTAIN DB-PROCESS DB-STORE	Field that contains relative record number (RRN) of a retrieved or stored RRDS file record; supplies value to CICS RIDFLD option.
RESET-OBTAIN	DB-OBTAIN DB-PROCESS	Flag that resets browse to beginning of file. When used with PREV, resets to end of file.