RLX for Db2

RLX for Db2REXX Language eXtensions

Getting Started

Version 9.1.7

January 2018

Publication RLX-005-11

Relational Architects Intl

ii RLX Getting Started

________________________________________________________________________

This Guide: (RAI Publication RLX-005-11)

This document applies to RLX Version 9 Release 1 Mod 7 (January 2018), and all subsequent releases, unless otherwise indicated in new editions or technical newsletters. Specifications contained herein are subject to change and will be reported in subsequent revisions or editions.

Purchase Orders for publications should be addressed to:

Documentation Coordinator Relational Architects Intl. Riverview Historic Plaza 33 Newark Street Hoboken NJ 07030 USA

Tel: 201 420-0400 Fax: 201 420-4080 Email [email protected]

Reader comments regarding the product, its documentation, and suggested improvements are welcome. A reader comment form for this purpose is provided at the back of this publication.

Copyright (c) 2016, 2018 by Relational Architects, Inc. (RAI) as an unpublished work -- all rights reserved. The software product(s) described herein and the documentation thereof are trade secrets and property of Relational Architects, Inc. All use, disclosure, duplication, electronic storage, reproduction or transmission without specific written authorization from RAI is strictly prohibited. These pro-ducts may also be protected under the trade-secret and copyright laws of countries other than the United States and international agreements.

Db2, QMF and ISPF are software products of IBM Corporation. REXX Language eXtensions, RDX, REXX Db2 eXtensions, AcceleREXX, RLX/CLIST, RLX/ISPF, RLX/TSO, RLX/SQL, RLX/VSAM, RLX/SDK, RLX/Net, RLX for Db2, RLX for z/OS, RLX/Compile, Multi/CAF, RFA and LMD are trademarks of Relational Architects International, Inc.

Ed 18A27

________________________________________________________________________

Preface iii

Preface

Related Publications

This Guide provides 'Getting Started' material for RLX and its embedded SQL support for REXX. This introductory material is augmented by the more extensive RLX product library which at present includes the following publications:

• RLX for Db2 User Guide and Reference RLX-003• RLX for z/OS User Guide and Reference RLX-101• RLX Installation and Customization Guide RLX-001• RLX Product Family Reference RPF-001 • RLX/VSAM Reference RXV-001 • RLX/SDK Reference RDK-001 • AcceleREXX User Guide RCX-001 • RLX/Translate Guide and Reference RCT-001

For information related to IBM's REXX implementation for TSO/E refer to the following IBM publications:

• TSO/E REXX Reference• TSO/E REXX User’s Guide

iv RLX Getting Started

For information related to Db2 for z/OS, refer to the following IBM publications:

• Db2 Administration Guide• Db2 Application Programming and SQL Guide• Db2 SQL Reference• Db2 Messages and Codes• Db2 Command Reference• Db2 Utility Guide and Reference

For information related to ISPF / PDF see the following IBM publications:

• ISPF Dialog Developer’s Guide and Reference• ISPF Edit and Edit Macros• ISPF User’s Guide

For information related to the DFSMS implementation of VSAM please refer to the following IBM publications:

• DFSMS Macro Instructions for Data Sets• DFSMS Access Method Services• DFSMS Using Data Sets• DFSMS Managing Catalogs

Notational Conventions

The following notational conventions are used in this Guide:

Uppercase commands and their operands should be entered as shown but need not beentered in uppercase.

Operands shown in lower case are variable; a value should be substituted for them.

Operands shown in brackets [ ] are optional, with a choice indicated by a vertical bar|. One or none may be chosen; the defaults are underscored.

Operands shown in braces { } are alternatives; one must be chosen.

An ellipsis (...) indicates that the parameter shown may be repeated to specifyadditional items of the same category.

In the Messages section, contents within arrowheads < > will be replaced at run-time with the actual value.

1

Table of Contents

Preface ................................................................................................................... iii Related Publications ............................................................................................................ iii

Notational Conventions ....................................................................................................... iv

Chapter 1: Concepts and Facilities .............................................................. 1-1 1.1 What is RLX ? ................................................................................................................... 1-1

1.2 The RLX Product Family ................................................................................................. 1-2

1.3 The RLX Product Library and Examples ......................................................................... 1-3

1.4 Rapid Application Development for Mission Critical Applications ................................... 1-5

1.5 RLX Support for Embedded SQL .................................................................................... 1-5

1.6 RLX/SQL Features ............................................................................................................ 1-6

Chapter 2: Getting started with RLX ......................................................... 2-1 2.1 The Singleton SELECT Example ....................................................................................... 2-2

2.2 CURSOR based processing ............................................................................................... 2-3

2.3 Explicitly naming the target Db2 subsystem ...................................................................... 2-4

2.4 Running RLX Execs in Batch ............................................................................................ 2-6

Chapter 3: RLX Extension Facilities ........................................................... 3-1 3.1 The DECLARE REXXSTEM service ............................................................................. 3-1

3.2 Names of REXX stemmed variables into which RLX copies data .................................... 3-3

3.3 Loading SQL query results directly into ISPF tables ......................................................... 3-4

3.4 The RLX TBDISPL Service ............................................................................................ 3-5

2 RLX Getting Started Guide

Chapter 4: RLX Reference Topics .............................................................. 4-1 4.1 RLX host variables ............................................................................................................ 4-1

4.2 Host variable datatypes ....................................................................................................... 4-2

4.3 Coding Long SQL Statements .......................................................................................... 4-3

4.4 RLX Feedback to your Execs ............................................................................................. 4-4

4.4.1 Unique RLX Feedback .......................................................................................... 4-6

4.5 The DESCRIBE service and the SQL Descriptor Area (SQLDA) .................................. 4-7

4.5.1 The DESCRIBE service for input SQLDA Variables ......................................... 4-10

4.6 The RLX IFI Interface ...................................................................................................... 4-11

Index: ................................................................................................................... I-1

Chapter 1: Concepts and Facilities 1-1

Chapter 1

Concepts and Facilities

1.1 What is RLX ? RLX designates a family of REXX Language eXtensions that endow REXX with additional capabilities. Together, the extensions make REXX a viable replacement for assembled and compiled host languages to let you `Do it all in REXX'. Interpretive command languages like REXX have traditionally been used to develop application frontends and simple procedures as well as to customize and extend products such as Tivoli NetView. RLX supports these uses and, in addition, lets you tackle the kinds of sophisticated applications that previously had to be coded in Assembler or high level languages. RLX provides an integrated development environment for REXX that lets you develop applications very quickly. Later, you can deploy ‘industrial strength’ solutions that exhibit the security and performance characteristics of applications written in compiled languages. The REXX Language eXtensions (and the corresponding RLX product components) include:

• native support for SQL and XML

• native support for Db2 commands and IFI requests (RLX/IFI)

• support for running REXX execs as Db2 stored procedures

• native support for RRSAF and CAF (RLX/CAF)

• a native VSAM interface (RLX/VSAM)

• a REXX Software Development Kit (SDK) that provides developers numerous functions, such as native access to MVS supervisor services, cross memory services and inter-process communications (RLX/SDK)

• special composite objects for Db2 in the TSO/ISPF environment (RLX/ISPF)

• an interpretive REXX compiler (AcceleREXX)

• SQL compiler (RLX/Compile)

• a CLIST to REXX translator (RLX/Translate)

1-2 RLX Getting Started Guide

RLX provides the best of both worlds. Development is quick and easy with interpretive REXX and dynamic SQL. To test an exec, you execute it, correct any errors if it fails, and re-execute it. Once you are satisfied with an application's functionality and correctness, the companion RLX/Compile product lets you deploy compiled 'industrial strength' applications into production. These static SQL applications exhibit qualitatively different behavior from their dynamic SQL counterparts. They not only run faster, they are more secure. Administrators can grant execute authority for compiled plans without granting users access to the Db2 tables and views referenced by a plan. This prevents unauthorized access to sensitive data through dynamic SQL facilities like QMF and SPUFI. Bottom Line: RLX provides rapid application development for mission critical applications. RLX is designed to run everywhere within z/OS that REXX does. Supported z/OS environments include TSO, batch TSO, native batch and Tivoli NetView. In addition, RLX runs in stored procedure address spaces established by both Db2 and Work Load Manager as well as in System REXX address spaces. RLX exploits TSO, ISPF and NetView facilities when they are available but does not require them to operate.

1.2 The RLX Product Family

The RLX Product Family includes the following REXX Language Extensions: RLX components for Db2 RLX/SQL provides embedded SQL/XML support for REXX that is as robust and flexible as that for COBOL. RLX execs can be developed rapidly and tested immediately without the preprocess, compile, linkedit and bind steps normally required by Db2 applications written in compiled languages. RLX/SQL includes a DECLARE REXXSTEM service which lets you copy SQL result tables directly into REXX stemmed arrays. RLX/TSO provides a REXX SQL implementation that, in REXX parlance, is integrated into TSO/E and exploits available ISPF facilities. For example, when errors occur RLX/TSO uses ISPF services to display full screen, scrollable diagnostic panels. Both RLX/SQL and RLX/TSO include a Db2 attachment facility (RLX/CAF) which allows user-written applications to create, manage and switch among multiple, concurrently active Db2 plan threads. RLX/CAF enables you to connect to multiple Db2 subsystems simultaneously and lets you maintain multiple threads for each subsystem. RLX/CAF supports both RRSAF and CAF as underlying Db2 attachments. In addition, both RLX/SQL and RLX/TSO include native support for Db2 commands and IFI requests through RLX/IFI. RLX/ISPF provides a pair of powerful composite objects that address common processing requirements in the Db2/ISPF environment. The RLX DECLARE ISPFTABLE service provides the means to load SQL query results directly into ISPF tables while the RLX TBDISPL service lets you display and process those results on scrollable ISPF table display panels.


RLX/Net extends REXX SQL support to NetView and endows dialogs running in that environment with the look and feel of ISPF. RLX/Compile extracts and compiles the SQL statements embedded in your REXX EXECs to produce static Db2 application plans and their associated load modules. RLX/Compile interoperates with both the AcceleREXX compiler and the REXX/370 Compiler from IBM. RLX components for z/OS RLX/VSAM provides a simple and intuitive VSAM interface that's native to REXX. RLX/VSAM supports all read, write and delete operations on VSAM ESDS, KSDS and RRDS files -- on a record and control interval basis. It also supports control interval processing of VSAM linear datasets. RLX/VSAM is modeled after the DFP macro interface so programmers familiar with VSAM coding conventions can make use of RLX/VSAM almost immediately. The RLX/SDK provides an evolving Software Development Kit (SDK) that affords native access to MVS system services, as well as facilities for partitioned dataset I/O, resource control, parsing, tokenizing, sorting and many other functions. The AcceleREXX compiler can dramatically improve the performance of your REXX execs while protecting them from modification. AcceleREXX provides an ISPF dialog framework to compile and link multiple EXECs together and even combine them into REXX function packages. RLX/Translate provides an automated means to translate your TSO CLISTs into REXX procedures. Once translated, all your command procedures can be maintained as REXX execs which can be further extended and compiled with the rest of the RLX product family.

1.3 The RLX Product Library and Examples This Guide provides 'Getting Started' material for RLX/SQL and its native, embedded SQL support for REXX. This introductory material is augmented by the more extensive RLX product library which at present includes the following publications:

• RLX for Db2 User Reference RLX-003 • RLX for z/OS User Reference RLX-101 • RLX Installation and Customization Guide RLX-001 • RLX/Translate Guide and Reference RCT-001

The RLX product library is designed to provide an appropriate level of detail for audiences whose requirements may differ.


In addition, the RLX EXEC library contains many examples of RLX usage. The various components of the RLX product family are further documented as follows: • REXX VSAM support is described in the RLX/VSAM section of the RLX for z/OS

User Reference. Examples of REXX VSAM usage appear in members of the RLX EXEC library whose names start with the letters 'RXV'.

• The REXX Software Development Kit (SDK) is described in the RLX/SDK section

of the RLX for z/OS User Reference. SDK functions are exercised by members of the RLX EXEC library whose names start with 'RXD'.

• The AcceleREXX compiler is described in the AcceleREXX section of the RLX for

MVS User Reference and its examples are prefixed by the letters 'RCXT'. • RLX/Translate is described in the RLX/Translate section of the RLX Reference and

its examples are prefixed by the letters 'RCT'. • The REXX SQL interface is described in the RLX for Db2 User Reference.

Members of the RLX EXEC library whose names start with RLXE and RMV provide examples of RLX/TSO and RLX/SQL usage. Additional examples of support for RXSQL syntax (IBM's REXX SQL implementation for SQL/DS) appear in members whose names start with RXS.

• The RRSAF and Call Attach Facility services provided by RLX/CAF are described

in the RLX/CAF section of the RLX for Db2 User Reference. Member RMVDCAF provides a complete and annotated example of RLX/CAF usage.

• The Db2/ISPF composite functions that comprise RLX/ISPF are described in the

RLX/ISPF section of the RLX for Db2 User Reference. Examples of RLX/ISPF usage appear in those members of the RLX EXEC library whose names start with RTD.

• RLX/Net is described in RLX for Db2 User Reference and its examples are prefixed

by the letters RNV. • RLX/Compile is described in the RLX/Compile section of the RLX for Db2 User

Reference and its examples are prefixed by the letters 'RCSD'.


1.4 Rapid Application Development for Mission Critical Applications

RLX provides the best of both worlds. Development is quick and easy with interpretive REXX and dynamic SQL. Once you are satisfied with an application's functionality and correctness, RLX/Compile lets you deploy compiled 'industrial strength' applications into production. These static SQL applications exhibit qualitatively different behavior from their dynamic SQL counterparts. They not only run faster, they are more secure. Administrators can grant execute authority for compiled plans without granting users access to the Db2 tables and views referenced by a plan. This prevents unauthorized access to sensitive data through dynamic SQL facilities like QMF and SPUFI. Bottom Line: RLX provides rapid application development for mission critical applications. RLX/Compile includes a complete application development system to compile, link edit and BIND 'real world' applications comprised of multiple modules. This is accomplished within an ISPF dialog framework which eliminates the tedious, error prone aspects of program preparation.

1.5 RLX Support for Embedded SQL

RLX offers comprehensive SQL/XML support (at the latest level of Db2 for z/OS) while strictly adhering to standard syntax for embedded SQL and embedded XML. RLX fully supports all SQL data definition, manipulation, and control statements which may be embedded in programs, subject to the user's Authorization ID. RLX users can

• Issue queries (SELECT, DECLARE, OPEN, FETCH, CLOSE) Applications can process individual rows as well as result tables.

• Manipulate data (INSERT, UPDATE, DELETE)

• Manage data consistency and referential integrity (COMMIT and ROLLBACK)

• Define and revise Db2 objects (CREATE, ALTER, DROP)

• Administer authorizations and privileges (GRANT and REVOKE)

• Invoke Db2 stored procedures and pass them parameters (CALL)

• Process query result(s) returned by Db2 stored procedures (ASSOCIATE LOCATORS and ALLLOCATE CURSOR)

• Process dynamic SQL (PREPARE, DESCRIBE, EXECUTE)

• Connect to remote servers (CONNECT and RELEASE)

• Set and obtain values of SQL special registers (various forms of the SET statement)


1.6 RLX/SQL Features • Full compatibility with Db2 security and authorization mechanisms. • Full compatibility with ISPF Dialog Management Services. • Automatic conversion between Db2 internal and REXX external datatypes. • Feedback from the variables comprising the SQL Communications Area are returned to the RLX Exec after each SQL statement executes. • Interactive facilities to pinpoint errors and speed their correction through extensive

diagnostics, error reporting and context sensitive help. • RLX provides profile facilities to customize the product according to the preferences

and requirements of an individual, group, department, or an entire installation. • Extensive features for enhanced reliability, availability and serviceability.

Chapter 2: RLX Getting Started 2-1

Chapter 2

Getting started with RLX

This chapter introduces RLX and illustrates its usage in REXX Execs that issue SQL statements and, possibly, requests for ISPF dialog services. The examples assume that the names of a default Db2 subsystem and RLX application plan were defined at installation time. RLX SQL procedures can be developed rapidly and tested immediately. There's no need for preprocess, compile, linkedit and Db2 BIND steps. Nor are data declarations necessary. You simply edit and run your Execs right within ISPF Edit. You can make revisions, issue the Edit SAVE command and immediately Execute another trial.


2.1 The Singleton SELECT Example _____________________________________________________________ /* REXX */ address rlx (1) "rlx select name, dbname, tsname", (2) "into :name, :dbname, :tsname", "from sysibm.systables", "where creator = 'ONETABLE'" If sqlcode = 0 (3) Do Say 'Tables owned by Authorization ID' creator Say 'name =' name 'dbname =' dbname 'tsname =' tsname (4) End 'rlx term' (5) _____________________________________________________________ Figure 2.1 This first example illustrates a REXX Exec that returns the Db2 table or view owned by a particular Db2 Authorization ID. The numbers in the figure's right margin correspond to the numbered, annotating paragraphs that follow: (1) ADDRESS RLX identifies the host command environment that receives and

Executes statements REXX does not recognize (known as host commands). The RLX host command environment provides fast branch entry for SQL/XML requests, Db2 commands and ISPF dialog services.

(2) The literal string 'RLX' identifies an embedded SQL statement just as EXEC SQL

does in a COBOL or PL/I program. The RLX literal prefix is required so the SQL SELECT statement will not be confused with the ISPF dialog service that is also named SELECT.

The INTO clause of this singleton SELECT statement includes references to REXX

'host' variables. RLX provides the same support for SQL host variables as do compiled languages like COBOL and PL/I. Host variables that appear embedded within SQL statements are prefixed by a colon, just as they are in COBOL and PL/I programs.

This first SQL request triggers RLX initialization. At this time RLX automatically

establishes a connection to the default Db2 subsystem and creates a thread for the RLX application plan. Section 2.3 describes how to specify the name of the target Db2 subsystem explicitly.


(3) The SQL Communications Area contains feedback from Db2 about your SQL statement's Execution. RLX returns the contents of the SQLCA to your Exec through a set of REXX variables which include the variable SQLCODE. The SQLCA variables are refreshed after each SQL statement Executes. Section 4.4 describes the other variables which comprise the SQLCA.

RLX also uses the SQLCODE variable to report error conditions it detects during its

own processing. This simplifies error checking since you need only inspect the SQLCODE variable to detect both SQL and RLX errors. In addition, RLX sets the value of the RC variable to provide its own summary status indication.

(4) RLX copies the values of the query result columns into the list of host variables

specified in the INTO clause of the singleton SELECT statement. Once populated, they can be referenced by name (without the colon prefix) in open code as in this REXX SAY statement.

(5) The RLX TERM service should always be called before your Exec completes its

processing. RLX TERM cleans up the RLX SQL environment and releases resources acquired on behalf of your Exec. If your Exec exits without issuing an RLX TERM request, an A03 system abend may result.

TIP: When developing Execs in the TSO environment, it's a good idea to set your TSO PROFILE to receive Write to Programmer messages at your terminal. This may be accomplished by entering the TSO command 'PROFILE WTPMSG'.

2.2 CURSOR based processing The singleton SELECT statement in the first example assumes (and requires) a single row query result. This next example illustrates RLX support for cursor based facilities with which multi-row query results can be processed one row at a time.

NOTE: RLX provides two additional statements in support of multi-row answer sets. The DECLARE REXXSTEM service lets you copy SQL result tables directly into REXX stemmed arrays, while the RLX DECLARE ISPFTABLE service loads SQL query results directly into ISPF tables. Both statements are described and illustrated in Chapter 3 of this Guide.

The TBLNAMES sample Exec illustrated in Figure 2.2 displays the set of Db2 tables and views owned by a particular authorization ID. For example, to display the names of the Db2 catalog tables, you invoke the TBLNAMES Exec and pass it 'SYSIBM' as a parameter. Specifically, TBLNAMES SYSIBM


________________________________________________________________

/* rexx */ address rlx arg creator (1) 'rlx declare table_names cursor for select name, type, dbname, tsname from sysibm.systables where creator = :creator' (2) 'rlx open table_names' (3) Say 'Tables owned by Authorization ID' creator 'rlx fetch table_names into :name, :type, :dbname, :tsname:ind1' (4) Do while sqlcode = 0 Say name type dbname tsname 'rlx fetch table_names into :name, :type, :dbname, :tsname:ind1' (4) End 'rlx close table_names' 'rlx term' exit rc

________________________________________________________________ Figure 2.2 The following numbered paragraphs annotate the correspondingly numbered statements in the Exec: (1) The Db2 authorization ID used to parameterize the SQL query is passed to the Exec

as an argument. The REXX ARG instruction populates the REXX variable named creator with the Db2 Authorization ID passed as a parameter.

(2) The REXX variable named creator is treated like a host variable when it appears

prefixed by a colon within a WHERE clause. (3) RLX accesses the current value of the REXX variable creator when the cursor is

opened. SQL OPEN uses the value of creator (the host variable in the DECLARE CURSOR'S WHERE clause) to materialize the SQL query result.

(4) the two FETCH statements copy result row columns into the list of host data and

indicator variables referenced in the INTO clause.

2.3 Explicitly naming the target Db2 subsystem This third example illustrates an Exec that writes SQL query results to an output dataset. To do so, the Exec issues TSO commands and ISPF dialog service requests. The Exec also explicitly sets the name of the target Db2 subsystem to which RLX should connect.


___________________________________________________________________________________ /* rexx */ address rlx rlxprof.dsn = 'Db2T' (1) 'display panel(mypanel)' (2) address TSO 'allocate f(output) da(output.dataset) shr' (3) 'rlx declare table_names cursor for select name, type, dbname, tsname from sysibm.systables where creator = :creator' 'rlx fetch table_names into :name, :type, :dbname, :tsname' Do while sqlcode = 0 queue name type dbname tsname address TSO 'EXECIO 1 DISKW output' (4) 'rlx fetch table_names into :name, :type, :dbname, :tsname' End 'rlx close table_names' address TSO 'free f(output)' (5) 'rlx term' exit rc

where (1) You can specify the name of the Db2 subsystem to which your application will

connect, although a default subsystem is defined when RLX is installed. RLX initialization occurs when your Exec requests its first RLX service. At that time, RLX attempts to access a set of REXX compound variables which share the stem RLXPROF. These RLX profile attributes may be set by simple REXX assignment. The Exec in this example identifies Db2T as the target Db2 subsystem by assigning the literal string 'Db2T' to the RLX profile variable RLXPROF.DSN.

NOTE: Db2 connections and application plans can be managed directly with the complete set of RRSAF or CAF primitives supplied with RLX/SQL..

(2) The host command environment identified by ADDRESS RLX provides branch

entry to all ISPF dialog services as well as to SQL statements and Db2 commands. Thus, the DISPLAY service can be invoked directly without the ADDRESS ISPExec prefix.

(3) The RLX host command environment does not support TSO command processors --

such as ALLOCATE and PRINTDS. These TSO command processors should be directed to the TSO host command environment for processing. Thus the ALLOCATE command is prefixed by ADDRESS TSO.

(4) Similarly, TSO/REXX commands -- such as EXECIO, HI and EXECUTIL -- should

also be directed to the TSO host command environment. Thus, the EXECIO command is also prefixed by ADDRESS TSO.

(5) Lastly, the ADDRESS TSO prefix directs the host command to FREE the Output file

to the TSO host command environment. ___________________________________________________________________________________

Figure 2.3


2.4 Running RLX Execs in Batch The last example in this chapter illustrates the JCL to run an RLX Exec natively in batch. The following job runs the TBLNAMES Exec that was described and illustrated in Section 2.2. _______________________________________________________________________

//......JOB

//STEP1 Exec PGM=IRXJCL,PARM='TBLNAMES SYSIBM TOKEN2 TOKEN3' (1) //STEPLIB DD DSN=RLX.VvRrMm.RLXLOAD,DISP=SHR (2) // DD DSN=DSNvrm.DSNLOAD,DISP=SHR //SYSEXEC DD DSN=RLX.VvRrMm.RLXEXEC,DISP=SHR (3) //ISPMLIB DD DSN=RLX.VvRrMm.RLXMLIB,DISP=SHR (4) //SYSTSPRT DD SYSOUT=* (5) where (1) IBM supplies the IRXJCL program to run REXX Execs in MVS batch. You pass

IRXJCL the name of the target Exec plus an optional, single argument through the PARM field of the JCL Exec statement. The lone argument can consist of several tokens as evidenced by 'SYSIBM TOKEN2 TOKEN3'.

(2) The STEPLIB dataset references the RLX system load library. The load library for

the Db2 subsystem to which RLX will connect also appears in the STEPLIB concatenation, following the RLX library.

(3) The SYSEXEC DD statement defines the REXX source library which contains the

TBLNAMES Exec. (4) The ISPMLIB DD statement defines the RLX message library from which RLX

reads the informational, warning and error messages it issues at run time. The RLX message library is maintained in an ISPF compatible format so it can be shared between ISPF and non-ISPF environments.

(5) The SYSTSPRT DD statement defines the print file to which REXX output is di-

rected. This includes output from the SAY statement as well as the text of messages. _______________________________________________________________________ Figure 2.4

NOTE: To run RLX in the TSO/ISPF environment (either batch or foreground) is somewhat more complex than the native batch example illustrated above. The RLX Installation Guide describes the dataset allocations required to run RLX in a way that exploits ISPF facilities, while Chapter 3.7 of the RLX for Db2 User Guide specifically addresses how to run RLX under batch ISPF. Lastly, member RLXBATCH of the RLXCNTL dataset contains a sample jobstream that runs RLX in the ISPF batch environment.

Chapter 3: RLX Extension Facilities 3-1

Chapter 3

RLX Extension Facilities

This chapter describes several RLX services that extend the functionality provided by embedded RLX SQL. For example, the RLX DECLARE REXXSTEM service lets you copy SQL query results directly into REXX stemmed variables, while RLX/ISPF (a separate program product) provides composite objects that combine common Db2 / ISPF operations into a single service. The DECLARE ISPFTABLE service enables you to load SQL query results directly into ISPF tables, while the RLX TBDISPL service provides the means to display and process those results on scrollable ISPF panels. The following sections describe each of these RLX extension services in turn.

3.1 The DECLARE REXXSTEM service The DECLARE REXXSTEM statement is patterned after the standard SQL DECLARE CURSOR statement but substitutes the keyword REXXSTEM for the keyword CURSOR. Its syntax is:

DECLARE label REXXSTEM for select statement The optional INTO clause (from the singleton SELECT statement) allows you to specify the names of REXX stemmed variables INTO which column values will be copied. From a SQL standpoint, these REXX stemmed variables function as an array of host data and indicator variables.


If you omit the INTO clause, RLX uses the names of columns specified in the SELECT clause as the names of the REXX stemmed variables, as in the following example: _____________________________________________________________________________________ /* REXX */ address RLX arg tbname 'RLX control limit 100' (1) "RLX declare csr rexxstem for (2) Select name, coltype from sysibm.syscolumns where tbname = :tbname" If sqlcode = 0 then /* Were any rows retrieved? */ Do say 'Column names and datatypes for Db2 table' table_name Do index = 1 to sqlcount (3) say name.index coltype.index (4) End End

where (1) The RLX CONTROL LIMIT service (described in Chapter 6.7 of the RLX for Db2

User Guide) lets you limit the number of rows processed by the DECLARE REXXSTEM service. In this example, the DECLARE REXXSTEM service is directed to stop processing after 100 rows of the answer set have been fetched and copied into stemmed variables.

(2) The RLX DECLARE REXXSTEM service materializes a query result and then

copies the answer set into REXX stemmed variables. In this case, RLX uses the names of the columns specified in the SELECT clause as the names of the REXX stemmed variables, because no INTO clause was specified.

(3) The DECLARE REXXSTEM service returns the number of rows of the answer set

that it fetched and copied. Your exec can inspect the REXX variable named SQLCOUNT for this value.

(4) Query results are returned in the stemmed variables 'tbname.' and 'coltype.'. RLX

appends numeric subscripts to the 'stem.' name to create an array of variables (for example tbname.1, tbname.2 etc). The SQL cursor associated with the REXXSTEM statement is automatically closed after the query result is fetched and copied.

___________________________________________________________________________________

Figure 3.1


3.2 Names of REXX stemmed variables into which RLX copies data

In the explicit form of the DECLARE REXXSTEM statement, REXX stem names are supplied (by the programmer) through the INTO clause. In its implicit form, the DECLARE REXXSTEM service derives the REXX stem names. In both cases, RLX appends numeric subscripts after the stem name to create arrays of variables that share the same stem (e.g. stem.1, stem.2, stem.3). These stemmed arrays serve as the host data and indicator variables into which the column values of the discrete result rows are copied. When RLX implicitly derives stemmed variable names, the name of the SQL result column becomes the name of the host data variable -- unless the SQL result column has no name. This can occur in the following circumstances:

SQL Built-in functions, e.g. AVG(COLUMN1)

Multi-term expressions, e.g. COLUMN_NAME + 10

literal constants, e.g. 10 or 'CONSTANT'

In these instances, RLX derives the name of a host data variable as follows: Each (D)ata (V)ariable becomes DVxxx where xxx is the ordinal number (1st, 2nd, 3rd, ...) of the SELECT list column for which RLX is deriving a default name. For example, if AVG(COLUMN3) is the 3rd column in the SELECT list, RLX uses DV3 as the name of the host data variable (and REXX stem). Should the SQL result column permit NULL values, RLX also creates an array of host indicator variables whose names follow a similar convention. Each indicator variable is named IVxxx where xxx corresponds to the ordinal number (1st, 2nd, 3rd, ...) of the SELECT list column that is associated with the indicator variable. Suppose, for example, the first column in the SELECT list permits NULLS. RLX will then create an indicator variable (and REXX stem) named IV1. As a further illustration of derived names, consider the following DECLARE REXXSTEM example:

_______________________________________

"RLX declare fruit_table rexxstem for

Select avg(apples), oranges + 10,

'peaches', pears

from fruit_table

_______________________________________


In this example, assume that each result column in the SELECT list -- except the literal constant 'peaches' -- can assume a value of NULL. In this case, RLX derives the names of data and indicator variables as if the following INTO clause were specified:

Into :DV1:IV1, :DV2:IV2, :DV3, :pears:IV4

(1) (2) (3) (4) (5) (6) (7)

where (1) The built in function avg(apples) is the first column in the SELECT list. It becomes

host data variable DV1. (2) The function avg(apples) may assume a value of NULL. As such, RLX creates a

host indicator variable named IV1 for this first SELECT list column . (3) The multi-term expression oranges + 10 is the second column in the SELECT list.

It becomes host data variable DV2. (4) Oranges + 10 may assume a value of NULL. As such, RLX creates an indicator

variable named IV2 for this second SELECT list column. (5) The constant peaches is the third column in the SELECT list. Thus, it becomes host

data variable DV3. (6) RLX uses the name of the query result column when it is non-blank. As such, the

host data variable created by RLX is named Pears. (7) The column Pears may assume a value of NULL. As such, RLX creates an

indicator variable named IND4 for this fourth SELECT list column.

3.3 Loading SQL query results directly into ISPF tables The DECLARE ISPFTABLE service lets you load SQL query results directly into temporary or permanent ISPF tables. This service combines the necessary SQL statements and ISPF dialog services into a single composite facility. Like the DECLARE REXXSTEM service, the DECLARE ISPFTABLE statement is patterned after the standard SQL DECLARE CURSOR statement. The syntax substitutes the keyword ISPFTABLE for the keyword CURSOR as follows:

DECLARE label ISPFTABLE for select statement

Chapter 42 of the RLX for Db2 User Guide fully describes the DECLARE ISPFTABLE service. Its optional INTO clause allows you to specify the names of host data and indicator variables INTO which column values will be retrieved. You can limit the number of rows which the DECLARE ISPFTABLE service will fetch and load via the RLX CONTROL LIMIT service.


NOTE: The limit check RLX performs is made on the number of rows loaded rather than the number of rows FETCHed.

The DECLARE ISPFTABLE service implicitly derives stem names for host data and indicator variables, as does the DECLARE REXXSTEM statement. The prefixes used by DECLARE ISPFTABLE to derive stem names are different from those used by the DECLARE REXXSTEM statement, to let you to distinguish the variables created by the two services. The DECLARE ISPFTABLE service uses the prefix MDV for Main Dialog Variables (rather than HV) and IDV for Indicator Dialog Variables (instead of IV). In addition, all stem names derived by DECLARE ISPFTABLE are 6 characters long with three digits for the ordinal suffix. (For example, MDV001, IDV001.)

3.4 The RLX TBDISPL Service Once the query result is loaded into an ISPF table, the RLX TBDISPL service allows you to display and process the SQL query result on a scrollable, ISPF table display panel. The RLX TBDISPL service dynamically creates a suitable panel and lets you scroll the display LEFT and RIGHT (should the width of the query result exceed the dimensions of the physical terminal). These extra functions are layered on top of the facilities provided by the ISPF TBDISPL service so calls to RLX TBDISPL return the same results as calls to ISPEXEC TBDISPL. Thus, you can use the ISPF Dialog Management Services documentation to design and code your dialogs. RLX TBDISPL's support for dynamic panel creation and horizontal scroll is transparent to your command procedure. Chapter 43 of the RLX for Db2 User Guide provides a complete discussion of the RLX TBDISPL service. Scrolling lets you move the viewable 'data window' up, down, left, and right across the data. UP / DOWN scrolling brings new rows into view. LEFT / RIGHT scrolling brings new columns into view. The headings scroll along with the data. RLX provides horizontal scroll support automatically when the width of SQL query result columns exceeds the width of the display. Figure 3.2 illustrates a reformulated version of the TBLNAMES exec that was first described in Section 2.2. The new exec uses RLX/ISPF extension facilities to extract Db2 data and display the query result on a scrollable ISPF panel.


_______________________________________________________________________ /* rexx */ address rlx arg creator 'rlx declare db2tbls ispftable for select name, type, dbname, tsname from sysibm.systables where creator = :creator' (1) If sqlcode = 0 then Do Do while rc = 0 (2) 'rlx tbdispl db2tbls panel(rlx)' (3) Do while ztdsels > 1 (4) /* Process the current row */ (5) "RLX tbdispl db2tbls" (6) End End End 'rlx term' exit rc

where (1) The RLX DECLARE ISPFTABLE statement functions as a single composite

service to create the ISPF table and load it with the SQL query result. (2) Continue to display and process the query result until the dialog user signals END or

RETURN. (3) The RLX TBDISPL service lets you display and process the SQL query result on a

scrollable ISPF panel -- without having to predefine a suitable ISPF TBDISPL type panel or provide logic to scroll the result horizontally. RLX TBDISPL lets the dialog user select one or more rows in a single interaction. This first RLX TBDISPL call retrieves the first row selected.

(4) Continue while there are pending selected rows. (5) Process the selected row. The updated values of dialog variables corresponding to

columns within the currently selected row are available to your dialog after each RLX TBDISPL call. The dialog variable RTDSEL contains whatever the user keyed into the row selection field associated with the currently retrieved row.

(6) This RLX TBDISPL statement, coded without a panel name and message ID, is used

to retrieve any selected rows pending. _______________________________________________________________________ Figure 3.2

Chapter 4: RLX Reference Topics 4-1

Chapter 4

RLX Reference Topics

4.1 RLX host variables RLX provides the same support for SQL host variables as do compiled host languages like COBOL or PL/I. In this scheme, host variables are the target for data fetched from Db2 and the source of values passed from REXX to Db2. When referenced within SQL statements, host variables should be prefixed by a colon, as in: :Data_variable:Indicator_variable

Such notation is valid only within SQL statements and must not be used in REXX open code. The first host identifier designates the data variable while the second identifier is its indicator variable. The data variable is considered to be NULL when its indicator variable is set to a negative value like -1. Conversely, when the indicator variable contains 0, the value of the corresponding data variable is considered significant (non-NULL). Db2 sets the indicator variable when data is fetched, while your application signals the null value when data is supplied to Db2 (through an INSERT or UPDATE statement.)


RLX, ISPF and REXX all maintain and share a common list of variables. Therefore, any host variables referenced in RLX SQL statements are automatically both REXX variables and ISPF dialog variables. The names of these variables do not change from one reference to the next although their values very well may. SQL host variables can be referenced in REXX open code and appear in ISPF dialog panel, message, and skeleton definitions. Consider the following flow of data from ISPF panel to REXX exec to Db2 table through the employee variable shared among ISPF, REXX and RLX. ________________________________________________________________ Employee ID ===>_employee + <--- (1) ISPF Dialog Panel If employee = z <--- (2) REXX symbolic variable 'RLX insert into employee_table values (:employee) <--- (3) SQL Host variable ________________________________________________________________ Figure 4.1

4.2 Host variable datatypes REXX supports character-string datatypes and character-string representations of numbers. Db2 supports many more datatypes than just NUM and CHAR so RLX automatically converts between Db2's internal format and the character string format supported by REXX. In addition to obtaining the datatypes of SQL host variables returned by Db2 (such as those referenced on a FETCH statement), RLX can often implicitly derive the datatypes of host input variables that supply values to Db2. This applies to host variables coded within an INSERT or UPDATE statement as well as host variables that parameterize WHERE clauses. Thus, you generally need not declare host variables as you must with compiled languages like COBOL. Such correct datatyping can enhance performance significantly by enabling Db2 to make use of indexes. RLX provides the VDEFINE service (described in Chapter 14.3 of the RLX for Db2 User Guide) for those cases in which the datatype of a host variable must be explicitly defined. For example, the RLX VDEFINE service must be issued for host variables that appear in SQL CALL statements as well as for host input variables that appear within SQL constructs like nested table expressions and CASE expressions. RLX returns the datatypes of the host input and output variables referenced in your exec's SQL statements through the SQL Descriptor Area (SQLDA ) described in the RLX User Guide and Reference.


4.3 Coding Long SQL Statements _____________________________________________ "RLX update employee_table (1) set first_name = :first_name, last_name = :last_name, dept = :dept, dept = 'Accounting', (2) phone = :phone", /* continued */ (3) "where employee = :employee and dept like :pattern"

_____________________________________________

Figure 4.2 SQL statements can be of indefinite length. However, REXX limits the length of literal strings to 250 characters. To overcome this restriction, you can break your SQL statement into two or more strings and use the REXX continuation operator to combine them as shown in Figure 4.2 where, (1) If your REXX source execs are maintained in variable blocked libraries, then your

statement string can span several lines without trailing quotes and REXX continuation characters. The trailing quote, or double quote, need only be coded on the last line -- as in (3).

(2) RLX is largely case insensitive. SQL statement strings are translated to uppercase

except embedded strings (like 'Accounting') which are coded within quotes. (3) The first string comprising the SQL statement ends with the closing double quote.

The comma continuation character signals REXX to continue the host command string on the next line

Sites which run versions of REXX prior to TSO/E Version 2.4 must deal with the additional restriction that REXX clauses may not exceed 500 characters in length. (TSO/E Version 2.4 relaxes this restriction). To overcome this length limitation, SQL statements longer than 500 characters can be assigned to as many REXX variables as necessary and then concatenated -- as illustrated in the following example: RLXSQL1 = 'DECLARE CURSOR1 CURSOR FOR' RLXSQL2 = 'SELECT * FROM RLX240.RLXNUM' RLXSQL3 = 'WHERE INTEGER BETWEEN :HIGH AND :LOW' 'RLX' RLXSQL1 RLXSQL2 RLXSQL3

NOTE: You can choose whatever names you wish for the REXX variables to which you assign portions of a SQL statement


4.4 RLX Feedback to your Execs RLX makes the contents of the SQL Communications Area (SQLCA) available to your exec through standard REXX variables. The variables which comprise the SQLCA (see Figure 4.4) are refreshed after each SQL statement executes.

NOTE: RLX calls the IBM routine DSNTIAR when it detects a runtime SQL error to format the SQLERRM field of the SQLCA into an intelligible error message. This formatted message is returned in REXX variables named SQLERRM1, SQLERRM2, SQLERRM3 and SQLERRM4.

___________________________________________________________ Variable Contents and purpose Name -------- ----------------------------------------------------------- SQLCODE The SQL return code 0 successful execution + Successful execution but with exception condition - Error condition SQLERRD3 number of rows affected by previous INSERT, DELETE, or UPDATE SQLERRD4 gives an estimate of the relative cost of a query Timerons is a short floating point value returned by Db2 that provides a rough relative estimate of the resources required to execute a query SQLERRM - the tokenized and unformatted error message returned by Db2 SQLERRM1 to SQLERRM4 These 4 variables contain the SQL Error Message field SQLERRM, as formatted by the DSNTIAR routine on 1 to 4 lines of 75 characters each. SQLWARN0 If blank, all other SQLWARNn variables are also blank. Otherwise set to 'W' and at least one other SQLWARNn variable is also 'W'. SQLWARN1 Set to 'W' if the value of a string column was truncated when it was stored into a host variable. SQLWARN2 Set by Db2 when at least one null value was eliminated from the argument set of a function.


SQLWARN3 Set to 'W' when the number of host variables specified in the SQL statement is not equal to the number of columns in the table or view being operated on by the statement. SQLWARN4 Set to 'W' if an UPDATE or DELETE statement does not include a WHERE clause SQLWARN5 Set to 'W' if the statement was not executed because it is a SQL/DS statement which is not valid in Db2. SQLWARN6 Set to 'W' if an adjustment was made to a DATE or TIMESTAMP value to correct an invalid date resulting from an arithmetic operation. SQLWARN7 Contains a W if one or more nonzero digits were eliminated from the fractional part of a number used as the operand of a decimal multiply or divide operation SQLWARN8 Contains a W if a character that could not be converted was replaced with a substitute character SQLWARN9 Contains a W if arithmetic exceptions were ignored during COUNT DISTINCT processing SQLWARNA Contains a W if at least one character field of the SQLCA or the SQLDA names or labels is invalid due to a character conversion error SQLSTATE Contains a return code for the outcome of the most recent execution of an SQL statement

_____________________________________________________________________________ Figure 4.4


4.4.1 Unique RLX Feedback RLX provides some unique feedback of its own. For example, both the DECLARE ISPFTABLE and DECLARE REXXSTEM services return the number of rows they process in the REXX variable named SQLCOUNT. In addition, the following SQLCODE values signify conditions unique to RLX. They are well beyond the range of values defined by IBM. ______________________________________________________________________ SQLCODE Significance Value -------- ------------------------------------------------------ -100000 Syntactic error detected by the RLX semantic parser -100001 Invalid value for a REXX variable given its datatype. For example - entering ABCD for a numeric datatype -100002 RLX detected a logic error. For example, an OPEN, FETCH, or CLOSE statement referenced a cursor name which was never DECLAREd. +100001 Limit exceeded on the number of SQL query result rows to be loaded into an ISPF table by the DECLARE REXXSTEM and DECLARE ISPFTABLE services (see the CONTROL LIMIT service description in the RLX Reference)

______________________________________________________________________

Figure 4.5


4.5 The DESCRIBE service and the SQL Descriptor Area (SQLDA)

RLX may create one or more SQL descriptor areas (SQLDAs) as part of preparing a SQL statement for execution. These SQLDAs contain information about the host variables (both input and output) associated with a SQL statement. A subsequent RLX DESCRIBE request maps these SQL descriptor area(s) into a set of REXX compound variables which your exec can reference. > An output SQLDA describes a statement's query result columns -- in other

words, the values received from Db2. RLX creates an output SQLDA for the following SQL statement types: singleton SELECT, DECLARE CURSOR, DECLARE REXXSTEM and DECLARE ISPFTABLE.

> An input SQLDA describes the host variables that supply values to Db2. These

include the host varibles that appear in a WHERE clause to parameterize a statement, as well as the host variables that appear in a SQL INSERT or UPDATE statement. In addition, statements like SET CURRENT SQLID can also obtain values from a host variable to present to Db2. Lastly, note that the singleton SELECT, DECLARE CURSOR, DECLARE REXXSTEM and DECLARE ISPFTABLE statements may also have an input SQLDA if the WHERE clause is parameterized by host variables.

The RLX DESCRIBE service maps SQLDA data into a set of REXX variables whose names are the same as the SQLDA fields described in the IBM SQL reference. RLX automatically translates binary values into numeric character strings. The format of the DESCRIBE service is: RLX DESCRIBE <statement> where <statement> refers to any one of the following: (1) The name of a declared CURSOR as in the following example: 'RLX declare cursor_name.cursor for select ...' 'rlx describe cursor_name'

Here 'cursor_name' references the name of the declared cursor.


(2) The name of a declared ISPFTABLE as in the following example: 'RLX declare ispfqry ispftable for ...' select ...' 'rlx describe ispfqry'

Here the name 'ispfqry' references the name of the declared ispf table (3) The name of a prepared statement (using RxSQL syntax) as in the following

example: 'rxsql prep query_result', 'select * from sysibm.syscolumns where tbname = 'SYSTABLES' 'rxsql describe query_result'

Here 'query_result' _references the prepared statement's label. (4) The value of the REXX variable 'RLXSTNM'. RLX assigns a unique internal

label to each statement during its preparation and then updates the value of RLXSTNM with this label each time RLX executes the statement. The following example illustrates the use of the RLXSTNM variable.

'rlx insert into Db2_table .... 'rlx describe' rlxstnm

One word of caution concerning the RLXSTNM variable. It's contents is

volatile in that its value is updated after each RLX statement executes. Therefore, you may wish to assign RLXSTNM to another REXX variable to preserve its value as in the following example:

'rlx insert into Db2_table .... 'rlx describe' rlxstnm insert_statement_label = rlxstnm

Figure 4.6 illustrates how to DESCRIBE the columns and host variables into which query results are returned.

NOTE: The RMVDDESC sample exec (in the RLXEXEC dataset) illustrates support for both input and output SQLDA's.


_______________________________________________________________________ /* rexx */ address rlx 'rlx declare table_names cursor for (1) select name, type, dbname, tsname from sysibm.systables where creator = :creator' 'rlx describe table_names' (2) say 'Count of query result columns =' sqln (3) Do index = 1 to sqld (4) say 'query column name =' sqlname.index (5) say 'query column datatype =' sqltype.index (6) say 'Does column allow nulls' sqlnulls.index (7) say 'query column length =' sqllen.index (8) End 'rlx term' return

where (1) This first SQL statement declares the cursor named 'table_names'. (2) The RLX DESCRIBE service creates (and assigns values to) a series of REXX

variables which describe the query's result columns and host output variables. (3) The REXX variable SQLD returns the number of query result columns

described in the SQLDA array. (In this example, the count is 4). (4) The remaining SQLDA variables are compound symbols referenced by a stem

name and subscript value. The number of elements in these stemmed arrays is returned as a printable integer in SQLD. Its value governs the number of iterations through the DO loop.

(5) RLX returns the set of column names into the array of variables which share the

stem 'SQLNAME' (6) RLX returns the set of column datatypes into the array of variables which share

the stem 'SQLTYPE'. (7) The SQLNULLS compound variable is set to 'Y' if null values are allowed for

this column. Otherwise, SQLNULLS is set to 'N'. (8) RLX returns the set of column lengths into the array of variables which share the

stem 'SQLLEN'. In the case of decimal datatypes, your exec should reference the compound variables SQLPRCSN and SQLSCALE respectively to obtain discrete values for precision and scale.

________________________________________________________________________ Figure 4.6 Illustration of the DESCRIBE service for output SQLDA variables


4.5.1 The DESCRIBE service for input SQLDA Variables Figure 4.7 illustrates how to DESCRIBE the input columns and host variables of a SQL INSERT statement that supply values to Db2. The REXX variables which describe input columns and their corresponding host variables are all named SQIxxx to distinguish them from the SQLxxx variables which describe output. _______________________________________________________________________ /* rexx */ address rlx 'rlx insert into datatype_table (integer, date, time, timestamp, float) values (:integer:iv1, :date:iv2, :time:iv3, :timestmp:iv4, :float:iv5)' 'rlx describe' rlxstnm (1) say 'Count of columns being inserted =' sqid (2) Do index = 1 to sqid (3) say 'Name of column associated with host input variable =' sqiname.index (4) say 'Input host variable datatype =' sqitype.index (5) say 'Does column allow nulls' sqinulls.index (6) say 'Input host variable length =' sqilen.index (7) End 'rlx term' exit rc

_______________________________________________________________________ Figure 4.7 Illustration of the DESCRIBE service for input SQLDA variables The numbers in the figure's right margin correspond to the numbered, annotating para-graphs that follow: (1) The REXX variable RLXSTNM contains the internal label of the SQL INSERT

statement just processed. The RLX DESCRIBE service creates (and assigns values to) a different set of REXX variables whose names start with SQI rather than SQL. The SQIxxx variables describe the columns of the INSERT statement and their corresponding host input variables.

(2) The REXX variable SQID contains the number of input columns (and input host

variables) described by the input SQLDA array. (In this example, the count is 5).

(3) The printable integer value returned in SQID governs the number of iterations

through the DO loop. (4) RLX returns the set of input column names into the array of variables which

share the stem 'SQINAME'


(5) RLX returns the set of input column (and host input variable) datatypes into the array of variables which share the stem 'SQITYPE'.

(6) The SQINULLS compound variable is set to 'Y' if null values are allowed for

this input column. Otherwise, SQINULLS is set to 'N'. (7) RLX returns the set of input column (and host input variable) lengths into the

array of variables which share the stem 'SQILEN'. In the case of decimal datatypes, your exec should reference the compound variables SQIPRCSN and SQISCALE respectively to obtain discrete values for precision and scale.

4.6 The RLX IFI Interface

RLX support for the Db2 Instrumentation Facility Interface (IFI) enables you to submit commands to Db2 and receive responses from the command. RLX support for IFI is illustrated in the following example: _____________________________________________________________ /* Rexx */ address RLX /* Issue Db2 command */ "ifi -dis thread(*)" (1) /* Process Output from the command */ Say 'IFCARC1 = ' ifcarc1 '- IFI return code' (2) Say 'IFCARC2 = ' ifcarc2 '- IFI reason code' (3) Say 'IFCABM = ' ifcabm '- Bytes moved into output area' (4) Say 'IFCABNM = ' ifcabnm '- Bytes not moved into output area' (5) say ' ' Do index = 1 to ificmd.0 (6) Say ificmd.index (7) End 'rlx term' Return

_____________________________________________________________ Figure 4.8 The numbers in the figure's right margin correspond to the numbered, annotating para-graphs that follow: (1) The IFI keyword signals RLX to route the command string to the Db2

Instrumentation Facility Interface. Thus the Db2 command '-DIS thread(*)' is routed to the Db2 subsystem to which the currently active plan and thread are connected.


(2) Once the Db2 command executes, RLX returns control and results to your exec in a set of REXX variables named IFxxxx.

NOTE: RLX translates all IFI binary values to character

representations of numeric values before setting the values of these REXX variables.

The first variable, IFCARC1 contains the return code from the Db2 command.

A value of zero indicates a successful call. (3) IFCARC2 contains the reason code from the IFI call where a value of zero

indicates a successful call. (4) IFICABM contains the number of bytes moved by IFI into the return area. RLX

in turn maps this data into an array of REXX stemmed variables described in (6).

(5) IFICABNM represents the number of bytes of the command output that did not

fit in the return area and still remain in the buffer. (6) The output data returned by the Db2 command is mapped into an array of

REXX compound symbols which share the stem 'IFICMD'. The number of elements in the IFICMD array is returned as a printable integer in IFICMD.0. In this example, the value of IFICMD.0 governs the number of iterations through the DO loop.

(7) The exec processes the response returned by the Db2 command -DISPLAY

THREAD(*) one line at a time by referencing successive elements of the IFICMD array.

I - 1

Index A A03 system abend 2-3 AcceleREXX 1-3, 1-4 ADDRESS ISPExec 2-5 address RLX 4-11 ADDRESS RLX 2-2, 2-5 ADDRESS TSO 2-5 ALLOCATE 2-5 application development system 1-5 ARG instruction 2-4 argument set 4-4 arithmetic exceptions 4-5 arithmetic operation 4-5 array of host indicator variables 3-3 array of variables 3-2 arrays of variables 3-3 authorization mechanisms 1-6 Automatic conversion 1-6 B Batch 2-6 binary values 4-7 braces vi brackets vi branch entry 2-2, 2-5 buffer 4-12 built in function 3-4 C CAF primitives 2-5 Call Attach Facility 1-4 case insensitive 4-3 CHAR 4-2 character conversion error 4-5 character representations of numeric values 4-12 character-string 4-2 CLISTs 1-3 COBOL 2-2, 4-1, 4-2 colon 2-2, 2-4

comma continuation character 4-3 common list of variables 4-2 compiled languages 4-2 compiled plans 1-2, 1-5 composite functions 1-4 composite objects 1-2, 3-1 composite service 3-6 concatenated 4-3 conditions unique to RLX 4-6 constant 3-4 context sensitive help 1-6 continuation character 4-3 continuation operator 4-3 control interval processing 1-3 CONTROL LIMIT 3-4 COUNT DISTINCT 4-5 CURSOR 2-3, 3-4 D data declarations 2-1 data variable 4-1 data window 3-5 datatypes 4-2 DATE 4-5 Db2 attachment facility 1-2 Db2 Authorization ID 2-2 Db2 Authorization ID passed as a parameter 2-4 Db2 catalog tables 2-3 Db2 command 4-12 Db2 subsystem 2-1, 2-4 Db2/ISPF 1-2, 1-4 decimal datatypes 4-9, 4-11 DECLARE ISPFTABLE 3-6 DECLARE CURSOR 3-1, 4-7 DECLARE ISPFTABLE 1-2, 2-3, 3-1, 3-4, 3-5, 4-7 DECLARE REXXSTEM 1-2, 2-3, 3-1, 3-2, 3-3, 3-5, 4-7 default Db2 subsystem 2-2 default name 3-3 default subsystem 2-5 DELETE 4-4 DESCRIBE 4-7, 4-8, 4-9, 4-10

I - 2 RLX Getting Started Guide

diagnostics 1-6 dialog variables 4-2 DIS 4-11 discrete result rows 3-3 DISPLAY 2-5 DISPLAY THREAD(*) 4-12 DO loop 4-10 Documentation Coordinator iv double quote 4-3 DOWN 3-5 DSNTIAR 4-4 DVxxx 3-3 dynamic panel creation 3-5 E ellipsis vi embedded RLX SQL 3-1 embedded strings 4-3 END 3-6 Error condition 4-4 error conditions 2-3 error message 4-4 error messages 2-6 example of Multi/CAF usage 1-4 Examples of REXX VSAM usage 1-4 examples of RLX usage 1-4 Examples of RLX/ISPF usage 1-4 ExecIO 2-5 ExecUTIL 2-5 explicit form 3-3 extension facilities 3-5 F feedback 4-6 feedback from Db2 2-3 fetch 3-4 FETCH 2-4, 4-2 flow of data 4-2 FREE 2-5 H headings 3-5 horizontal scroll 3-5 host command environment 2-2 host command string 4-3 host commands 2-2 host data variable 3-3, 3-4 host indicator variable 3-4 host variable 2-4

host variables 4-1, 4-2, 4-7, 4-8 Host variables 2-2 I IBM SQL reference 4-7 IFCARC1 4-12 IFCARC2 4-12 IFI 4-11 IFI binary values 4-12 IFI keyword 4-11 IFICABM 4-12 IFICABNM 4-12 IFICMD 4-12 IFxxxx 4-12 illustration of derived names 3-3 implicit form 3-3 indexes 4-2 indicator variable 3-3, 4-1 indicator variables 2-4, 3-1, 3-3 input columns 4-10 input host variables 4-10 input SQLDA 4-7 input SQLDA array 4-10 input variables 4-2 INSERT 4-1, 4-2, 4-4, 4-7, 4-10 Instrumentation Facility Interface (IFI) 4-11 internal label 4-8, 4-10 INTO 2-4 INTO clause 2-2, 2-3, 3-1, 3-2, 3-3, 3-4 invalid date 4-5 IRXJCL 2-6 ISPEXEC 3-5 ISPF 1-3 ISPF dialog framework 1-5 ISPF Dialog Management Services 1-6, 3-5 ISPF dialog services 3-4 ISPF tables 2-3 ISPF TBDISPL 3-6 ISPFTABLE 3-4, 3-5, 4-6, 4-8 ISPMLIB 2-6 iterations 4-12 IVxxx 3-3 J JCL 2-6

I - 3

L LEFT 3-5 length limitation 4-3 length of literal strings 4-3 limit check 3-5 LIMIT service 3-4 literal constants 3-3 load 3-4 logic error 4-6 M multiple threads 1-2 multi-row query results 2-3 multi-term expression 3-4 Multi-term expressions 3-3 MVS system services 1-3 N NetView 1-3 notational conventions vi NULL 4-1 NULL values 3-3 NUM 4-2 number of iterations 4-10, 4-12 number of rows 3-2 numbers 4-2 numeric character strings 4-7 numeric subscripts 3-2, 3-3 O ordinal suffix 3-5 output variables 4-2 P PDF Edit 2-1 pending 3-6 performance 4-2 permanent ISPF tables 3-4 physical terminal 3-5 PL/1 2-2, 4-1 precision 4-9, 4-11 preferences 1-6 prefix MDV 3-5 prefixes 3-5 prepare 4-8

print file 2-6 printable integer 4-12 PRINTDS 2-5 PROFILE WTPMSG 2-3 Q QMF 1-2, 1-5 R reason code 4-12 referential integrity 1-5 Related Publications v remote servers 1-5 resources required 4-4 result column 3-4 RETURN 3-6 return code 4-12 REXX compound symbols 4-12 REXX compound variables 2-5 REXX continuation characters 4-3 REXX continuation operator 4-3 REXX function packages 1-3 REXX Language Extensions 1-2 REXX SAY statement 2-3 REXX Software Development Kit (SDK) 1-4 REXX source library 2-6 REXX stem names 3-3 REXX stemmed arrays 1-2, 2-3 REXX stemmed variables 3-1, 3-2 REXX/370 Compiler 1-3 REXXSTEM 3-2, 3-5, 4-6 REXXSTEM example 3-3 RIGHT 3-5 RLX application plan 2-2 RLX CONTROL LIMIT 3-2 RLX EXEC library 1-4 RLX Feedback 4-6 RLX host command environment 2-2, 2-5 RLX initialization 2-2 RLX literal prefix 2-2 RLX message library 2-6 RLX Product Family 1-2 RLX product library 1-3 RLX profile attributes 2-5 RLX semantic parser 4-6 RLX system load library 2-6 RLX TBDISPL 3-1, 3-5, 3-6 RLX TERM 2-3 RLX/CAF 1-2, 1-4 RLX/Compile 1-2, 1-3, 1-4, 1-5 RLX/ISPF 1-2, 3-5


RLX/Net 1-3, 1-4 RLX/SDK 1-3 RLX/SQL 1-2 RLX/Translate 1-3, 1-4 RLX/TSO 1-2 RLX/VSAM 1-3 RLXPROF 2-5 RLXPROF.DSN 2-5 RLXSTNM 4-8, 4-10 row selection field 3-6 rows FETCHed 3-5 rows loaded 3-5 RTDSEL 3-6 run time 2-6 runtime SQL error 4-4 RXSDESC 4-8 RxSQL 4-8 RXSQL 1-4 S SAY statement 2-6 scroll 3-5 scrollable ISPF table 1-2 Scrolling 3-5 SELECT 3-2, 4-7 SELECT list column 3-4 SELECT statement 2-2 selected rows pending 3-6 SET CURRENT SQLID 4-7 singleton SELECT statement 2-3, 3-1 Software Development Kit 1-1 Software Development Kit (SDK) 1-3 SPUFI 1-2, 1-5 SQILEN 4-11 SQIN 4-10 SQINAME 4-10 SQITYPE 4-11 SQL 1-5, 2-1 SQL query result 3-6 SQL Built-in functions 3-3 SQL Communications Area 2-3 SQL Communications Area (SQLCA) 4-4 SQL DECLARE CURSOR 3-4 SQL Descriptor Area 4-2 SQL Descriptor Area SQLDA 4-7 SQL descriptor areas 4-7 SQL query result 2-4 SQL query results 3-4 SQL result column 3-3 SQL result tables 1-2 SQL SELECT statement 2-2 SQL special registers 1-5 SQL/DS 1-4, 4-5 SQLCA 2-3

SQLCODE 2-3, 4-4 SQLCOUNT 3-2, 4-6 SQLDA 4-7, 4-8, 4-9, 4-10 SQLERRD3 4-4 SQLERRD4 4-4 SQLERRM 4-4 SQLERRM1 to SQLERRM4 4-4 SQLLEN 4-9 SQLN 4-9 SQLNAME 4-9 SQLSTATE 4-5 SQLTYPE 4-9 SQLWARN0 4-4 SQLWARN1 4-4 SQLWARN2 4-4 SQLWARN3 4-4 SQLWARN4 4-5 SQLWARN5 4-5 SQLWARN6 4-5 SQLWARN7 4-5 SQLWARN8 4-5 SQLWARN9 4-5 SQLWARNA 4-5 statement length 4-3 statement string 4-3 static Db2 application plans 1-3 static SQL applications 1-2, 1-5 status indication 2-3 stem names 3-5 stemmed arrays 3-3, 4-9 stemmed variables 4-12 STEPLIB 2-6 stop processing 3-2 subscript value 4-9 substitute character 4-5 successful execution 4-4 Syntactic error 4-6 SYSEXEC 2-6 SYSIBM 2-3 SYSTSPRT 2-6 T target Db2 subsystem 2-2 TBDISPL 1-2, 3-5, 3-6 TBLNAMES Exec 2-6 TBLNAMES sample Exec 2-3 thread 2-2 Timerons 4-4 TIMESTAMP 4-5 tokens 2-6 trailing quotes 4-3 TSO CLISTs 1-3 TSO command processors 2-5 TSO host command environment 2-5

I - 5

TSO PROFILE 2-3 TSO/E 1-2 TSO/E Version 2.4 4-3 TSO/REXX commands 2-5 U unauthorized access 1-2, 1-5 unformatted error message 4-4 UP 3-5 UPDATE 4-1, 4-2, 4-4, 4-7 updated values 3-6 V variable blocked libraries 4-3 variables 4-2 variables that parameterize 4-2 VSAM 1-3 VSAM 1-1 W WHERE 2-4, 4-2, 4-7 WHERE clause 2-4 WHERE clause is parameterized by host variables 4-7 width of SQL query result 3-5


Reader Comment Form _____________________________________________________________________________ Manual: RLX for Db2 Getting Started Edition: Version 9.1.7 - January 2018 _____________________________________________________________________________ Please assist us in improving this manual and in developing future enhancements to this product. We would appreciate your comments about the content and organization of this manual and the product it documents. Please refer to specific page numbers when applicable. Please forward your comments to us on this Reader's Comment Form with the understanding that all comments become the property of Relational Architects International. We may use or distribute whatever information you supply in any way we believe appropriate without incurring any obligation to you. Outside the United States, your local representative of Relational Architects product will be glad to forward this form to us. Name _______________________________ Company _____________________________ Title _______________________________ Address _____________________________ Department _______________________________ City _____________________________ Telephone _______________________________ State _____________ Zip ________ - - - - - - - - - - - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --

Comments:

Documents

RLX for Db2