IBM SC34-5764-01 Manual

Cics transaction server for vse/esa

page of 481

/ 481
Contents
Table of Contents
Bookmarks

Table of Contents

Quick Links

CICS Transaction Server for VSE/ESA

REXX Guide

SC34-5764-01

Table of Contents

Summary of Contents for IBM SC34-5764-01

Page 1 CICS Transaction Server for VSE/ESA REXX Guide SC34-5764-01...
Page 3 CICS Transaction Server for VSE/ESA REXX Guide SC34-5764-01...
Page 4 443. Second edition (September 2000) This edition applies to Release 1 of CICS Transaction Server for VSE/ESA, program number 5648-054, and to all subsequent versions, releases, and modifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product.
Page 6 Tracing Results ....... . 30 Exercises - Using the TRACE Instruction ..... . . 30 Chapter 4.
Page 7 REXX Interface to CEDA and CEMT Transaction Programs ....105 High-level Client/Server Support Support for Commands Written in REXX ..... . 105 Command Definition of REXX Commands .
Page 8 Operators ........115 Parentheses and Operator Precedence ..... . . 118 Clauses and Instructions .
Page 9 OPTIONS ........151 PARSE ........152 PROCEDURE .
Page 10 OVERLAY........189 POS (Position) ....... . 189 QUEUED .
Page 11 Arithmetic Operation Rules—Additional Operators ....220 Numeric Comparisons ......222 Exponential Notation .
Page 12 QQUIT ........249 QUERY ........249 QUIT .
Page 13 REXX/CICS Client Exec Example ......292 REXX/CICS Server Exec Example......293 Chapter 24.
Page 14 Options........304 PANEL Variables ....... 305 Panel Facility Return Code Information .
Page 15 Example ........331 Notes ........331 DEFCMD .
Page 16 Return Codes ....... . 350 Example ........351 Note .
Page 17 Return Codes ....... . 368 Example ........368 Notes .
Page 18 LISTPOOL ........391 LISTTRNID ........392 C2S .
Page 19 COBOL for VSE/ESA (COBOL/VSE) ......440 DB2 Server for VSE ......440 DL/I VSE .
Page 20 Index ........447 Sending your comments to IBM ......455...
Page 21: Preface
Preface What this book is about This book describes REXX/CICS or REXX for CICS Transaction Server for VSE/ESA. This IBM program product provides a native REXX-based application development, customization, prototyping, and procedures language environment for REXX/CICS, along with associated runtime facilities.
Page 22 CICS TS for VSE/ESA: REXX Guide...
Page 24 CICS TS for VSE/ESA: REXX Guide...
Page 25: Chapter 1. Introduction
Extensive parsing capabilities REXX includes extensive parsing capabilities for character manipulation. This parsing capability lets you set up a pattern to separate characters, numbers, and mixed input. © Copyright IBM Corp. 1992, 2009...
Page 26: Components Of Rexx
Introduction Components of REXX The various components of REXX make it a powerful tool for programmers. REXX is made up of: v Clauses, which can be instructions, null clauses, or labels. Instructions can be: – Keyword instructions – Assignments – Commands (REXX/CICS and CICS commands and SQL). The language processor processes keyword instructions and assignments.
Page 27: Chapter 2. Writing And Running A Rexx Program
ADDTWO, which adds two numbers: From a CICS terminal you would clear the screen and enter: REXX addtwo For this example, the first number you will enter is 42, and the second number is 21. Here is the ADDTWO program: © Copyright IBM Corp. 1992, 2009...
Page 28: Syntax Of Rexx Instructions
Writing and Running a REXX Program /**************************** REXX *********************************/ /* This program adds two numbers and produces their sum. /*******************************************************************/ say 'Enter first number.' PULL number1 say 'Enter second number.' PULL number2 sum = number1 + number2 SAY 'The sum of the two numbers is' sum'.' Figure 2.
Page 29 SAY 'This is a REXX literal string.' /* Using single quotation marks */ SAY "This is a REXX literal string." /* Using double quotation marks */ Do not enclose a literal string with one each of the two different types of quotation marks. For example, the following is incorrect: SAY 'This is a REXX literal string."...
Page 30 Writing and Running a REXX Program SAY 'This is' 'a string.' The space between the two separate strings is preserved: This is a string. Continuing a literal string without adding a space If you need to continue an instruction to a second or more lines, but do not want REXX to add spaces in the line, use the concatenation operand (two single OR bars, ||).
Page 31: Types Of Rexx Clauses
Writing and Running a REXX Program Types of REXX Clauses REXX clauses can be: instructions, null clauses, and labels. Instructions can be keyword instructions, assignments, or commands. The following example shows a program with these types of clauses. A description of each type of clause follows the example. /* QUOTA REXX program.
Page 32: Programs Using Double-Byte Character Set Names
Writing and Running a REXX Program Label A label, such as sub: is a symbolic name followed by a colon. A label can contain either single- or double-byte characters or a combination of single- and double-byte characters. (Double-byte characters are valid only if OPTIONS ETMODE is the first instruction in your program.) A label identifies a portion of the program and is commonly used in subroutines and functions, and with the SIGNAL instruction.
Page 33: Typing In A Program
The name of the program is HELLO EXEC (for now, assume that the file type is exec). 1. Sign on to a CICS Transaction Server for VSE/ESA terminal by entering CESN and supplying your user ID and password when it is requested.
Page 34: Interpreting Error Messages
Writing and Running a REXX Program rexx hello Hello! What is your name? Hello SAM Here is what happens: 1. The SAY instruction displays Hello! What is your name? 2. The PULL instruction pauses the program, waiting for a reply. 3.
Page 35: How To Prevent Translation To Uppercase
/************************** REXX **********************************/ /* This REXX program contains a deliberate error of not closing /* a comment. Without the error, it would pull input to produce */ /* a greeting. /******************************************************************/ PULL who /* Get the person's name. IF who = '' THEN SAY 'Hello, stranger' ELSE SAY 'Hello,' who...
Page 36: Characters Input To A Program
Writing and Running a REXX Program Quotation marks ensure that information in a program is processed exactly as typed. This is important in the following situations: v For output that must be lowercase or a mixture of uppercase and lowercase. v To ensure that commands are processed correctly.
Page 37: Specifying Values When Calling A Program
/**************************** REXX ******************************/ /* This program adds two numbers and produces their sum. /****************************************************************/ PULL number1 PULL number2 sum = number1 + number2 SAY 'The sum of the two numbers is' sum'.' Figure 7. Example of a program That Uses PULL The PULL instruction can extract more than one value at a time from the terminal by separating a line of input.
Page 38: Preventing Translation Of Input To Uppercase
Writing and Running a REXX Program REXX add 42 21 10 The language processor assigns the value 42 to number1, the first variable following ARG. It assigns the value 21 10 to number2, the second variable. In this situation, the program ends with an error when it tries to add the two variables.
Page 39: Passing Arguments
Writing and Running a REXX Program 4. lastname = WEBER, firstname = JOE, score = 91 5. lastname = Baker, firstname = Amanda, score = Marie 95 6. lastname = Callahan, firstname = Eunice, score = 88 Passing Arguments Values passed to a program are usually called arguments. An argument can consist of one word or a string of words.
Page 40 CICS TS for VSE/ESA: REXX Guide...
Page 41: Chapter 3. Using Variables And Expressions
? ! . _ special characters X'41'–X'FE' double-byte character set (DBCS) characters. (OPTIONS ETMODE must be the first instruction in your program for these characters to be valid in a variable name.) Restrictions on the variable name are: © Copyright IBM Corp. 1992, 2009...
Page 42: Variable Values
Using Variables and Expressions v The first character cannot be 0 through 9 or a period (.) v The variable name cannot exceed 250 bytes. For names containing DBCS characters, count each DBCS character as 2 bytes, and count the shift-out (SO) and shift-in (SI) as 1 byte each. v SO (X'0E') and SI (X'0F') must delimit DBCS characters within a DBCS name.
Page 43: Using Expressions
ANSWERS 1. Incorrect, because the first character is a number. 2. Incorrect, because the first character is a “£”. 3. Valid 4. Valid 5. Valid, but it is a special variable name that you should use only to receive results from a subroutine. Using Expressions An expression is something that needs to be evaluated and consists of numbers, variables, or strings, and zero or more operators.
Page 44 Using Variables and Expressions Raise a number to a whole number power −number (Prefix −) Same as the subtraction 0 - number +number (Prefix +) Same as the addition 0 + number Using numeric constants and arithmetic operators, you can write arithmetic expressions such as: 7 + 2 /* result is 9 7 - 2...
Page 45: Comparison Operators
7 + 2 * 3 - 1 \___/ 3. Addition and subtraction from left to right 7 + 6 - 1 = 12 Using Arithmetic Expressions You can use arithmetic expressions in a program many different ways. The following example uses several arithmetic operators to round and remove extra decimal places from a dollar and cents value.
Page 46 Using Variables and Expressions For example, if A = 4 and Z = 3, then the results of the previous comparison questions are: (A = Z) Does 4 = 3? (A > Z) Is 4 > 3? (A < Z) Is 4 <...
Page 47: Logical (Boolean) Operators
/****************************** REXX *********************************/ /* This program compares what you paid for lunch for two /* days in a row and then comments on the comparison. /*********************************************************************/ PARSE PULL yesterday /* Gets yesterday's price from input stream */ PARSE PULL today /* Gets today's price */ IF today >...
Page 48 Using Variables and Expressions Operator Meaning & Returns 1 if both comparisons are true. For example: (4 > 2) & (a = a) /* true, so result is 1 */ (2 > 4) & (a = a) /* false, so result is 0 */ Inclusive OR Returns 1 if at least one comparison is true.
Page 49: Concatenation Operators
\___________________/ true \_____________________________/ As a result, when you run the program, it produces the result: Go skiing. Exercises - Using Logical Expressions A student applying to colleges has decided to evaluate them according to the following specifications: IF (inexpensive | scholarship) & (reputable | nearby) THEN SAY "I'll consider it."...
Page 50: Priority Of Operators
Using Variables and Expressions /****************************** REXX *********************************/ /* This program formats data into columns for output. /*********************************************************************/ sport = 'base' equipment = 'ball' column = ' cost = 5 SAY sport||equipment column '£' cost Figure 14. Example Using Concatenation Operators The result of this example is: baseball £...
Page 51: Tracing Expressions With The Trace Instruction
3. Evaluate 0 & 1 is 0 Exercises - Priority of Operators 1. What are the answers to the following examples? a. 22 + (12 * 1) b. -6 / -2 > (45 % 7 / 2) - 1 c. 10 * 2 - (5 + 1) // 5 * 2 + 15 - 1 2.
Page 52: Tracing Results
Using Variables and Expressions 1 /************************* REXX ***************************/ 2 /* This program uses the TRACE instruction to show how 3 /* an expression is evaluated, operation by operation. 4 /**********************************************************/ 5 a = 9 6 y = 2 7 TRACE I 9 IF a + 1 >...
Page 53 /****************************** REXX ********************************/ /* This program uses the TRACE instruction to show how the language */ /* processor evaluates an expression, operation by operation. /********************************************************************/ a = 1 z = 2 c = 3 d = 4 TRACE I IF (a > z) | (c < 2 * d) THEN SAY 'At least one expression was true.' ELSE SAY 'Neither expression was true.'...
Page 54 Using Variables and Expressions CICS TS for VSE/ESA: REXX Guide...
Page 55: Chapter 4. Controlling The Flow Within A Program
SELECT WHEN...OTHERWISE...END can direct the execution to one of many choices. IF...THEN...ELSE Instructions The examples of IF...THEN...ELSE instructions in previous chapters demonstrate the two-choice selection. In a flow chart, this appears as follows: False expression ELSE instruction © Copyright IBM Corp. 1992, 2009 True THEN instruction...
Page 56: Nested If
Control Flow within a Program As a REXX instruction, the flowchart example looks like: IF expression THEN instruction ELSE instruction You can also arrange the clauses in one of the following ways to enhance readability: IF expression THEN instruction ELSE instruction IF expression THEN...
Page 57 /******************************** REXX *******************************/ /* This program demonstrates what can happen when you do not include */ /* DOs, ENDs, and ELSEs in nested IF...THEN...ELSE instructions. /*********************************************************************/ weather = 'fine' tenniscourt = 'occupied' IF weather = 'fine' THEN SAY 'What a lovely day!' IF tenniscourt = 'free' THEN SAY 'Let''s play tennis!' ELSE...
Page 58 Control Flow within a Program Exercise - Using the IF...THEN...ELSE Instruction Write the REXX instructions for the following flowchart: False False True False ANSWER IF a = 0 THEN IF c = 2 THEN z = 1 ELSE NOP ELSE IF z = 2 THEN IF c = 3 THEN a = 1...
Page 59: Select When
SELECT WHEN...OTHERWISE...END Instruction To select one of any number of choices, use the SELECT WHEN...OTHERWISE...END instruction. In a flowchart it appears as follows: SELECT True expression WHEN False True expression WHEN False True expression WHEN OTHERWISE As a REXX instruction, the flowchart example looks like: SELECT WHEN expression THEN instruction WHEN expression THEN instruction...
Page 60 Control Flow within a Program /******************************** REXX *******************************/ /* This program receives input with a person's age and sex. In /* reply, it produces a person's status as follows: BABIES - under 5 GIRLS - female 5 to 12 BOYS - male 5 to 12 TEENAGERS - 13 through 19 WOMEN...
Page 61: Using Looping Instructions
/******************************** REXX *******************************/ /* This program uses the input of a whole number from 1 to 12 that /* represents a month. It produces the number of days in that /* month. /*********************************************************************/ ARG month SELECT WHEN month = 9 THEN days = 30 WHEN month = 4 THEN days = 30...
Page 62 Control Flow within a Program DO number = 1 TO 5 SAY 'Loop' number SAY 'Hello!' SAY 'Dropped out of the loop when number reached' number This example results in five lines of Hello! preceded by the number of the loop. The number increases at the bottom of the loop and is tested at the top.
Page 63 /******************************* REXX ********************************/ /* This program processes strings until the value of a string is /* a null string. /*********************************************************************/ DO FOREVER PULL string IF string = '' THEN PULL file_name IF file_name = '' THEN EXIT ELSE result = process(string) IF result = 0 THEN SAY "Processing complete for string:"...
Page 64: Conditional Loops
Control Flow within a Program Number 1 Number 2 Number 3 Number 4 Number 5 Number 6 Number 7 Number 9 Number 10 Exercises - Using Loops 1. What are the results of the following loops? DO digit = 1 TO 3 SAY digit SAY 'Digit is now' digit DO count = 10 BY -2 TO 6...
Page 65 DO WHILE Loops DO WHILE loops in a flowchart appear as follows: DO WHILE True expression False As REXX instructions, the flowchart example looks like: DO WHILE expression /* expression must be true */ instruction(s) Use a DO WHILE loop when you want to execute the loop while a condition is true. DO WHILE tests the condition at the top of the loop.
Page 66 Control Flow within a Program /******************************** REXX *******************************/ /* This program uses a DO WHILE loop to keep track of window seats /* in an 8-seat commuter airline. /*********************************************************************/ window_seats = 0 /* Initialize window seats to 0 */ passenger = 0 /* Initialize passengers to 0 DO WHILE (passenger <...
Page 67 /******************************** REXX ******************************/ /* This program uses a DO UNTIL loop to ask for a password. If the */ /* password is incorrect three times, the loop ends. /********************************************************************/ password = 'abracadabra' time = 0 DO UNTIL (answer = password) | (time = 3) PULL answer time = time + 1 Figure 24.
Page 68: Combining Types Of Loops
Control Flow within a Program ANSWER /******************************** REXX *******************************/ /* This program uses a DO UNTIL loop to keep track of window seats /* in an 8-seat commuter airline. /*********************************************************************/ window_seats = 0 /* Initialize window seats to 0 */ passenger = 0 /* Initialize passengers to 0 DO UNTIL (passenger >= 8) | (window_seats = 4)
Page 69 DO outer = 1 TO 2 DO inner = 1 TO 2 SAY 'HIP' SAY 'HURRAH' The output from this example is: HURRAH HURRAH If you need to leave a loop when a certain condition arises, use the LEAVE instruction followed by the name of the control variable of the loop.
Page 70: Using Interrupt Instructions
Control Flow within a Program Outer 1 Inner 1 Outer 1 Inner 2 Outer 1 Inner 3 Outer 2 Inner 1 Outer 2 Inner 2 Outer 2 Inner 3 Outer 3 Inner 1 Outer 3 Inner 2 Outer 3 Inner 3 2.
Page 71: Call And Return Instructions
CALL and RETURN Instructions The CALL instruction interrupts the flow of a program by passing control to an internal or external subroutine. An internal subroutine is part of the calling program. An external subroutine is another program. The RETURN instruction returns control from a subroutine back to the calling program and optionally returns a value.
Page 72: Signal Instruction
Control Flow within a Program SIGNAL Instruction The SIGNAL instruction, like CALL, interrupts the usual flow of a program and causes control to pass to a specified label. The label to which control passes can be before or after the SIGNAL instruction. Unlike CALL, SIGNAL does not return to a specific instruction to resume execution.
Page 73: Chapter 5. Using Functions
Example of a Function Calculations that functions represent often require many instructions. For instance, the simple calculation for finding the highest number in a group of three numbers, might be written as follows: © Copyright IBM Corp. 1992, 2009...
Page 74: Built-In Functions
Using Functions /***************************** REXX **********************************/ /* This program receives three numbers as arguments and analyzes /* which number is the greatest. /*********************************************************************/ PARSE ARG number1, number2, number3 . IF number1 > number2 THEN IF number1 > number3 THEN greatest = number1 ELSE greatest = number3 ELSE...
Page 75: Arithmetic Functions
Arithmetic Functions Function Description Returns the absolute value of the input number. DIGITS Returns the current setting of NUMERIC DIGITS. FORM Returns the current setting of NUMERIC FORM. FUZZ Returns the current setting of NUMERIC FUZZ. Returns the largest number from the list specified, formatted according to the current NUMERIC settings.
Page 76: Formatting Functions
Using Functions Formatting Functions Function Description CENTER or Returns a string of a specified length with the input string centered in it, with pad characters CENTRE added as necessary to make up the length. COPIES Returns the specified number of concatenated copies of the input string. FORMAT Returns the input number, rounded and formatted.
Page 77: Miscellaneous Functions
Function Description WORDPOS Returns the word number of the first word of a specified phrase in the input string. WORDS Returns the number of words in the input string. Miscellaneous Functions Function Description ADDRESS Returns the name of the environment to which commands are currently being sent. Returns an argument string or information about the argument strings to a program or internal routine.
Page 78 Using Functions Other useful built-in functions to test input are WORDS, VERIFY, LENGTH, and SIGN. Exercise - Writing a program with Built-In Functions Write a program that checks a file name for a length of 8 characters. If the name is longer than 8 characters, the program truncates it to 8 and sends a message indicating the shortened name.
Page 79: Chapter 6. Writing Subroutines And Functions
SUBSTR as either a function or a subroutine. This is how to call SUBSTR as a function to shorten a word to its first eight characters: a = SUBSTR('verylongword',1,8) You get the same results if you call SUBSTR as a subroutine. © Copyright IBM Corp. 1992, 2009 /* a is set to 'verylong' */...
Page 80: Writing Subroutines And Functions
Writing Subroutines and Functions CALL SUBSTR 'verylongword', 1, 8 a = RESULT When deciding whether to write a subroutine or a function, ask yourself the following questions: v Is a returned value optional? If so, write a subroutine. v Do I need a value returned as an expression within an instruction? If so, write a function. The rest of this chapter describes how to write subroutines and functions and finally summarizes the differences and similarities between the two.
Page 81 instruction(s) z=func1(arg1, arg2) instruction(s) EXIT instruction(s) RETURN Both subroutines and functions can be internal (designated by a label) or external (designated by the subroutine or function in the REXX File System/VSE Librarian sublibrary member name). The two preceding examples illustrate an internal subroutine named sub1 and an internal function named func1. IMPORTANT NOTE Because internal subroutines and functions generally appear after the main part of the program, when you have an internal subroutine or function, it is important to end the main part of the program...
Page 82: When To Use Internal Versus External Subroutines Or Functions
Writing Subroutines and Functions MAIN instruction(s) z=func2(arg1) instruction(s) … … … exit FUNC2 ARG var1 instruction(s) RETURN value When to Use Internal Versus External Subroutines or Functions To determine whether to make a subroutine or function internal or external, you might consider factors, such as: v Size of the subroutine or function.
Page 83 /******************************* REXX ********************************/ /* This program receives a calculated value from an internal /* subroutine and uses that value in a SAY instruction. /*********************************************************************/ number1 = 5 number2 = 10 CALL subroutine SAY answer EXIT subroutine: answer = number1 + number2 RETURN Figure 29.
Page 84 Writing Subroutines and Functions /******************************* REXX ********************************/ NOTE: This program contains an error. /* It uses a DO loop to call an internal subroutine, and the /* subroutine uses a DO loop with the same control variable as the /* main program. The DO loop in the main program runs only once. /*********************************************************************/ number1 = 5 number2 = 10...
Page 85 The following examples show how results differ when a subroutine or function uses or does not use PROCEDURE. /******************************* REXX ********************************/ /* This program uses a PROCEDURE instruction to protect the /* variables within its subroutine. /*********************************************************************/ number1 = 10 CALL subroutine SAY number1 number2 /* Produces 10 NUMBER2 */...
Page 86 Writing Subroutines and Functions /******************************* REXX ********************************/ /* This program does not use a PROCEDURE instruction to protect the */ /* variables within its function. /*********************************************************************/ number1 = 10 SAY pass() number2 EXIT pass: number1 = 7 number2 = 5 RETURN number1 Figure 36.
Page 87 In a function call, you can pass up to 20 arguments separated by commas. function(argument1,argument2,argument3,...) Using the ARG Instruction: A subroutine or function can receive the arguments with the ARG instruction. In the ARG instruction, commas also separate arguments. ARG arg1, arg2, arg3, ... The names of the arguments that are passed do not have to be the same as those on the ARG instruction because information is passed by position rather than by argument name.
Page 88: Receiving Information From A Subroutine Or Function
Writing Subroutines and Functions /***********************************REXX***********************************/ This program receives as arguments the length and width of a rectangle and passes that information to an internal function, named perimeter. The function then calculates the perimeter of the rectangle. /*****************************************************************************/ PARSE ARG long wide SAY ‘The perimeter is’...
Page 89 Exercise - Writing an Internal and an External Subroutine Write a program that plays a simulated coin toss game and produces the accumulated scores. There should be four possible inputs: v 'HEADS' v 'TAILS' v '' (Null—to quit the game) v None of these three (incorrect response).
Page 90 Writing Subroutines and Functions /*************************** REXX ************************************/ /* This internal subroutine checks for valid input of "HEADS", /* "TAILS", or "" (to quit). If the input is anything else, the /* subroutine says the input is not valid and gets the next input. */ /* The subroutine keeps repeating until the input is valid.
Page 91 /******************************* REXX ********************************/ /* This function receives a list of numbers, adds them, computes /* their average, and returns the average to the calling program. /*********************************************************************/ ARG numlist /* receive the numbers in a single variable */ sum = 0 DO n = 1 TO WORDS(numlist) /* Repeat for as many times as there */ /* are numbers...
Page 92: Subroutines And Functions-Similarities And Differences
Writing Subroutines and Functions Subroutines and Functions—Similarities and Differences The following tables highlight similarities and differences between subroutines and functions: Similarities between Subroutines and Functions Can be internal or external. Internal – Can pass information by using common variables – Can protect variables with the PROCEDURE instruction –...
Page 93: Chapter 7. Manipulating Data
/* The value FIRST appears because the /* variable FIRST is a stem, which /* cannot change. SAY name.first.middle.last /* Produces NAME.Fred.MIDDLE.Higgins You can use a DO loop to initialize a group of compound variables and set up an array. © Copyright IBM Corp. 1992, 2009...
Page 94: Using Stems
Manipulating Data DO i = 1 TO 6 PARSE PULL employee.i If you use the same names used in the example of the employee array, you have a group of compound variables as follows: employee.1 = 'Adams, Joe' employee.2 = 'Crandall, Amy' employee.3 = 'Devon, David' employee.4 = 'Garrison, Donna' employee.5 = 'Leone, Mary'...
Page 95: Parsing Data
SAY a.first SAY z.a.4 2. After these assignment instructions, what output do the SAY instructions produce? hole.1 = 'full' hole. = 'empty' hole.s = 'full' SAY hole.1 SAY hole.s SAY hole.mouse ANSWERS last D.last A.FIRST cv3d empty full empty Parsing Data Parsing is separating data and assigning parts of it into one or more variables.
Page 96 Manipulating Data /* This REXX program parses the string: "Knowledge is power." PARSE PULL word1 word2 word3 /* word1 contains 'Knowledge' */ /* word2 contains 'is' /* word3 contains 'power.' You can include the optional keyword UPPER on any variant of the PARSE instruction.This causes the language processor to uppercase character information before assigning it into variables.
Page 97: More About Parsing Into Words
quote = 'Knowledge is power.' PARSE VAR quote word1 word2 word3 /* word1 contains 'Knowledge' */ /* word2 contains 'is' /* word3 contains 'power.' PARSE VAR does not uppercase character information before assigning it into variables. If you want uppercase translation, use PARSE UPPER VAR. More about Parsing into Words In the preceding examples, the number of words in the data to parse is always the same as the number of variables in the template.
Page 98 Manipulating Data String If you use a string in a template, parsing checks the input data for a matching string. When assigning data into variables, parsing generally skips over the part of the input string that matches the string in the template.
Page 99 /* part1 contains 'Igno' /* part2 contains 'rance' /* part3 contains ' is bliss.' /* part4 contains 'Ignorance is bliss.' */ When each variable in a template has column numbers both before and after it, the two numbers indicate the beginning and the end of the data for the variable. quote = 'Ignorance is bliss.' ...+...1...+...2 PARSE VAR quote 1 part1 10 11 part2 13 14 part3 19 1 part4 20...
Page 100: Parsing Multiple Strings As Arguments
Manipulating Data (Without +, −, or = before the left parenthesis, the language processor would consider the variable to be a string pattern.) The following example uses the variable numeric pattern movex. quote = 'Ignorance is bliss.' ...+...1...+...2 movex = 3 /* variable position PARSE VAR quote part5 +10 part6 +3 part7 -(movex) part8 /* part5 contains 'Ignorance '...
Page 101 c) word3 = PARSE VALUE 'Experience is the best teacher.' WITH v1 5 v2 ...+...1...+...2...+...3. a) v1 = b) v2 = quote = 'Experience is the best teacher.' ...+...1...+...2...+...3. PARSE VAR quote v1 v2 15 v3 3 v4 a) v1 = b) v2 = c) v3 = d) v4 =...
Page 102 Manipulating Data f) word6 = '' a) word1 = Experience b) word2 = is c) word3 = teacher. a) v1 = Expe b) v2 = rience is the best teacher. a) v1 = Experience b) v2 = is (Note that v2 contains 'is '.) c) v3 = the best teacher.
Page 103: Chapter 8. Using Commands From A Program
“REXX/CICS Commands,” on page 319. CICS commands These commands implement the EXEC CICS commands that application programs use to access CICS services. These commands are documented in the CICS Transaction Server for VSE/ESA Application Programming Reference. SQL statements These statements are prepared and executed dynamically. See Chapter 22, “REXX/CICS DB2 Interface,”...
Page 104: Calling Another Rexx Program As A Command
Using Commands from a Program Calling Another REXX Program as a Command Previously, this book discussed how to call another program as an external routine (Chapter 6, “Writing Subroutines and Functions,” on page 57). You can also call a program from another program explicitly with the EXEC command.
Page 105: How Is A Command Passed To The Host Environment
This is an optional environment that executes commands for the REXX File System. This is an optional environment that executes commands for the REXX List System. Note: It is recommended that the default environment of REXXCICS be used for all commands (that is, the ADDRESS instruction should not be specified).
Page 106 CICS TS for VSE/ESA: REXX Guide...
Page 107: Chapter 9. Diagnosing Problems Within A Program
Note: Every command sets a value for RC, so it does not remain the same for the duration of a program. When using RC, make sure it contains the return code of the command you want to test. © Copyright IBM Corp. 1992, 2009...
Page 108: Tracing With The Interactive Debug Facility
Diagnosing Problems within a Program SIGL The language processor sets the SIGL special variable in connection with a transfer of control within a program because of a function, a SIGNAL or a CALL instruction. When the language processor transfers control to another routine or another part of the program, it sets the SIGL special variable to the line number from which the transfer occurred.
Page 109: Saving Interactive Trace Output
instruction2 ELSE instructionA If the command ends with a nonzero return code, the ELSE path is taken. To force taking the first path, the input during interactive debug could be: RC = 0 Ending Interactive Debug You can end interactive debug in one of the following ways: v Use the TRACE OFF instruction as input.
Page 110 CICS TS for VSE/ESA: REXX Guide...
Page 111: Chapter 10. Programming Style And Techniques
If you had started off by writing down some instructions without considering the data, it would have taken you longer. Test Yourself... Write the program. If you are careful, it should run the first time! © Copyright IBM Corp. 1992, 2009...
Page 112: Happy Hour
Programming Style and Techniques Answer: /* CON EXEC */ /* Tossing a coin. The machine is lucky, not the user */ do forever say "Let's play a game! Type 'Heads', 'Tails'", "or 'Quit' and press ENTER." pull answer select when answer = "HEADS" then say "Sorry! It was TAILS.
Page 113 /* CATMOUSE EXEC /* The user says where the mouse is to go. But where /* will the cat jump? say "This is the mouse ----------> say "These are the cat's paws ---> ( )" say "This is the mousehole ------> say "This is a wall ------------->...
Page 114: Designing A Program
Programming Style and Techniques then mouse = cat otherwise mouse = mouse + move if mouse = hole then leave if mouse = cat then leave /*---------------------------------------------------*/ /* Cat turn /*---------------------------------------------------*/ jump = random(1,spring) if cat > mouse then do /* cat tries to jump left */ Temp = cat - jump if Temp <...
Page 115: Methods For Designing Loops
Do forever call Display Mouse's move Cat's move Conclusion Methods for Designing Loops The method for designing loops is to ask two questions: v Will it always end? v Whenever it terminates, will the data meet the conditions required? Well, the loop terminates (and the game ends) when: 1.
Page 116: What Do We Have So Far
Programming Style and Techniques What Do We Have So Far? Putting all this together, we have: /*------------------------------------------------------*/ /* Main program /*------------------------------------------------------*/ do forever call display /*---------------------------------------------------*/ /* Mouse's turn /*---------------------------------------------------*/ if mouse = hole then leave if mouse = cat then leave /*---------------------------------------------------*/ /* Cat's turn /*---------------------------------------------------*/...
Page 117: Reconsider The Data
At this stage, look at the specification again. A sailor might need to put on the pullover in the dark, quickly, without worrying about the front or back. Therefore, the front should be the same as the back; and the two sleeves should also be the same.
Page 118: Coding Style
Programming Style and Techniques /* ROTATE EXEC /* Example: two iterations of wheel, six iterations */ /* of cog. On the first three iterations, "x < 2" */ /* is true. On the next three, it is false. trace L do x = 1 to 2 wheel: do 3...
Page 119 /********************************************************/ /* SAMPLE #1: A portion of CATMOUSE EXEC /* not divided into segments and written with no /* indentation, and no comments. This style is not /* recommended. /********************************************************/ do forever call display pull move if datatype(move,whole) & move >= 0 & move <=2 then select when mouse+move >...
Page 120 Programming Style and Techniques /********************************************************/ /* SAMPLE #2: A portion of CATMOUSE EXEC /* divided into segments and written with 'some' /* indentation and 'some' comments. /********************************************************/ /********************************************************/ /* Main program /********************************************************/ do forever call display /*****************************************************/ /* Mouse's turn /*****************************************************/ pull move if datatype(move,whole) &...
Page 121 /********************************************************/ /* SAMPLE #3: A portion of CATMOUSE EXEC /* divided into segments and written with 'more' /* indentation and 'more' comments. /* Note commands in uppercase (to highlight logic) /********************************************************/ /********************************************************/ /* Main program /********************************************************/ DO FOREVER CALL display /**********************************/ /* Mouse's turn /**********************************/...
Page 122 CICS TS for VSE/ESA: REXX Guide...
Page 124 CICS TS for VSE/ESA: REXX Guide...
Page 125: Chapter 11. Introduction
Explains how to read a syntax diagram. Who Should Read This Reference This reference describes the CICS Transaction Server for VSE/ESA REXX Guide and Reference Interpreter (hereafter referred to as the interpreter or language processor) and the REstructured eXtended eXecutor (called REXX) language.
Page 126: Overview Of Product Features
VSAM-Based File System for REXX Execs and Data v Dynamic Support for EXEC CICS Commands v REXX Interface to CEDA and CEMT Transaction Programs v High-level Client/Server Support v Support for Commands Written in REXX v Command Definition of REXX Commands...
Page 127: Dynamic Support For Exec Cics Commands
(WAITREQ), and to retrieve (C2S) and set (S2C) the contents of client REXX variables. Note: Servers do not execute as nested execs of clients, but rather execute as parallel entities. Servers use Automatic Server Initiation (ASI) to start automatically when they receive their first request. Support for Commands Written in REXX REXX/CICS supports the ability for users to write new REXX/CICS commands in REXX.
Page 128: Sql Interface
Introduction SQL Interface REXX programs may contain SQL statements. These statements are interpreted and executed dynamically. The results of the SQL statements are placed into REXX variables for use within the REXX program. Programming Considerations To embed SQL statements withn a REXX exec, the host command environment must be changed, The ADDRESS instruction, followed by the name of the environment, is used to change the host command environment.
Page 129 v Required items appear on the horizontal line (the main path). STATEMENT required_item v Optional items appear below the main path. STATEMENT optional_item v If you can choose from two or more items, they appear vertically, in a stack. If you must choose one of the items, one item of the stack appears on the main path. STATEMENT required_choice1 required_choice2...
Page 130 Introduction CICS TS for VSE/ESA: REXX Guide...
Page 131: Chapter 12. Rexx General Concepts
“REXX” are in the first line (line 1). /* REXX program */ EXIT Figure 48. Example of Using the REXX Program Identifier A REXX program is built from a series of clauses that are composed of: © Copyright IBM Corp. 1992, 2009...
Page 132: Characters
REXX General Concepts v Zero or more blanks (which are ignored) v A sequence of tokens (see section “Tokens” on page 111) v Zero or more blanks (again ignored) v A semicolon (;) delimiter that may be implied by line-end, certain keywords, or the colon (:). Conceptually, each clause is scanned from left to right before processing, and the tokens composing it are identified.
Page 133: Tokens
You can avoid this type of problem by using concatenation for literal strings containing /* or */; line 2 would be: if substr(input,1,5) = '/' || '*123' You could comment out lines 2 and 3 correctly as follows: parse pull input 02 /* if substr(input,1,5) = '/' || '*123' then call process 04 */ dept = substr(input,32,5)
Page 134 REXX General Concepts Note: A hexadecimal string is not a representation of a number. Rather, it is an escape mechanism that lets a user describe a character in terms of its encoding (and, therefore, is machine-dependent). In EBCDIC, '40'X is the encoding for a blank. In every case, a string of the form '...'x is simply an alternative to a straightforward string.
Page 135 If a symbol does not begin with a digit or a period, you can use it as a variable and can assign it a value. If you have not assigned it a value, its value is the characters of the symbol itself, translated to uppercase (that is, lowercase a–z to uppercase A–Z).
Page 136: Implied Semicolons
REXX General Concepts 345>=123 345 >=123 345 >= 123 345 > = 123 Some of these characters may not be available in all character sets, and, if this is the case, appropriate translations may be used. In particular, the vertical bar (|) or character is often shown as a split vertical bar.
Page 137: Continuations
Continuations One way to continue a clause onto the next line is to use the comma, which is referred to as the continuation character. The comma is functionally replaced by a blank, and, thus, no semicolon is implied. One or more comments can follow the continuation character before the end of the line. The continuation character cannot be used in the middle of a string or it will be processed as part of the string itself.
Page 138 REXX General Concepts blanks and comments. In addition, one or more blanks, where they occur in expressions but are not adjacent to another operator, also act as an operator. There are four types of operators: v Concatenation v Arithmetic v Comparison v Logical String Concatenation The concatenation operators combine two strings to form one string by appending the second string to the...
Page 139 Prefix − Same as the subtraction: 0 - number Prefix + Same as the addition: 0 + number. See Chapter 16, “Numbers and Arithmetic,” on page 217 for details about precision, the format of valid numbers, and the operation rules for arithmetic. Note that if an arithmetic result is shown in exponential notation, it is likely that rounding has occurred.
Page 140: Parentheses And Operator Precedence
REXX General Concepts >>= Strictly greater than or equal to \<<, ¬<< Strictly NOT less than <<= Strictly less than or equal to \>>, ¬>> Strictly NOT greater than Note: Throughout the language, the not character, ¬, is synonymous with the backslash (\). You can use the two characters interchangeably, according to availability and personal preference.
Page 141 = > < (comparison operators) == >> << \= ¬= >< <> \> ¬> \< ¬< \== ¬== \>> ¬>> \<< ¬<< >= >>= <= <<= /= /== & (and) | && (or, exclusive or) Examples: Suppose the symbol A is a variable whose value is 3, DAY is a variable whose value is Monday, and other variables are uninitialized.
Page 142: Clauses And Instructions
REXX General Concepts Clauses and Instructions Clauses can be subdivided into the following types: Null Clauses A clause consisting only of blanks or comments or both is a null clause. It is completely ignored (except that if it includes a comment it is traced, if appropriate). Note: A null clause is not an instruction;...
Page 143: Assignments And Symbols
Assignments and Symbols A variable is an object whose value can change during the running of a REXX program. The process of changing the value of a variable is called assigning a new value to it. The value of a variable is a single character string, of any length, that may contain any characters.
Page 144: Simple Symbols
REXX General Concepts Simple Symbols A simple symbol does not contain any periods and does not start with a digit (0–9). By default, its value is the characters of the symbol (that is, translated to uppercase). If the symbol has been assigned a value, it names a variable and its value is the value of that variable.
Page 145: Stems
where d0 is the uppercase form of the symbol s0, and v1 to vn are the values of the constant or simple symbols s1 through sn. Any of the symbols s1-sn can be null. The values v1-vn can also be null and can contain any characters (in particular, lowercase characters are not translated to uppercase, blanks are not removed, and periods have no special significance).
Page 146: Commands To External Environments
REXX General Concepts pull amount name if datatype(amount)='CHAR' then leave total.name = total.name + amount Note: You can always obtain the value that has been assigned to the whole collection of variables by using the stem. However, this is not the same as using a compound variable whose derived name is the same as the stem.
Page 147: Basic Structure Of Rexx Running Under Cics
The expression is evaluated, resulting in a character string (which may be the null string), which is then prepared as appropriate and submitted to the underlying system. Any part of the expression not to be evaluated should be enclosed in quotation marks. The environment then processes the command, which may have side-effects.
Page 148: Where Execs Execute
REXX General Concepts argument to the exec. For example: EDIT TEST.EXEC causes the REXX/CICS editor exec, CICEDIT, to start and TEST.EXEC, the argument, names the file to edit or create. All REXX/CICS transaction identifiers must have CICS definitions which associate them with the REXX/CICS main module, CICREXD.
Page 149: Rexx File System
REXX File System Execs can be stored as members in the VSAM-based REXX File System (RFS), provided with REXX/CICS, or in VSE librarian members with a member type of PROC. Note: If the file identifier you specified for invoking an exec does not include a file type extension, then only RFS file identifiers with a file type of EXEC are searched when you attempt to locate and issue the REXX exec.
Page 150: Rexx Command Environment Support
From within the ADDRESS CICS command environment, support is provided for most CICS commands (as defined in the CICS Transaction Server for VSE/ESA Application Programming Reference. See Chapter 25, “REXX/CICS Commands,” on page 319 for detailed information on the commands supported.
Page 151: Pseudo-Conversational Transaction Support
Pseudo-conversational Transaction Support CICS pseudo-conversational support for REXX execs is supported though the use of the CICS RETURN TRANSID() command, by the REXX/CICS PSEUDO command (see section “PSEUDO” on page 362), and the SETSYS PSEUDO command (see section “SETSYS” on page 371). Interfaces to Other Programming Languages REXX/CICS supports (by support for CICS LINK and CICS XCTL REXX/CICS commands) the ability to invoke CICS programs written in any REXX/CICS supported language.
Page 152 REXX General Concepts CICS TS for VSE/ESA: REXX Guide...
Page 153: Chapter 13. Keyword Instructions
One or more blanks following VALUE are required to separate the expression from the subkeyword in the example following: ADDRESS VALUE expression However, no blank is required after the VALUE subkeyword in the following example, although it would add to the readability: ADDRESS VALUE'ENVIR'||number © Copyright IBM Corp. 1992, 2009...
Page 154: Address
ADDRESS ADDRESS Purpose ADDRESS environment expression expression1 VALUE ADDRESS temporarily or permanently changes the destination of commands. Commands are strings sent to an external environment. You can send commands by specifying clauses consisting of only an expression or by using the ADDRESS instruction. The concept of alternative subcommand environments is described in section “Issuing Commands from a program”...
Page 155 ADDRESS The two environment names are automatically saved across internal and external subroutine and function calls. See the CALL instruction (page “Purpose” on page 135) for more details. The address setting is the currently selected environment name. You can retrieve the current address setting by using the ADDRESS built-in function (see page 175).
Page 156: Arg
Purpose template_list ARG retrieves the argument strings provided to a program or internal routine and assigns them to variables. It is a short form of the instruction: PARSE UPPER ARG template_list The template_list is often a single template but can be several templates separated by commas. If specified, each template is a list of symbols separated by blanks or patterns or both.
Page 157: Call
CALL Purpose CALL name expression ERROR FAILURE HALT ERROR FAILURE NAME trapname HALT CALL calls a routine (if you specify name) or controls the trapping of certain conditions (if you specify ON or OFF). To control trapping, you specify OFF or ON and the condition you want to trap. OFF turns off the specified condition trap.
Page 158 CALL The CALL then causes a branch to the routine called name, using exactly the same mechanism as function calls, see Chapter 14, “Functions,” on page 171. The search order is in the section on functions but briefly is as follows: Internal routines: These are sequences of instructions inside the same program, starting at the label that matches name in the CALL instruction.
Page 159 v The status of DO loops and other structures: Executing a SIGNAL while within a subroutine is safe because DO loops, and so forth, that were active when the subroutine was called are not ended. (But those currently active within the subroutine are ended.) v Trace action: After a subroutine is debugged, you can insert a TRACE Off at the beginning of it, and this does not affect the tracing of the caller.
Page 160 Purpose repetitor conditional repetitor: name=expri FOREVER exprr conditional: WHILE exprw UNTIL expru DO groups instructions together and optionally processes them repetitively. During repetitive execution, a control variable (name) can be stepped through some range of values. Syntax Notes: v The exprr, expri, exprb, exprt, and exprf options (if present) are any expressions that evaluate to a number.
Page 161 Repetitive DO Loops If a DO instruction has a repetitor phrase or a conditional phrase or both, the group of instructions forms a repetitive DO loop. The instructions are processed according to the repetitor phrase, optionally modified by the conditional phrase. (See section “Conditional Phrases (WHILE and UNTIL)” on page 140). Simple Repetitive Loops: A simple repetitive loop is a repetitive DO loop in which the repetitor phrase is an expression that evaluates to a count of the iterations.
Page 162 The control variable can be altered within the loop, and this may affect the iteration of the loop. Altering the value of the control variable is not usually considered good programming practice, though it may be appropriate in certain circumstances. Note that the end condition is tested at the start of each iteration (and after the control variable is stepped, on the second and subsequent iterations).
Page 163 Note: Using the LEAVE or ITERATE instructions can also modify the execution of repetitive loops. Evaluate exprr + 0 evaluate expri + 0 exprt + 0, exprb + 0, exprf + 0 in order written Assign start value to control variable Use TO value (expr) to test control variable for termination...
Page 164: Drop
DROP DROP Purpose DROP name (name) DROP “unassigns” variables, that is, restores them to their original uninitialized state. If name is not enclosed in parentheses, it identifies a variable you want to drop and must be a symbol that is a valid variable name, separated from any other name by one or more blanks or comments.
Page 165: Exit
EXIT Purpose EXIT expression EXIT leaves a program unconditionally. Optionally EXIT returns a character string to the caller. The program is stopped immediately, even if an internal routine is currently being run. If no internal routine is active, RETURN (see page “Purpose” on page 161) and EXIT are identical in their effect on the program that is being run.
Page 166 Purpose IF expression THEN instruction IF conditionally processes an instruction or group of instructions depending on the evaluation of the expression. The expression is evaluated and must result in 0 or 1. The instruction after the THEN is processed only if the result is 1 (true). If you specify an ELSE, the instruction after the ELSE is processed only if the result of the evaluation is 0 (false).
Page 167: Interpret
INTERPRET Purpose INTERPRET expression ; INTERPRET processes instructions that have been built dynamically by evaluating expression. The expression is evaluated and is then processed (interpreted) just as though the resulting string were a line inserted into the program (and bracketed by a DO; and an END;). Any instructions (including INTERPRET instructions) are allowed, but note that constructions such as DO...END and SELECT...END must be complete.
Page 168 INTERPRET >O> "Hello Kitty" >L> "!" >O> "Hello Kitty!" Hello Kitty! Here, lines 3 and 4 set the variables used in line 5. Execution of line 5 then proceeds in two stages. First the string to be interpreted is built up, using a literal string, a variable (INDIRECT), and another literal string.
Page 169: Iterate
ITERATE Purpose ITERATE name ITERATE alters the flow within a repetitive DO loop (that is, any DO construct other than that with a simple DO). Execution of the group of instructions stops, and control is passed to the DO instruction just as though the END clause had been encountered.
Page 170: Leave
LEAVE LEAVE Purpose LEAVE name LEAVE causes an immediate exit from one or more repetitive DO loops (that is, any DO construct other than a simple DO). Processing of the group of instructions is ended, and control is passed to the instruction following the END clause, just as though the END clause had been encountered and the termination condition had been met.
Page 171: Nop
Purpose NOP ; NOP is a dummy instruction that has no effect. It can be useful as the target of a THEN or ELSE clause: Example: Select when a=c then nop /* Do nothing */ when a>c then say 'A > C' otherwise say 'A <...
Page 172: Numeric
NUMERIC NUMERIC Purpose NUMERIC DIGITS expression1 SCIENTIFIC FORM ENGINEERING VALUE FUZZ expression3 NUMERIC changes the way in which a program carries out arithmetic operations. The options of this instruction are described in detail on pages 217-224, but in summary: NUMERIC DIGITS controls the precision to which arithmetic operations and arithmetic built-in functions are evaluated.
Page 173: Options
OPTIONS Purpose OPTIONS expression ; OPTIONS passes special requests or parameters to the language processor. For example, these may be language processor options or perhaps define a special character set. The expression is evaluated, and the result is examined one word at a time. The language processor converts the words to uppercase.
Page 174: Parse
PARSE PARSE Purpose PARSE UPPER EXTERNAL LINEIN NUMERIC PULL SOURCE VALUE VAR name VERSION PARSE assigns data (from various sources) to one or more variables according to the rules of parsing. (See Chapter 15, “Parsing,” on page 203.) The template_list is often a single template but may be several templates separated by commas. If specified, each template is a list of symbols separated by blanks or patterns or both.
Page 175 CALL instruction, or as a server process. 3. The name of the exec in uppercase. The name of the file (RFS), or VSE Librarian Sublibrary from which the exec was originally loaded.
Page 176 PARSE PARSE VERSION parses information describing the language level and the date of the language processor. This information consists of five words delimited by blanks: 1. The string REXX370, signifying the 370 implementation. 2. The language level description (for example, 3.48). 3.
Page 177: Procedure
PROCEDURE Purpose PROCEDURE EXPOSE name (name) PROCEDURE, within an internal routine (subroutine or function), protects variables by making them unknown to the instructions that follow it. After a RETURN instruction is processed, the original variables environment is restored and any variables used in the routine (that were not exposed) are dropped. (An exposed variable is one belonging to a caller of a routine that the PROCEDURE instruction has exposed.
Page 178 PROCEDURE Example: /* This is the main REXX program */ j=1; z.1='a' call toft say j k m /* Displays "1 7 M" exit /* This is a subroutine toft: procedure expose j k z.j say j k z.j /* Displays "1 K a" k=7;...
Page 179 Example: /* This is the main REXX program */ a.=11; i=13; j=15 i = i + 1 C.5 = 'FRED' call lucky7 say a. a.1 i j c. c.5 say 'You should see 11 7 14 15 C. FRED' exit lucky7:Procedure Expose i j a.
Page 180: Pull
PULL PULL Purpose PULL template_list PULL reads a string from the program stack. If the program stack is empty, PULL then 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.
Page 181: Push
PUSH Purpose PUSH expression PUSH stacks the string resulting from the evaluation of expression LIFO (Last In, First Out) onto the external data queue. If you do not specify expression, a null string is stacked. Note: The REXX/CICS implementation of the external data queue is the program stack. The language processor reads a line from the program stack.
Page 182: Queue
QUEUE QUEUE Purpose QUEUE expression QUEUE appends the string resulting from expression to the tail of the external data queue. That is, it is added FIFO (First In, First Out). If you do not specify expression, a null string is queued. Note: The REXX/CICS implementation of the external data queue is the program stack.
Page 183: Return
RETURN RETURN Purpose RETURN expression RETURN returns control (and possibly a result) from a REXX program or internal routine to the point of its invocation. If no internal routine (subroutine or function) is active, RETURN and EXIT are identical in their effect on the program that is being run, (see page “Purpose”...
Page 184: Say
Purpose expression SAY writes a line to the default output stream (the terminal) so the user sees it displayed. The result of expression may be of any length. If you omit expression, the null string is written. You can use the SET TERMOUT command to redirect SAY output. Example: data=100 Say data 'divided by 4 =>' data/4...
Page 185: Select
SELECT Purpose SELECT; WHEN expression END ; SELECT conditionally calls one of several alternative instructions. Each expression after a WHEN is evaluated in turn and must result in 0 or 1. If the result is 1, the instruction following the associated THEN (which may be a complex instruction such as IF, DO, or SELECT) is processed and control then passes to the END.
Page 186: Signal
SIGNAL SIGNAL Purpose SIGNAL labelname expression VALUE ERROR FAILURE HALT NOVALUE SYNTAX ERROR FAILURE HALT NOVALUE SYNTAX SIGNAL causes an unusual change in the flow of control (if you specify labelname or VALUE expression), or controls the trapping of certain conditions (if you specify ON or OFF). To control trapping, you specify OFF or ON and the condition you want to trap.
Page 187 The VALUE form of the SIGNAL instruction allows a branch to a label whose name is determined at the time of execution. This can safely effect a multi-way CALL (or function call) to internal routines because any DO loops, and so forth, in the calling routine are protected against termination by the call mechanism. Example: fred='PETE' call multiway fred, 7...
Page 188: Trace
TRACE TRACE Purpose TRACE number Normal Commands Error Failure Intermediates Labels Results Scan Or, alternatively: TRACE string symbol expression VALUE TRACE controls the tracing action (that is, how much is displayed to the user) during processing of a REXX program. (Tracing describes some or all of the clauses in a program, producing descriptions of clauses as they are processed.) TRACE is mainly used for debugging.
Page 189 Traces (that is, displays) all clauses before execution. Commands Traces all commands before execution. If the command results in an error or failure displays the return code from the command. Error Traces any command resulting in an error or failure from the command.
Page 190 TRACE Using the ? prefix, therefore, switches you alternately in or out of interactive debug. (Because the language processor ignores any further TRACE statements in your program after you are in interactive debug, use CALL TRACE '?' to turn off interactive debug.) Inhibits host command execution.
Page 191 message when interactive debug is entered, an indication of a syntax error when in interactive debug, or the traceback clauses after a syntax error in the program (see below). Identifies the result of an expression (for TRACE R) or the value assigned to a variable during >>>...
Page 192: Upper
UPPER UPPER Purpose This is a non-SAA instruction provided in REXX/CICS. UPPER variable UPPER translates the contents of one or more variables to uppercase. The variables are translated in sequence from left to right. The variable is a symbol, separated from any other variables by one or more blanks or comments. Specify only simple symbols and compound symbols.
Page 194: Search Order
Functions instruction, various other status information (TRACE and NUMERIC settings and so forth) is saved too. See the CALL instruction (page “Purpose” on page 135) for details about this. You can use SIGNAL and CALL together to call an internal routine whose name is determined at the time of execution;...
Page 195: Errors During Execution
Internal routines are not used if the function name is given as a literal string (that is, specified in quotation marks); in this case the function must be built-in or external. This lets you usurp the name of, say, a built-in function to extend its capabilities, yet still be able to call the built-in function when needed. Example: /* This internal DATE function modifies the /* default for the DATE function to standard date.
Page 196: Built-In Functions
Functions Built-in Functions REXX provides a rich set of built-in functions, including character manipulation, conversion, and information functions. Other built-in and external functions are generally available—see section “External Functions Provided in REXX/CICS” on page 200. The following are general notes on the built-in functions: v The parentheses in a function are always needed, even if no arguments are required.
Page 197: Abbrev (Abbreviation)
ABBREV (Abbreviation) ABBREV(information,info ,length returns 1 if info is equal to the leading characters of information and the length of info is not less than length. Returns 0 if either of these conditions is not met. If you specify length, it must be a positive whole number or zero. The default for length is the number of characters in info.
Page 198: Bitand (Bit By Bit And)
Functions returns an argument string or information about the argument strings to a program or internal routine. If you do not specify n, the number of arguments passed to the program or internal routine is returned. If you specify only n, the nth argument string is returned. If the argument string does not exist, the null string is returned.
Page 199: Bitor (Bit By Bit Or)
BITAND('12'x) -> BITAND('73'x,'27'x) -> BITAND('13'x,'5555'x) -> BITAND('13'x,'5555'x,'74'x) -> BITAND('pQrS',,'BF'x) -> BITOR (Bit by Bit OR) BITOR(string1 string2 returns a string composed of the two input strings logically inclusive-ORed together, bit by bit. (The encodings of the strings are used in the logical operation.) The length of the result is the length of the longer of the two strings.
Page 200: Center/Centre
Functions If binary_string is the null string, B2X returns a null string. If the number of binary digits in binary_string is not a multiple of four, then up to three 0 digits are added on the left before the conversion to make a total that is a multiple of four.
Page 201: Copies
v The instruction processed as a result of the condition trap (CALL or SIGNAL) v The status of the trapped condition. To select the information to return, use the following options. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.) Condition name returns the name of the current trapped condition.
Page 202: C2X (Character To Hexadecimal)
Functions If string is null, returns 0. Here are some examples: C2D('09'X) -> C2D('81'X) -> C2D('FF81'X) -> 65409 C2D('') -> C2D('a') -> /* EBCDIC */ If you specify n, the string is taken as a signed number expressed in n characters. The number is positive if the leftmost bit is off, and negative, in two's complement notation, if the leftmost bit is on.
Page 203: Date
Binary returns 1 if string contains only the characters 0 or 1 or both. returns 1 if string is a mixed SBCS/DBCS string. Dbcs returns 1 if string is a DBCS-only string enclosed by SO and SI bytes. Lowercase returns 1 if string contains only characters from the range a–z. Mixed case returns 1 if string contains only characters from the ranges a–z and A–Z.
Page 204 Functions base date, 1 January 0001, in the format: dddddd (no leading zeros or blanks). The expression DATE('B')//7 returns a number in the range 0–6 that corresponds to the current day of the week, where 0 is Monday and 6 is Sunday. Thus, this function can be used to determine the day of the week independent of the national language in which you are working.
Page 205: Dbcs (Double-Byte Character Set Functions)
DBCS (Double-Byte Character Set Functions) The following are all part of DBCS processing functions. DBADJUST DBBRACKET DBCENTER DBCJUSTIFY DBLEFT DELSTR (Delete String) DELSTR(string,n ,length returns string after deleting the substring that begins at the nth character and is of length characters. If you omit length, or if length is greater than the number of characters from n to the end of string, the function deletes the rest of string (including the nth character).
Page 206: D2X (Decimal To Hexadecimal)
Functions If you specify n, it is the length of the final result in characters; after conversion, the input string is sign-extended to the required length. If the number is too big to fit into n characters, then the result is truncated on the left.
Page 207: Externals
returns the REXX error message associated with error number n. The n must be in the range 0–99, and any other value is an error. Returns the null string if n is in the allowed range but is not a defined REXX error number.
Page 208: Fuzz
Functions The number is first rounded according to standard REXX rules, just as though the operation number+0 had been carried out. The result is precisely that of this operation if you specify only number. If you specify any other options, the number is formatted as follows. The before and after options describe how many characters are used for the integer and decimal parts of the result, respectively.
Page 209: Index
INDEX POS is the preferred built-in function for obtaining the position of one string in another. See page 189 for a complete description. INDEX(haystack,needle ,start returns the character position of one string, needle, in another, haystack, or returns 0 if the string needle is not found or is a null string.
Page 210: Lastpos (Last Position)
Functions LASTPOS (Last Position) LASTPOS(needle,haystack ,start returns the position of the last occurrence of one string, needle, in another, haystack. (See also the POS function.) Returns 0 if needle is the null string or is not found. By default the search starts at the last character of haystack and scans backward.
Page 211: Min (Minimum)
MAX( number returns the largest number from the list specified, formatted according to the current NUMERIC settings. Here are some examples: MAX(12,6,7,9) MAX(17.3,19,17.03) MAX(-7,-3,-4.3) MAX(1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,MAX(20,21)) Implementation maximum: You can specify up to 20 numbers, and can nest calls to MAX if more arguments are needed.
Page 212: Queued
Functions haystack. By default the search starts at the first character of haystack (that is, the value of start is 1). You can override this by specifying start (which must be a positive whole number), the point at which the search starts.
Page 213: Reverse
REVERSE REVERSE(string) returns string, swapped end for end. Here are some examples: REVERSE('ABc.') -> '.cBA' REVERSE('XYZ ') -> ' ZYX' RIGHT RIGHT(string,length ,pad returns a string of length length containing the rightmost length characters of string. The string returned is padded with pad characters (or truncated) on the left as needed.
Page 214: Storage
Functions Here are some examples: SPACE('abc def ') -> SPACE(' abc def',3) -> SPACE('abc def ',1) -> SPACE('abc def ',0) -> SPACE('abc def ',2,'+') -> STORAGE See section “External Functions Provided in REXX/CICS” on page 200. STRIP STRIP(string option returns string with leading or trailing characters or both removed, based on the option you specify. The following are valid options.
Page 215: Subword
SUBWORD SUBWORD(string,n ,length returns the substring of string that starts at the nth word, and is up to length blank-delimited words. The n must be a positive whole number. If you omit length, it defaults to the number of remaining words in string. The returned string never has leading or trailing blanks, but includes all blanks between the selected words.
Page 216 Functions (described later) was started or reset. The number has no leading zeros or blanks, and the setting of NUMERIC DIGITS does not affect the number. The fractional part always has six digits. Hours returns up to two characters giving the number of hours since midnight in the format: hh (no leading zeros or blanks, except for a result of 0).
Page 217: Trace
TRACE TRACE( option returns trace actions currently in effect and, optionally, alters the setting. If you specify option, it selects the trace setting. It must be one of the valid prefixes ? or ! or one of the alphabetic character options associated with the TRACE instruction (that is, starting with A, C, E, F, I, L, N, O, R, or S) or both.
Page 218: Userid
Functions decimal point. If you specify n, it must be a positive whole number or zero. The number is first rounded according to standard REXX rules, just as though the operation number+0 had been carried out. The number is then truncated to n decimal places (or trailing zeros are added if needed to make up the specified length).
Page 219: Verify
/* REXX EXEC - ASSIGN FIND VALUE OF FRED */ FRED = 7 'RLS VARPUT FRED \USERS\userid\' X = VALUE(FRED,,RLS) SAY X /* X now = 7 Notes: 1. If the VALUE function refers to an uninitialized REXX variable then the default value of the variable is always returned;...
Page 220: Wordindex
Functions WORDINDEX WORDINDEX(string,n) returns the position of the first character in the nth blank-delimited word in string or returns 0 if fewer than n words are in string. The n must be a positive whole number. Here are some examples: WORDINDEX('Now is the time',3) WORDINDEX('Now is the time',6) WORDLENGTH...
Page 221: X2B (Hexadecimal To Binary)
and end. The default value for start is '00'x, and the default value for end is 'FF'x. If start is greater than end, the values wrap from 'FF'x to '00'x. If specified, start and end must be single characters. Here are some examples: XRANGE('a','f') ->...
Page 222: External Functions Provided In Rexx/Cics
Functions X2D(hexstring returns the decimal representation of hexstring. The hexstring is a string of hexadecimal characters. If the result cannot be expressed as a whole number, an error results. That is, the result must not have more digits than the current setting of NUMERIC DIGITS. You can optionally include blanks in hexstring (at byte boundaries only, not leading or trailing) to aid readability;...
Page 223: Syssba
If you specify data, after the old value has been retrieved storage starting at address is overwritten with data (the length argument has no effect on this). Note: The STORAGE function can operate on storage above the 16MB line. Warning: The STORAGE function, which allows a REXX user to display and/or modify the virtual storage of the CICS region, can only be successfully invoked from an authorized exec or by an authorized user.
Page 224 Functions CICS TS for VSE/ESA: REXX Guide...
Page 225: Chapter 15. Parsing
All of the parsing instructions assign the parts of a source string into the variables named in a template. There are various parsing instructions because of differences in the nature or origin of source strings. (A summary of all the parsing instructions is on page 210.) © Copyright IBM Corp. 1992, 2009 /* same results */...
Page 226 Parsing The PARSE VAR instruction is similar to PARSE VALUE except that the source string to parse is always a variable. In PARSE VAR, the name of the variable containing the source string follows the keywords PARSE VAR. In the next example, the variable stars contains the source string. The template is star1 star2 star3.
Page 227: Templates Containing String Patterns
/* Alternative to period as placeholder stars='Arcturus Betelgeuse Sirius Rigil' parse var stars drop junk brightest rest A placeholder saves the overhead of unneeded variables. Templates Containing String Patterns A string pattern matches characters in the source string to indicate where to split it. A string pattern can be Literal string pattern One or more characters within quotation marks.
Page 228: Templates Containing Positional (Numeric) Patterns
Parsing Templates Containing Positional (Numeric) Patterns A positional pattern is a number that identifies the character position at which to split data in the source string. The number must be a whole number. An absolute positional pattern is v A number with no plus (+) or minus (-) sign preceding it or with an equal sign (=) preceding it v A variable in parentheses with an equal sign before the left parenthesis.
Page 229 A relative positional pattern is a number with a plus (+) or minus (-) sign preceding it. (It can also be a variable within parentheses, with a plus (+) or minus (-) sign preceding the left parenthesis; for details see section “Parsing with Variable Patterns”...
Page 230 Parsing │ 2 │ │var1 4 │ │ 1 │ │var2 2│ │ 4 var3 5│ │11 var4 │ │ 2 │ │var1 +2 │ │ ─3 │ │var2 +1│ │+2 var3 +1│ │+6 var4 │ └──┬──┘ └───┬────┘ └──┬───┘ └───┬───┘ └────┬─────┘ └───┬────┘ │...
Page 231: Parsing With Variable Patterns
v 'R E' v ' X' v ' X' The variable var1 receives 'R'; var2 receives 'E'. Both var3 and var4 receive ' X' (with a blank before the X) because each is the only variable in its section of the template. (For details on treatment of blanks, see page 204.) Parsing with Variable Patterns You may want to specify a pattern by using the value of a variable instead of a fixed string or number.
Page 232: Parsing Instructions Summary
Parsing Converts alphabetic characters to uppercase before parsing PARSE UPPER ARG PARSE UPPER EXTERNAL PARSE UPPER NUMERIC PULL PARSE UPPER PULL PARSE UPPER SOURCE PARSE UPPER VALUE PARSE UPPER VAR PARSE UPPER VERSION The ARG instruction is simply a short form of PARSE UPPER ARG. The PULL instruction is simply a short form of PARSE UPPER PULL.
Page 233: Advanced Topics In Parsing
When total=7 then new='purple' When total=9 then new='orange' When total=10 then new='green' Otherwise new=var1 Say new; exit Err: say 'Input error--color is not "red" or "blue" or "yellow"'; exit ARG converts alphabetic characters to uppercase before parsing. An example of ARG with the arguments in the CALL to a subroutine is in section “Parsing Multiple Strings.”...
Page 234: Combining String And Positional Patterns: A Special Case
Parsing This instruction consists of the keywords PARSE ARG and three comma-separated templates. (For an ARG instruction, the source strings to parse come from arguments you specify when you call a program or CALL a subroutine or function.) Each comma is an instruction to the parser to move on to the next string. Example: /* Parsing multiple strings in a subroutine num='3'...
Page 235: Parsing With Dbcs Characters
Parsing with DBCS Characters Parsing with DBCS characters generally follows the same rules as parsing with SBCS characters. Literal strings and symbols can contain DBCS characters, but numbers must be in SBCS characters. See “PARSE” on page 398 for examples of DBCS parsing. Details of Steps in Parsing The three figures that follow are to help you understand the concept of parsing.
Page 236 Parsing ┌────────────────────────────────────────┐ ┌────────────────────────────────┐ │START │Token is first one in template. │ │Length=length(source string) │Match start=1. Match end=1. └─────────┬──────────────────────┘ ┌────────── │ │ │ ┌───────────────────┐yes ┌────────────────────┐ │ │End of template? ├─── │Parsing complete. │ └─────────┬─────────┘ └────────────────────┘ │ │ ┌───────────────────┐ │ │CALL Find Next │...
Page 237 ┌────────────────────────────────────────────────┐ ┌─────────────┐ ┌────────────────────────────────┐ │Start: │yes │String start=match end. │End of ├─── │Match start=length + 1. │template? │ │Match end=length + 1. Return. └─────┬───────┘ └────────────────────────────────┘ ┌─────────────┐ ┌────────────────────────────────┐ │Token period │yes │ │or variable? ├─── │Step to next token. └─────┬───────┘ └────────────────────────────────┘ ┌─────────────┐ ┌─────────┐...
Page 238 ┌─────────────────────────┐ ┌────────────────────────┐ │Start: Match end <= │no │ │ string start? ├─── │String end=match start. │ └───────────┬─────────────┘ └────────────────────────┘ ┌─────────────────────────┐ │String end=length + 1. │ └───────────┬─────────────┘ ┌──────────────────────────────────────────────────────────────────────┐ │Substring=substr(source string,string start,(string end─string start))│ │Token=previous pattern. └───────────┬──────────────────────────────────────────────────────────┘ ───────────────────────────────────────────────┐ ┌─────────────────────────┐no │Any more tokens? ├─────────────┐ └───────────┬─────────────┘...
Page 239: Chapter 16. Numbers And Arithmetic
NUMERIC DIGITS setting, the number is expressed in exponential notation: 1e6 * 1e6 -> 1E+12 1 / 3E10 -> 3.33333333E-11 /* not 0.0000000000333333333 */ © Copyright IBM Corp. 1992, 2009 /* not 1000000000000 */...
Page 240: Definition
Numbers and Arithmetic Definition A precise definition of the arithmetic facilities of the REXX language is given here. Numbers A number in REXX is a character string that includes one or more decimal digits, with an optional decimal point. (See section “Exponential Notation” on page 222 for an extension of this definition.) The decimal point may be embedded in the number, or may be a prefix or suffix.
Page 241: Arithmetic Operation Rules-Basic Operators
an operation, when a number is rounded to the required precision.) The operation is then carried out under up to double that precision, as described under the individual operations that follow. When the operation is completed, the result is rounded if necessary to the precision specified by the NUMERIC DIGITS instruction.
Page 242: Arithmetic Operation Rules-Additional Operators
Numbers and Arithmetic The result is then rounded, counting from the first significant digit of the result, to the current setting of NUMERIC DIGITS. Division For the division: yyy / xxxxx the following steps are taken: First the number yyy is extended with zeros on the right until it is larger than the number xxxxx (with note being taken of the change in the power of ten that this implies).
Page 243 all bits have now been inspected, the initial calculation is complete; otherwise the accumulator is squared and the next bit is inspected for multiplication. When the initial calculation is complete, the temporary result is divided into 1 if the power was negative. The multiplications and division are done under the arithmetic operation rules, using a precision of DIGITS + L + 1 digits.
Page 244: Numeric Comparisons
Numbers and Arithmetic Numeric Comparisons The comparison operators are listed in section “Comparison” on page 117. You can use any of these for comparing numeric strings. However, you should not use ==, \==, ¬==, >>, \>>, ¬>>, <<, \<<, and ¬<< for comparing numbers because leading and trailing blanks and leading zeros are significant with these operators.
Page 245 For both large and small numbers some form of exponential notation is useful, both to make long numbers more readable, and to make execution possible in extreme cases. In addition, exponential notation is used whenever the “simple” form would give misleading information. For example: numeric digits 5 say 54321*54321...
Page 246: Numeric Information
Numbers and Arithmetic /* after the instruction */ Numeric form scientific 123.45 * 1e11 -> 1.2345E+13 /* after the instruction */ Numeric form engineering 123.45 * 1e11 -> 12.345E+12 Numeric Information To determine the current settings of the NUMERIC options, use the built-in functions DIGITS, FORM, and FUZZ.
Page 247: Chapter 17. Conditions And Condition Traps
As the name following the VAR subkeyword of a PARSE instruction v As a variable reference in a parsing template, a PROCEDURE instruction, or a DROP instruction. Note: SIGNAL ON NOVALUE can trap any uninitialized variables except tails in compound variables. © Copyright IBM Corp. 1992, 2009 NAME trapname...
Page 248: Action Taken When A Condition Is Not Trapped
Conditions and Condition Traps /* The following does not raise NOVALUE. */ signal on novalue a.=0 say a.z say 'NOVALUE is not raised.' exit novalue: say 'NOVALUE is raised.' You can specify this condition only for SIGNAL ON. SYNTAX raised if any language processing error is detected while the program is running. This includes all kinds of processing errors, including true syntax errors and “run-time”...
Page 249 Because these conditions (ERROR, FAILURE, and HALT) can arise during execution of an INTERPRET instruction, execution of the INTERPRET may be interrupted and later resumed if CALL ON was used. As the condition is raised, and before the CALL is made, the condition trap is put into a delayed state. This state persists until the RETURN from the CALL, or until an explicit CALL (or SIGNAL) ON (or OFF) is made for the condition.
Page 250: Condition Information
Conditions and Condition Traps Condition Information When any condition is trapped and causes a SIGNAL or CALL, this becomes the current trapped condition, and certain condition information associated with it is recorded. You can inspect this information by using the CONDITION built-in function (see page 178). The condition information includes: v The name of the current trapped condition v The name of the instruction processed as a result of the condition trap (CALL or SIGNAL)
Page 251 code following the SYNTAX label may PARSE SOURCE to find the source of the data, then call an editor to edit the source file positioned at the line in error. Note that in this case you may have to run the program again before any changes made in the editor can take effect.
Page 252 CICS TS for VSE/ESA: REXX Guide...
Page 253: Chapter 18. Rexx/Cics Text Editor
EDIT followed by a REXX File System (RFS) file identifier and an edit session is issued for this file. Note: If you specify REXX as a CICS transaction identifier with no exec name, the IBM supplied REXXTRY interactive utility (CICRXTRY exec) is issued. REXXTRY provides an interactive shell for performing REXX statements and commands.
Page 254: Screen Format
Text Editor Screen Format When you call the editor without a profile, the default screen definition is displayed as shown in the following figure. EDIT ---- POOL1:\USERS\USER1\TEST ------------------------------- COLUMN 1 73 COMMAND ===> 00000 ***************************** TOP OF DATA ************************ 00001 00002 00003 00004...
Page 255: Consecutive Block Commands
line just below it for input. You can also append a number to the end of the prefix command. This acts as a replication factor. If the number “5” is appended to the “I”, five lines are opened for input instead of one. Consecutive Block Commands The following commands work with consecutive blocks of lines and consist of two characters: Delete a block of lines...
Page 256: Command Line Commands
Text Editor Example: /* Macro to alter the setting of the REXX/CICS editor */ ADDRESS EDITSVR 'SET NUMBERS OFF' 'SET CURLINE 10' 'SET MSGLINE 2' 'SET CMDLINE TOP' 'SET CASE MIXED IGNORE' This example addresses the editor command environment and alters the editor settings. Example: /* Macro to use the REXX/CICS editor as an I/O interface */ ADDRESS EDITSVR...
Page 257: Backward
Notes: If arguments is not specified, any previously defined arguments are deleted. ARGS stores the default parameters to be passed to the program being edited when invoked with the text editor EXEC command. Operands arguments specifies the parameter string to be passed. If you do not specify arguments, any previously defined arguments are deleted.
Page 258: Cancel
Text Editor Return Codes Normal return Example 'BOTTOM' This example scrolls to the bottom of the file. CANCEL CANCEL CANCEL ends the current edit session without saving the changes. Return Codes Normal return Request failed Example 'CANCEL' This example quits the current editor session unconditionally, without saving any file changes. Notes 1.
Page 259: Change
Return Codes Normal request Invalid operand Example 'CASE MIXED RESPECT' This example sets the case to MIXED and the sensitivity to RESPECT. For more information on sensitivity, see the FIND command, section “FIND” on page 242. CHANGE CHANGE /string1/string2/ CHANGE changes a string in the file. Operands string1 specifies the string being replaced.
Page 260: Ctlchar
Text Editor BOTTOM displays the command line on the bottom line of the screen. Return Codes Normal return Invalid operand Example 'CMDLINE TOP' This example places the command line on the second line of the screen. CTLCHAR CTLCHAR character ESCAPE PROTECT NOPROTECT CTLCHAR sets a control character's function.
Page 261: Display
Operands number specifies the screen line number. Return Codes Normal return Invalid operand Example 'CURLINE 3' This example sets the current display line to screen line 3. Note The current line is displayed at the screen line number specified in this command. However, the current line cannot be displayed on line 1 because line 1 is reserved for the title line.
Page 262: Edit
Text Editor Example 'DOWN 5' This example scrolls forward through the file five lines. EDIT NONAME EDIT fileid lib.sublib(mem.type) LIB EDIT opens a new edit session. Operands fileid specifies the file ID of the file to be created or edited. lib.sublib(mem.type) specifies a VSE Librarian sublibrary and member to be edited.
Page 263: Exec
3. The default user profile macro that the editor tries to call is CICEPROF. The CICEPROF macro creates an ISPF/PDF like environment. A second profile macro, named CICXPROF, is provided. CICXPROF creates a VM/CMS XEDIT like environment. 4. If a file ID or VSE Librarian sublibrary member name is not specified, an RFS file with the special name, NONAME, is created.
Page 264: Find
Text Editor Operands fileid specifies the file ID of the file. If you do not specify fileid, the file is saved as the default file ID. Return Codes Normal return Invalid operand Not authorized Insufficient space in file pool Request failed Example 'FILE' This example saves the current file being edited, using the current file ID specification for the edit session.
Page 265: Forward
2. The search begins at the current line and continues downward until BOTTOM OF DATA is reached, or a match is made. If BOTTOM OF DATA is reached without a match, then the current line remains where it was before the FIND was processed, rather than making BOTTOM OF DATA the current line. FORWARD FORward FORWARD scrolls forward toward the end of the file for a specified number of screen displays.
Page 266: Input
Text Editor GETLIB lib.sublib(mem.type) GETLIB imports a member from a VSE Librarian sublibrary into the current edit session. The file is inserted after the current line. Operands lib.sublib(mem.type) specifies a VSE Librarian sublibrary and member name. Return Codes Normal return File not found Not authorized Request failed...
Page 267: Left
Request failed Example 'JOIN' This example joins the line that the cursor is on with the line immediately following it. LEFT LEFT number LEFT scrolls left in the file. Operands number specifies the number of characters to scroll. If you do not specify number, the screen scrolls left one character in the file.
Page 268: Macro
'MACRO POOL1:\USERS\USER1\TEST' This example calls the macro, POOL1:\USERS\USER1\TEST.EXEC. Note Macros have the ability to make calls to the REXX/CICS editor server. Any command that you can enter from the command line of the editor can be run from a macro. MSGLINE...
Page 269: Nulls
Operands number displays the message line on the corresponding screen line. does not display the message line. INFO displays messages in the header line. Return Codes Normal return Invalid operand Example 'MSGLINE 2' This example places the message line on screen line 2. NULLS NULLS NULLS controls whether the fields on the screen will be written with trailing blanks or trailing nulls.
Page 270: Pfkey
Text Editor Return Codes Normal return Invalid operand Example 'NUMBERS ON' This example displays sequential numbers in the prefix area. Note Line number sequencing is not done on the data within the edit session, but are pseudo line numbers associated with the file lines during the edit session only. PFKEY PFkey number...
Page 271: Qquit
BOTTOM displays the PF key line on the bottom line of the screen. number specifies the screen line number. removes the PF key from the display screen. Return Codes Normal return Invalid operand Example 'PFKLINE BOTTOM' This example places the PF key line on the bottom line of the screen. QQUIT QQuit QQUIT ends the current edit session without saving changes.
Page 272: Quit
Text Editor CMDLINE displays the current setting of the command line. For more information see the Text Editor command, section “CMDLINE” on page 237. COLUMN displays the starting column in the file that is displayed on the screen. displays the directory that is associated with the file. FILEID displays the name of the file being edited.
Page 273: Reserved
Note When the current file has been changed, the editor does not let you exit until either a save is done or you enter the QQUIT command. RESERVED REServed line HIGH NOHIGH RESERVED reserves a line on the screen for your output. Operands line specifies the line that is reserved and the text is displayed.
Page 274: Save
Text Editor RIght number RIGHT scrolls right in the file. Operands number specifies the number of characters to scroll. If you do not specify number, the screen scrolls to the right one character in the file. If you specify 0 for number, the file scrolls to the far right. Return Codes Normal return Invalid operand...
Page 275: Split
SORT SORT sorts the lines from the current line on down. Operands specifies that all the lines from the current line to the end of the file are sorted. specifies that the lines from the current line for the value of num are sorted. specifies that the lines are sorted in ascending order.
Page 276: Synonym
Text Editor STRIP STRIP strips the trailing blanks off all file lines. Return Codes Normal return Example 'STRIP' This example strips all trailing blanks of each file line. SYNONYM SYNONYM syn command SYNONYM assigns a command action to any other valid command. Operands specifies any valid command that executes the command action for which it is a synonym.
Page 277: Return Codes
Operands column specifies the last column you want to keep. Return Codes Normal return Invalid operand Example 'TRUNC 72' This example truncates all lines in the file to a length of 72 characters. Note This command is useful when you are working with data sets that have sequence numbers that require removing.
Page 278 CICS TS for VSE/ESA: REXX Guide...
Page 279: Chapter 19. Rexx/Cics File System
The following example shows a fully qualified file ID. POOL1 is the file pool name, USERS and USER1 are directory ID's, and TEST.EXEC is the file ID. Example: POOL1:\USERS\USER1\TEST.EXEC The following example shows file pools, directories, and files. © Copyright IBM Corp. 1992, 2009...
Page 280: Current Directory And Path
REXX File System (RFS). The current directory can be set using the CD command, see section “CD” on page 321. The CD command has a similar format to the IBM Personal Computer OS/2 and IBM Personal Computer DOS CD commands. The syntax is CD followed by the partially or fully qualified directory name.
Page 281: Security
The exec name is fully qualified, using the directory ID of each directory in the search before the search of each respective directory is performed. The fully qualified names are as follows: 'POOL1:\USERS\USER1\EXECS\TEST2.EXEC' 'POOL1:\TEST2.EXEC' 'POOL1:\USERS\USER1\TEST2.EXEC' When the REXX/CICS command EXEC is invoked, all three directories above are searched resulting in REXX/CICS finding the exec in the POOL1:\USERS\USER1 directory.
Page 282: Ckdir
File System AUTH authorizes access to RFS directories. Operands dirid specifies a REXX File System directory identifier. This is partially or fully qualified. See the CD command, “CD” on page 321, for more information. PRIVATE specifies that only the owner of the directory has read/write access to the files. This is the default. PUBLICR specifies that any user has read-only access to the files in the directory.
Page 283: Copy
Return Codes See the RFS command, section “RFS” on page 363. Example 'CKFILE POOL1:\USERS\USER1\TEST.EXEC' This example checks for a file called TEST.EXEC in the existing directory POOL1:\USERS\USER1. COPY RFS COPY fileid1 fileid2 COPY copies a file. Operands fileid1 specifies the source file identifier, it may be a fully or partially qualified directory and file identifier. fileid2 specifies the target file identifier, it may be a fully or partially qualified directory and file identifier.
Page 284: Diskw
File System DISKR reads records from an RFS file. Operands fileid specifies the file identifier. stem. specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 for more information. The default stem is DATA.. Return Codes See the RFS command, section “RFS”...
Page 285: Mkdir
GETDIR returns a list of the contents of the current or specified directory into the specified REXX array. Operands stem. specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 for more information.
Page 286: Rename
File System Example 'RFS RDIR POOL1:\USERS\USER1\DOCS' This example deletes a directory called DOCS in the existing directory POOL1:\USERS\USER1. RENAME RFS RENAME fileid1 fileid2 RENAME renames an RFS file to a new name. Operands fileid1 specifies the source file identifier, it may be a fully or partially qualified directory and file identifier. fileid2 specifies the source target file identifier, it may be a fully or partially qualified directory and file identifier.
Page 287: Macros Under The Rexx/Cics File List Utility
USER=USER1 - DIRECTORY=\USERS\USER1 FILENAME FILETYPE ATTRIBUTES RECORDS SIZE TEST1 EXEC FILE TEST2 EXEC FILE COMMAND ===> F1=HELP F2=REFRESH F3=END F7=UP 18 F8=DOWN 18 F11=EDIT F12=CANCEL Your user ID is displayed in the upper left hand corner. The current directory is displayed beside your user ID.
Page 288: Copy
File System When you type CD from the command line use the following syntax: dirid CD changes the current directory. Operands dirid specifies a REXX File System directory level identifier. This is partially or fully qualified. See the CD command, section “CD” on page 321, for more information. Example 'CD TEMP' This example changes the current directory to TEMP and updates the FLST display.
Page 289: Delete
DELETE When you type DELETE on the FLST command column use the following syntax: DELETE DELETE deletes a file. When you type DELETE from the command line use the following syntax: DELETE fileid Operands fileid specifies the file ID of the file the command acts on. Example 'DELETE TEST1.EXEC' This example, executed from the command line, deletes file TEST1.EXEC.
Page 290: Flst
File System Operands parameter specifies the parameters passed to the exec as arguments. Example 'EXEC / PARMS' This example, executed on the command column next to TEST3.EXEC, executes exec TEST3.EXEC and passes PARMS as the argument. When you type EXEC from the command line use the following syntax: EXEC fileid parameter Operands...
Page 291: Macro
'MACRO POOL1:\USERS\USER1\TEST' This example calls the macro, POOL1:\USERS\USER1\TEST.EXEC. Note Macros have the ability to make calls to the REXX/CICS FLST server. Any command that can be entered from the command line of the FLST can be run from a macro. PFKEY...
Page 292: Refresh
File System Note If you specify text, the PF key is set with the text. If you do not specify text, the PF key is processed. REFRESH When you type REFRESH on the FLST command column use the following syntax: REFRESH REFRESH refreshes the file list.
Page 293: Sort
SORT When you type SORT from the command line use the following syntax: SORT SORT sorts the file list. Operands specifies sorting the files by date/time. (This is the default.) specifies sorting the files by file name. FT specifies sorting the files by file type. specifies sorting the files by attribute.
Page 294: Flst Return Codes
File System Example 'SYNONYM DISCARD RFS DELETE' This example makes DISCARD equivalent to the RFS command DELETE. When you type UP from the command line use the following syntax: UP scrolls up one or more lines. Operands specifies the number of lines to be scrolled up. Example 'UP 5' This example scrolls backward through the list five lines.
Page 295: Chapter 20. Rexx/Cics List System
A fully qualified list ID consists of a \, each directory's ID in the path followed by a \, and the list ID. The following example shows a fully qualified list ID. USERS and USER1 are directory ID's, and TEST.DATA is the list ID. Example: \USERS\USER1\TEST.DATA © Copyright IBM Corp. 1992, 2009...
Page 296: Current Directory And Path
List System The following example shows RLS directories and lists. Example: TEST1.DATA USERS\ USER1\ TEST2.DATA DOCS\ TEST3.DOCUMENT File USER2\ LETTER.DOCUMENT PROJECT1\ PROD1.INFO DATA\ PROD1.DATA TEST1.DATA CHARTS\ CHART1.DATA CHART2.DATA This example shows a list directory structure. The root directory contains a file (TEST1.DATA) and two subdirectories (USERS and PROJECT1).
Page 297: Rls Commands
RLS commands Under the RLS command environment you issue commands to interface with RLS. If you set the command environment to RLS, you should not specify RLS in front of RLS commands. Example: 'RLS READ \USERS\USER1\TEST.DATA DATA.' This example reads the contents of the RLS list \USERS\USER1\TEST.DATA into the DATA. REXX compound variable.
Page 298: Lpush
List System *QUEUE* LPULL varname queid LPULL pulls a record from the top of the RLS queue. Operands varname specifies a simple REXX variable name. It does not end in a period, distinguishing a variable name from a stem name. *QUEUE* is a keyword specifying the special default name.
Page 299: Lqueue
LQUEUE *QUEUE* LQUEUE varname queid LQUEUE adds a record to the end of the RLS queue (FIFO). Operands varname specifies a simple REXX variable name. It does not end in a period, distinguishing a variable name from a stem name. *QUEUE* is a keyword specifying the special default name.
Page 300: Vardrop
List System Operands listname specifies the list identifier. stem. specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 for more information. The default stem is DATA.. is a keyword that enqueues on a file for update. Return Codes See the RLS command, section “RLS”...
Page 301: Varput
Operands varname specifies a simple REXX variable name. It does not end in a period, distinguishing a variable name from a stem name. dirid specifies a REXX List System directory level identifier. This is partially or fully qualified. See the CLD command, section “CLD”...
Page 302 List System stem. specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 for more information. The default stem is DATA.. Return Codes See the RLS command, section “RLS” on page 366. Example 'RLS WRITE \USERS\USER1\TEST.DATA DATA.' This example stores the entire contents of the REXX compound variable DATA.
Page 303: Chapter 21. Rexx/Cics Command Definition
REXX/CICS command definitions. The DEFCMD and DEFSCMD commands are used from within a REXX exec to define or change REXX command definitions. You can add or change your own command definitions, using the DEFCMD command, without any special authorization. You must be a REXX/CICS © Copyright IBM Corp. 1992, 2009...
Page 304: Command Arguments Passed To Rexx Programs
Command Definition authorized user to use DEFSCMD to change command definitions that affect other REXX/CICS users. See section “DEFCMD” on page 332 for more information on the DEFCMD command and section “DEFSCMD” on page 335 for more information on the DEFSCMD command. Command Arguments Passed to REXX Programs When a REXX/CICS command is written in REXX and that command is used, the REXX program (defined by DEFCMD or DEFSCMD) is either invoked or awakened (from a WAITREQ induced "sleep").
Page 305: Cicparms Control Block
Table 3. CICPARMS Control Block Offset (Decimal) Number of Bytes Field Name Description Reserved for IBM use. RXWBADDR REXX work block address which is required to be placed into register 10 before calls to the CICGETV stub routine (for REXX variable access)
Page 306: Non-Rexx Language Interfaces
Command Definition Non-REXX Language Interfaces REXX/CICS makes it possible to transparently convert a REXX process to a non-REXX process. To do this requires that non-REXX command routines should be able to access REXX variables in the REXX exec that issued the command to be processed. The routine used to accomplish this is called CICGETV and must be linkedited with your command routine, and called as is described below.
Page 307: Chapter 22. Rexx/Cics Db2 Interface
You can make each request by writing a valid SQL statement as a REXX command directed to the EXECSQL environment. The SQL statement is made up of the following elements: v SQL keywords v Pre-declared identifiers v Literal values. Use the following syntax: "EXECSQL statement" © Copyright IBM Corp. 1992, 2009...
Page 308 DB2 Interface ADDRESS EXECSQL "statement" "statement" SQL can exist on more than one line. Each part of the statement is enclosed in quotes and a comma delimits additional statement text as follows: ADDRESS EXECSQL "SQL text", "additional text", "final text" The following rules apply to embedded SQL: v You can pass the following SQL directly to the EXECSQL command environment: ALTER...
Page 309: Receiving The Results
For information about the meaning of specific SQLTYPE codes found in SQL_COLTYPE, see the DB2 Server for VSE & VM SQL Reference, SC09-2671. SQL_COLLEN.n Contains the length of each DB2 column whose data was returned by a SELECT statement. If the data type is DECIMAL, the scale is placed after the length of the column (after one blank space).
Page 310: Using The Sql Communications Area
DB2 Interface SQLCOLn.1 Some SELECT functions such as CURRENT SQLID, MAX, and AVG are not associated with a particular DB2 column. To view the results you must reference column name SQLCOLn.1. The n begins with, and is incremented by one, for each function included in the SELECT statement.
Page 311 Exit rc /*---------------------------------------*/ /* Display the members of the department */ /*---------------------------------------*/ Say 'Here are the members of Department' dept Do n = 1 to lastname.0 Say lastname.n phoneno.n Exit DB2 Interface Chapter 22. REXX/CICS DB2 Interface...
Page 312 DB2 Interface CICS TS for VSE/ESA: REXX Guide...
Page 313: Chapter 23. Rexx/Cics High-Level Client/Server Support
REXX command strings. REXX/CICS provides the optional ability for the environment name (specified in the ADDRESS instruction) to be the name of an application server. This capability is provided by the REXX/CICS DEFCMD and DEFSCMD commands. The DEFCMD command provides the ability to define (or redefine) REXX commands and environments, and it provides the ability to specify whether an environment-command combination is to be handled by a traditional CALLed routine or by an REXX application server.
Page 314: Rexx/Cics Client Exec Example
Because REXX/CICS allows REXX clients and servers to be recoded in non-REXX languages, performance intensive parts of an application system can be selectively rewritten, if needed. The FLST and EDIT commands that REXX/CICS provides are examples of client/server environments. REXX/CICS Client Exec Example...
Page 315: Rexx/Cics Server Exec Example
WORK = WORK + 1 'S2C WORK' varname return /* subroutine to process command2 */ Command2: return /* routine to shut down this server */ stop_server: say 'The Server is stopping' exit High-level Client/Server Support Chapter 23. REXX/CICS High-level Client/Server Support...
Page 316 High-level Client/Server Support CICS TS for VSE/ESA: REXX Guide...
Page 317: Chapter 24. Rexx/Cics Panel Facility
** START OF REXX PROGRAM USING THE PREVIOUS PANEL. /* program to query applicant's name and address */ lname = ''; /* null out all name parts */ fname = ''; mi = ''; mail_street = ''; © Copyright IBM Corp. 1992, 2009...
Page 318: Defining Panels
Panel Facility mail_city = 'DALLAS'; /* prefill the most likely response for city/state */ mail_state = 'TX'; mail_zip = ''; do forever; 'panel send applican cursor(lname)'; if rc > 0 then call error_routine; 'panel receive applican'; /* pseudo-conversational this would be separate */ if pan.aid = 'PF3' | pan.aid = 'PF12' then leave;...
Page 319: Define
characters are re-activated. Certain keyword combinations are incompatible and are not allowed while others which may seem meaningless are allowed. For example, INVISIBLE and color. This may be useful when the field attribute is changed dynamically within a REXX program (the invisible field can be made visible which makes color meaningful).
Page 320: Operands
Panel Facility Defcolor unprotect bright & Variable identifier Operands char specifies the control character being defined. VAriable defines a REXX variable identifier control character. Variable identifier control characters are used to associate Panel Facility control characters with REXX variable names. More than one variable control character can be defined at one time.
Page 321: Defining The Actual Panel Layout With The '.Panel' Verb
Notes: 1. When you do not specify a default color, the color is based on the field type and intensity values: protect/normal displays blue, protect/bright displays white, unprotect/normal displays green, and unprotect/bright displays red. 2. If any field on a panel has explicitly specified a color (including DEFCOLOR), all bright fields with DEFCOLOR or no color specified are displayed white and all normal fields with DEFCOLOR or no color specified are displayed green.
Page 322: Panel
Panel Facility The panel layout is close to what you see, with the exception of the control characters and the imbedded variables which are not shown when the panel is displayed. A field typed on the third line after the .PANEL starting at column ten is positioned on the terminal screen third line, column ten.
Page 323: Operands
.PANEL panel_name protect_cc skip_cc unprotect_cc Operands panel_name specifies the panel being defined. It must be one to eight characters in length and follow the rules for REXX File System file names. (See Chapter 19, “REXX/CICS File System,” on page 257, for more information.) Note: The panel_name must be the same as the RFS file name.
Page 324: Panel Runtime
Panel Facility The characteristics of the PANEL command follow. v All the arguments or keywords are not meaningful or valid for all commands. v The last panel command in a REXX exec is the END command. This releases any storage held by previous panel commands.
Page 325: Operands
NORmal GReen BRight INVisible BLUe TUrquoise WHite YEllow PInk DEfcolor Operands Send is the panel command that sends a panel. Receive is the panel command that receives a panel. Converse is the panel command that sends a panel and waits for operator input. Test is the panel command that displays a panel.
Page 326: Options
Panel Facility the field. The field list must be enclosed with parenthesis. Only the attributes stated are changed and the other attributes default to what was statically defined. A field defined originally as RED and UNDERLINE remains underlined if only blue is stated dynamically. ALarm (specified for SEND and CONVERSE only) sounds the bell when displaying panel.
Page 327: Panel Variables
Notes: 1. When you do not specify a default color, the color is based on the field type and intensity values: protect/normal displays blue, protect/bright displays white, unprotect/normal displays green, and unprotect/bright displays red. 2. If any field on a panel has explicitly specified a color (including DEFCOLOR), all bright fields with DEFCOLOR or no color specified are displayed white and all normal fields with DEFCOLOR or no color specified are displayed green.
Page 328: Panel Facility Return Code Information
Codes and Input Codes” on page 308 for more information. PAN.LOC Internal location code. Three to four-digit number used by IBM support. If the REXX variable RC contains the value 10, the PAN.LOC should be used in conjunction with PAN.REA for error determination.
Page 329: Return Codes
CICS command error; the CICS EIBRESP is returned in the panel reason code. If the error is not programmer resolvable, save and collect as much information as needed to recreate the error and contact IBM support. RFS errors; reason code contains the RFS return code Internal system error;...
Page 330: State Codes And Input Codes
Panel Facility Variable value was too long and was truncated to fit output field Text field was truncated. Check to see if explicit length did not force a subsequent field to overlay another field. Bad or missing panel command. It should be SEND, RECEIVE, CONVERSE, TEST, or END. A modified field was received but it had no corresponding input field definition.
Page 331 Numeric extended highlight (blink/reverse/underline) Cursor Pad() Variable Drop State codes State codes for 20xx location codes: panel commands (send/receive/converse/...) File() Cursor() Position() Alarm Noerase Keyboard lock (lockkb/freekb) Clrinput Attribute field type (protect/skip/unprotect) color (red/blue/green/...) Intensity (bright/normal/invisible) Justify (left/right/nojustify) Numeric extended highlight (blink/reverse/underline) Cursor Pad() closing parenthesis of the ATTRIBUTE argument...
Page 332: Location Codes
Panel Facility State Codes State codes for 12xx location codes: panel name protect/skip field unprotect field text within a protect/skip field (not implemented yet) explicit input field length number unprotect variable protect/skip variable Input codes Input codes for 12xx location codes: Plain displayable text Explicit length number Protect field control character...
Page 333: Example 2
Example 2 .DEFINE > prot green .DEFINE < unprot underline white .DEFINE + var service. .DEFINE % skip turq .PANEL service > Panel service &disp_date % &salutation % Tab the cursor to the type of service wanted and press the ENTER key. <+>...
Page 334: Example 4
Panel Facility Example 4 .DEFINE ) protect bright .DEFINE + drop .DEFINE & var msg. A panel to display output dynamic messages. .PANEL msgbox2 )+-------------------------------------------+# )| & )| & )+-------------------------------------------+# Example 5 .DEFINE > skip blue .DEFINE < skip green right .DEFINE % var center_days.
Page 335: Panel Facility
'PANEL SEND SIGNON' CLR_INP_FIELDS PATH_NAME , 'CURSOR(' CURS_NAME ')' ATTR_STRING IF RC > 4 THEN /* more than a warning */ SIGNAL ERROR /* clean up and exit */ 'PANEL RECEIVE SIGNON ' IF RC > 4 THEN SIGNAL ERROR /* clean up and exit */ ITERATE /* redisplay panel */ CLR_INP_FIELDS = ''...
Page 336 Panel Facility END; /* select */ END; /* do forever */ EXIT IF SYMBOL('ACCOUNT.ACC_NUM') == 'VAR' THEN RETURN(1) ELSE RETURN(0); NON_ITEMIZE_ROUTINE: QUERY_RET_ROUTINE: 'PANEL SEND MSGBOX1 POS(7 10) NOERASE' PATH_NAME IF RC > 4 THEN SIGNAL ERROR; 'PANEL RECEIVE MSGBOX1' IF RC > 4 THEN SIGNAL ERROR;...
Page 337 NUM_OF_DAYS.2 = 29; ELSE NUM_OF_DAYS.2 = 28; FIRST_WEEKDAY = (TOT_DAYS+1) // 7; FIRST_WEEKDAY_SAVE = FIRST_WEEKDAY; DISP_CENTER_MON = MONTH_NAME.MONTH; /* center display month name */ CENTER_DAYS. = ''; /* null out all unused month days */ /* starting at the first weekday of the month fill in center month */ DO I = FIRST_WEEKDAY+1 TO NUM_OF_DAYS.MONTH + FIRST_WEEKDAY ;...
Page 338 Panel Facility LEFT_MONTH = 12; ELSE LEFT_MONTH = MONTH - 1; FIRST_WEEKDAY = (TOT_DAYS - NUM_OF_DAYS.LEFT_MONTH +1) // 7; DISP_LEFT_MON = MONTH_NAME.LEFT_MONTH; LEFT_DAYS. = ''; DO I = FIRST_WEEKDAY+1 TO NUM_OF_DAYS.LEFT_MONTH + FIRST_WEEKDAY ; LEFT_DAYS.I = I - FIRST_WEEKDAY; END; END;...
Page 339 (SUBSTR(DATE_SAVE,7,2)+FIRST_WEEKDAY_SAVE); ATTR_STRING = 'ATTRIB(' CUR_DAY_FIELD 'RED )' ; END; END; /* select */ 'PANEL RECEIVE CALENDAR' END; /* do forever loop */ ERROR: SAY 'RETURN CODE ' RC SAY 'REA CODE ' PAN.REA SAY 'LOC CODE ' PAN.LOC EXIT; EXIT_ROUTINE: 'PANEL END';...
Page 340 CICS TS for VSE/ESA: REXX Guide...
Page 341: Chapter 25. Rexx/Cics Commands
REXX special variable RC. Also, EIB fields are placed in REXX variables DFHEIBLK, EIBRESP, EIBRESP2, and EIBRCODE. v For an explanation of the return code values see the CICS Transaction Server for VSE/ESA Application Programming Reference. For information on return codes with negative values, see Appendix B, “Return Codes,”...
Page 342: Authuser
Commands AUTHUSER Note: This is an authorized command. AUTHUSER userid AUTHUSER authorizes a list of user IDs. Operands userid is a CICS signon user ID that becomes REXX/CICS authorized. Return Codes Normal return 2602 Invalid operand or operand missing 2621 Specified user ID invalid length 2642 Error storing user ID...
Page 343: Operands
dirid CD changes the RFS file system directory. Operands dirid specifies a partial or full REXX File System directory that becomes the new current working directory for you. If dirid is not specified, the current working directory is retrieved and placed in the REXX special variable RESULT, instead of changing the current working directory.
Page 344 Commands for execs. CICS TS for VSE/ESA: REXX Guide...
Page 345: Ceda
CEDA CEDA RDO_Command Executes a CEDA command for resource definition online (RDO). Operands RDO_Command specifies a command string passed as input to the CEDA transaction program. Return Codes specifies the return code passed back by CICS if an error is detected Normal return -101 Invalid command...
Page 346: Cemt
Commands CEMT CEMT master_term_cmd CEMT executes a CICS master terminal command from REXX. Operands master_term_cmd specifies a command string passed as input to the CEMT transaction program. Return Codes specifies the return code passed back by CICS if an error is detected Normal return -101 Invalid command...
Page 347: Cld
dirid CLD changes your current RLS list directory. Operands dirid specifies a partial or full REXX List System directory that becomes the new current working directory for you. If dirid is not specified, the current working directory is retrieved and placed into the REXX variable RESULT, instead of changing the current working directory.
Page 348: Convtmap
Commands CONVTMAP CONVTMAP lib.sublib(mem.type) rfs_fileid CONVTMAP reads a VSE Librarian sublibrary member and converts a DSECT (created by a previously assembled BMS map) into a structure, and stores the result in a REXX File System file. The BMS map used as input to CONVTMAP must be in assembler language format. The resulting output file is formatted as a REXX file structure.
Page 349: Copyr2S
COPYR2S Note: This is an authorized command. COPYR2S source_vname COPYR2S copies REXX variable contents to GETMAINed storage. Operands source_vname specifies the REXX variable containing the value copied to the previously GETMAINed area. Note: This value should be in quotes so that substitution does not occur. specifies that all the REXX variables are copied.
Page 350: Return Codes
Commands Return Codes Normal return 2002 Invalid operand 2021 Invalid structure definition 2022 Invalid variable structure definition 2023 Field name not found 2025 Failure processing GETVAR request 2026 Invalid numeric input 2027 RFS read error 2028 Invalid offset 2029 Invalid length value Examples /* Needed if entering example from the REXXTRY utility */ 'PSEUDO OFF'...
Page 351: Copys2R
COPYS2R Note: This is an authorized command. COPYS2R stor_anchor COPYS2R copies data from GETMAINed storage to a REXX variable. Operands stor_anchor specifies the REXX variable containing the anchor for the target storage area that was GETMAINed earlier. This anchor consists of four bytes, containing the address of the earlier GETMAINed storage. specifies that all the REXX variables are copied.
Page 352: Return Codes
Commands Return Codes Normal return 2102 Invalid operand 2121 Invalid structure definition 2122 Invalid variable structure definition 2123 Field name not found 2125 Failure processing GETVAR request 2126 Invalid numeric input 2127 RFS read error 2128 Invalid offset 2129 Invalid length value Example var1 = '' /* set REXX variable VAR1 to null */ struct1 = 'flda 4 fldb 2 fldc 3 fldd 8 flde 5'...
Page 353: C2S
REXX variable to copy from. server_rexx_varname is an optional name that specifies the server REXX variable to copy into. If it is not specified, it defaults to the same as the client_rexx_varname. Return Codes Normal return...
Page 354: Defcmd
REXX command server processing this command (or commands). If this server exec is already running then this command is routed to the executing server. If a REXX server by this name is not running, then Automatic Server Initiation (ASI) is used to start the server automatically.
Page 355: Return Codes
CICSLOAD. REXX is a keyword indicating that the processing agent for this REXX command is a REXX exec that operates as a command server. AUTH Note: This is an authorized option. is a keyword indicating that this is an authorized REXX/CICS command. It is a command that can only be executed by an authorized REXX/CICS user (specified on AUTHUSER command) or from within an exec loaded from an authorized library.
Page 356 Commands from the REXX user (programmer), a command can be quickly written in REXX and later transparently rewritten in another language, if it becomes performance critical. CICS TS for VSE/ESA: REXX Guide...
Page 357: Defscmd
REXX command server processing this command (or commands). If this server exec is already running then this command is routed to the executing server. If a REXX server by this name is not running, then Automatic Server Initiation (ASI) is used to start the server automatically.
Page 358: Return Codes
REXX is a keyword indicating that the processing agent for this REXX command is a REXX exec that operates as a command server. AUTH is a keyword indicating that this is an authorized REXX/CICS command. It is a command that can only be executed by an authorized REXX/CICS user (specified on AUTHUSER command) or from within an exec loaded from an authorized library.
Page 359 Commands 5. REXX commands can be written in REXX. These REXX commands in turn call other REXX commands which are written in REXX, in a building block fashion. Since DEFSCMD hides the implementation detail from the REXX user (programmer), a command can be quickly written in REXX and later transparently rewritten in another language, if it becomes performance critical.
Page 360: Deftrnid
Commands DEFTRNID Note: This is an authorized command. DEFTRNID trnid execname DEFTRNID is a region-wide authorized command that can be used to define the name of an exec to be invoked for a particular CICS transaction identifier. Operands trnid specifies a one to four character CICS transaction ID. execname specifies a 1 to 17 character REXX/CICS exec name, in the form: filename.filetype if it is in the REXX File System.
Page 361: Dir
dirid ( stem. DIR displays the current directory contents or optionally returns the directory contents in a REXX compound variable. Operands dirid specifies the partial or full REXX File System directory that is displayed. If you omit this, then the current directory is displayed.
Page 362: Edit
Commands EDIT NONAME EDIT fileid lib.sublib(mem.type) LIB EDIT opens a new edit session. Operands NONAME a file ID is not specified. This is the default. fileid specifies the file ID of the file to be created or edited. lib.sublib(mem.type) specifies a VSE Librarian sublibrary and member to be edited. is a keyword that follows a VSE Librarian sublibrary member name when a sublibrary member is being edited.
Page 363: Exec
EXEC EXEC execid args EXEC calls a REXX exec at a lower level (as a nested exec). All variables for this new exec are kept separate from the higher level exec, which is suspended until the nested exec ends. Operands execid specifies the 1 to 17 character identifier of the exec.
Page 364: Execdrop
Commands EXECDROP Note: This is an authorized command. EXECDROP AUTHClib AUTHElib PROClib name EXECDROP removes an EXECLOADed exec from virtual storage. Operands AUTHClib indicates that member was loaded from an authorized command sublibrary. AUTHElib indicates that member was loaded from an authorized exec sublibrary. indicates that a VSE Librarian sublibrary and member has been specified.
Page 365: Note
Commands Note If a partial directory ID is given, it is temporarily appended to the end of the current working directory value to get a fully qualified directory ID. Chapter 25. REXX/CICS Commands...
Page 366: Execio
Commands EXECIO EXECIO lines READ tsqname WRITE tsqname EXECIO performs file input/output to a CICS temporary storage queue. Operands lines specifies the number of lines to read or write. An asterisk (*) is a special case that is specified for READ operations only, and indicates that the file is read from the target line (or line 1 if no target line is specified) to the end of the file.
Page 367 2. If a stem is specified for a READ operation (and a stem should be specified if more than one record is read), the actual number of records read is placed into stem.0. 3. Use the CICS-supplied CEBR transaction to browse temporary storage queues. For example, enter: CEBR QUEUE1 to look at the queue created above.
Page 368: Execload
Commands EXECLOAD Note: This is an authorized command. EXECLOAD AUTHClib AUTHElib PROClib name EXECLOAD loads an exec into virtual storage. Operands AUTHClib indicates that member must be loaded from an authorized command sublibrary. AUTHElib indicates that member must be loaded from an authorized exec sublibrary. indicates that a VSE Librarian sublibrary and member has been specified.
Page 369: Example
Example 'EXECLOAD POOL1:\USERS\USER2\TEST.EXEC (RFS' This example loads the exec TEST.EXEC from RFS into storage. Subsequent calls of TEXT.EXEC will use the loaded copy. Notes 1. If an exec is loaded into virtual storage, it is automatically shared by all users. 2.
Page 370: Execmap
Commands EXECMAP EXECMAP EXECMAP returns the sublibraries and members, the number of users, the descriptor table start (in hex), and the amount of storage required of the execs that have been loaded using EXECLOAD. Return Codes Normal return 1623 EXECLOAD directory not found Example 'EXECMAP' If the exec POOL1:\USERS\USER1\TEST.EXEC had been EXECLOADed then this display would result.
Page 371: Export
EXPORT EXPORT rfs_fileid lib.sublib(mem.type) EXPORT exports an RFS file to a VSE Librarian sublibrary member. Operands rfs_fileid specifies a fully qualified REXX File System file ID. lib.sublib(mem.type) specifies a VSE Librarian sublibrary and member. Return Codes Normal return 1701 Invalid command 1702 Invalid operand 1723...
Page 372: Filepool
Commands FILEPOOL Note: This is an authorized command. FILEPOOL DEFINE poolid dirid fileid ( FORMAT poolid ADD poolid fileid FILEPOOL performs RFS file pool administration activities. Operands DEFINE defines a new RFS file pool. poolid specifies the name of the target file pool. dirid specifies the CICS file identifier of the file pool directory.
Page 373: Example
Commands Example 'FILEPOOL DEFINE POOL1 REXXDIR1 REXXLIB1 (USER' This example defines file pool POOL1 and tells RFS the CICS file definition to use is REXXLIB1. It also indicates to the FILEPOOL FORMAT command to issue an RFS MKDIR to build the \USERS directory. Note This is an authorized command, performed by a REXX/CICS administrator or systems programmer.
Page 374: Flst
Commands FLST FLST dirid FLST calls the file list utility to work with the files. Operands dirid specifies an optional full or partial directory ID that a file list is displayed. If you do not specify dirid, it defaults to the current working directory. Return Codes FLST returns the return code given by RFS.
Page 375: Getvers
GETVERS GETVERS GETVERS retrieves the current REXX/CICS, program name, version, and compile time information, and places it into the REXX variable VERSION. The returned information is in the form: VxRyMmmmm mm/dd/yy hh.mm, where: specifies the REXX/CICS Version number. specifies the REXX/CICS Release number. mm/dd/yy specifies the compile date for the REXX/CICS base program.
Page 376: Help
Commands HELP HELP search_term HELP browses or searches this book (the IBM REXX Development System for CICS/ TS for VSE/ESA) online. Operands search_term specifies the string you want located. Return Codes specifies the return code passed by from internal RFS or PANEL commands...
Page 377: Import
IMPORT IMPORT lib.sublib(mem.type) rfs_fileid IMPORT imports a VSE Librarian sublibrary member to an RFS file. Operands lib.sublib(mem.type) specifies a VSE Librarian sublibrary and member. rfs_fileid specifies a fully qualified REXX File System file ID. Return Codes Normal return 1701 Invalid command 1702 Invalid operand 1723...
Page 378: Listcmd
Commands LISTCMD LISTCMD envname cmdname LISTCMD lists REXX command definition information (previously specified by DEFCMD). Operands envname specifies the name of the command environment defined using DEFCMD or DEFSCMD. cmdname specifies the name of a command specified in DEFCMD or DEFSCMD. Return Codes Normal return Invalid environment name...
Page 379: Listclib
LISTCLIB LISTCLIB stem. LISTCLIB displays the names of the authorized command libraries to the terminal or to a specified stem array, if a stem has been specified. The libraries are displayed in their search order. Operands stem. specifies the name of a stem. (A stem must end in a period.) The information returned is the name of each VSE Librarian sublibrary specified on the last SETSYS AUTHCLIB command.
Page 380: Listelib
Commands LISTELIB LISTELIB stem. LISTELIB displays the names of the authorized exec libraries to the terminal or to a specified stem array, if a stem has been specified. The libraries are displayed in their search order. Operands stem. specifies the name of a stem. (A stem must end in a period.) The information returned is the name of each VSE Librarian sublibrary specified on the last SETSYS AUTHELIB command.
Page 381: Listpool
LISTPOOL LISTPOOL stem. LISTPOOL displays RFS file pool information to the terminal or to a specified stem array, if a stem has been specified. Operands stem. specifies the name of a stem. (A stem must end in a period.) Refer to section “Stems” on page 123 for more information.
Page 382: Listtrnid
Commands LISTTRNID Note: This is an authorized command. LISTTRNID LISTTRNID lists the current transaction ID definitions created by the DEFTRNID command. Return Codes Normal return 2325 Error retrieving trantable information Example 'LISTTRNID' The CICSTART exec defines the default transactions and their EXEC names. The resulting display is: TRNID EXEC name REXX...
Page 383: Path
PATH PATH dirid lib.sublib PATH defines the search path for REXX execs. Operands dirid specifies one or more fully qualified REXX File System directories that are searched when you are attempting to locate an exec to be executed. A full RFS directory ID starts with a pool ID and is in the form: POOL1:\dirid1\...\diridn When more than one directory ID is specified, a blank is used to separate them.
Page 384: Pseudo
Commands PSEUDO PSEUDO PSEUDO turns the pseudo-conversational mode on or off. Operands enables automatic pseudo-conversational support so that when the next REXX PULL instruction or REXX/CICS WAITREAD command is encountered in the current exec, instead of a conversational terminal read occurring immediately, an EXEC CICS RETURN TRANSID is used to suspend the exec until terminal input occurs, and then the terminal read occurs.
Page 385: Rfs
PRIVATE AUTH dirid PUBLICR PUBLICW SECURED CKDIR dirid CKFILE fileid COPY fileid1 fileid2 DELETE fileid DATA. DISKR fileid stem. DATA. DISKW fileid stem. GETDIR stem. dirid MKDIR dirid RDIR dirid RENAME fileid1 fileid2 RFS performs file input/output to the REXX File System. Operands AUTH is a command that authorizes access to RFS directories.
Page 386: Return Codes
Commands fileid2 specifies the target file identifier, it may be a fully or partially qualified directory and file identifier. DELETE is a command that deletes an RFS file. fileid specifies the source file identifier, it may be fully or partially qualified. DISKR is a command that reads records from an RFS file.
Page 387: Note
Commands Note File access security checking is performed at the directory level, rather than the file level. If a specified file ID is not a fully qualified ID, the current directory or PATH directories are used in an attempt to resolve the partial name into a fully qualified name;...
Page 388: Rls
Commands CKDIR dirid DELETE listname *QUEUE* LPULL varname queid *QUEUE* LPUSH varname queid *QUEUE* LQUEUE varname queid MKDIR dirid DATA. READ listname stem. VARDROP varname dirid VARGET varname dirid VARPUT varname dirid DATA. WRITE listname stem. RLS performs list input/output to the REXX List System. Operands CKDIR is a command that checks for an existing RLS directory level.
Page 389: Return Codes
MKDIR is a command that creates a new RLS directory level. READ is a command that reads records from an RLS list into a stem. listname specifies the list identifier. stem. specifies the name of a stem. (A stem must end in a period.) Refer to section “Stems” on page 123 for more information.
Page 390: Scrninfo
Commands SCRNINFO SCRNINFO SCRNINFO returns a two-digit decimal screen height (in lines) in the variable SCRNHT, and returns a three-digit decimal screen width (in columns) in the variable SCRNWD. Return Codes specifies the return code passed back by CICS if an error is detected Normal return -499 Internal error...
Page 391: Set
LANG CANFR FRANC ESPAN UCENG HANZI KANJI 1024 MAXVSTOR kilobytes RETRieve pfkeynn TERM TERMOUT NOTERM CANCEL Notes: If no parameters are passed to the SET command, then SET creates a stem variable (SET.) that contains all of the processing options for the user that was created by the SET or SETSYS commands.
Page 392: Return Codes
Commands RETRieve allows a PF key being set to retrieve the last line entered. pfkeynn specifies the PF key number. TERMOUT sends terminal line-mode output to a CICS temporary storage queue (for example: SAY and TRACE output) even when a terminal is attached. TERM specifies that linemode output will be sent to the terminal.
Page 393: Setsys
SETSYS Note: This is an authorized command. SETSYS LANG CANFR FRANC ESPAN UCENG HANZI KANJI MAXVSTOR RETRieve pfkeynn PSEUDO AUTHClib AUTHElib SETSYS sets the REXX/CICS processing options for the system. Operands LANG specifies that one of the following languages are available: English CANFR Canadian French...
Page 394: Return Codes
Commands pfkeynn specifies the PF key number. PSEUDO establishes the default region-wide REXX/CICS automatic pseudo-conversational setting. For more information on the PSEUDO command, see section “PSEUDO” on page 362. specifies that the automatic pseudo-conversational setting is on. This is the default. specifies that the automatic pseudo-conversational setting is off.
Page 395: S2C
No client available Example 'S2C VARA VARB' This example shows the contents of the server REXX variable VARA copying into the client REXX variable VARB. The length of VARB is the same as the length of VARA. Notes 1. The maximum length allowed of a varname, for this command, is 250 characters. If a longer name is specified, only the first 250 characters are used.
Page 396: Termid
Commands TERMID TERMID TERMID returns the four-character CICS terminal ID from the CICS field EIBTRMID in the variable TERMID. Return Codes Normal return 2921 Error in obtaining terminal ID 2928 Error setting TERMID value Example 'TERMID' This example places the CICS terminal ID from the CICS field EIBTRMID in the variable TERMID. CICS TS for VSE/ESA: REXX Guide...
Page 397: Waitread
WAITREAD WAITREAD WAITREAD performs full screen terminal input and places the results into the compound variable with: WAITREAD.0 containing the number of elements returned. WAITREAD.1 containing the AID description. WAITREAD.2 containing the cursor position. WAITREAD.3 through WAITREAD.n remaining 3270 fields that have been modified. Return Codes Normal return 3021...
Page 398: Waitreq
3123 Error saving request variable 3199 Internal error Note: The return code reflected to the client program is the value of the REXX server variable at entry to the WAITREQ command or at exit of the server exec. Example 'WAITREQ' This example causes the server exec to be suspended until another request for the server is encountered.
Page 400 CICS TS for VSE/ESA: REXX Guide...
Page 401: Appendix A. Error Numbers And Messages
In these messages, the term “language processor” refers to the REXX/CICS interpreter. In addition to the following error messages, the language processor issues this terminal (unrecoverable) message: CICREX255T Insufficient storage for Exec interpreter © Copyright IBM Corp. 1992, 2009 Error code CICS message Error 26 CICREX466E...
Page 402 Error Numbers and Messages System action: Execution is terminated at the point of the error. The following are the REXX error messages: CICREX218E Error 46 Invalid variable reference Explanation: Within an ARG, DROP, PARSE, PULL, or PROCEDURE instruction, the syntax of a variable reference (a variable whose value is to be used, indicated by its name being enclosed in parentheses) is incorrect.
Page 403 When a1=b1 then When a1=b1 then DO Say 'A1 equals B1' Say 'A1 equals B1' exit exit Otherwise nop Otherwise nop System action: Execution stops. User response: Make the necessary corrections. CICREX455E Error 8 running fn ft, line nn: Unexpected THEN or ELSE Explanation: The language processor has found a THEN or an ELSE that does not match a corresponding IF clause.
Page 404 Error Numbers and Messages A-Z a-z 0-9 (Alphamerics) @ # £ $ . ? ! _ (Name Characters) & * ( ) - + = \ ¬ ' " ; : < , > / | (Special Characters) If surrounded by X'0E' (shift-out) and X'0F' (shift-in), and if ETMODE is on, the following are also valid characters: X'41' - X'FE' (DBCS Characters)
Page 405 passed back from an EXIT or RETURN instruction (when a REXX program is called as a command) is not a whole number or will not fit in a general register. This error may be due to mistyping the name of a symbol so that it is not the name of a variable in the expression on any of these statements.
Page 406 Error Numbers and Messages Say Enter A, B, or C should be written as: Say 'Enter A, B, or C' System action: Execution stops. User response: Make the necessary corrections. CICREX474E Error 39 running fn ft, line nn: Evaluation stack overflow Explanation: The language processor was not able to evaluate the expression because it is too complex (many nested parentheses, functions, and so forth).
Page 407 System action: Execution stops. User response: Report any occurrence of this message to your IBM representative. CICREX482E Error 19 running fn ft, line nn: String or symbol expected Explanation: The language processor expected a symbol following the CALL or SIGNAL instructions, but none was found.
Page 408 Error Numbers and Messages v NUMERIC FUZZ expression v OPTIONS expression v SIGNAL VALUE expression v TRACE VALUE expression. (FUZZ must be smaller than DIGITS.) System action: Execution stops. User response: Make the necessary corrections. CICREX489E Error 38 running fn ft, line nn: Invalid template or pattern Explanation: The language processor found an incorrect special character, for example %, within a...
Page 409: Appendix B. Return Codes
Command not valid from this location Directory not empty Missing operand Missing file pool data record. File pool is probably not formatted. Internal error EDITOR and EDIT Normal return Invalid command Invalid operand File not found Not authorized © Copyright IBM Corp. 1992, 2009...
Page 410: Dir
Return Codes Insufficient space in filepool Request failed Invalid file ID Search argument not found File is currently being edited Number out of range Cursor is not in file area Out of virtual storage Prefix command conflict Not defined Internal error Normal return Cannot access current RFS directory information Invalid stem name...
Page 411: Listcmd
Directory already exists Directory not specified List not found List not specified List is in update mode List is not in update mode User is not signed on Queue empty Named queue not found Stem or variable not specified Stem or variable name too long Stem or variable count invalid Block not found CICGETV error...
Page 412: Deftrnid
Return Codes DEFTRNID Normal return 1202 Invalid operand 1222 Invalid option 1223 Error storing trantable information 1225 Error retrieving trantable information 1226 Exec name length error 1228 Error setting trantable value 1233 Transaction not found in table EXECDROP Normal return 1401 Invalid command 1402...
Page 413: Listclib And Listelib
1823 Error storing file pool information 1824 File pool ID not specified 1825 Error retrieving file pool information 1826 Invalid file pool ID 1827 Invalid file pool data retrieved 1828 File pool not defined 1829 RFS could not add library to file pool 1830 RFS could not create users directory 1831...
Page 414: Listtrnid
Return Codes 2226 Invalid stem variable name LISTTRNID Normal return 2325 Error retrieving trantable information Normal return 2440 No variable name specified 2441 Error retrieving variable 2442 Error storing variable 2448 No client available PSEUDO Normal return 2502 Invalid operand 2521 Operand not specified AUTHUSER...
Page 415: Waitreq
No terminal is attached 3099 Internal error WAITREQ Normal return 3121 WAITREQ not enabled 3122 Exec not a server 3123 Error saving request variable 3199 Internal error EXEC specifies the return code set by the exit of the called exec Normal return...
Page 416 Return Codes -527 Redundant specification for option -528 Value for option not specified -529 Value specified for option which should not have a value -530 Value specified for option is not numeric -531 Invalid value -532 Value specified is too long -533 Value specified is too short -534...
Page 417: Appendix C. Double-Byte Character Set (Dbcs) Support
No case translation In general, there is no concept of lowercase and uppercase in DBCS. v Notational conventions This appendix uses the following notational conventions: © Copyright IBM Corp. 1992, 2009 EBCDIC X'41' to X'FE' X'41' to X'FE' X'4040'...
Page 418: Enabling Dbcs Data Operations And Symbol Use
DBCS character -> SBCS character -> DBCS blank -> EBCDIC shift-out (X'0E') -> EBCDIC shift-in (X'0F') -> Note: In EBCDIC, the shift-out (SO) and shift-in (SI) characters distinguish DBCS characters from SBCS characters. Enabling DBCS Data Operations and Symbol Use The OPTIONS instruction controls how REXX regards DBCS data.
Page 419: Validation
Validation The user must follow certain rules and conditions when using DBCS. DBCS Symbol Validation DBCS symbols are valid only if you comply with the following rules: v The DBCS portion of the symbol must be an even number of bytes in length v DBCS alphanumeric and special symbols are regarded as different to their corresponding SBCS characters.
Page 420 PARSE In EBCDIC: x1 = '<><.A.B><. . ><.E><.F><>' PARSE VAR x1 w1 -> '<><.A.B><. . ><.E><.F><>' PARSE VAR x1 1 w1 -> '<><.A.B><. . ><.E><.F><>' PARSE VAR x1 w1 . -> '<.A.B>' The leading and trailing SO and SI are unnecessary for word parsing and, thus, they are stripped off. However, one pair is still needed for a valid mixed DBCS string to be returned.
Page 421: Dbcs Function Handling
When the data is split up in shorter lengths, again the DBCS data integrity is kept under OPTIONS EXMODE. In EBCDIC, if the terminal line size is less than 4, the string is treated as SBCS data, because 4 is the minimum for mixed string data. UPPER Under OPTIONS EXMODE, the UPPER instruction translates only SBCS characters in contents of one or more variables to uppercase, but it never translates DBCS characters.
Page 422: Built-In Function Examples
In EBCDIC: '<.A>' = '<.A. >' -> '<><><.A>' = '<.A><><>' -> '<> <.A>' = '<.A>' -> '<.A><><.B>' = '<.A.B>' -> 'abc' < 'ab<. >' -> 5. Word extraction from a string—“Word” means that characters in a string are delimited by an SBCS or a DBCS blank.
Page 423 DATATYPE DATATYPE('<.A.B>') -> 'CHAR' DATATYPE('<.A.B>','D') -> DATATYPE('<.A.B>','C') -> DATATYPE('a<.A.B>b','D') -> DATATYPE('a<.A.B>b','C') -> DATATYPE('abcde','C') -> DATATYPE('<.A.B','C') -> DATATYPE('<.A.B>','S') -> Note: If string is not a valid mixed string and C or D is specified as type, 0 is returned. FIND FIND('<.A. .B.C> abc','<.B.C> abc') FIND('<.A.
Page 424 RIGHT('a<>',2) -> ' a' CENTER('<.A.B>',10,'<.E>') -> '<.E.E.E.E.A.B.E.E.E.E>' CENTER('<.A.B>',11,'<.E>') -> '<.E.E.E.E.A.B.E.E.E.E.E>' CENTER('<.A.B>',10,'e') -> 'eeee<.A.B>eeee' Applying the character concatenation for padding and character extraction from a string rules. LENGTH In EBCDIC: LENGTH('<.A.B><.C.D><>') -> Applying the counting characters rule. REVERSE In EBCDIC: REVERSE('<.A.B><.C.D><>') ->...
Page 425 Drop A.3 ; <.A.B>=3 /* if ETMODE is on */ SYMBOL('<.A.B>') -> 'VAR' SYMBOL(<.A.B>) -> 'LIT' /* has tested "3" */ SYMBOL('a.<.A.B>') -> 'LIT' /* has tested A.3 */ TRANSLATE In EBCDIC: TRANSLATE('abcd','<.A.B.C>','abc') TRANSLATE('abcd','<><.A.B.C>','abc') TRANSLATE('abcd','<><.A.B.C>','ab<>c') TRANSLATE('a<>bcd','<><.A.B.C>','ab<>c') -> '<.A.B.C>d' TRANSLATE('a<>xcd','<><.A.B.C>','ab<>c') -> '<.A>x<.C>d' Applying the character extraction from a string, character comparison, and character concatenation rules.
Page 426: Dbcs Processing Functions
WORDPOS In EBCDIC: WORDPOS('<.B.C> abc','<.A. .B.C> abc') WORDPOS('<.A.B>','<.A.B. .A.B><. .B.C. .A.B>',3) -> Applying the word extraction from a string and character comparison rules. DBCS Processing Functions This section describes the functions that support DBCS mixed strings. These functions handle mixed strings regardless of the OPTIONS mode.
Page 427: Dbcenter
DBCENTER DBCENTER(string,length returns a string of length length with string centered in it, with pad characters added as necessary to make up length. The default pad character is a blank. If string is longer than length, it is truncated at both ends to fit.
Page 428: Dbright
padded with pad characters (or truncated) on the right as needed. The default pad character is a blank. The option controls the counting rule. Y counts SO and SI within mixed strings as one each. N does not count the SO and SI and is the default. Here are some EBCDIC examples: DBLEFT('ab<.A.B>',4) DBLEFT('ab<.A.B>',3)
Page 429: Dbtodbcs
DBRRIGHT(string,length ,option returns the remainder from the DBRIGHT function of string. If length is greater than the length of string, returns a null string. The option controls the counting rule. Y counts SO and SI within mixed strings as one each. N does not count the SO and SI and is the default.
Page 430: Dbvalidate
DBVALIDATE DBVALIDATE(string ,'C' returns 1 if the string is a valid mixed string or SBCS string. Otherwise, returns 0. Mixed string validation rules are: 1. Only valid DBCS character codes 2. DBCS string is an even number of bytes in length 3.
Page 431: Appendix D. Reserved Keywords And Special Variables
More important, the choice of strategy (if it is to be done at all) is a personal one by the programmer. The REXX language does not impose it. Special Variables There are three special variables that the language processor can set automatically: © Copyright IBM Corp. 1992, 2009...
Page 432 Keywords and Variables is set to the return code from any run host command (or subcommand). Following the SIGNAL events, SYNTAX, ERROR, and FAILURE, RC is set to the code appropriate to the event: the syntax error number (see appendix on error messages) or the command return code. RC is unchanged following a NOVALUE or HALT event.
Page 433: Appendix E. Debug Aids
(if tracing was off on entry to the subroutine) tracing (and interactive debug) is turned off until the next entry to the subroutine. © Copyright IBM Corp. 1992, 2009...
Page 434: Interrupting Execution And Controlling Tracing
You can use standard CICS facilities to interrupt a REXX exec (the REXX transaction). If properly authorized, you can issue the CEMT SET TASK PURGE command to halt an exec. Refer to the CICS Transaction Server for VSE/ESA CICS Supplied Transactions for more information. CICS TS for VSE/ESA: REXX Guide...
Page 435: Appendix F. Rexx/Cics Business Value Discussion
REXX programs tend to be shorter and easier to follow than programs written in other languages. To use REXX for CICS Transaction Server for VSE/ESA REXX a new programmer does not have to learn JCL, COBOL or significant technical detail of CICS (such as the CICS translator).
Page 436 CICS Transaction Server for VSE/ESA REXX facilitates systems management One of the major uses of REXX is as a Procedures (Scripting) Language. CICS Transaction Server for VSE/ESA REXX can be used to automate sequences of CICS system and application systems management activities, providing greater productivity and reliability.
Page 437: Product Positioning
The translated messages files are included on the product tape and are not separate features. Product Positioning The IBM CICS computing environment is one of the largest concentrations of customer production applications and data in the world. There has been tremendous customer investment in CICS-based mainframe systems, CICS-based application development, data collection for CICS-based systems, and employee education relating to the use and support of CICS-based systems.
Page 438 CICS TS for VSE/ESA: REXX Guide...
Page 439: Appendix G. System Definition/Customization/Administration
Defining Authorized Users Users may be specified as authorized by the AUTHUSER command. It is recommended that all AUTHUSER commands be placed in the CICSTART exec, or in an exec issued from within the CICSTART exec. © Copyright IBM Corp. 1992, 2009...
Page 440: Setting System Options
CICSTART exec to be run. Security Exit This section describes replaceable security exit CICSECX2. IBM provides a sample assembler CICSECX2 exit for customers to customize or replace. Note: This exit must reside in the same region as REXX/CICS (for example: the use of distributed program link is not allowed).
Page 441 Function IDs Alter Read Update System Definition/Customization/Administration Appendix G. System Definition/Customization/Administration...
Page 442 System Definition/Customization/Administration CICS TS for VSE/ESA: REXX Guide...
Page 443: Appendix H. Security
LIBDEF PROC search chain for the CICS partition. Authorized users can be defined by any existing authorized user or in an authorized exec. The REXX/CICS CICSTART exec that is called at REXX/CICS initialization (at the first REXX/CICS transaction after a CICS restart) is automatically © Copyright IBM Corp. 1992, 2009...
Page 444: Security Definitions
REXX/CICS System Sublibraries All authorized commands written in the REXX language must be loaded from a VSE Librarian sublibrary specified on the SETSYS AUTHCLIB command. These may be both IBM and customer (or vendor) supplied. All authorized execs must be loaded from a VSE Librarian sublibrary specified on either the SETSYS AUTHCLIB or SETSYS AUTHELIB commands.
Page 445 Notes: 1. The AUTH option of the DEFCMD or DEFSCMD is itself an authorized command option. That is, AUTH may only be used if the user issuing it is an authorized user or if it was issued from an exec loaded from an authorized sublibrary.
Page 446 Security CICS TS for VSE/ESA: REXX Guide...
Page 447: Appendix I. Performance Considerations
The performance characteristics of such a server can be better managed. The advantage of a server exec over a nested exec is that a server exec can be started and can process multiple client requests before ending. This has a shorter path-length, provides better response time, and often uses less system resource.
Page 448 CICS TS for VSE/ESA: REXX Guide...
Page 449: Appendix J. Basic Mapping Support Example
DFHMDF POS=(9,6),LENGTH=25, INITIAL='PLEASE ENTER YOUR USERID:',ATTRB=(PROT,NORM) * DUSERID DUSERID DFHMDF POS=(9,32),LENGTH=8,ATTRB=(UNPROT,BRT,IC,FSET) DFHMDF POS=(9,41),LENGTH=1,ATTRB=(PROT,NORM) DFHMDF POS=(14,6),LENGTH=4,INITIAL='MSG:',ATTRB=(PROT,NORM) * DMSG DMSG DFHMDF POS=(14,11),LENGTH=29,ATTRB=(UNPROT,NORM,FSET) DFHMDF POS=(14,41),LENGTH=1,ATTRB=(PROT,NORM) DFHMSD TYPE=FINAL © Copyright IBM Corp. 1992, 2009 00000010 00000020 00000030 00000040 *00000050 *00000060 00000070 00000080 00000100 *00000120...
Page 450 BMS Example The map DSECT follows. * TEST PANEL FOR REXX/CICS PANEL1S EQU SPACE CL12 DUSERIDL DS DUSERIDF DS DUSERIDA DS DUSERIDC DS DUSERIDH DS DUSERIDI DS 0CL8 DUSERIDO DS SPACE DMSGL DMSGF DMSGA DMSGC DMSGH DMSGI 0CL29 DMSGO CL29 SPACE PANEL1E EQU PANEL1S...
Page 451 /* and initialize 'PSEUDO OFF' ZEROES = '00'x 'CICS GETMAIN SET(WORKPTR) LENGTH(90) INITIMG(ZEROES)' VAR1 = 'USERID must be 8 characters' /* Copy the REXX variable VAR1 to the GETMAINed storage 'COPYR2S VAR1 WORKPTR 30' /* Copy the storage area to REXX variable 'COPYS2R WORKPTR X 0 90' 'CICS SEND MAP(PANELG) FREEKB ERASE FROM(X)' 'CICS RECEIVE MAP(PANELG) INTO(Y)'...
Page 452 BMS Example REXX/CICS HEADER PANEL1 PLEASE ENTER YOUR USERID: TEST MSG: Please enter 8 character USERID CICS TS for VSE/ESA: REXX Guide PANEL1...
Page 453: Appendix K. Post-Installation Configuration
COPY CICEDIT.Z:=.PROC R=Y COPY CICEMAP.Z:=.PROC R=Y COPY CICEPROF.Z:=.PROC R=Y COPY CICESVR.Z:=.PROC R=Y COPY CICEXIO.Z:=.PROC R=Y COPY CICFLST.Z:=.PROC R=Y COPY CICFPOOL.Z:=.PROC R=Y COPY CICFPROF.Z:=.PROC R=Y COPY CICFSVR.Z:=.PROC R=Y COPY CICGVER.Z:=.PROC R=Y COPY CICGVERD.Z:=.PROC R=Y COPY CICHELP.Z:=.PROC R=Y © Copyright IBM Corp. 1992, 2009...
Page 454: Update Cicstart.proc
PI Configuration COPY CICHPREP.Z:=.PROC R=Y COPY CICIVP1.Z:=.PROC R=Y COPY CICIVP2.Z:=.PROC R=Y COPY CICIVP3.Z:=.PROC R=Y COPY CICLCLIB.Z:=.PROC R=Y COPY CICLELIB.Z:=.PROC R=Y COPY CICLISTC.Z:=.PROC R=Y COPY CICLISTP.Z:=.PROC R=Y COPY CICLISTT.Z:=.PROC R=Y COPY CICOVSIB.Z:=.PROC R=Y COPY CICPATH.Z:=.PROC R=Y COPY CICPSAMP.Z:=.PROC R=Y COPY CICRXTRY.Z:=.PROC R=Y COPY CICSET.Z:=.PROC R=Y COPY CICSETS.Z:=.PROC R=Y COPY CICSPROF.Z:=.PROC R=Y...
Page 455: Format The Rfs Filepools
PI Configuration Format the RFS Filepools Ensure that all required configuration tasks have been performed, and if necessary re-start CICS. Sign on with a userid defined as an authorized user in CICSTART.PROC. Enter REXX (which is the default transaction id associated with the CICRXTRY exec). You should see the following line at the top of the screen: Enter a REXX command or EXIT to quit and a READ in the lower right hand corner.
Page 456: Verify The Installation
PI Configuration CONNECT S=PRD1.BASE : user.sublib COPY CICR3270.Y : CICR3270.BOOK COPY CICINDEX.N : CICINDEX.PANSRC COPY CICSNDX.N : CICSNDX.PANSRC COPY CICCHAP.N : CICCHAP.PANSRC Start CICS with at least EDSALIM=25M. Approximately 10M of free EDSA is needed to execute this procedure, therefore allow this much extra over your normal configuration. CEMT I DSAS displays the current usage, and can increase EDSALIM as long as partition getvis storage is available.
Page 457: Configure The Rexx Db2 Interface
Sample output: Enter a REXX command or EXIT to quit CALL CICIVP1 ***------------------------------------------------------*** *** This is a test REXX program running under CICS/VSE *** It was loaded from PROCLIB-user.sublib(CICIVP1) ***------------------------------------------------------*** What is your name? <type name and press ENTER> Welcome to REXX/CICS for CICS/VSE , xxxxx Invoking nested exec CICIVP2 (which has tracing on) 11 *-* say 'You entered CICIVP2 exec' >>>...
Page 458 PI Configuration A package for the CICSQL program is loaded into the DB2 database under the SQLDBA user. This is supplied as member CICSQL.A. If you fail to do this, REXX gives return codes such as -805 whenever an "ADDRESS EXECSQL command"...
Page 459: Bibliography
CICS TS for VSE/ESA Shared Data Tables Guide CICS TS for VSE/ESA Security Guide CICS TS for VSE/ESA External Interfaces Guide CICS TS for VSE/ESA XRF Guide CICS TS for VSE/ESA Report Controller User's Guide © Copyright IBM Corp. 1992, 2009 GC34-5763 GC33-1645 GC33-1646 GC33-1941...
Page 460: Where To Find More Information
CICS TS for VSE/ESA as it contains information about the system programming commands. v The REXX Language, A Practical Approach to Programming, by M. F. Cowlishaw (IBM* Order number: ZB35-5100 and available in book stores) offers general information about the REXX language.
Page 461: High-Level Assembler Language (Hlasm)
TCP/IP User's Guide Turbo Dispatcher Guide and Reference Unattended Node Support High-Level Assembler Language (HLASM) General Information Installation and Customization Guide Language Reference Programmer’s Guide Language Environment for VSE/ESA (LE/VSE) C Run-Time Library Reference C Run-Time Programming Guide Concepts Guide Debug Tool for VSE/ESA Fact Sheet Debug Tool for VSE/ESA Installation and Customization Guide Debug Tool for VSE/ESA User’s Guide and Reference...
Page 462: Books From Vse/Esa 2.5 Optional Program Libraries
Diagnosis Guide General Information Installation and Customization Guide Language Reference Licensed Program Specifications Migration Guide Migrating VSE Applications To Advanced COBOL Programming Guide DB2 Server for VSE Application Programming Database Administration Installation Interactive SQL Guide and Reference Operation Overview System Administration...
Page 463: Dl/I Vse
DL/I VSE Application and Database Design Application Programming: CALL and RQDLI Interface Application Programming: High-Level Programming Interface Database Administration Diagnostic Guide General Information Guide for New Users Interactive Resource Definition and Utilities Library Guide and Master Index Licensed Program Specifications Low-level Code and Continuity Check Feature Library Guide and Master Index Messages and Codes...
Page 464 CICS TS for VSE/ESA: REXX Guide...
Page 465: Notices
Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead.
Page 466 CICS TS for VSE/ESA: REXX Guide...
Page 467: Trademarks
The following terms are trademarks of International Business Machines Corporation in the United States, or other countries, or both: ACF/VTAM C/370 CICS OS/2 CICS/MVS CICSPlex Hiperbatch IBMLink MVS/ESA OS/2 System/390 © Copyright IBM Corp. 1992, 2009 CICS CICS/ESA CICS/VSE OfficeVision/VM RACF VSE/ESA...
Page 468 CICS TS for VSE/ESA: REXX Guide...
Page 469: Index
¬<< (strictly not less than operator) 118 ¬= (not equal operator) 117 ¬== (strictly not equal operator) 117 © Copyright IBM Corp. 1992, 2009 abuttal 27, 116 action taken when a condition is not trapped 226 action taken when a condition is trapped 226...
Page 470 CKFILE command 260 clause null 10 REXX types 9 CLD command 274, 325 client exec example 292 client/server 425 CMDLINE command 237 code page 110 codes and messages 379, 387 coding style 96 collating sequence using XRANGE 198 collections of variables 196...
Page 471 error 379, 387 debugging 29 ERROR 225 ERROR condition of SIGNAL and CALL instructions 228 error messages 12 ETMODE 151 European option of DATE function 182 evaluation of expressions 115 example 244 ADDRESS instruction 10 AUTH 260 AUTHUSER command 320 C2S command 331 CD command 321 CEDA command 323...
Page 472 FAILURE condition of SIGNAL and CALL instructions 225, 228 failure, definition 125 feature of REXX 3 FIFO (first-in/first-out) stacking 160 file access security 259 FILE command 241 file list utility (FLST) 264 file name, type, mode of program 153 file pool 257 root directory 257 file system commands 259...
Page 473 LPUSH command 276 LQUEUE command 277 MACRO command 246 mapping between commands 319 master terminal transaction (CEMT) 3 messages interpreting 12 minutes calculated from midnight 194 mixed DBCS string 181 MKDIR command 257, 263, 273, 277 Month option of DATE function 182 MSGLINE command 246 multi-way call 136, 165 multiple strings 78, 211...
Page 474 quotation marks around a literal string 6 in an instruction 6 random number function of RANDOM 190 RDIR command 263 READ command 277 recursive call 136 reference 103 relative numeric pattern in parsing 77 relative positional patterns 207 RENAME command 264 Rename supplied Procedures 431 reordering data with TRANSLATE function 195 repeating a string with COPIES 179...
Page 475 subkeyword 120 subroutine comparison to a function 57, 70 description 57 protecting variable 62 writing 58 subsidiary list 142, 155 SUBSTR 192 substring 192 suggested readings xix symbols and strings in DBCS 396 SYNONYM command 254 syntax 387 rules of REXX 6 SYNTAX condition of SIGNAL instruction 226, 228 SYSSBA command 201 system libraries 422...
Page 476 CICS TS for VSE/ESA: REXX Guide...
Page 477: Sending Your Comments To Ibm
IBM representative or your IBM authorized remarketer. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate, without incurring any obligation to you.
Page 478 CICS TS for VSE/ESA: REXX Guide...
Page 480 SC34-5764-01...

This manual is also suitable for:

Rexx

IBM SC34-5764-01 Manual

Preface

Part 1. User's Guide

Chapter 1. Introduction

Chapter 2. Writing and Running a REXX Program

Chapter 3. Using Variables and Expressions

Chapter 4. Controlling the Flow Within a Program

Chapter 5. Using Functions

Chapter 6. Writing Subroutines and Functions

Chapter 7. Manipulating Data

Chapter 8. Using Commands from a Program

Chapter 9. Diagnosing Problems Within a Program

Chapter 10. Programming Style and Techniques

Part 2. Reference

Chapter 11. Introduction

Chapter 12. REXX General Concepts

Chapter 13. Keyword Instructions

Chapter 14. Functions

Chapter 15. Parsing

Quick Links

Related Manuals for IBM SC34-5764-01

Summary of Contents for IBM SC34-5764-01