CA IDMS Reference DML Reference for Assembler

Transcription

1 CA IDMS Reference DML Reference for Assembler Date: 15-Jan-2018

2

3 This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the Documentation ) is for your informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation is proprietary information of CA and may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. If you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice. The manufacturer of this Documentation is CA. Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections , , and (c)(1) - (2) and DFARS Section (b)(3), as applicable, or their successors. Copyright 2017 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies. 15-Jan /496

4 Table of Contents Introduction to CA IDMS Data Manipulation Language Operating Environments Accessing the Database Programming in the DC/UCF Environment Assembling and Executing Programs Callable Services and Common Facilities Callable Services Common Facilities DML Precompiler Options for Assembler Dictionary Usage Mode Comment Generation Syntax List Generation Syntax Parameters Log Suppression Syntax Communications Blocks and Error Detection Major Database Status Codes (Assembler) Minor Database Status Codes (Assembler) CA IDMS Communications Block (Assembler) Field Descriptions ERRSTAT Field and Codes DB Status Codes DML Reference for Assembler 4

5 Major DB Status Codes Minor DB Status Codes DC Status Codes (Assembler) Major DC Status Codes Minor DC Status Codes Testing for DML Error-Status Codes Logical-Record Request Control (LRC) Block LRC Block Fields Testing for the Logical-Record Path Status DC/UCF General Registers DC/UCF Status Codes Testing for DC/UCF Return Codes Assembler Data Manipulation Language Statements Functions of DML Statements #ABEND -- terminates the issuing task abnormally Syntax Parameters Status Codes Example... BIND -- moves the bind address Currency Syntax Parameters Status Codes Example... DBKEY FROM CURRENCY -- moves the db-key of the current record Currency Syntax Parameters Status Codes Example... DBKEY RELATIVE TO CURRENCY -- moves the db-key Currency Syntax Parameters Status Codes Example... PGINFO -- moves the page information Syntax DML Reference for Assembler 5

6 Parameters Status Codes Example... PROC -- moves the information block Syntax Parameters Status Codes Example... STATS -- moves system runtime statistics Syntax Parameters Status Codes Example #ACCEPT -- retrieves system task-related information Syntax Parameters Status Codes Example #ATTACH -- instructs the system to initiate a new task Syntax Parameters Status Codes Example... PROC -- establishes communication Syntax Parameters Status Codes Example... REC -- establishes addressability for a record Syntax Parameters Status Codes Example... SUBSCH -- helps the run unit Syntax Parameters Status Codes Example #BIND TASK -- initiates a DC/UCF task Syntax Parameters DML Reference for Assembler 6

7 Status Codes Example #CHAP -- changes the dispatching priority Syntax Parameters Status Codes Example commits changes made to the database Currency Syntax Parameters Status Codes #COMMIT -- commits changes made to the database Currency Syntax Parameters establishes a record occurrence Currency Syntax Parameters Status Codes Example #DELETE -- notifies the DC/UCF system Syntax Parameters Status Codes Example #DELQUE -- deletes all or part of a queue Syntax Parameters Status Codes Example #DELSCR -- deletes scratch records Syntax Parameters Status Codes Example #DEQ -- releases resources acquired by the issuing task Syntax Parameters Status Codes DML Reference for Assembler 7

8 Example cancels the current membership of a specified record Currency Syntax Parameters Status Codes Example #ENQ -- acquires resources or tests for availability Syntax Parameters Status Codes Example #ENDPAG -- terminates a map paging session Syntax Parameters Status Codes Example disconnects or erases records Currency Syntax Parameters Status Codes Example... (LRF) -- deletes logical record occurrences Syntax Parameters Status Codes Statements -- accesses database CALC/DUPLICATE Syntax Parameters Example Status CURRENT Syntax Parameters Example Status DBKEY Currency Syntax DML Reference for Assembler 8

9 Parameters Example Status OWNER Currency Syntax Parameters Example Status USING SORT KEY Currency Syntax Parameters Example Status WITHIN SET/AREA Set Currency Area Currency Syntax Parameters Example Status Codes commits changes to database and terminates run unit Currency Syntax Status Codes #FINISH -- commits changes to the database Currency Syntax Parameters Status Codes #FREESTG -- requests that the system release variable storage Syntax Parameters Status Codes Example transfers the contents of an accessed record occurrence Currency Syntax Parameters Status Codes Example DML Reference for Assembler 9

10 #GETIME -- gets time and date from the operating system Syntax Parameters Status Codes Example #GETQUE -- retrieves a queue record Syntax Parameters Status Codes Example #GETSCR -- retrieves a scratch record Syntax Parameters Status Codes Example #GETSTG -- acquires variable storage from a storage pool Syntax Parameters Status Codes Example tests for the presence of member record occurrences Currency Syntax Parameters Status Codes Example places an explicit shared or exclusive lock on a record Currency Syntax Parameters Status Codes Example #KEEP -- establishes long-term record locks Syntax Parameters Status Codes Example #LINEEND -- requests termination of the current line I/O session Syntax Parameters Status Codes DML Reference for Assembler 10

11 #LINEIN -- requests a synchronous transfer of data Syntax Parameters Status Codes Example #LINEOUT -- requests a transfer of data Syntax Parameters Status Codes Example #LINK -- establishes linkage with a program Syntax Parameters Status Codes Example #LOAD -- loads a module into the program pool Syntax Parameters Status Codes Example #MAPINQ Moving Map-Related Data Syntax Parameters Example Testing for Global Map Input Conditions Syntax Parameters Example Testing Cursor Position Syntax Parameters Example Testing for Identical Data Example Testing for Input Conditions Syntax Parameters Example Status Codes #MAPMOD -- requests that the system modify options in the map request block Considerations DML Reference for Assembler 11

12 Syntax Parameters Status Codes Example replaces element values of the database record Modifying CALC- and Sort-Control Elements Native VSAM Considerations Currency Syntax Parameters Status Codes Example... (LRF) -- changes field values of an existing logical-record occurrence Syntax Parameters Status Codes Example #MREQ -- determines how data is transferred Native Mode Transfers Synchronous and Asynchronous Requests Syntax #MREQ IN #MREQ OUT #MREQ OUTIN Parameters Status Codes Examples... (LRF) -- retrieves the named logical record Functions Syntax Parameters Status Codes Example #POST -- modifies an event control block Syntax Parameters Status Codes Example #PRINT -- requests that the system transmit data Considerations Syntax Parameters DML Reference for Assembler 12

13 Status Codes Example #PUTJRNL -- writes a task-defined record to the journal file Syntax Parameters Status Codes Example #PUTQUE -- stores a queue record in the queue Syntax Parameters Status Codes Example #PUTSCR -- stores or replaces a scratch record Syntax Parameters Status Codes Example prepares a database area for access by DML functions Syntax Parameters Status Codes Example Syntax Parameters Status Codes Example... Syntax... Parameters... Status Codes... Example #RETURN -- returns control to a program rolls back uncommitted changes made to the database Currency Syntax Parameters Status Codes Example #ROLLBAK -- rolls back the Uncommitted Changes Made to the Database Currency Syntax DML Reference for Assembler 13

14 Parameters Status Codes Example #SENDMSG -- sends a message to another terminal or user Syntax Parameters Status Codes Example #SETIME -- defines an event to occur after a specified time interval Syntax Parameters Status Codes Example #SNAP -- requests a memory snap Syntax Parameters Status Codes Example #STAE -- establishes or cancels linkage to an abend routine Syntax Parameters Status Codes Example acquires space and stores records in the database Location Modes Before 318 Currency Syntax Parameter Status Codes Example... (LRF) -- updates the database with field values for new record occurrances Syntax Parameters Status Codes Example #STRTPAG -- initiates a map paging session Syntax Parameters Status Codes Examples DML Reference for Assembler 14

15 #TREQ -- transfers data between a terminal device and your application Regular and Execute #TREQ #TREQ ALLOC Syntax #TREQ ALLOC Parameter #TREQ CHECK Syntax #TREQ CHECK Parameters #TREQ DISC Syntax #TREQ DISC Parameter #TREQ GET Syntax #TREQ GET Parameter #TREQ PUT Syntax #TREQ PUT Parameter #TREQ PUTGET Syntax #TREQ PUTGET Parameter #TREQ READ Syntax #TREQ READ Parameter #TREQ UIOCB Syntax #TREQ UIOCB Parameter #TREQ WRITE Syntax #TREQ WRITE Parameter #TREQ WRITREAD Syntax #TREQ WRITREAD Parameter Syntax Rules Parameters Examples Status Codes List #TREQ Syntax Parameters #TRNSTAT -- enables access to transaction statistics about tasks Syntax Parameters Status Codes Example #WAIT -- relinquishes control to the system Syntax Parameters Status Codes Example #WTL -- retrieves, sends, and writes messages Syntax Parameters DML Reference for Assembler 15

16 Status Codes Example #XCTL -- transfers control to a specified program Syntax Parameters Status Codes Example WHERE Syntax Parameters - Main Parameters - Expansion of comparison Examples Logical Record Clauses ON Clause Syntax Parameters Standard Path Statuses Example WHERE Clause Functions of the WHERE Clause Two Elements in a WHERE Clause Coding WHERE Including Boolean Operators Syntax Parameters Examples Logical-Record Status Codes Assembler DML Coding Considerations Coding User-Supplied Operands Coding Parameters Synonym Processing Logical Record Facility Keywords DML Precompiler-Directive Statements initializes global SET symbols Syntax Parameters DML Reference for Assembler 16

17 @COPY IDMS #MRB #MAPBIND Considerations for Assembler Programs in a DC/UCF Online System SVC Instructions in an Online Program Making Your Assembler Program Reentrant Methods of Calling an Online Assembler Subprogram TRANFER CONTROL, LINK, or ADS LINK COBOL or PL/I CALL Assembler LINK macro Standard IBM calling conventions DML Precompile, Assembly, and Link-Edit JCL IDMSDMLA Under z/os IDMSDMLA Under z/vse IDMSDMLA Under CMS Link-Edit Considerations (Assembler) Sample CA IDMS/DB Batch Program Input to the Precompiler Output from the Precompiler Output from the Assembler Sample DC/UCF Online Program Input to the DML Precompiler Output from the DML Precompiler Output from Assembler Assembler DML Macros and Error Messages DML Macros Error Messages DML Reference for Assembler 17

18 STAE Exits How STAE Exits Work STAE Routine Programming Considerations Beginning Register Values Overview for IDMSDB EMPLOYEE Data Structure Diagram Systems Network Architecture Considerations (SNA) General Considerations SNA Terminology Program Communications in the SNA Environment Error Handling SNA Functions in a CA IDMS/DC Environment Allocating a Session Establishing Conversation Attributes Issuing the TREQ ALLOC Statement Starting a Task on a Remote Logical Unit Starting a Task from a Remote System Synchronous and Asynchronous Processing Sending Data LU6.2 Considerations for Sending Data Non-LU6.2 Considerations for Sending Data Requesting a Confirmation Responding to a Confirmation Request Sending Error Information Changing Direction Send to Receive Receiving Data Changing Direction Receive to Send Terminating a Conversation Normal Termination Abnormal Termination Terminating a Session Byte Communications Blocks (Assembler) DML Reference for Assembler 18

19 Where to Specify the 18-Byte Block Byte IDMS-DB Block Online Debugger Syntax (Assembler) General Registers Symbols DC/UCF System Symbols Address Symbols and Markers User Symbols Program Symbols Syntax Data Field Names Syntax Line Numbers Syntax Qualifying Program Symbols Expression Operators Delimiters Debugger Commands AT DEBUG EXIT IOUSER LIST MENU PROMPT QUALIFY QUIT RESUME SET SNAP WHERE DML Reference for Assembler 19

20 DML Reference for Assembler This section presents navigational and LRF DML statements for use in CA IDMS/DB and CA IDMS/DC. CA IDMS UCF data communications environments are also discussed. Most data communications DML statements are applicable in both CA IDMS/DC and CA DMS UCF environments. The acronym DC/UCF is used to represent this. Audience: Assembler language programmers who run programs against CA IDMS/DB databases and who want to use the DC/UCF system facilities Assembler DML statements are embedded in the program source as if they were part of the host language. During assembly, most DML precompiler statements are expanded into executable Assembler source code (whether or not the DML precompiler was executed), and source-level error checking is performed. DML Reference for Assembler provides information about how to use Assembler Data Manipulation Language (DML) statements in your Assembler program to perform the following: Access a CA IDMS/DB database Perform data communications functions through CA IDMS/DC and CA IDMS UCF (DC/UCF) Depending on your operating environment, your Assembler program uses different sets of DML statements. For example, a batch program uses database DML statements; an online program can use both database and data communications DML statements. For more information, see the following topics: Introduction to CA IDMS Data Manipulation Language (see page 22) Operating Environments (see page 23) Assembling and Executing Programs (see page 27) Callable Services and Common Facilities (see page 29) DML Precompiler Options for Assembler (see page 30) Communications Blocks and Error Detection (see page 33) Assembler Data Manipulation Language Statements (see page 68) Assembler DML Coding Considerations (see page 380) DML Precompiler-Directive Statements (see page 385) Considerations for Assembler Programs in a DC/UCF Online System (see page 400) DML Precompile, Assembly, and Link-Edit JCL (see page 403) Sample CA IDMS/DB Batch Program (see page 420) Sample DC/UCF Online Program (see page 444) Assembler DML Macros and Error Messages (see page 451) STAE Exits (see page 461) EMPLOYEE Data Structure Diagram (see page 464) Systems Network Architecture Considerations (SNA) (see page 465) 18-Byte Communications Blocks (Assembler) (see page 488) 15-Jan /496

21 Online Debugger Syntax (Assembler) (see page 490) 15-Jan /496

22 Introduction to CA IDMS Data Manipulation Language This guide discusses how to use Assembler Data Manipulation Language (DML) statements in your Assembler program to perform the following: Access a CA IDMS/DB database Perform data communications functions through CA IDMS/DC and CA IDMS UCF (DC/UCF) Assembler DML statements are embedded in the program source as if they were part of the host language. During assembly, most DML precompiler statements are expanded into executable Assembler source code (whether or not the DML precompiler was executed), and source-level error checking is performed. Depending on your operating environment, your Assembler program uses different sets of DML statements. For example, a batch program uses database DML statements; an online program can use both database and data communications DML statements. This section discusses the following: When to use different sets of Assembler DML statements depending on your operating environment How to use the DML precompiler to prepare your program for assembly and execution 15-Jan /496

23 Operating Environments This section you learn when to use different sets of Assembler DML statemente depending on your operating environment. The following categories of Assembler DML statements are discussed: Database (see page 23)statements perform CA IDMS/DB database access functions in either a batch or an online environment. Database DML statements have an at sign (@) prefix; for Data communications (see page 25), also called online statements, perform data communications functions for CA IDMS/DC and CA IDMS UCF (DC/UCF) programs. Online DML statements have a pound sign (#) prefix; for example, #LINK. DC-batch statements are a subset of online DML statements that allow batch application programs to access DC/UCF facilities such as queues and printers. This category consists of the following DML statements: #DELQUE, #GETQUE, #PUTQUE, and #PRINT. Note: For more information about DC-batch programming, see the Navigational DML Programming ( /Navigational+DML+Programming+Reference)section. Accessing the Database Your program can access a CA IDMS/DB database by using either navigational or LRF (logical record) DML statements: Navigational statements access database records and sets one record at a time. LRF statements access predefined groups of database records using the Logical Record Facility (LRF). Navigational and LRF DML statements are discussed separately below. Navigating the Database 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 provide: Control over error checking -- You can check the result of each navigational statement Flexibility in choosing how you want to access the database -- For example, your program can access the database either sequentially (performing an area sweep), by using a symbolic key value (CALC), or by using a database key value (DIRECT) 15-Jan /496

24 To use navigational DML statements, you must have a thorough knowledge of the database structure. The database structure is illustrated in a data structure diagram. For an example of a data structure diagram, see the EMPLOYEE Data Structure Diagram. The following figure illustrates a database structure that contains two owner records (EMPLOYEE and JOB) that share one member record (EMPOSITION). To obtain EMPLOYEE and JOB information, the program must retrieve an EMPLOYEE record, the first EMPOSITION record in the EMP-EMPOSITION set, and the owner record in the JOB-EMPOSITION set. DMA1x1 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 Accessing the Database Through LRF LRF DML statements use the Logical Record Facility (LRF) to access database records. LRF accesses fields from multiple database records as if they were data fields in a single record. LRF DML statements allow your program to specify selection criteria (by using the WHERE clause) that enable your program to access only the logical records you need. Note: For more information, see Using Logical Record Facility ( /IDMS19/Using+Logical+Record+Facility). LRF DML statements provide: Easy access to database records -- You need not be familiar with database structure, and your programs need not include database navigation logic. 15-Jan /496

25 Data flexibility -- You do not usually have to modify or recompile your LRF program when the database is changed. Runtime efficiency -- LRF minimizes communication between the program and the database management system (DBMS). The following figure illustrates how to use LRF DML statements to access the EMPJOBLR record. The EMPJOBLR record is a logical record that contains the EMPLOYEE record, the EMPOSITION record, the OFFICE record, and the JOB record. The EMPJOBLR logical record contains information from the EMPLOYEE, EMPOSITION, and JOB records. DMA1x2 The LRF DML statements are deletes a logical record from the updates a logical retrieves a logical adds a new logical record to the database. Programming in the DC/UCF Environment DC/UCF application programs can use both database and online DML statements. Online DML statements perform the following types of functions: Program management statements govern flow of control and abend processing Storage management statements allocate and release variable storage Task management statements provide runtime services that control task processing Time management statements obtain the time and date and define time-related events Scratch management statements create, delete, or retrieve records from the scratch area Queue management statements create, delete, or retrieve records in a queue area Terminal management statements transfer data between the application program and a terminal 15-Jan /496

26 Utility function statements retrieve task-related information or statistics, send messages, and monitor access to database records Recovery statements perform functions relating to database, scratch, and queue area recovery in the event of a system failure Example The following example illustrates how online DML statements access the database and perform data communications functions. Specifically, this example maps in data entered from the terminal, retrieves and displays the specified information, and performs a DC return, naming TSK02 as the next task to be performed. #MREQ IN,MRB=EMPMAP,INDATA=YES,COND=ALL,ERROR=ERRORTN #MREQ OUT,MRB=EMPMAP,OUTDATA=YES,OPTNS=NEWPAGE #RETURN NXTTASK=TSK02 15-Jan /496

27 Assembling and Executing Programs An Assembler source program that contains DML statements is processed by the DML precompiler (IDMSDMLA) before it is submitted to the assembler. The DML precompiler performs the following functions: Converts most DML statements into standard Assembler source statements. Ensures that all statements issued by the program are consistent with the logical structure of the database, the subschema view of the program, and the access restrictions defined in the subschema. Copies information maintained in the dictionary into program storage. Dictionary entities include database record descriptions, file definitions, map records, map definitions, logical records, and other predefined modules. Updates the dictionary with compile-time statistics used to monitor database activities for a given application program. Performs source level error checking. Generates an optional source statement listing of error conditions detected during DML processing. Supports the use of native VSAM files in conjunction with database access methods. Recognizes record, element, and file synonyms defined in the dictionary. Allows programs to be compiled for execution under various TP monitors without changing the source DML statements. An Assembler program must be submitted to the DML precompiler if the program contains any of the following statements: IDMS statement statement Logical-record DML statement containing a WHERE clause If none of these statements is included, the Assembler program can bypass the DML precompiler. The source can be submitted directly to the assembler because most Assembler DML statements are macro instructions that are expanded during assembly. It is recommended, however, that all programs accessing the database or running under a DC/UCF system use the DML precompiler. For a list of Assembler DML macros, see the Assembler DML Macros and Error Messages. Output from the DML precompiler is a card-image source file that serves as input to the assembler. Output from the assembler consists of an object program and a source listing that includes any generated diagnostics. During assembly, most procedural DML verbs are expanded into executable Assembler source code, whether or not the DML precompiler was executed. 15-Jan /496

28 After the program is assembled, it is submitted to the linkage editor. The linkage editor link edits the object program into a specified load library. Output from the linkage editor consists of a load module and a link map. The following figure illustrates the steps involved in assembling and executing an Assembler program containing DML statements. DMA1x1 15-Jan /496

29 Callable Services and Common Facilities CA IDMS provides callable services and common facilities to use with your application programs: Callable Services (see page 29) Common Facilities (see page 29) 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. 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. 15-Jan /496

30 DML Precompiler Options for Assembler This section contains syntax for Assembler DML precompiler options. DML precompiler option statements are included in the input source code to the DML precompiler. These statements are used to: Override the default shared update usage mode for the DDLDML area of the dictionary and ready the area in either retrieval or protected update mode Print comment lines stored in the dictionary for subschema data items on the DML listing Generate a source statement listing of the output from the DML precompiler Suppress the logging of program activity statistics in the dictionary These options are discussed in the following topics: Dictionary Usage Mode (see page 30) Comment Generation (see page 31) List Generation (see page 31) Log Suppression (see page 32) Dictionary Usage Mode When the main area (DDLDML area) of the dictionary accessed by the DML precompiler is readied, several options are available. The default usage mode, shared update usage, is defined at system generation. Shared update mode readies the DDLDML area for both retrieval and update and allows other concurrently executing run units to ready the DDLDML area in shared update or shared retrieval usage mode. You can override the default usage mode by specifying either retrieval or protected update usage mode in your application program. Syntax *RETRIEVAL *PROTECTED-UPDATE The asterisk (*) must be in column 1. Parameters *RETRIEVAL Readies the DDLDML area for retrieval only and allows other concurrently executing run units to open the DDLDML area in shared retrieval, shared update, protected retrieval, or protected update mode. Note: If the DDLDML area is readied for retrieval only, no program activity statistics can be logged. 15-Jan /496

31 *PROTECTED-UPDATE Readies the DDLDML area for both retrieval and update and allows other concurrently executing run units to open the DDLDML area in retrieval usage mode only. The protected update usage mode prevents concurrent update of the area by run units executing under the same central version. If included, the dictionary usage mode statement must precede all source statements. Comment Generation Syntax The *SCHEMA-COMMENTS option causes schema-defined data item comments and IDD-defined record-element comments in the dictionary to be printed on the DML source listing. You can specify this option by including the following entry at the beginning of the input source code, after the dictionary usage mode statements (if present) and before any DML or Assembler statements. *SCHEMA-COMMENTS The asterisk (*) must be in column 1. If the input does not include a *SCHEMA-COMMENTS entry, comment lines are not generated. List Generation Syntax You can turn on or off the source statement listing output by the DML precompiler by inserting a list generation option in the source program. *NODMLIST *DMLIST The asterisk (*) must be in column 1. Parameters *NODMLIST Specifies that no source code listing is to be generated for the DML statements that follow. *DMLIST Generates the source code listing for all the DML statements that follow. 15-Jan /496

32 In general, you would include one of these entries at the beginning of the input source code before any standard DML or Assembler statements. However, generation of the list can be turned on or off any number of times within one source program by inserting appropriate *DMLIST/*NODMLIST entries in the code. Note: The DML precompiler always produces a listing of error messages. The *DMLIST option controls listing of the DML source code. Log Suppression You can suppress the logging of program activity statistics in the dictionary by using the *NO- ACTIVITY-LOG option. This option, if included, is placed at the beginning of the DML source program. The DML precompiler generates and logs the following program activity statistics unless the *NO- ACTIVITY-LOG option is included in the program source code: Program name Language Date last compiled Number of lines Number of compilations Date created Subschema name (if any) File statistics Database access statistics (for example, records and modules copied from the dictionary; subprograms called; and records, sets, and areas accessed by DML verbs) Syntax *NO-ACTIVITY LOG The asterisk (*) must be in column 1. Note: Program activity statistics cannot be logged if you ready the dictionary DDLDML area for retrieval only. 15-Jan /496

33 Communications Blocks and Error Detection This section describes the communication blocks and registers available under CA IDMS/DB and DC /UCF systems to return status information to an application program that requests database and data communication services. CA IDMS/DB and DC/UCF systems use the following facilities to communicate with your application program: The IDMS communications block (see page 37) returns information from the database management system (DBMS) to your application program. The ERRSTAT (see page 43) field of the IDMS communications block receives a status code that indicates the successful or unsuccessful execution of a DML command. You can test for the content of the ERRSTAT field in your database program. The logical-record request control (LRC) block (see page 52) returns information from the Logical Record Facility (LRF) to your application program when you are accessing logical records that have been created by LRF. The LRSTAT field of the LRC block returns the path status for a logical-record DML request. You can test for the contents of the LRSTAT field in your program. Register 15 is used by the DC/UCF system to return information regarding the successful or unsuccessful execution of DML commands that request data communication services. You can test for the content of register 15 to determine the outcome of a DC/UCF DML statement. In addition to the above topics, this section lists the status codes returned by the DBMS for database requests and the return codes issued by DC/UCF system for data communications requests. Major Database Status Codes (Assembler) Major Code Database Function 00 Any DML statement 01 FINISH 02 ERASE 03 FIND/OBTAIN 05 GET 06 KEEP 07 CONNECT 08 MODIFY 09 READY 11 DISCONNECT 12 STORE 14 BIND 15-Jan /496

34 15 ACCEPT 16 IF 17 RETURN 18 COMMIT 19 ROLLBACK 20 LRF requests Minor Database Status Codes (Assembler) Minor Code Database Function Status 00 Combined with a major code of 00, this code indicates successful completion of the DML operation. Combined with a nonzero major code, this code indicates that the DML operation was not completed successfully due to central version causes, such as time-outs and program checks. 01 An area has not been readied. When this code is combined with a major code of 16, an IF operation has resulted in a valid false condition. 02 Either the db-key used with a FIND/OBTAIN DB-KEY statement or the direct db-key suggested for a STORE is not within the page range for the specified record name. 03 Invalid currency for the named record, set, or area. This can only occur when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned if the run unit tries to retrieve or update a record using a currency that has been invalidated because of changes made by another database session that is sharing the same transaction. 04 The occurrence count of a variably occurring element has been specified as either less than zero or greater than the maximum number of occurrences defined in the control element. 05 The specified DML function would have violated a duplicates-not-allowed option for a CALC, sorted, or index set. 06 No currency has been established for the named record, set, or area. 07 The end of a set, area, or index has been reached or the set is empty. 08 The specified record, set, procedure, or LR verb is not in the subschema or the specified record is not a member of the set. 09 The area has been readied with an incorrect usage mode. 10 An existing access restriction or subschema usage prohibits execution of the specified DML function. For LRF users, the subschema in use allows access to database records only. Combined with a major code of 00, this code means the program has attempted to access a database record, but the subschema in use allows access to logical records only. 11 The record cannot be stored in the specified area due to insufficient space. 12 There is no db-key for the record to be stored. This is a system internal error and should be reported. 13 A current record of run unit either has not been established or has been nullified by a previous ERASE statement. 15-Jan /496

35 Minor Code Database Function Status 14 The CONNECT statement cannot be executed because the requested record has been defined as a mandatory automatic member of the set. 15 The DISCONNECT statement cannot be executed because the requested record has been defined as a mandatory member of the set. 16 The record cannot be connected to a set of which it is already a member. 17 The transaction manager encountered an error. 18 The record has not been bound. 19 The run unit's transaction was forced to back out. 20 The current record is not the same type as the specified record name. 21 Not all areas being used have been readied in the correct usage mode. 22 The record name specified is not currently a member of the set name specified. 23 The area name specified is either not in the subschema or not an extent area; or the record name specified has not been defined within the area name specified. 25 No currency has been established for the named set. 26 No duplicates exist for the named record or the record occurrences cannot be found. 28 The run unit has attempted to ready an area that has been readied previously. 29 The run unit has attempted to place a lock on a record that is locked already by another run unit. A deadlock results. Unless the run unit issued either a FIND/OBTAIN KEEP EXCLUSIVE or a KEEP EXCLUSIVE, the run unit is aborted. 30 An attempt has been made to erase the owner record of a nonempty set. 31 The retrieval statement format conflicts with the record's location mode. 32 An attempt to retrieve a CALC/DUPLICATE record was unsuccessful; the value of the CALC field in variable storage is not equal to the value of the CALC control element in the current record of run unit. 33 At least one set in which the record participates has not been included in the subschema. 40 The WHERE clause in an OBTAIN NEXT logical-record request is inconsistent with a previous OBTAIN FIRST or OBTAIN NEXT command for the same record. Previously specified criteria, such as reference to a key field, have been changed. A path status of LR-ERROR is returned to the LRC block. 41 The subschema contains no path that matches the WHERE clause in a logical-record request. A path status of LR-ERROR is returned to the LRC block. 42 An ON clause included in the path by the DBA specified return of the LR-ERROR path status to the LRC block; an error has occurred while processing the LRF request. 43 A program check has been recognized during evaluation of a WHERE clause; the program check indicates that either a WHERE clause has specified comparison of a packed decimal field to an unpacked nonnumeric data field, or data in variable storage or a database record does not conform to its description. A path status of LR-ERROR is returned to the LRC block unless the DBA has included an ON clause to override this action in the path. 44 The WHERE clause in a logical-record request does not supply a key element (sort key, CALC key, or db-key) expected by the path. A path status of LR-ERROR is returned to the LRC block Jan /496

36 Minor Code Database Function Status During evaluation of a WHERE clause, a program check has been recognized because a subscript value is neither greater than 0 nor less than its maximum allowed value plus 1. A path status of LR-ERROR is returned to the LRC block unless the DBA has included an ON clause to override this action in the path. 46 A program check has revealed an arithmetic exception (for example: overflow, underflow, significance, divide) during evaluation of a WHERE clause. A path status of LR-ERROR is returned to the LRC block unless the DBA has included an ON clause to override this action in the path. 53 The subschema definition of an indexed set does not match the indexed set's physical structure in the database. 54 Either the prefix length of an SR51 record is less than zero or the data length is less than or equal to zero. 55 An invalid length has been defined for a variable-length record. 56 An insufficient amount of memory to accommodate the CA IDMS compression /decompression routines is available. 57 A retrieval-only run unit has detected an inconsistency in an index that should cause an 1143 abend, but optional APAR bit 216 has been turned on. 58 An attempt was made to rollback updates in a local mode program. Updates made to an area during a local mode program's execution cannot be automatically rolled out. The area must be manually recovered. 60 A record occurrence type is inconsistent with the set named in the ERROR-SET field in the IDMS communications block. This code usually indicates a broken chain. 61 No record can be found for an internal db-key. This code usually indicates a broken chain. 62 A system-generated db-key points to a record occurrence, but no record with that db-key can be found. This code usually indicates a broken chain. 63 The DBMS cannot interpret the DML function to be performed. When combined with a major code of 00, this code means invalid function parameters have been passed on the call to the DBMS. For LRF users, a WHERE clause includes a keyword that is longer than the 32 characters allowed. 64 The record cannot be found; the CALC control element has not been defined properly in the subschema. 65 The database page read was not the page requested. 66 The area specified is not available in the requested usage mode. 67 The subschema invoked does not match the subschema object tables. 68 The CICS interface was not started. 69 A BIND RUN-UNIT may not have been issued; the CV may be inactive or not accepting new run units; or the connection with the CV may have been broken due to time out or other factors. When combined with a major code of 00, this code means the program has been disconnected from the DBMS. 70 The database will not ready properly; a JCL error is the probable cause. 71 The page range or page group for the area being readied or the page requested cannot be found in the DMCL. 15-Jan /496

37 Minor Code Database Function Status 72 There is insufficient memory to dynamically load a subschema or database procedure. 73 A central version run unit will exceed the MAXERUS value specified at system generation. 74 The dynamic load of a module has failed. If operating under the central version, a subschema or database procedure module either was not found in the data dictionary or the load (core image) library or, if loaded, will exceed the number of subschema and database procedures provided for at system generation. 75 A read error has occurred. 76 A write error has occurred. 77 The run unit has not been bound or has been bound twice. When combined with a major code of 00, this code means either the program is no longer signed on to the subschema or the variable subschema tables have been overwritten. 78 An area wait deadlock has occurred. 79 The run unit has requested more db-key locks than are available to the system. 80 The target node is either not active or has been disabled. 81 The converted subschema requires specified database name to be in the DBNAME table. 82 The subschema must be named in the DBNAME table. 83 An error has occurred in accessing native VSAM data sets. 87 The owner and member records for a set to be updated are not in the same page group or do not have the same db-key radix. 91 The subschema requires a DBNAME to do the bind run unit. 92 No subschema areas map to DMCL. 93 A subschema area symbolic was not found in DMCL. 94 The specified dbname is neither a dbname defined in the DBNAME table, nor a SEGMENT defined in the DMCL. 95 The specified subschema failed DBTABLE mapping using the specified dbname. Note: For a complete description of DB runtime status codes, see the section "CA IDMS Status Codes" in the Messages and Codes. CA IDMS Communications Block (Assembler) The CA IDMS communications block passes information between the DBMS and the application program. Whenever a run unit issues a call to the DBMS for a database operation, the DBMS returns information about the outcome of the requested service to the ERRSTAT field in the application program communications block. 15-Jan /496

38 To receive status information from the DBMS, an application program must define the communications block in variable storage. You must either copy the CA IDMScommunications block from the dictionary into your program's variable storage by using statement or generate the communications block by using statement. The following example illustrates statement before and after it has been expanded by the DML IDMS,SUBSCHEMA-CTRL DS 0D SSCTRL DS 0CL216 PGMNAME DC CL8' ' ERRSTAT DC CL4'1400' DBKEY DS FL4 RECNAME DC CL16' ' AREANAME DC CL16' ' ERRORSET DC CL16' ' ERRORREC DC CL16' ' ERRAREA DC CL16' ' SSCIDBCM DS 0CL100 IDBMSCOM DS 100CL1 ORG SSCIDBCM RDBMSCOM DS 0CL100 PGINFO DS 0CL4 PGINFGRP DS HL2 PGINFDBK DS HL2 DS CL96 DIRDBKEY DC FL4'0' DBSTATUS DS 0CL8 DBSTMTCD DS CL2 DBSTATCD DS CL5 DS CL1 RECOCCUR DC FL4'0' DMLSEQ DC FL4'0' (Before DML expansion) (After DML expansion) The same expansion would result by using statement in your application program instead of IDMS,SUBSCHEMA-CTRL statement. statement is a macro that generates the variable storage definitions of the communications block instead of copying the block from the dictionary. Note: For more information about the differences between these statements, see the DML Precompiler Options for Assembler (see page 30). After every call to the DBMS, the DBMS issues an error-status code that indicates successful or unsuccessful completion of the requested service. This status code is returned to the ERRSTAT field in the communications block. You should examine the ERRSTAT field after every call to the DBMS. Depending on the error-status code, it may be useful to examine other fields and/or branch to a routine that responds to the condition indicated by the error-status code. The following figure shows the layout of the 16-byte communications block; each field is described separately. Starting with offset 200, the layout of the block differs for application programs that run under CICS. Note: For more information about the 18-byte communications block, see the 18-Byte Communications Blocks (Assembler) (see page 488). 15-Jan /496