PUBLIC SDK for SAP Adaptive Server Enterprise 16.0 SP03 PL07 Document Version: 1.0 – 2019-06-06 Embedded SQL/COBOL Programmers Guide company. All rights reserved. All rights company. affiliate THE BEST RUN 2019 SAP SE or an SAP SE or an SAP SAP 2019 © Content 1 Introduction ................................................................7 1.1 Embedded SQL Features........................................................7 1.2 Transact-SQL Support in Embedded SQL ............................................8 1.3 Getting Started.............................................................. 8 Using the Examples.........................................................9 Backward Compatibility ......................................................9 1.4 Creating and Running an Embedded SQL Program.....................................10 1.5 How the Precompiler Processes Your Applications..................................... 11 Multiple Embedded SQL Source Files............................................11 Precompiler-generated Files ..................................................12 Group Element Referencing...................................................12 2 General Information.........................................................13 2.1 Five Tasks of an Embedded SQL Program........................................... 13 Simplified Embedded SQL Program.............................................14 2.2 General Rules for Embedded SQL.................................................14 Statement Placement ......................................................15 Comments.............................................................. 16 Identifiers ...............................................................16 Quotation Marks.......................................................... 16 Reserved Words...........................................................16 Variable Naming Conventions.................................................16 Scoping Rules............................................................ 17 Statement Batches.........................................................17 2.3 Embedded SQL Constructs.....................................................18 3 Communicating with SAP ASE.................................................20 3.1 Scoping Rules: SQLCA, SQLCODE, and SQLSTATE.....................................20 3.2 Declaring SQLCA.............................................................21 Multiple SQLCAs.......................................................... 21 SQLCA Variables.......................................................... 21 SQLCODE within SQLCA.....................................................22 3.3 SQLCODE as a Standalone Area..................................................23 3.4 SQLSTATE.................................................................24 SQLSTATE Codes and Error Messages...........................................25 4 Variables .................................................................26 4.1 Declaring Variables...........................................................26 Embedded SQL/COBOL Programmers Guide 2 PUBLIC Content Declaring a Character Array..................................................27 4.2 Using Host Variables..........................................................28 Host Input Variables........................................................29 Host Result Variables.......................................................29 Host Status Variables.......................................................29 Host Output Variables...................................................... 29 4.3 Using Indicator Variables.......................................................30 Indicator Variables and Server Restrictions....................................... 30 Using Host Variables with Indicator Variables......................................31 Host Variable Conventions...................................................33 4.4 Arrays....................................................................34 Multiple Arrays...........................................................34 4.5 Scoping Rules.............................................................. 34 4.6 Datatypes.................................................................36 Elementary Data Items......................................................37 Group Data Items..........................................................37 Special Data Items.........................................................38 COBOL and Adaptive Server Enterprise datatypes Comparison.........................38 Converting datatypes.......................................................38 5 Connecting to SAP ASE......................................................42 5.1 Connecting to a Server ........................................................42 user...................................................................43 password ...............................................................43 connection_name .........................................................43 server .................................................................43 connect Example..........................................................44 5.2 Changing the Current Connection................................................ 44 5.3 Establishing Multiple Connections................................................44 Connection Names........................................................ 45 Using SAP ASE Connections ................................................. 46 5.4 Disconnecting from a Server....................................................47 6 Using Transact-SQL Statements................................................48 6.1 Transact-SQL statements in Embedded SQL ........................................ 48 Invalid Statements.........................................................49 Transact-SQL Statements that Differ in Embedded SQL.............................. 49 6.2 Selecting Rows..............................................................49 Selecting One Row.........................................................50 Selecting Multiple Rows Through Arrays......................................... 50 Using Stored Procedures....................................................64 6.3 Grouping Statements.........................................................68 Embedded SQL/COBOL Programmers Guide Content PUBLIC 3 Grouping Statements by Batches..............................................68 Grouping Statements by Transactions...........................................69 6.4 Including Files and Directories................................................... 71 7 Using Dynamic SQL .........................................................72 7.1 When to Use Dynamic SQL..................................................... 72 7.2 Dynamic SQL Protocol........................................................ 73 7.3 Method 1: Using execute immediate...............................................74 Method 1 Examples........................................................ 75 7.4 Method 2: Using Prepare and Execute..............................................75 prepare.................................................................76 execute.................................................................76 Method 2 Example.........................................................77 7.5 Method 3: Using Prepare and Fetch with a Cursor......................................77 prepare.................................................................78 declare.................................................................78 open...................................................................79 fetch and close ...........................................................79 Method 3 Example.........................................................80 7.6 Method 4: Using Prepare and Fetch with System Descriptors..............................81 Method 4 Dynamic Descriptors................................................81 Dynamic Descriptor Statements...............................................82 Method 4 Example.........................................................83 About SQLDAs........................................................... 85 Using SYBSETSQLDA.......................................................87 Method 4 Example Using SQLDAs..............................................89 8 Errors Handling............................................................ 92 8.1 Testing for Errors............................................................ 93 SQLCODE Return Values.................................................... 93 8.2 Testing for Warning Conditions.................................................. 94 8.3 Trapping Errors with the Whenever Statement........................................95 whenever Testing Conditions................................................. 95 whenever Actions......................................................... 96 8.4 Using get diagnostics......................................................... 97 8.5 Writing Routines to Handle Warnings and Errors...................................... 97 8.6 Precompiler-detected Errors ....................................................98 9 Embedded SQL Statements: Reference Pages.................................... 100 9.1 allocate descriptor...........................................................101 9.2 begin declare section.........................................................103 9.3 begin transaction..........................................................