IDMS Cobol Guidelines -- Version 1.0
09/03/97

1. Program Size
2. DML Commands
3. Work Areas
4. Bind Command
5. Ready Command
6. DBKEY Usage
7. Data Base Sweeps
8. Find/Obtain Command
9. Store Command
10. Disconnect Command
11. Erase Command
12. Walking A Set
13. Ascertaining Set Membership
14. Processing Via Record
15. Loading Sorted Sets
16. Commit Command
17. Status Code Check
18. Run Mode
19. Subroutines
20. Record Lock-Unlock Facility
21. Keep Longterm
22. Scratch Records
23. Queue Records
24. DeadLock-RollBack

 IDMS Cobol Standard

DC programs should be limited to 20K. Programs larger than this should be reduced in size by limiting working storage.

Use only DML commands for all IDMS calls. Allow the DML preprocessor to translate commands into correctly formatted call statements.

IDMS-DC: Programmers must initialize "copied in" work areas (maps and records) which are copied in from the IDD.

IDMS record BIND statements and area READY statements should be processed after it has been determined that accessing the database is necessary. Whenever possible, housekeeping and editing should be performed first.

• READY the areas individually and only the areas that need to be accessed.
• READY the areas with appropriate usage mode as determined by application processing requirements. This limits database contention.
• Issue all necessary READY statements contiguously (no intervening processes) at one time. This reduces the chance of area deadlock and allows more efficient processing.

• Direct database entry is the fastest access method. When practical, DBKEYs should be temporarily saved and used within a program (i.e., to access a previously retrieved record after performing several intervening database operations).
• Use caution when DBKEYs are saved outside of a program. DBKEYs of erased records are reused. An IDMS UNLOAD/RELOAD changes all DBKEYs. Therefore, incorrect results may occur if DBKEYS are saved outside of a program. An exception is:

In on-line pseudo-conversational programming, it may be necessary to keep DBKEY(s) accessible in temporary storage until the end of a functional task which could involve several programs.

• An area sweep is a very time-consuming process. Use area sweeps only when necessary.
• Obtain the first occurrence of the record type being processed with "OBTAIN FIRST record-type WITHIN AREA" before processing the "OBTAIN NEXT record-type WITHIN AREA" iteration to ensure proper currency.
• Retain or reestablish record currencies very carefully when processing more than one record type during the area sweep. Remember that only one record can be CURRENT of the AREA. In other words, remember to OBTAIN CURRENT record-name before processing the OBTAIN NEXT record-name command.
• Discontinue the sweep of the area IF YOU ARE ABLE to determine that you have reached the end of the record type within an area. An area sweep will continue to the end of the area, not the end of the data. For example:

When sweeping sorted records within the account area, once account number 99999999 is encountered the sweep can be discontinued, even though you have not yet reached the end of the area.

• When the contents of a record are not needed, (i.e., it is necessary to establish currency only), use the FIND command. IDMS does not go through the overhead of moving the contents of the record occurrence into the program storage area with the FIND command.
• Use the "OBTAIN" to locate and access database records. Do not use the FIND/GET sequence of verbs when the contents of a record are needed. Either set of commands produce the same results but the 'OBTAIN' uses less verbiage.

All key values and currencies for automatic sets should be defined and established immediately before issuing a "STORE" command.

Usually only CALC records can be DISCONNECTed without immediately re-CONNECTing to another owner. VIA records should be re-CONNECTed immediately to another owner to prevent orphan VIA records.

Use the unqualified ERASE very carefully. Review all record and set relationships closely before using the command, especially if using the ERASE ALL option.

When walking a set, on an END-OF-SET condition (0307), if it is necessary to access the information in the owner record always make sure an "OBTAIN" command has been issued for the owner record. On an END-OF-SET condition, currency is established for the owner record (current of run-unit) but the contents of the record occurrence are not moved into program storage (i.e. it operates as a "FIND" DML command).

When a record is an optional or manual member of a set, the program must issue an "IF set-name MEMBER" DML command prior to an "OBTAIN OWNER" DML command. If the member record occurrence does not participate in a set occurrence and an "OBTAIN OWNER" command is issued, IDMS will return the owner of the current set.

Process VIA records in a via set (if necessary), immediately after the owner has been obtained or found. Since the entire page on which the owner and (hopefully) many of the members are stored is brought into the buffer, I/O will be reduced.

IDMS-DB: When adding multiple member occurrences to an occurrence of a sorted set, pre-sort the records in sort key sequence to decrease I/O.

• When processing long running batch update jobs, "COMMITS" should be used in conjunction with operating system or user-written checkpoint facilities to allow job restart capabilities.
• The COMMIT should also always be issued immediately after record updates which have used the KEEP record lock option in order to release the locks.
• Unless there is a reason not to, commit after every 100 updates.
• If there is a reason to not issue a COMMITin an update program, place a comment at the top of the program that states that there is no COMMITand the reason for the omission of the COMMIT.

Checking multiple non-zero return codes can be cumbersome under "AUTOSTATUS". An example for handling this is:

STORE SIRE012-SITC3V              
  ON ANY-STATUS                 
    NEXT SENTENCE.            
IF DB-STATUS-OK                   
  ADD 1 TO T3V-WRITTEN          
ELSE                              
  IF ERROR-STATUS = '1205'      
    NEXT SENTENCE             
  ELSE                          
    PERFORM IDMS-STATUS.

IDMS DB:

• As a general rule, database updates should be run as a Central Version (CV) job, and reporting jobs should be run local mode. Efficiency considerations may warrant exceptions.
• An update should be run local mode when it would be quicker to run a backup in front and restore the database in the event of an error, than it would be to journal all activity and rollback when an error occurs.
• Refer to the JCL Standards for details on the different JCL requirements for CV versus local mode.

IDMS-DC: Stable, closed procedural sub-routines (i.e., a date routine) should be invoked by using a "CALL" statement instead of a DC LINK. The DC overhead involved with handling a LINK can be avoided.

IDMS record locks are of two types: SHARED (select) and EXCLUSIVE (update). Shared locks prevent the update of the record occurrence by other run-units, while allowing all run-units to retrieve the record. Exclusive locks prevent any other run units from retrieving or updating the record occurrence. Under central version, record locks can be set in two ways, either implicitly or explicitly.

Implicit locks are set automatically by IDMS central version as follows:

• Implicit SHARED locks (select) are placed on record occurrences that become current-of-run- unit, -record type, -set, or -area;
• Implicit EXCLUSIVE locks (update) are placed on record occurrences that are altered by the STORE, ERASE, MODIFY, CONNECT, and DISCONNECT verbs.

LOCK Release:

• Implicit SHARED locks are valid until a change of currency is effected, or until the run-unit terminates. All other locks are valid for the duration of the run-unit.
• Implicit EXCLUSIVE locks are released with the issue of a COMMIT, ROLLBACK, or FINISH verb.

IDMS-DC: This option may be used for heavily accessed information. Storage can be allocated for the short term or long term and can be released explicitly through program request. This option should be considered for only relatively small amounts of information since storage is obtained from the storage pool. Kept storage is maintained across tasks running on the same logical terminal. Data "KEPT" in the storage pool is not recoverable from a system shutdown or failure. Data in the storage pool is not preserved from one execution of IDMS-DC to another.

IDMS-DC: These records are a good option for large amounts of information maintained across tasks. Scratch records are accessible on the same logical terminal, are not deleted until DC shutdown, and are not maintained across system failure.

These records are a good option when a large amount of information must be kept across tasks. Queue records are accessible by all terminals, tasks, and batch applications. They are kept through a DC shutdown or failure.

• Deadlock conditions can occur whenever two or more run-units attempt to set record locks in a sequence that prevents the further execution of either run unit. For example, consider the situation where run-unit X has record 'A' locked and requests a lock on record 'B', while simultaneously run-unit Y has record 'B' locked and requests a lock on record 'A'.
• As neither request can be granted, both run-units are locked in a deadlock condition. A deadlock can also occur at the area level as well as the record level, through the use of the READY command.
• For both of the above deadlock conditions, automatic IDMS resolution includes the following: abortion of the run-unit initiating the deadlock:

rollback the database modifications effected during its uncompleted recovery unit;

post an error status of nn29 in the run-unit's IDMS communications block. Any subsequent attempts by the run-unit to execute an IDMS verb, without re-readying the run-unit, results in an error status of nn69 being posted in the IDMS communication block.