Introduction to CA IDMS Data Manipulation Language

Introduction to CA IDMS Data Manipulation Language

The CA IDMS data manipulation language (DML) consists of statements that direct CA IDMS database (DB) and data communications (DC) processing. DML statements are coded in the program source as if they were a part of the host language. The precompiler converts DML statements into standard COBOL statements and performs source-level error checking.

Depending on the operating environment, your program will use different sets of DML statements. For example, a batch program uses only database DML statements; an online program can use both database and data communications DML statements.

Batch processing typically involves large volumes of transactions, sequential processing, and output in the form of files and reports. Batch programs use database DML statements only.

The following figure illustrates the flow of a typical batch application. Input to DEPTRPT consists of department IDs. Output consists of a listing of departments and their employees. The error report lists the department IDs of missing and empty departments.

Online processing typically involves transaction requests entered from terminals connected directly to the computer, transaction results displayed at the terminal, multiple requests from multiple sources, and sharing one copy of a program among multiple users. Additionally, online processing is immediate; fast response time is essential in processing large volumes of transactions from multiple online users. Online programs use data communications DML statements and can include database DML statements.

The following figure illustrates the flow of a typical online application. EMPDISP retrieves information for an operator-specified employee ID. Output to the terminal consists of DEPARTMENT, EMPLOYEE, JOB, and OFFICE information.

The CA IDMS programming environment is outlined below, followed by a discussion of compile and runtime considerations.

This section contains the following topics:

Programming in the CA IDMS Environment

Compiling and Executing CA IDMS Programs

Callable Services and Common Facilities

Programming in the CA IDMS Environment

CA IDMS DML statements are divided into two categories:

• Database statements perform retrieval and update functions in either the batch or the online environment. There are three categories of database DML statements:
  • Navigational statements access database records and sets, one record at a time
  • LRF statements access groups of database records using the Logical Record Facility (LRF)
  • SQL statements access groups of database records using the Structured Query Language (SQL)
• Data communications (also called online) statements, request data communications services such as for online programs

You can include database DML statements in batch programs or combine them with data communications DML statements in online programs that require database access. A discussion of accessing the database by using DML statements is presented below, followed by a discussion of additional considerations for coding online programs.

Accessing the Database

Database access under CA IDMS can be accomplished by using navigational, LRF DML, or SQL DML statements. Navigational statements are used with a subschema usage mode of either DML or MIXED.

LRF DML statements, which use the Logical Record Facility (LRF), are used with a subschema usage mode of either LR or MIXED.

SQL DML statements, which use Structured Query Language, access records without reference to subschemas.

Some statements, such as BIND RUN-UNIT, READY, and FINISH, are used in all three environments. They are noted in the individual discussions of each DML statement in Data Manipulation Language Statements.

Navigational, LRF, and SQL DML statements are discussed separately below.

Navigational DML Statements

Navigational DML statements access database records and sets one record at a time, checking and maintaining currency in order to assure correct results. Navigational DML statements give you control over error checking and flexibility in choosing database access strategy. To use navigational DML statements, you must have a thorough knowledge of the database structure. For an example of a data structure diagram, refer to EMPLOYEE Database Definition.

Navigational DML statements provide:

• Control over error checking—You can check the result of each navigational statement, enabling more thorough error detection
• Flexibility in choosing database access strategy—You can enter the database either sequentially (area sweep), by using a symbolic key value (CALC), or by using a database key value (DIRECT)

Navigational DML statements are grouped into four categories:

• Control statements initiate and terminate processing, effect recovery, prevent concurrent updates, and evaluate set conditions
• Retrieval statements locate data in the database and make it available to the application program
• Modification statements update the database
• Accept statements pass database keys, storage address information, and statistics to the program

LRF DML Statements

LRF DML statements use the Logical Record Facility (LRF) to access database records. LRF allows you to access fields from multiple database records as if they were data fields in a single record. LRF DML statements allow you to specify selection criteria (by using the WHERE clause) that enable you to access only those logical records you need.

LRF DML statements provide:

• Easy access to database records—You need not be familiar with database structure; your programs need not include database navigation logic.
• Data flexibility—Modification and recompilation of LRF programs are not necessarily required when the physical or logical structure of the database is changed.
• Run-time efficiency—LRF minimizes communication between the program and the DBMS.

The LRF DML statements are listed below:

• ERASE deletes a logical record as specified in the path definition
• MODIFY modifies a logical record as specified in the path definition
• OBTAIN retrieves a logical record as specified in the path definition
• STORE stores a new logical record as specified in the path definition

SQL DML Statements

You can use SQL DML to access the same databases you access using navigational DML. Additionally, you can use SQL DML to access databases that have been defined using SQL DDL.

Using SQL DML, you do not have to be familiar with database structure and your programs do not have to include database navigation logic.

You can perform the following functions using SQL DML statements:

• Select rows
• Update rows
• Delete rows
• Insert rows

Note: For more information about SQL DML statements, see the CA IDMS SQL Reference Guide.

Programming in the Online Environment

The CA IDMS/DC system is fully integrated with the CA IDMS DBMS and the data dictionary. It enables you to request both data communications and database services through standard subroutine calls generated by the precompiler from DML statements. The following figure illustrates a typical stream of online DML statements in a COBOL program. This example maps in a user-specified employee ID, retrieves and displays the specified information, and performs a DC RETURN naming TSK02 as the next task to be performed.

PROCEDURE DIVISION.
  BIND MAP EMPMAPLR.
  BIND MAP EMPMAPLR RECORD EMPLOYEE.
  ACCEPT TASK CODE INTO TASK-CODE-IN.
  IF TASK-CODE-IN = 'TSK01'
          GO TO INITIAL-MAPOUT.
  MAP IN USING EMPMAPLR.
     .
     .
 navigational, LRF, or SQL database DML statements
     .
     .
  MAP OUT USING EMPMAPLR
      OUTPUT DATA IS YES
      MESSAGE IS DISPLAY-MESSAGE LENGTH 80.
  DC RETURN NEXT TASK CODE 'TSK02'.

Online DML statements, which request CA IDMS to perform data communications services, are grouped into nine categories:

1. Program management statements govern flow of control and abend processing
2. Storage management statements allocate and release variable storage
3. Task management statements provide runtime services that enhance control over task processing
4. Time management statements obtain the time and date, and define time-related events
5. Scratch management statements create, delete, or retrieve records from the scratch area
6. Queue management statements create, delete, or retrieve records in a queue area
7. Terminal management statements transfer data between the application program and a terminal
8. Utility function statements retrieve task-related information or statistics, send messages, and monitor access to database records
9. Recovery statements perform functions relating to database, scratch, and queue area recovery in the event of a system failure

Compiling and Executing CA IDMS Programs

A CA IDMS COBOL source program contains DML statements that are processed by the precompiler. The precompiler converts DML statements into COBOL CALL statements and copies information maintained in the data dictionary into the application program. After successful compilation and link editing, the application program can be executed. The compilation and runtime processes are described separately below.

Compiling Programs

There are three components that prepare a COBOL DML program for execution: the precompiler, the COBOL compiler, and the linkage editor.

1. The precompiler converts DML statements in the source program to COBOL CALL statements and copies information maintained in the data dictionary into the application program. For example, database record descriptions, file definitions, map records, map definitions, and other predefined modules such as the IDMS communications block can be copied into the program.

   Output from the precompiler is a source file that serves as input to the COBOL precompiler and as an optional source listing. The output file differs from the source input to the precompiler in the following ways:

   • Source code (such as the IDMS communications block and the IDMS-STATUS routine) has been added to the program.
   • DML statements have been replaced by COBOL CALL statements and changed to comment entries (asterisk in column 7).

   Additionally, the precompiler produces a listing of the following errors:

   • Incorrect DML entries
   • Statements inconsistent with the program's declared subschema view
   • Any other error conditions detected during DMLC processing
   • Warning messages indicating source code conditions that could adversely affect run units using the program
2. The COBOL compiler compiles the source program after it has been successfully processed by the precompiler. Output from the COBOL compiler consists of an object program and a source listing that includes any generated diagnostics.
3. The linkage editor link edits the object program into a specified load library. Output from the linkage editor consists of a load module (or phase) and a link map.

The job control language required to execute each step is listed in DML Precompile, COBOL Compile, and Link-Edit JCL.

The component steps needed to prepare a COBOL DML program for execution are illustrated in the following figure:

Executing Programs

At run time, CA IDMS requests are treated as application program subroutine calls. When the subroutine call is executed, control passes to the DBMS or the DC system, which processes the requested function.

A CA IDMS program must be defined to the CA IDMS system in which it will operate. The program can be defined either at system generation or at run time by using a DCMT VARY DYNAMIC PROGRAM command.

The following COBOL features are not used in programs running in an online environment under CA IDMS:

• ENVIRONMENT and DATA DIVISION entries normally associated with file management (for example, INPUT-OUTPUT SECTION, FILE SECTION)
• The Report Writer and Segmentation features, as well as features invoked by the SORT, EXHIBIT, TRACE, DISPLAY, ACCEPT, STRING, UNSTRING, and INSPECT commands. The EXAMINE and TRANSFORM verbs, though valid under VS/COBOL, will not compile under VS/COBOL-II since the logic of these verbs has been incorporated into the inspect verb and are not valid verbs in COBOL-II. Additionally, the EXTERNAL clause of the record statement is invalid for all versions of COBOL.

  Note: The restriction on INSPECT, STRING, and UNSTRING commands arise because they issue supervisor calls in some environments. This restriction applies mainly when running VS COBOL on a VSE or z/OS operating system. It does not apply when using LE-compiant COBOL with IBM's runtime Language environment. See section H.2 for considerations when using these commands with VS/COBOL II.

• The I/O statements READ, WRITE, OPEN, and CLOSE
• The COBOL compiler DEBUG option; the COUNT, FLOW, STATE, ENDJOB, TEST, RESIDENT, DYNAM, and SYMDMP commands (OS only); or the COUNT, FLOW, STATE, STXIT, and SYMDMP commands (z/VSE only)

The TEST compile option can be used for a program compiled using an Language Environment compliant compiler, but the DEBUG runtime option must not be used in the online environment. A load module compiled with the TEST option can be run with the DEBUG runtime option in batch. This allows the same load module which is being tested in a batch environment to run in an online environment without being recompiled.

• Any feature that can lead to the issuance of a supervisor call (SVC)

These features lead to a supervisor call (SVC), which will inhibit system performance and can also crash the DC system.

Usage of the DBCS COBOL compile time option by a CA IDMS program can lead to IGYPS0156-E run time errors. Programs using LRF are especially susceptible to this problem. This option is the default for LE/COBOL compilers starting with z/OS. 3.2.0. You should compile CA IDMS programs using the NODBCS option.

The COBOL compiler provides a TRUNC option. Use this option with care in any CA IDMS program that accesses dbkey values. Exercise particular care if arithmetic operations are performed on the dbkey, for example multiplying a page number by the dbkey radix. Unexpected results can occur if an inappropriate value is specified for the TRUNC option. Such unexpected results can occur because COBOL truncates numeric values to fit the PICTURE clause in some cases.

Avoid this problem by using the compiler option TRUNC(BIN). On some older COBOL compilers the equivalent option is NOTRUNC.

Note: For more information about the TRUNC option, see the documentation of your compiler vendor.

Callable Services and Common Facilities

CA IDMS provides callable services and common facilities to use with your application programs.

Callable Services

The callable services include:

• The IDMSCALC utility that lets you sort input into target page sequence.
• The IDMSIN01 facility that lets you perform miscellaneous CA IDMS functions.
• The TCP/IP socket program interface that lets you communicate with another TCP/IP application.

Note: For more information about using these callable services, see the CA IDMS Callable Services Guide.

Common Facilities

The common facilities include:

• The Command Facility that lets you submit command statements in a batch or online environment.
• The Online Compiler Text Editor that lets you edit compiler output and resubmit it as input using the CA IDMS development tools.
• The Transfer Control Facility that lets you transfer between CA IDMS development tools.
• The SYSIDMS parameter file that contains parameters that you can add to a batch job running in local mode or under the central version. These parameters let you specify environment requirements, runtime directives, and operating system-dependent information.

Note: For more information about using these common facilities and the SYSIDMS parameter file, see the CA IDMS Common Facilities Guide.