IBM SC34-5764-01 PULL

PULL

Purpose

 PULL

template_list

; 

PULL reads a string from the program stack. If the program stack is empty, PULLthen tries reading a line

from the current terminal input device. It is just a short form of the instruction:

 PARSE UPPER PULL

template_list

; 

The current head-of-queue is read as one string. Without a template_list specified, no further action is

taken (and the string is thus effectively discarded). If specified, a template_list is usually a single template,

which is a list of symbols separated by blanks or patterns or both. (The template_list can be several

templates separated by commas, but PULL parses only one source string; if you specify several

comma-separated templates, variables in templates other than the first one are assigned the null string.)

The string is translated to uppercase (that is, lowercase a–zto uppercase A–Z) and then parsed into

variables according to the rules described in the section on parsing (page 203). Use the PARSE PULL

instruction if you do not desire uppercase translation.

Notes:

1. The REXX/CICS implementation of the external data queue is the program stack. The language

processor reads a line from the program stack. If the program stack is empty, a terminal read occurs.

The program stack for you is in an RLS queue named \SYSTEM\rexxtnum\*PROGSTACK* where

rexxtrnum is an internal REXX task number.

2. If the PULL causes a read from the terminal, the variable PULLKEY is set upon completion of the

PULL command. It will contain the name of the aid key pressed in response to the PULL command (for

example: ENTER, PFKEY 1, PAKEY 1, MSR, PEN, or CLEAR).

For information on named queues, see the REXX List System LPULL command in section “LPULL” on

page 275.

Example:

Say 'Do you want to erase the file? Answer Yes or No:'

Pull answer .

if answer='NO' then say 'The file will not be erased.'

Here the dummy placeholder, a period (.), is used on the template to isolate the first word the user enters.

If the external data queue is empty, a console read is issued and the program pauses, if necessary,until a

line is complete.

The QUEUED built-in function (see page 190) returns the number of lines currently in the program stack.

PULL

158 CICS TS for VSE/ESA: REXX Guide

Contents

Main Page Page Page Contents Part 1. User's Guide..............................1 iv Part 2. Reference ..............................101 vi Page viii Page x Page xii Page xiv Part 3. Appendixes .............................377 xvi Page Page Preface What this book is about Who this book is for What you need to know to understand this book Prerequisites Page Page Page Chapter 1. Introduction Components of REXX 4 Chapter 2. Writing and Running a REXX Program What you need to run a REXX Program? What is a REXX Program? Syntax of REXX Instructions The Format of REXX Instructions 6 The Letter Case of REXX Instructions Using Quotation Marks in an Instruction Ending an instruction Continuing an instruction Continuing a literal string without adding a space 8 Types of REXX Clauses Keyword Instructions Assignment Label Null Clause Programs Using Double-Byte Character Set Names Typing in a Program Running a Program Interpreting Error Messages 12 How to Prevent Translation to Uppercase Characters within a program Characters Input to a program Exercises - Running and Modifying the Example Programs 14 Passing Information to a program Getting Information from the Program Stack or Terminal Input Device Specifying Values When Calling a program Specifying Too Few Values Specifying Too Many Values Preventing Translation of Input to Uppercase Exercises - Using the ARG Instruction 16 Passing Arguments Using the CALL Instruction or a REXX Function Call Page Chapter 3. Using Variables and Expressions Program Variables Using Variables Variable Names Variable Values Exercises - Identifying Valid Variable Names 20 Using Expressions Arithmetic Operators Division Order of Evaluation 22 Using Arithmetic Expressions ExercisesCalculating Arithmetic Expressions Comparison Operators The Strictly Equal and Equal Operators Using Comparison Expressions 24 Exercises - Using Comparison Expressions Logical (Boolean) Operators Using Logical Expressions 26 Exercises - Using Logical Expressions Concatenation Operators Using Concatenation Operators Priority of Operators 28 Exercises - Priority of Operators Tracing Expressions with the TRACE Instruction Tracing Operations Tracing Results Exercises - Using the TRACE Instruction 30 When you run this program, it produces: Page Chapter 4. Controlling the Flow within a program Conditional, Looping, and Interrupt Instructions Using Conditional Instructions IF...THEN...ELSE Instructions instruction instruction Nested IF...THEN...ELSE Instructions 34 Page Page SELECT WHEN...OTHERWISE...END Instruction Exercises - Using SELECT WHEN...OTHERWISE...END 38 Using Looping Instructions Repetitive Loops Infinite Loops DO FOREVER Loops 40 LEAVE Instruction This example results in a list of numbers from 1 to 10 with the exception of number 8. ITERATE Instruction Exercises - Using Loops Conditional Loops 42 DO WHILE Loops instruction(s) DO WHILE END Exercise - Using a DO WHILE Loop DO UNTIL Loops DO UNTIL loops in a flowchart appear as follows: 44 DO UNTIL instruction(s) Exercise - Using a DO UNTIL Loop ANSWER Combining Types of Loops 46 The result of this example is as follows: Nested DO Loops Exercises - Combining Loops Using Interrupt Instructions EXIT Instruction 48 CALL and RETURN Instructions SIGNAL Instruction Chapter 5. Using Functions What is a Function? Example of a Function Built-In Functions 52 Arithmetic Functions Comparison Functions Conversion Functions Formatting Functions String Manipulating Functions 54 Miscellaneous Functions Testing Input with Built-In Functions Exercise - Writing a program with Built-In Functions 56 Chapter 6. Writing Subroutines and Functions What are Subroutines and Functions? When to Write Subroutines Rather Than Functions Writing Subroutines and Functions Page When to Use Internal Versus External Subroutines or Functions Passing Information Page 62 The next two examples are the same, except they use functions rather than subroutines. The next example is the same except PROCEDURE EXPOSE is in a function instead of a subroutine. For more information about the PROCEDURE instruction, see section PROCEDURE on page 155. Passing Information by Using Arguments 64 Page Receiving Information from a Subroutine or Function Exercise - Writing an Internal and an External Subroutine Exercise - Writing a Function 68 Page Subroutines and FunctionsSimilarities and Differences The following tables highlight similarities and differences between subroutines and functions: 70 Chapter 7. Manipulating Data Using Compound Variables and Stems What Is a Compound Variable? Using Stems Exercises - Using Compound Variables and Stems 72 Parsing Data Parsing Instructions PULL Instruction ARG Instruction PARSE VALUE ... WITH Instruction 74 PARSE VAR Instruction More about Parsing into Words Parsing with Patterns String Variable 76 Number Page Parsing Multiple Strings as Arguments Exercise - Practice with Parsing 78 Page 80 Chapter 8. Using Commands from a program Types of Commands Using Quotations Marks in Commands Using Variables in Commands Calling Another REXX Program as a Command Calling Another Program with the EXEC Command 82 Issuing Commands from a program What is a Host Command Environment? How Is a Command Passed to the Host Environment? Changing the Host Command Environment Determining the Active Host Command Environment Using Commands from a Program Page Chapter 9. Diagnosing Problems within a program Debugging Programs Tracing Commands with the TRACE Instruction TRACE C TRACE E Tracing with the Interactive Debug Facility 86 Starting Interactive Debug Options within Interactive Debug Diagnosing Problems within a Program Saving Interactive TRACE Output Diagnosing Problems within a Program Page Chapter 10. Programming Style and Techniques Consider the Data Test Yourself... Answer: Happy Hour 90 Page Good job! Now, take a while to put your new skills into action, or continue reading. Designing a Program 92 Methods for Designing Loops The Conclusion What Do We Have So Far? Stepwise Refinement: An Example 94 Reconsider the Data Correcting Your Program Modifying Your Program Tracing Your Program Coding Style 96 Page 98 Page Page Page Page Chapter 11. Introduction Who Should Read This Reference How to Use This Reference Overview of Product Features SAA Level 2 REXX Language Support Under REXX/CICS 104 Support for the Interpretive Execution of REXX Execs CICS-Based Text Editor for REXX Execs and Data Dynamic Support for EXEC CICS Commands REXX Interface to CEDA and CEMT Transaction Programs High-level Client/Server Support Support for Commands Written in REXX Command Definition of REXX Commands SQL Interface Programming Considerations 106 Embedding SQL statments How to Read the Syntax Diagrams Page Page Chapter 12. REXX General Concepts Structure and General Syntax Characters Comments 110 Tokens 112 Page Implied Semicolons 114 Continuations Expressions and Operators Expressions Operators String Concatenation Arithmetic 116 Comparison Logical (Boolean) Parentheses and Operator Precedence 118 Page Clauses and Instructions Null Clauses 120 Labels Instructions Assignments and Symbols Constant Symbols Simple Symbols Compound Symbols 122 Stems Commands to External Environments Environment 124 Commands Basic Structure of REXX Running Under CICS REXX Exec Invocation Where Execs Execute Locating and Loading Execs 126 Editing Execs Page Page Pseudo-conversational Transaction Support Interfaces to Other Programming Languages DBCS Support Miscellaneous Features Page Chapter 13. Keyword Instructions ADDRESS ADDRESS 132 Page ARG ARG 134 CALL 136 Page DO Simple DO Group 138 Repetitive DO Loops Conditional Phrases (WHILE and UNTIL) 140 Note: Using the LEAVE or ITERATEinstructions can also modify the execution of repetitive loops. DROP DROP 142 EXIT EXIT IF IF 144 INTERPRET INTERPRET 146 ITERATE ITERATE LEAVE LEAVE 148 NOP NOP NUMERIC NUMERIC 150 OPTIONS OPTIONS PARSE PARSE 152 PARSE Page PROCEDURE 156 Page PULL PULL 158 PUSH PUSH QUEUE QUEUE 160 RETURN RETURN SAY SAY 162 SELECT SELECT SIGNAL SIGNAL 164 SIGNAL TRACE Alphabetic Character (Word) Options 166 Prefix Options Numeric Options A Typical Example 168 Format of TRACE Output Page UPPER UPPER 170 Chapter 14. Functions Syntax Functions and Subroutines Search Order 172 Errors During Execution Built-in Functions 174 ABBREV (Abbreviation) ABS (Absolute Value) ADDRESS ARG (Argument) BITAND (Bit by Bit AND) 176 BITOR (Bit by Bit OR) BITXOR (Bit by Bit Exclusive OR) B2X (Binary to Hexadecimal) CENTER/CENTRE COMPARE 178 CONDITION COPIES C2D (Character to Decimal) C2X (Character to Hexadecimal) DATATYPE 180 DATE 182 DBCS (Double-Byte Character Set Functions) DELSTR (Delete String) DELWORD (Delete Word) DIGITS D2C (Decimal to Character) D2X (Decimal to Hexadecimal) ERRORTEXT 184 EXTERNALS FIND FORM FORMAT FUZZ 186 INDEX INSERT JUSTIFY LASTPOS (Last Position) LEFT 188 MAX (Maximum) LENGTH MIN (Minimum) OVERLAY POS (Position) QUEUED RANDOM 190 REVERSE RIGHT SIGN SOURCELINE SPACE STORAGE STRIP 192 SUBSTR (Substring) SUBWORD SYMBOL TIME 194 TRACE TRANSLATE TRUNC (Truncate) USERID VALUE 196 VERIFY WORD WORDINDEX WORDLENGTH 198 WORDPOS (Word Position) WORDS X2B (Hexadecimal to Binary) X2C (Hexadecimal to Character) X2D (Hexadecimal to Decimal) External Functions Provided in REXX/CICS STORAGE 200 SYSSBA Page Chapter 15. Parsing General Description Simple Templates for Parsing into Words The Period as a Placeholder 204 Templates Containing String Patterns Templates Containing Positional (Numeric) Patterns 206 Page Combining Patterns and Parsing Into Words 208 Parsing with Variable Patterns Using UPPER Parsing Instructions Summary 210 Parsing Instructions Examples All examples in this section parse source strings into words. ARG Advanced Topics in Parsing Parsing Multiple Strings Combining String and Positional Patterns: A Special Case 212 Parsing with DBCS Characters Details of Steps in Parsing 214 Page 216 Chapter 16. Numbers and Arithmetic Introduction Definition Numbers 218 Precision Arithmetic Operators Arithmetic Operation RulesBasic Operators Addition and Subtraction Multiplication Division Basic Operator Examples Arithmetic Operation RulesAdditional Operators Power Integer Division Remainder Additional Operator Examples Numeric Comparisons Exponential Notation 222 Page Numeric Information Whole Numbers 224 Numbers Used Directly by REXX Errors Chapter 17. Conditions and Condition Traps Action Taken When a Condition Is Not Trapped Action Taken When a Condition Is Trapped 226 Page Condition Information Descriptive Strings 228 Special Variables The Special Variable RC Page Page Chapter 18. REXX/CICS Text Editor Invocation Screen Format Prefix Commands 232 Individual Line Commands Consecutive Block Commands Destination Commands Macros Under the REXX/CICS Editor Command Line Commands ARBCHAR 234 ARGS BACKWARD BOTTOM CANCEL CASE 236 CHANGE CMDLINE CTLCHAR CURLINE 238 DISPLAY DOWN EDIT 240 FILE FIND Examples 242 FORWARD GET GETLIB INPUT JOIN 244 LEFT LINEADD LPREFIX MACRO MSGLINE NULLS NUMBERS PFKEY PFKLINE 248 QQUIT QUERY QUIT 250 RESERVED RESET RIGHT SAVE SORT 252 SPLIT STRIP SYNONYM TOP TRUNC UP Page Chapter 19. REXX/CICS File System File Pools, Directories, and Files Current Directory and Path 258 Security RFS commands AUTH CKDIR CKFILE 260 COPY DISKR DISKW GETDIR MKDIR RDIR RENAME File List Utility 264 Invocation Macros under the REXX/CICS File List Utility FLST Commands CANCEL COPY 266 DOWN END FLST 268 MACRO PFKEY REFRESH RENAME 270 SORT SYNONYM UP FLST Return Codes 272 Running Execs and Transactions from FLST Chapter 20. REXX/CICS List System Directories and Lists Current Directory and Path Security 274 RLS commands CKDIR LPULL LPUSH 276 LQUEUE MKDIR READ VARDROP VARGET VARPUT WRITE Page Chapter 21. REXX/CICS Command Definition Background Highlights Accomplishing Command Definition Command Arguments Passed to REXX Programs Command Arguments Passed to Assembler Programs 282 CICPARMS Control Block Table3. CICPARMS Control Block Non-REXX Language Interfaces CICGETV - Call to Get, Set, or Drop a REXX Variable 284 Chapter 22. REXX/CICS DB2 Interface Programming Considerations Embedding SQL Statements 286 Receiving the Results Using the SQL Communications Area Example Using SQL Statements 288 Page Page Chapter 23. REXX/CICS High-level Client/Server Support Overview High-level, Natural, Transparent REXX Client Interface Support for REXX-based Application Clients and Servers Value of REXX in Client/Server Computing REXX/CICS Client Exec Example High-level Client/Server Support 292 REXX/CICS Server Exec Example High-level Client/Server Support Page Chapter 24. REXX/CICS Panel Facility Facility Example of Panel Definition Defining Panels Defining the Field Control Characters with the '.DEFINE' Verb 296 .DEFINE Default field control characters Options 298 Defining the Actual PANEL Layout with the '.PANEL' Verb .PANEL 300 Panel Generation and Panel Input/Output PANEL RUNTIME 302 Page Options 304 PANEL Variables Panel Facility Return Code Information 306 System Error Reason Codes Programmer Introduced Warning/Error Reason Codes State Codes and Input Codes State codes 308 Input codes State Codes Input codes 310 Location Codes Examples of Sample Panels Example 1 Example 2 Example 3 Example 4 Example 5 312 IF RC=4 & PAN.REA = 124THEN /* warning and no input received */ Example of a REXX Panel Program Page 314 Page 316 Page Page Chapter 25. REXX/CICS Commands Page Page Page CEDA CEMT 324 CLD CONVTMAP 326 COPYR2S 328 COPYS2R 330 Page DEFCMD 332 Page Page DEFSCMD 336 Page DEFTRNID 338 Page EDIT 340 Page EXECDROP 342 Page EXECIO 344 Page EXECLOAD 346 Page Page EXPORT FILEPOOL 350 Page Page GETVERS Page IMPORT Page Page Page Page Page PATH PSEUDO 362 RFS 364 Page RLS 366 Page Page SET 370 SETSYS 372 Page Page WAITREAD WAITREQ 376 Page Page Appendix A. Error Numbers and Messages The following are the REXX error messages: 380 Page 382 Page 384 Page 386 Appendix B. Return Codes Panel Facility SQL RFS and FLST EDITOR and EDIT DIR SET 388 PATH RLS LISTCMD CLD DEFCMD DEFSCMD DEFTRNID EXECDROP 390 EXECLOAD EXECMAP LISTCLIB and LISTELIB GETVERS COPYR2S COPYS2R LISTPOOL LISTTRNID C2S 392 PSEUDO AUTHUSER WAITREQ CEDA and CEMT EXECIO CONVTMAP SCRNINFO 394 Appendix C. Double-Byte Character Set (DBCS) Support General Description Enabling DBCS Data Operations and Symbol Use Symbols and Strings 396 DBCS-Only Symbols and Mixed SBCS/DBCS Symbols DBCS-Only Strings and Mixed SBCS/DBCS Strings Validation DBCS Symbol Validation Mixed String Validation Instruction Examples PARSE PUSH and QUEUE 398 SAY and TRACE UPPER DBCS Function Handling Built-in Function Examples ABBREV 400 COMPARE COPIES DATATYPE Note: If string is not a valid mixed string and Cor Dis specified as type,0is returned. FIND Applying the word extraction from a string and character comparison rules. INDEX, POS, and LASTPOS LENGTH REVERSE 402 SPACE STRIP TRANSLATE VALUE VERIFY WORD, WORDINDEX, and WORDLENGTH WORDS DBCS Processing Functions 404 Counting Option Function Descriptions DBADJUST DBCENTER DBCJUSTIFY DBLEFT DBRIGHT DBRLEFT 406 DBRRIGHT DBTODBCS DBTOSBCS DBUNBRACKET DBVALIDATE DBWIDTH 408 Appendix D. Reserved Keywords and Special Variables Reserved Keywords Special Variables Keywords and Variables 410 Appendix E. Debug Aids Interactive Debugging of Programs Interrupting Execution and Controlling Tracing Debug Aids 412 Appendix F. REXX/CICS Business Value Discussion Business Solutions Business Value Discussion 414 Product Positioning Business Value Discussion Page Appendix G. System Definition/Customization/Administration Authorized REXX/CICS Commands/Authorized Command Options System Profile Exec Authorized REXX/CICS VSE Librarian sublibraries Defining Authorized Users Page Page Page Appendix H. Security REXX/CICS Supports Multiple Transaction Identifiers REXX/CICS File Security ESA/VSE Command Level Security REXX/CICS Authorized Command Support Security Definitions REXX/CICS General Users 422 REXX/CICS Authorized Users REXX/CICS Authorized Commands Page Page Appendix I. Performance Considerations Page Appendix J. Basic Mapping Support Example The map DSECT follows. The following is the file structure created by CONVTMAP. The following example is exec BMSMAP1. It creates a simple panel that asks for a user ID. BMS Example 428 The BMSMAP1 exec created the following panels. BMS Example Page Appendix K. Post-Installation Configuration Create the RFS Filepools Install Resource Definitions Update LSRPOOL Definitions Rename supplied Procedures Update CICSTART.PROC Update CICS Initialization JCL 432 Format the RFS Filepools Create the Help Files Verify the Installation 434 Sample output: Configure the REXX DB2 Interface 436 Bibliography CICS Transaction Server for VSE/ESA Release 1 library Where to Find More Information Books from VSE/ESA 2.5 base program libraries VSE/ESA Version 2 Release 5 438 High-Level Assembler Language (HLASM) Language Environment for VSE/ESA (LE/VSE) VSE/ICCF VSE/POWER VSE/VSAM Books from VSE/ESA 2.5 optional program libraries C for VSE/ESA (C/VSE) COBOL for VSE/ESA (COBOL/VSE) 440 DB2 Server for VSE DL/I VSE PL/I for VSE/ESA (PL/I VSE) Screen Definition Facility II (SDF II) Page Notices Page Trademarks Page Index Special characters A B C D E 448 Page F G 450 H I M N O P Q R S 452 T U V W X Page Sending your comments to IBM