IBM SC34-5764-01 User Manual

CICS Transaction Server fo r VSE/ES AR EXX GuideSC34-5764-01

OVERLAY...189POS (Position) ...189QUEUED ...190RANDOM ...

(Without +, −,or= before the left parenthesis, the language processor would consider the variable to be astring pattern.) The following example uses t

c) word3 =4. PARSE VALUE 'Experience is the best teacher.' WITH v1 5 v2...+...1...+...2...+...3.a) v1 =b) v2 =5.quote = 'Experien

f) word6 = ''3.a) word1 = Experienceb) word2 = isc) word3 = teacher.4.a) v1 = Expeb) v2 = rience is the best teacher.5.a) v1 = Experienceb)

Chapter 8. Using Commands from a programThis chapter describes how to use commands in a REXX program.Types of CommandsA REXX program can issue several

Calling Another REXX Program as a CommandPreviously, this book discussed how to call another program as an external routine (Chapter 6, “WritingSubrou

RFS This is an optional environment that executes commands for the REXX File System.RLS This is an optional environment that executes commands for the

84 CICS TS for VSE/ESA: REXX Guide

Chapter 9. Diagnosing Problems within a programThis chapter describes how to trace command output and other debugging techniques.Debugging ProgramsWhe

SIGLThe language processor sets the SIGL special variable in connection with a transfer of control within aprogram because of a function, a SIGNAL or

instruction2ENDELSEinstructionAIf the command ends with a nonzero return code, the ELSE path is taken. To force taking the first path,the input during

Arithmetic Operation Rules—Additional Operators ...220Numeric Comparisons ...222Exponential Notation ...

88 CICS TS for VSE/ESA: REXX Guide

Chapter 10. Programming Style and TechniquesThe method you use for constructing your programs is just as important as the language you use to writethe

Answer:Happy HourHere is a chance to have some fun.This is a very simple arcade game. Type it in and play it with your friends. Later in this chapter,

/* CATMOUSE EXEC *//* The user says where the mouse is to go. But where *//* will the cat jump? */say "This is the mouse ----------> @"sa

Good job! Now, take a while to put your new skills into action, or continue reading.Designing a ProgramStill thinking about method, which is just as i

Do forevercall DisplayMouse's moveCat's moveendConclusionMethods for Designing LoopsThe method for designing loops is to ask two questions:v

What Do We Have So Far?Putting all this together, we have:The method that we have just discussed is sometimes called stepwise refinement. You start wi

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 ba

This gives the trace:rotate6 *-* wheel:8 *-* cog:10 *-* true:8 *-* cog:10 *-* true:8 *-* cog:10 *-* true:6 *-* wheel:8 *-* cog:13 *-* false:8 *-* cog:

This next example is easier to read. It is divided into segments, each with its own heading. The commentson the right are sometimes called remarks. Th

QQUIT ...249QUERY ...249QUIT ...250RESERVED ...

This next example has additional features that are popular with some programmers. Keywords written inuppercase and a different indentation style highl

Congratulations! Now you know the best ways to program your REXX execs. Have fun writing programsthat will make your life easier!/********************

100 CICS TS for VSE/ESA: REXX Guide

Part 2. Reference© Copyright IBM Corp. 1992, 2009 101

102 CICS TS for VSE/ESA: REXX Guide

Chapter 11. IntroductionThis introductory section:v Identifies the reference's purpose and audiencev Explains how to use the referencev Gives an

Overview of Product FeaturesThe following list is the product features of REXX/CICS described in this section.v SAA Level 2 REXX Language Support Unde

Dynamic Support for EXEC CICS CommandsSupport for most EXEC CICS API commands is included in REXX/CICS. This is a dynamic interface (noEXEC CICS comma

SQL InterfaceREXX programs may contain SQL statements. These statements are interpreted and executeddynamically. The results of the SQL statements are

v Required items appear on the horizontal line (the main path). STATEMENT required_item v Optional items appear below the main path. STATEMENTop

Security ...274RLS commands ...275CKDIR ...275DELETE ...

Introduction108CICS TS for VSE/ESA: REXX Guide

Chapter 12. REXX General ConceptsThe REstructured eXtended eXecutor (REXX) language is particularly suitable for:v Command proceduresv Application fro

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 (

You can avoid this type of problem by using concatenation for literal strings containing /* or */; line 2would be:if substr(input,1,5) = '/'

Note: A hexadecimal string is not a representation of a number. Rather, it is an escapemechanism that lets a user describe a character in terms of its

If a symbol does not begin with a digit or a period, you can use it as a variable and can assign it avalue. If you have not assigned it a value, its v

345>=123345 >=123345 >= 123345 > = 123Some of these characters may not be available in all character sets, and, if this is the case,approp

ContinuationsOne way to continue a clause onto the next line is to use the comma, which is referred to as thecontinuation character. The comma is func

blanks and comments. In addition, one or more blanks, where they occur in expressions but are notadjacent to another operator, also act as an operator

Prefix −Same as the subtraction: 0 - numberPrefix +Same as the addition: 0 + number.See Chapter 16, “Numbers and Arithmetic,” on page 217 for details

Options...304PANEL Variables ...305Panel Facility Return Code Information ...

>>= Strictly greater than or equal to\<<, ¬<<Strictly NOT less than<<= Strictly less than or equal to\>>, ¬>>Stric

=>< (comparison operators)== >> <<\= ¬=>< <>\> ¬>\< ¬<\== ¬==\>> ¬>>\<< ¬<<>= >

Clauses and InstructionsClauses can be subdivided into the following types:Null ClausesA clause consisting only of blanks or comments or both is a nul

Assignments and SymbolsA variable is an object whose value can change during the running of a REXX program. The process ofchanging the value of a vari

Simple SymbolsA 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

where d0 is the uppercase form of the symbol s0, and v1 to vn are the values of the constant or simplesymbols s1 through sn. Any of the symbols s1-sn

pull amount nameif datatype(amount)='CHAR' then leavetotal.name = total.name + amountendNote: You can always obtain the value that has been

The expression is evaluated, resulting in a character string (which may be the null string), which is thenprepared as appropriate and submitted to the

argument to the exec. For example: EDIT TEST.EXEC causes the REXX/CICS editor exec, CICEDIT, tostart and TEST.EXEC, the argument, names the file to ed

REXX File SystemExecs can be stored as members in the VSAM-based REXX File System (RFS), provided withREXX/CICS, or in VSE librarian members with a me

Example ...331Notes ...331DEFCMD ...332Operands ...

v The USERID function returnsa1to8character CICS user ID if the user is signed on. If the CICS userhas not signed on and a default user has been speci

Pseudo-conversational Transaction SupportCICS pseudo-conversational support for REXX execs is supported though the use of the CICS RETURNTRANSID() com

REXX General Concepts130CICS TS for VSE/ESA: REXX Guide

Chapter 13. Keyword InstructionsA keyword instruction is one or more clauses, the first of which starts with a keyword that identifies theinstruction.

ADDRESSPurpose ADDRESSenvironmentexpressionexpression1VALUE; ADDRESS temporarily or permanently changes the destination of commands. Commands are

The two environment names are automatically saved across internal and external subroutine and functioncalls. See the CALL instruction (page “Purpose”

ARGPurpose ARGtemplate_list; ARG retrieves the argument strings provided to a program or internal routine and assigns them tovariables. It is a sh

CALLPurpose CALL,nameexpressionOFF ERRORFAILUREHALTON ERRORFAILURE NAME trapnameHALT; CALL calls a routine (if you specify name) or controls the

The CALL then causes a branch to the routine called name, using exactly the same mechanism asfunction calls, see Chapter 14, “Functions,” on page 171.

v The status of DO loops and other structures: Executing a SIGNAL while within a subroutine is safebecause DO loops, and so forth, that were active wh

Return Codes ...350Example ...351Note ...351FLST ...

DOPurposeDO groups instructions together and optionally processes them repetitively. During repetitive execution, acontrol variable (name) can be step

Repetitive DO LoopsIf a DO instruction has a repetitor phrase or a conditional phrase or both, the group of instructions forms arepetitive DO loop. Th

end /* 1.7 *//* 2.4 *//* 3.1 *//* 3.8 */The control variable can be altered within the loop, and this may affect the iteration of the loop. Alteringth

Note: Using the LEAVE or ITERATE instructions can also modify the execution of repetitive loops.Evaluate exprr + 0evaluate expri + 0exprt + 0, exprb +

DROPPurpose DROPname(name); DROP “unassigns” variables, that is, restores them to their original uninitialized state. If name is notenclosed in p

EXITPurpose EXITexpression; EXIT leaves a program unconditionally. Optionally EXIT returns a character string to the caller. Theprogram is stopped

IFPurpose IF expression;THEN instruction; ELSE instruction;IF conditionally processes an instruction or group of instructions depending on the eva

INTERPRETPurpose INTERPRET expression ; INTERPRET processes instructions that have been built dynamically by evaluating expression.The expression

>O> "Hello Kitty">L> "!">O> "Hello Kitty!"Hello Kitty!Here, lines 3 and 4 set the variables used in li

ITERATEPurpose ITERATEname; ITERATE alters the flow within a repetitive DO loop (that is, any DO construct other than that with a simpleDO).Execut

Return Codes ...368Example ...368Notes ...368SET...

LEAVEPurpose LEAVEname; LEAVE causes an immediate exit from one or more repetitive DO loops (that is, any DO construct otherthan a simple DO).Proc

NOPPurpose NOP ; NOP is a dummy instruction that has no effect. It can be useful as the target of a THEN or ELSE clause:Example:Selectwhen a=c the

NUMERICPurpose NUMERIC DIGITSexpression1SCIENTIFICFORMENGINEERINGexpression2VALUEFUZZexpression3; NUMERIC changes the way in which a program carri

OPTIONSPurpose OPTIONS expression ; OPTIONS passes special requests or parameters to the language processor. For example, these may belanguage pro

PARSEPurpose PARSEUPPERARGEXTERNALLINEINNUMERICPULLSOURCEVALUE WITHexpressionVAR nameVERSIONtemplate_list; PARSE assigns data (from various source

Example:Parse Numeric Var1After this instruction, Var1 would be equal to: 9 0 SCIENTIFIC. See section “NUMERIC” on page 150and the built-in functions

PARSE VERSIONparses information describing the language level and the date of the language processor. Thisinformation consists of five words delimited

PROCEDUREPurpose PROCEDUREEXPOSE name(name); PROCEDURE, within an internal routine (subroutine or function), protects variables by making themunk

Example:/* This is the main REXX program */j=1; z.1='a'call toftsayjkm /*Displays "1 7 M" */exit/* This is a subroutine */toft: pr

Example:/* This is the main REXX program */a.=11; i=13; j=15i=i+1C.5 = 'FRED'call lucky7saya.a.1ijc.c.5say 'You should see 11 7 14 15 C

LISTPOOL ...391LISTTRNID ...392C2S...392PSEUDO ...

PULLPurpose PULLtemplate_list; PULL reads a string from the program stack. If the program stack is empty, PULL then tries reading a linefrom the c

PUSHPurpose PUSHexpression; PUSH stacks the string resulting from the evaluation of expression LIFO (Last In, First Out) onto theexternal data que

QUEUEPurpose QUEUEexpression; QUEUE appends the string resulting from expression to the tail of the external data queue. That is, it isadded FIFO

RETURNPurpose RETURNexpression; RETURN returns control (and possibly a result) from a REXX program or internal routine to the point of itsinvocati

SAYPurpose SAYexpression; SAY writes a line to the default output stream (the terminal) so the user sees it displayed. The result ofexpression may

SELECTPurpose SELECT;WHEN expression THEN instruction;;OTHERWISEinstruction;END ; SELECT conditionally calls one of several alternative instru

SIGNALPurpose SIGNAL labelnameexpressionVALUEOFF ERRORFAILUREHALTNOVALUESYNTAXON ERRORFAILURE NAME trapnameHALTNOVALUESYNTAX; SIGNAL causes an unu

The VALUE form of the SIGNAL instruction allows a branch to a label whose name is determined at thetime of execution. This can safely effect a multi-w

TRACEPurposeTRACE controls the tracing action (that is, how much is displayed to the user) during processing of aREXX program. (Tracing describes some

All Traces (that is, displays) all clauses before execution.CommandsTraces all commands before execution. If the command results in an error or failur

System Profile Exec ...417Authorized REXX/CICS VSE Librarian sublibraries ...417Defining Authorized Users

Using the ? prefix, therefore, switches you alternately in or out of interactive debug. (Because thelanguage processor ignores any further TRACE state

message when interactive debug is entered, an indication of a syntax error when in interactivedebug, or the traceback clauses after a syntax error in

UPPERPurposeThis is a non-SAA instruction provided in REXX/CICS. UPPERvariable ; UPPER translates the contents of one or more variables to upperc

Chapter 14. FunctionsA function is an internal, built-in, or external routine that returns a single result string. (A subroutine is afunction that is

instruction, various other status information (TRACE and NUMERIC settings and so forth) is savedtoo. See the CALL instruction (page “Purpose” on page

Internal routines are not used if the function name is given as a literal string (that is, specified inquotation marks); in this case the function mus

Built-in FunctionsREXX provides a rich set of built-in functions, including character manipulation, conversion, andinformation functions.Other built-i

ABBREV (Abbreviation) ABBREV(information,info,length) returns 1 if info is equal to the leading characters of information and the length of info i

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

BITAND('12'x) -> '12'xBITAND('73'x,'27'x) -> '23'xBITAND('13'x,'5555'x) -&

Screen Definition Facility II (SDF II) ...441Notices ...443Trademarks ...

If binary_string is the null string, B2X returns a null string. If the number of binary digits in binary_string isnot a multiple of four, then up to t

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 retur

If string is null, returns 0.Here are some examples:C2D('09'X) -> 9C2D('81'X) -> 129C2D('FF81'X) -> 65409C2D(&a

Binaryreturns 1 if string contains only the characters 0 or 1 or both.C returns 1 if string is a mixed SBCS/DBCS string.Dbcs returns 1 if string is a

base date, 1 January 0001, in the format: dddddd (no leading zeros or blanks). The expressionDATE('B')//7 returns a number in the range 0–6

DBCS (Double-Byte Character Set Functions)The following are all part of DBCS processing functions.DBADJUST DBRIGHT DBUNBRACKETDBBRACKET DBRLEFT DBVALI

If you specify n, it is the length of the final result in characters; after conversion, the input string issign-extended to the required length. If th

returns the REXX error message associated with error number n. The n must be in the range 0–99, andany other value is an error. Returns the null strin

The number is first rounded according to standard REXX rules, just as though the operation number+0 hadbeen carried out. The result is precisely that

INDEXPOS is the preferred built-in function for obtaining the position of one string in another. See page 189 for acomplete description. INDEX(hayst

PrefaceWhat this book is aboutThis book describes REXX/CICS or REXX for CICS Transaction Server for VSE/ESA. This IBM programproduct provides a native

LASTPOS (Last Position) LASTPOS(needle,haystack,start) returns the position of the last occurrence of one string, needle, in another, haystack. (S

 MAX(,number) returns the largest number from the list specified, formatted according to the current NUMERIC settings.Here are some examples:MAX(

haystack. By default the search starts at the first character of haystack (that is, the value of start is 1). Youcan override this by specifying start

REVERSE REVERSE(string) returns string, swapped end for end.Here are some examples:REVERSE('ABc.') -> '.cBA'REVERSE('X

Here are some examples:SPACE('abc def ') -> 'abc def'SPACE(' abc def',3) -> 'abc def'SPACE('abc def

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 nmust

(described later) was started or reset. The number has no leading zeros or blanks, and the settingof NUMERIC DIGITS does not affect the number. The fr

TRACE TRACE(option) returns trace actions currently in effect and, optionally, alters the setting.If you specify option, it selects the trace sett

decimal point. If you specify n, it must be a positive whole number or zero. The number is first roundedaccording to standard REXX rules, just as thou

/* REXX EXEC - ASSIGN FIND VALUE OF FRED */FRED = 7'RLS VARPUT FRED \USERS\userid\'X = VALUE(FRED,,RLS)SAY X/*Xnow=7 */Notes:1. If the VALUE

xx CICS TS for VSE/ESA: REXX Guide

WORDINDEX WORDINDEX(string,n) returns the position of the first character in the nth blank-delimited word in string or returns 0 if fewer thann wo

and end. The default value for start is '00'x, and the default value for end is 'FF'x.Ifstart is greater thanend, the values wrap

 X2D(hexstring,n) returns the decimal representation of hexstring. The hexstring is a string of hexadecimal characters. If theresult cannot be exp

If you specify data, after the old value has been retrieved storage starting at address is overwritten withdata (the length argument has no effect on

Functions202CICS TS for VSE/ESA: REXX Guide

Chapter 15. ParsingGeneral DescriptionThe parsing instructions are ARG, PARSE, and PULL (see section “ARG” on page 134, section “PARSE”on page 152, an

The PARSE VAR instruction is similar to PARSE VALUE except that the source string to parse is always avariable. In PARSE VAR, the name of the variable

/* Alternative to period as placeholder */stars='Arcturus Betelgeuse Sirius Rigil'parse var stars drop junk brightest rest /* brightest=&apo

Templates Containing Positional (Numeric) PatternsA positional pattern is a number that identifies the character position at which to split data in th

A relative positional pattern is a number with a plus (+) or minus (-) sign preceding it. (It can also be avariable within parentheses, with a plus (+

Part 1. User's Guide© Copyright IBM Corp. 1992, 2009 1

│ 2 │ │var1 4 │ │ 1 │ │var2 2│ │ 4 var3 5│ │11 var4 ││ 2 │ │var1 +2 │ │ ─3 │ │var2 +1│ │+2 var3 +1│ │+6 var4 │└──┬──┘ └───┬────┘ └──┬───┘ └───┬───┘ └─

v 'R E'v 'X'v 'X'The variable var1 receives 'R'; var2 receives 'E'. Both var3 and var4 receive &apos

Converts alphabetic characters to uppercasebefore parsingMaintains alphabetic characters in case enteredARGPARSE UPPER ARGPARSE ARGPARSE UPPER EXTERNA

When total=7 then new='purple'When total=9 then new='orange'When total=10 then new='green'Otherwise new=var1 /* entered

This instruction consists of the keywords PARSE ARG and three comma-separated templates. (For anARG instruction, the source strings to parse come from

Parsing with DBCS CharactersParsing with DBCS characters generally follows the same rules as parsing with SBCS characters. Literalstrings and symbols

┌────────────────────────────────────────┐│┌────────────────────────────────┐ ││START │ ││Token is first one in template. │ ││Length=length(source st

┌────────────────────────────────────────────────┐│┌─────────────┐ ┌────────────────────────────────┐ ││Start: │yes │String start=match end. │ ││End

┌─────────────────────────┐ ┌────────────────────────┐│Start: Match end <= │no │ ││ string start? ├───│String end=match start. │└───────────┬─────

Chapter 16. Numbers and ArithmeticREXX defines the usual arithmetic operations (addition, subtraction, multiplication, and division) in asnatural a wa

2 CICS TS for VSE/ESA: REXX Guide

DefinitionA precise definition of the arithmetic facilities of the REXX language is given here.NumbersA number in REXX is a character string that incl

an operation, when a number is rounded to the required precision.) The operation is then carried out underup to double that precision, as described un

The result is then rounded, counting from the first significant digit of the result, to the current setting ofNUMERIC DIGITS.DivisionFor the division:

all bits have now been inspected, the initial calculation is complete; otherwise the accumulator is squaredand the next bit is inspected for multiplic

Numeric ComparisonsThe comparison operators are listed in section “Comparison” on page 117. You can use any of these forcomparing numeric strings. How

For both large and small numbers some form of exponential notation is useful, both to make long numbersmore readable, and to make execution possible i

/* after the instruction */Numeric form scientific123.45 * 1e11 -> 1.2345E+13/* after the instruction */Numeric form engineering123.45 * 1e11 ->

Chapter 17. Conditions and Condition TrapsA condition is a specified event or state that CALL ON or SIGNAL ON can trap. A condition trap canmodify the

/* The following does not raise NOVALUE. */signal on novaluea.=0say a.zsay 'NOVALUE is not raised.'exitnovalue:say 'NOVALUE is raised.&

Because these conditions (ERROR, FAILURE, and HALT) can arise during execution of an INTERPRETinstruction, execution of the INTERPRET may be interrupt

Chapter 1. IntroductionThis chapter describes the REXX programming language and some of its features.What is REXX?REXX is an extremely versatile progr

Condition InformationWhen any condition is trapped and causes a SIGNAL or CALL, this becomes the current trappedcondition, and certain condition infor

code following the SYNTAX label may PARSE SOURCE to find the source of the data, then call an editorto edit the source file positioned at the line in

230 CICS TS for VSE/ESA: REXX Guide

Chapter 18. REXX/CICS Text EditorREXX/CICS provides a general purpose CICS-based text editor, patterned after VM/CMS XEDIT.The editor is provided so t

Screen FormatWhen you call the editor without a profile, the default screen definition is displayed as shown in thefollowing figure.EDIT ---- POOL1:\U

line just below it for input. You can also append a number to the end of the prefix command. This acts asa replication factor. If the number “5” is ap

Example:/* Macro to alter the setting of the REXX/CICS editor */ADDRESS EDITSVR'SET NUMBERS OFF''SET CURLINE 10''SET MSGLINE

Notes:1Ifarguments is not specified, any previously defined arguments are deleted.ARGS stores the default parameters to be passed to the program being

Return Codes0 Normal returnExample'BOTTOM'This example scrolls to the bottom of the file.CANCEL CANCEL CANCEL ends the current edit sess

Return Codes0 Normal request202 Invalid operandExample'CASE MIXED RESPECT'This example sets the case to MIXED and the sensitivity to RESPECT

Components of REXXThe various components of REXX make it a powerful tool for programmers. REXX is made up of:v Clauses, which can be instructions, nul

BOTTOMdisplays the command line on the bottom line of the screen.Return Codes0 Normal return202 Invalid operandExample'CMDLINE TOP'This exam

Operandsnumberspecifies the screen line number.Return Codes0 Normal return202 Invalid operandExample'CURLINE 3'This example sets the current

Example'DOWN 5'This example scrolls forward through the file five lines.EDIT EDITNONAMEfileidlib.sublib(mem.type) LIB( MACRO macronameED

3. The default user profile macro that the editor tries to call is CICEPROF. The CICEPROF macro createsan ISPF/PDF like environment. A second profile

Operandsfileidspecifies the file ID of the file. If you do not specify fileid, the file is saved as the default file ID.Return Codes0 Normal return202

2. The search begins at the current line and continues downward until BOTTOM OF DATA is reached, ora match is made. If BOTTOM OF DATA is reached witho

 GETLIB lib.sublib(mem.type) GETLIB imports a member from a VSE Librarian sublibrary into the current edit session. The file isinserted after the

210 Request failedExample'JOIN'This example joins the line that the cursor is on with the line immediately following it.LEFT LEFT1number

Operandsprefixspecifies any standard prefix (such a C, CC, M, MM, B, A) that is entered during an edit session.Return Codes0 Normal return202 Invalid

Operandsnumberdisplays the message line on the corresponding screen line.OFFdoes not display the message line.INFOdisplays messages in the header line

Chapter 2. Writing and Running a REXX ProgramThis chapter introduces programs and their syntax, describes the steps involved in writing and runningpro

Return Codes0 Normal return202 Invalid operandExample'NUMBERS ON'This example displays sequential numbers in the prefix area.NoteLine number

BOTTOMdisplays the PF key line on the bottom line of the screen.numberspecifies the screen line number.OFFremoves the PF key from the display screen.R

CMDLINEdisplays the current setting of the command line. For more information see the Text Editor command,section “CMDLINE” on page 237.COLUMNdisplays

NoteWhen the current file has been changed, the editor does not let you exit until either a save is done or youenter the QQUIT command.RESERVED RESe

 RIght1numberRIGHT scrolls right in the file.Operandsnumberspecifies the number of characters to scroll. If you do not specify number, the screen

 SORT *numAD1fromcoltocolSORT sorts the lines from the current line on down.Operands* specifies that all the lines from the current line to the en

 STRIP STRIP strips the trailing blanks off all file lines.Return Codes0 Normal returnExample'STRIP'This example strips all trailing bla

Operandscolumnspecifies the last column you want to keep.Return Codes0 Normal return202 Invalid operandExample'TRUNC 72'This example truncat

256 CICS TS for VSE/ESA: REXX Guide

Chapter 19. REXX/CICS File SystemThe REXX File System (RFS) is provided for the storage of text files and execs created with theREXX/CICS editor, and

When you run the example program, the first PULL instruction assigns the variable number1 the value 42.The second PULL instruction assigns the variabl

Example:POOL1: File Pool\ Root DirectoryTEST1.EXEC FileUSERS\ SubdirectoryUSER1\ SubdirectoryTEST2.EXEC FileDOCS\ SubdirectoryTEST3.DOCUMENT FileUSER2

The exec name is fully qualified, using the directory ID of each directory in the search before the search ofeach respective directory is performed. T

AUTH authorizes access to RFS directories.Operandsdiridspecifies a REXX File System directory identifier. This is partially or fully qualified. See th

Return CodesSee the RFS command, section “RFS” on page 363.Example'CKFILE POOL1:\USERS\USER1\TEST.EXEC'This example checks for a file called

DISKR reads records from an RFS file.Operandsfileidspecifies the file identifier.stem.specifies the name of a stem. (A stem must end in a period.) See

GETDIR returns a list of the contents of the current or specified directory into the specified REXX array.Operandsstem.specifies the name of a stem. (

Example'RFS RDIR POOL1:\USERS\USER1\DOCS'This example deletes a directory called DOCS in the existing directory POOL1:\USERS\USER1.RENAME

USER=USER1 - DIRECTORY=\USERS\USER1CMD FILENAME FILETYPE ATTRIBUTES RECORDS SIZE DATE TIMETEST1 EXEC FILE 11 1 1994/03/27 10:30:29TEST2 EXEC FILE 5 1

CDWhen you type CD from the command line use the following syntax: CDdiridCD changes the current directory.Operandsdiridspecifies a REXX File Syst

DELETEWhen you type DELETE on the FLST command column use the following syntax: DELETE DELETE deletes a file.When you type DELETE from the command

SAY 'This is a REXX literal string.' /* Using single quotation marks */SAY "This is a REXX literal string." /* Using double quotat

Operandsparameterspecifies the parameters passed to the exec as arguments.Example'EXEC / PARMS'This example, executed on the command column

NoteSee Chapter 19, “REXX/CICS File System,” on page 257 for more information about the REXX FileSystem.MACROWhen you type MACRO from the command line

NoteIf you specify text, the PF key is set with the text. If you do not specify text, the PF key is processed.REFRESHWhen you type REFRESH on the FLST

SORTWhen you type SORT from the command line use the following syntax: SORTDTFNFTATRCSZSORT sorts the file list.OperandsDTspecifies sorting the fi

Example'SYNONYM DISCARD RFS DELETE'This example makes DISCARD equivalent to the RFS command DELETE.UPWhen you type UP from the command line

Chapter 20. REXX/CICS List SystemREXX/CICS provides a facility for maintaining tables or lists of data in virtual storage. This facility is calledthe

The following example shows RLS directories and lists.Example:\ Root DirectoryTEST1.DATA FileUSERS\ SubdirectoryUSER1\ SubdirectoryTEST2.DATA FileDOCS

RLS commandsUnder the RLS command environment you issue commands to interface with RLS. If you set thecommand environment to RLS, you should not speci

 RLS*QUEUE*LPULL varnamequeidLPULL pulls a record from the top of the RLS queue.Operandsvarnamespecifies a simple REXX variable name. It does not

LQUEUE RLS*QUEUE*LQUEUE varnamequeidLQUEUE adds a record to the end of the RLS queue (FIFO).Operandsvarnamespecifies a simple REXX variable name.

CICS Transaction Server fo r VSE/ES AR EXX GuideSC34-5764-01

SAY 'This is' 'a string.'The space between the two separate strings is preserved:This is a string.Continuing a literal string with

Operandslistnamespecifies the list identifier.stem.specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 formor

Operandsvarnamespecifies a simple REXX variable name. It does not end in a period, distinguishing a variable namefrom a stem name.diridspecifies a REX

stem.specifies the name of a stem. (A stem must end in a period.) See section “Stems” on page 123 formore information. The default stem is DATA..Retur

Chapter 21. REXX/CICS Command DefinitionThe REXX/CICS Command Definition Facility provides a means of easily defining (or redefining) REXXcommands and

authorized user to use DEFSCMD to change command definitions that affect other REXX/CICS users. Seesection “DEFCMD” on page 332 for more information o

Entry Specifications when DEFCMD CICSLINK is specified:When the code for the command program gets control by an EXEC CICS LINK, the CICS Commareaconta

Non-REXX Language InterfacesREXX/CICS makes it possible to transparently convert a REXX process to a non-REXX process. To dothis requires that non-REX

Chapter 22. REXX/CICS DB2 InterfaceThe REXX/CICS DB2 Interface provides a means of executing SQL from a REXX exec. The SQL areprepared and executed dy

ADDRESS EXECSQL"statement""statement"...SQL can exist on more than one line. Each part of the statement is enclosed in quotes and

v Host variables are not allowed within the SQL. Instead, you can use REXX variables to pass input datato the EXECSQL environment. The REXX variables

Types of REXX ClausesREXX clauses can be: instructions, null clauses, and labels. Instructions can be keyword instructions,assignments, or commands. T

SQLCOLn.1Some SELECT functions such as CURRENT SQLID, MAX, and AVG are not associated with aparticular DB2 column. To view the results you must refere

Exit rcend/*---------------------------------------*//* Display the members of the department *//*---------------------------------------*/Say 'H

DB2 Interface290CICS TS for VSE/ESA: REXX Guide

Chapter 23. REXX/CICS High-level Client/Server SupportClient/Server computing has become very popular in the Information Processing industry. Some of

v Because REXX/CICS allows REXX clients and servers to be recoded in non-REXX languages,performance intensive parts of an application system can be se

REXX/CICS Server Exec Example/* EXAMPLE REXX/CICS SERVER1 EXEC */TRACE 'O' /* turn off source tracing *//*----------------------------------

High-level Client/Server Support294CICS TS for VSE/ESA: REXX Guide

Chapter 24. REXX/CICS Panel FacilityFacilityThe REXX panel facility provides the REXX programmer with simple tools and commands for paneldefinition an

mail_city = 'DALLAS'; /* prefill the most likely response for city/state */mail_state = 'TX';mail_zip = '';do forever;&a

characters are re-activated. Certain keyword combinations are incompatible and are not allowed whileothers which may seem meaningless are allowed. For

LabelA label, such as sub: is a symbolic name followed by a colon. A label can contain either single- ordouble-byte characters or a combination of sin

! Defcolor unprotect bright& Variable identifierOperandscharspecifies the control character being defined.VAriabledefines a REXX variable identifi

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/brig

The panel layout is close to what you see, with the exception of the control characters and the imbeddedvariables which are not shown when the panel i

 .PANEL panel_nameprotect_ccskip_cc variable_pairtextvariable_ccunprotect_cc variable_ccfield_length variable_pair.PANELOperandspanel_namespecifi

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

NORmalBRightINVisibleGReenREDBLUeTUrquoiseWHiteYEllowPInkDEfcolorBLInkREVerseUNDerlineNOJustifyLEftRIghtNULlsPAd ( )BLAnkscharNUMeric CUrsor MDT 

the field. The field list must be enclosed with parenthesis. Only the attributes stated are changedand the other attributes default to what was static

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/brig

OPID OPERATOR IDMSRE MAGNETIC READERSTRF STRUCTURE FIELDTRIG TRIGGERPA1PA2PA3PF1PF2PF3PF4PF5PF6PF7PF8PF9PF10PF11PF12PF13PF14PF15PF16PF17PF18PF19PF20PF

Return Codes4 Warning. Panel facility continues processing. Processing stops for other return code values.8 Programmer error10 Programmer error, PAN.R

character is X'0F') The SO and SI characters are non-printable. In the following example, the less than (<)and greater than (>) symbol

117 Variable value was too long and was truncated to fit output field118 Text field was truncated. Check to see if explicit length did not force a sub

06 Numeric07 extended highlight (blink/reverse/underline)08 MDT09 Cursor10 Pad()11 Variable12 DropState codesState codes for 20xx location codes:01 pa

State CodesState codes for 12xx location codes:01 panel name02 protect/skip field03 unprotect field04 text within a protect/skip field05 (not implemen

Example 2.DEFINE > prot green.DEFINE < unprot underline white.DEFINE + var service..DEFINE % skip turq.PANEL service> Panel service &disp

Example 4.DEFINE ) protect bright.DEFINE + drop.DEFINE & var msg.A panel to display output dynamic messages..PANEL msgbox2)+----------------------

'PANEL SEND SIGNON' CLR_INP_FIELDS PATH_NAME ,'CURSOR(' CURS_NAME ')' ATTR_STRINGIF RC > 4 THEN /* more than a warnin

END; /* select */END; /* do forever */EXITIF SYMBOL('ACCOUNT.ACC_NUM') == 'VAR' THENRETURN(1)ELSERETURN(0);NON_ITEMIZE_ROUTINE:QUE

NUM_OF_DAYS.2 = 29;ELSENUM_OF_DAYS.2 = 28;FIRST_WEEKDAY = (TOT_DAYS+1) // 7;FIRST_WEEKDAY_SAVE = FIRST_WEEKDAY;DISP_CENTER_MON = MONTH_NAME.MONTH; /*

LEFT_MONTH = 12;ELSELEFT_MONTH = MONTH - 1;FIRST_WEEKDAY = (TOT_DAYS - NUM_OF_DAYS.LEFT_MONTH +1) // 7;DISP_LEFT_MON = MONTH_NAME.LEFT_MONTH;LEFT_DAYS

(SUBSTR(DATE_SAVE,7,2)+FIRST_WEEKDAY_SAVE);ATTR_STRING = 'ATTRIB(' CUR_DAY_FIELD 'RED )' ;END;END; /* select */'PANEL RECEIVE

rexx helloHello! What is your name?samHello SAMHere is what happens:1. The SAY instruction displays Hello! What is your name?2. The PULL instruction p

318 CICS TS for VSE/ESA: REXX Guide

Chapter 25. REXX/CICS CommandsThis chapter provides you with detailed reference information for all REXX/CICS commands. Return codeinformation for all

AUTHUSERNote: This is an authorized command. AUTHUSER;useridAUTHUSER authorizes a list of user IDs.Operandsuseridis a CICS signon user ID that be

CD CDdiridCD changes the RFS file system directory.Operandsdiridspecifies a partial or full REXX File System directory that becomes the new curren

for execs.Commands322CICS TS for VSE/ESA: REXX Guide

CEDA CEDA RDO_Command Executes a CEDA command for resource definition online (RDO).OperandsRDO_Commandspecifies a command string passed as input t

CEMT CEMT master_term_cmd CEMT executes a CICS master terminal command from REXX.Operandsmaster_term_cmdspecifies a command string passed as input

CLD CLDdiridCLD changes your current RLS list directory.Operandsdiridspecifies a partial or full REXX List System directory that becomes the new c

CONVTMAP CONVTMAP lib.sublib(mem.type) rfs_fileid CONVTMAP reads a VSE Librarian sublibrary member and converts a DSECT (created by a previouslyas

COPYR2SNote: This is an authorized command. COPYR2S source_vname stor_anchor offset* lengthstruct_vname fieldnamestruct_name fieldnameCOPYR2S copi

When the program runs, the language processor sends the following lines of output.7 +++ PULL who /* Get the person's name.IF who ='' TH

Return Codes0 Normal return2002 Invalid operand2021 Invalid structure definition2022 Invalid variable structure definition2023 Field name not found202

COPYS2RNote: This is an authorized command. COPYS2R stor_anchor vname offset length* struct_vname fieldnamestruct_name fieldnameCOPYS2R copies dat

Return Codes0 Normal return2102 Invalid operand2121 Invalid structure definition2122 Invalid variable structure definition2123 Field name not found212

C2S C2S client_rexx_varnameserver_rexx_varnameC2S copies a client REXX variable to a server REXX variable.Operandsclient_rexx_varnamespecifies the

DEFCMD DEFCMD etarget ecmdnmetarget *itarget icmdnmitarget *==pgmnameCICS_loadmodexecname( CLEAR( CICSLINKCICSLOAD AUTHREXXDEFCMD defines (or rede

CICSLOADis a keyword indicating that the processing agent is a CICS program that is loaded by an EXECCICSLOAD.REXXis a keyword indicating that the pro

from the REXX user (programmer), a command can be quickly written in REXX and later transparentlyrewritten in another language, if it becomes performa

DEFSCMDNote: This is an authorized command. DEFSCMD etarget ecmdnmetarget ***itarget icmdnmitarget *==pgmnameCICS_loadmodexecname( CLEAR( CICSLINKCI

CICSLINKis a keyword indicating that the processing agent for the defined REXX command is a standard CICSprogram that is called by an EXEC CICS LINK.C

5. REXX commands can be written in REXX. These REXX commands in turn call other REXX commandswhich are written in REXX, in a building block fashion. S

Quotation marks ensure that information in a program is processed exactly as typed. This is important inthe following situations:v For output that mus

DEFTRNIDNote: This is an authorized command. DEFTRNID trnid execnameCLEARDEFTRNID is a region-wide authorized command that can be used to define t

DIR DIRdirid ( stem.DIR displays the current directory contents or optionally returns the directory contents in a REXXcompound variable.Operandsdi

EDIT EDITNONAMEfileidlib.sublib(mem.type) LIB( MACRO macronameEDIT opens a new edit session.OperandsNONAMEa file ID is not specified. This is the

EXEC EXEC execid args EXEC calls a REXX exec at a lower level (as a nested exec). All variables for this new exec are keptseparate from the higher

EXECDROPNote: This is an authorized command. EXECDROP AUTHClib memberAUTHElibPROClibnameMEM(RFSLIBEXECDROP removes an EXECLOADed exec from virtual

NoteIf a partial directory ID is given, it is temporarily appended to the end of the current working directory valueto get a fully qualified directory

EXECIO EXECIO lines*READ tsqnameWRITE tsqnamestem.varnamerecnoEXECIO performs file input/output to a CICS temporary storage queue.Operandslinesspe

2. If a stem is specified for a READ operation (and a stem should be specified if more than one record isread), the actual number of records read is p

EXECLOADNote: This is an authorized command. EXECLOAD AUTHClib memberAUTHElibPROClibnameMEM(RFSLIBEXECLOAD loads an exec into virtual storage.Oper

Example'EXECLOAD POOL1:\USERS\USER2\TEST.EXEC (RFS'This example loads the exec TEST.EXEC from RFS into storage. Subsequent calls of TEXT.EXE

The PULL instruction can extract more than one value at a time from the terminal by separating a line ofinput. The following variation of the example

EXECMAP EXECMAP EXECMAP returns the sublibraries and members, the number of users, the descriptor table start (in hex),and the amount of storage r

EXPORT EXPORT rfs_fileid lib.sublib(mem.type) EXPORT exports an RFS file to a VSE Librarian sublibrary member.Operandsrfs_fileidspecifies a fully

FILEPOOLNote: This is an authorized command. FILEPOOL DEFINE poolid dirid fileid (USERFORMAT poolidADD poolid fileidFILEPOOL performs RFS file poo

Example'FILEPOOL DEFINE POOL1 REXXDIR1 REXXLIB1 (USER'This example defines file pool POOL1 and tells RFS the CICS file definition to use is

FLST FLSTdiridFLST calls the file list utility to work with the files.Operandsdiridspecifies an optional full or partial directory ID that a file

GETVERS GETVERS GETVERS retrieves the current REXX/CICS, program name, version, and compile time information, andplaces it into the REXX variable

HELP HELPsearch_termHELP browses or searches this book (the IBM REXX Development System for CICS/ TS for VSE/ESA)online.Operandssearch_termspecifi

IMPORT IMPORT lib.sublib(mem.type) rfs_fileid IMPORT imports a VSE Librarian sublibrary member to an RFS file.Operandslib.sublib(mem.type)specifie

LISTCMD LISTCMDenvname cmdnameLISTCMD lists REXX command definition information (previously specified by DEFCMD).Operandsenvnamespecifies the name

LISTCLIB LISTCLIBstem.LISTCLIB displays the names of the authorized command libraries to the terminal or to a specified stemarray, if a stem has b

REXX add 42 21 10The language processor assigns the value 42 to number1, the first variable following ARG. It assigns thevalue 21 10 to number2, the s

LISTELIB LISTELIBstem.LISTELIB displays the names of the authorized exec libraries to the terminal or to a specified stem array, ifa stem has been

LISTPOOL LISTPOOLstem.LISTPOOL displays RFS file pool information to the terminal or to a specified stem array, if a stem hasbeen specified.Operan

LISTTRNIDNote: This is an authorized command. LISTTRNID LISTTRNID lists the current transaction ID definitions created by the DEFTRNID command.Ret

PATH PATH;diridlib.sublibPATH defines the search path for REXX execs.Operandsdiridspecifies one or more fully qualified REXX File System director

PSEUDO PSEUDO ONOFFPSEUDO turns the pseudo-conversational mode on or off.OperandsONenables automatic pseudo-conversational support so that when th

RFS RFSPRIVATEAUTH diridPUBLICRPUBLICWSECUREDCKDIR diridCKFILE fileidCOPY fileid1 fileid2DELETE fileidDATA.DISKR fileidstem.DATA.DISKW fileidstem.GE

fileid2specifies the target file identifier, it may be a fully or partially qualified directory and file identifier.DELETEis a command that deletes an

NoteFile access security checking is performed at the directory level, rather than the file level. If a specified fileID is not a fully qualified ID,

RLS RLS CKDIR diridDELETE listname*QUEUE*LPULL varnamequeid*QUEUE*LPUSH varnamequeid*QUEUE*LQUEUE varnamequeidMKDIR diridDATA.READ listnamestem. ( U

MKDIRis a command that creates a new RLS directory level.READis a command that reads records from an RLS list into a stem.listnamespecifies the list i

4. lastname = WEBER, firstname = JOE, score = 915. lastname = Baker, firstname = Amanda, score = Marie 956. lastname = Callahan, firstname = Eunice, s

SCRNINFO SCRNINFO SCRNINFO returns a two-digit decimal screen height (in lines) in the variable SCRNHT, and returns athree-digit decimal screen wi

SET SET(1)ENGLANGCANFRFRANCGERESPANUCENGHANZIKANJI1024MAXVSTORkilobytesRETRieve pfkeynnTERM CEBRxxxxTERMOUTNOTERM tsq_nameCANCELNotes:1 If no para

RETRieveallows a PF key being set to retrieve the last line entered.pfkeynnspecifies the PF key number.TERMOUTsends terminal line-mode output to a CIC

SETSYSNote: This is an authorized command. SETSYSLANG ENGCANFRFRANCGERESPANUCENGHANZIKANJI1024MAXVSTORkilobytesRETRieve pfkeynnONPSEUDOOFFAUTHClib

pfkeynnspecifies the PF key number.PSEUDOestablishes the default region-wide REXX/CICS automatic pseudo-conversational setting. For moreinformation on

S2C S2C server_rexx_varnameclient_rexx_varnameS2C copies a server REXX variable to a client REXX variable.Operandsserver_rexx_varnameis the name o

TERMID TERMID TERMID returns the four-character CICS terminal ID from the CICS field EIBTRMID in the variableTERMID.Return Codes0 Normal return292

WAITREAD WAITREAD WAITREAD performs full screen terminal input and places the results into the compound variable with:WAITREAD.0containing the num

WAITREQ WAITREQ WAITREQ is used only in REXX servers causing the server to wait for a request. After a request isreceived, it is placed into REXX

Part 3. Appendixes© Copyright IBM Corp. 1992, 2009 377

Note!Before using this information and the product it supports, be sure to read the general information under “Notices” on page443.Second edition (Sep

18 CICS TS for VSE/ESA: REXX Guide

378 CICS TS for VSE/ESA: REXX Guide

Appendix A. Error Numbers and MessagesExternal interfaces to the language processor can generate three of the error messages either before thelanguage

System action: Execution is terminated at the point ofthe error.User response: Redefine storage and reissue thecommand.The following are the REXX erro

When a1=b1 then When a1=b1 then DOSay 'A1 equals B1' Say 'A1 equals B1'exit exitOtherwise nop endend Otherwise nopendSystem action

A-Z a-z 0-9 (Alphamerics)@#£$.?!_ (Name Characters)&*()-+=\¬ '";:<,>/|(Special Characters)If surrounded by X'0E' (shift-

passed back from an EXIT or RETURN instruction(when a REXX program is called as a command) is nota whole number or will not fit in a general register.

Say Enter A, B, or Cshould be written as:Say 'Enter A, B, or C'System action: Execution stops.User response: Make the necessary corrections.

end with a RETURN statement specifying anexpression.System action: Execution stops.User response: Make the necessary corrections.CICREX481E Error 49 r

v NUMERIC FUZZ expressionv OPTIONS expressionv SIGNAL VALUE expressionv TRACE VALUE expression.(FUZZ must be smaller than DIGITS.)System action: Execu

Appendix B. Return CodesThis appendix is a list of all the REXX/CICS return codes.Panel Facility4 Warning. Panel facility continues processing8 Progra

Chapter 3. Using Variables and ExpressionsThis chapter describes variables, expressions, and operators, and explains how to use them in REXXprograms.P

207 Insufficient space in filepool210 Request failed211 Invalid file ID223 Search argument not found226 File is currently being edited229 Number out o

715 Directory already exists716 Directory not specified723 List not found726 List not specified728 List is in update mode729 List is not in update mod

DEFTRNID0 Normal return1202 Invalid operand1222 Invalid option1223 Error storing trantable information1225 Error retrieving trantable information1226

1823 Error storing file pool information1824 File pool ID not specified1825 Error retrieving file pool information1826 Invalid file pool ID1827 Invali

2226 Invalid stem variable nameLISTTRNID0 Normal return2325 Error retrieving trantable informationC2S0 Normal return2440 No variable name specified244

3021 No terminal is attached3099 Internal errorWAITREQ0 Normal return3121 WAITREQ not enabled3122 Exec not a server3123 Error saving request variable3

-527 Redundant specification for option-528 Value for option not specified-529 Value specified for option which should not have a value-530 Value spec

Appendix C. Double-Byte Character Set (DBCS) SupportA Double-Byte Character Set supports languages that have more characters than can be represented b

DBCS character -> .A .B .C .DSBCS character -> abcdeDBCS blank -> '. 'EBCDIC shift-out (X'0E') -> <EBCDIC shift-in

ValidationThe user must follow certain rules and conditions when using DBCS.DBCS Symbol ValidationDBCS symbols are valid only if you comply with the f

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 ea

PARSEIn EBCDIC:x1 = '<><.A.B><. . ><.E><.F><>'PARSE VAR x1 w1w1 -> '<><.A.B><. .

When the data is split up in shorter lengths, again the DBCS data integrity is kept under OPTIONSEXMODE. In EBCDIC, if the terminal line size is less

In EBCDIC:'<.A>' = '<.A. >' -> 1 /* true */'<><><.A>' = '<.A><><>

DATATYPEDATATYPE('<.A.B>') -> 'CHAR'DATATYPE('<.A.B>','D') -> 1DATATYPE('<.A.B>&a

RIGHT('a<>',2) -> 'a'CENTER('<.A.B>',10,'<.E>') -> '<.E.E.E.E.A.B.E.E.E.E>&

Drop A.3 ; <.A.B>=3 /* if ETMODE is on */SYMBOL('<.A.B>') -> 'VAR'SYMBOL(<.A.B>) -> 'LIT' /* has

WORDPOSIn EBCDIC:WORDPOS('<.B.C> abc','<.A. .B.C> abc') -> 2WORDPOS('<.A.B>','<.A.B. .A.B&g

DBCENTER DBCENTER(string,length,pad ,option) returns a string of length length with string centered in it, with pad characters added as necessary

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

 DBRRIGHT(string,length,option) returns the remainder from the DBRIGHT function of string.Iflength is greater than the length of string,returns a

ANSWERS1. Incorrect, because the first character is a number.2. Incorrect, because the first character is a “£”.3. Valid4. Valid5. Valid, but it is a

DBVALIDATE DBVALIDATE(string,'C') returns 1 if the string is a valid mixed string or SBCS string. Otherwise, returns 0. Mixed string val

Appendix D. Reserved Keywords and Special VariablesYou can use keywords as ordinary symbols in many situations where there is no ambiguity. The precis

RC is set to the return code from any run host command (or subcommand). Following the SIGNALevents, SYNTAX, ERROR, and FAILURE, RC is set to the code

Appendix E. Debug AidsThis appendix describes the interactive debugging of problems, interrupting execution, and controllingtracing.Interactive Debugg

Since any instructions may be run in interactive debug, you have considerable control over execution.Some examples:Say expr /* displays the result of

Appendix F. REXX/CICS Business Value DiscussionCICS Transaction Server for VSE/ESA REXX provides an ideal system to deliver superior, valuable, andapp

v CICS Transaction Server for VSE/ESA REXX is useable by business peopleQuite often, business people who best understand the business and their requir

v CICS Transaction Server for VSE/ESA REXX supports six languagesCICS Transaction Server for VSE/ESA REXX provides REXX messages in six languages, in

416 CICS TS for VSE/ESA: REXX Guide

Appendix G. System Definition/Customization/AdministrationThis appendix discusses the system definition, customization, and administration of REXX/CIC

** Raise a number to a whole number power−number(Prefix −) Same as the subtraction 0 - number+number(Prefix +) Same as the addition 0 + numberUsing nu

Setting System OptionsSystem options are specified by using the REXX/CICS SETSYS command. It is recommended thatsystem-wide SETSYS commands be placed

Function IDsA AlterR ReadU UpdateSystem Definition/Customization/AdministrationAppendix G. System Definition/Customization/Administration 419

System Definition/Customization/Administration420CICS TS for VSE/ESA: REXX Guide

Appendix H. SecurityREXX/CICS can be viewed as a more sophisticated version of the CICS-supplied Command LevelInterpreter Transaction (CECI). The REXX

authorized. This is the logical place to define authorized users and libraries. The sublibrary containing theCICSTART exec is treated as the initial “

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 a

Security424CICS TS for VSE/ESA: REXX Guide

Appendix I. Performance ConsiderationsBecause of the production nature of CICS, emphasis is placed on performance. Many design choices canaffect perfo

426 CICS TS for VSE/ESA: REXX Guide

Appendix J. Basic Mapping Support ExampleThis appendix has a list of steps that you must follow so you can use the CICS basic mapping support(BMS) wit

7+2*3-1\___/63. Addition and subtraction from left to right7+6-1=12Using Arithmetic ExpressionsYou can use arithmetic expressions in a program many di

The map DSECT follows.* TEST PANEL FOR REXX/CICS 00000010PANEL1S EQU * START OF DEFINITION 00000020SPACE 00000030DS CL12 TIOA PREFIX 00000040DUSERIDL

/* and initialize */'PSEUDO OFF'ZEROES = '00'x'CICS GETMAIN SET(WORKPTR) LENGTH(90) INITIMG(ZEROES)'VAR1 = 'USERID

REXX/CICS HEADER PANEL1 PANEL1PLEASE ENTER YOUR USERID: TESTMSG: Please enter 8 character USERIDBMS Example430CICS TS for VSE/ESA: REXX Guide

Appendix K. Post-Installation ConfigurationThis appendix has a list of the steps to configure the REXX support.Create the RFS FilepoolsThe REXX Filing

COPY CICHPREP.Z:=.PROC R=YCOPY CICIVP1.Z:=.PROC R=YCOPY CICIVP2.Z:=.PROC R=YCOPY CICIVP3.Z:=.PROC R=YCOPY CICLCLIB.Z:=.PROC R=YCOPY CICLELIB.Z:=.PROC

Format the RFS FilepoolsEnsure that all required configuration tasks have been performed, and if necessary re-start CICS. Sign onwith a userid defined

CONNECT S=PRD1.BASE : user.sublibCOPY CICR3270.Y : CICR3270.BOOKCOPY CICINDEX.N : CICINDEX.PANSRCCOPY CICSNDX.N : CICSNDX.PANSRCCOPY CICCHAP.N : CICCH

Sample output:Enter a REXX command or EXIT to quitCALL CICIVP1***------------------------------------------------------****** This is a test REXX prog

A package for the CICSQL program is loaded into the DB2 database under the SQLDBA user. This issupplied as member CICSQL.A.If you fail to do this, REX

BibliographyCICS Transaction Server for VSE/ESA Release 1 libraryEvaluation and planningCICS TS for VSE/ESA Enhancements Guide GC34-5763CICS TS for VS

For example, if A=4and Z=3, then the results of the previous comparison questions are:(A=Z) Does4=3? 0 (False)(A>Z) Is4>3? 1 (True)(A<Z) Is4&

CICS ClientsCICS Clients: Administration SC33-1792CICS Universal Clients Version 3 for OS/2: Administration SC34-5450CICS Universal Clients Version 3

TCP/IP User's Guide SC33-6601Turbo Dispatcher Guide and Reference SC33-6797Unattended Node Support SC33-6712High-Level Assembler Language (HLASM)

Diagnosis LY43-0065Data Areas LY43-0104Messages and Codes SC31-6493Migration Guide GC31-8072Network Implementation Guide SC31-6494Operation SC31-6495O

DL/I VSEApplication and Database Design SH24-5022Application Programming: CALL and RQDLI Interface SH12-5411Application Programming: High-Level Progra

442 CICS TS for VSE/ESA: REXX Guide

NoticesThis information was developed for products and services offered in the U.S.A. IBM®may not offer theproducts, services, or features discussed i

444 CICS TS for VSE/ESA: REXX Guide

TrademarksThe following terms are trademarks of International Business Machines Corporation in the United States,or other countries, or both:ACF/VTAM

446 CICS TS for VSE/ESA: REXX Guide

IndexSpecial characters! prefix on TRACE option 168? prefix on TRACE option 167/ (division operator) 21, 116, 218// (remainder operator) 21, 116, 221/

Exercises - Using Comparison Expressions1. Based on the preceding example of using a comparison expression, what result does the languageprocessor pro

CASE command 236, 242CATMOUSE EXEC 91CD command 127, 231, 258, 321, 339CEDA command 105, 323CEMT command 105, 324Century option of DATE function 182CH

error 379, 387debugging 29ERROR 225ERROR condition of SIGNAL and CALLinstructions 228error messages 12ETMODE 151European option of DATE function 182ev

FFAILURE condition of SIGNAL and CALLinstructions 225, 228failure, definition 125featureof REXX 3FIFO (first-in/first-out) stacking 160file access sec

LPUSH command 276LQUEUE command 277MMACRO command 246mapping between commands 319master terminal transaction (CEMT) 3messagesinterpreting 12minutes ca

quotation marksaround a literal string 6in an instruction 6Rrandom number function of RANDOM 190RDIR command 263READ command 277recursive call 136refe

subkeyword 120subroutinecomparison to a function 57, 70description 57protecting variable 62writing 58subsidiary list 142, 155SUBSTR 192substring 192su

454 CICS TS for VSE/ESA: REXX Guide

Sending your comments to IBMIf you especially like or dislike anything about this book, please use one of the methods listed below tosend your comment

456 CICS TS for VSE/ESA: REXX Guide

OperatorMeaning& ANDReturns 1 if both comparisons are true. For example:(4 > 2) & (a = a) /* true, so result is 1 */(2 > 4) & (a = a

SC34-5764-01

Spine information: CICS TS for VSE/ESA REXX Guide

\___________________/ /true /\_____________________________/trueAs a result, when you run the program, it produces the result:Go skiing.Exercises - Us

ContentsPreface ...xixWhat this book is about ...xixWho this book is for ...

The result of this example is:baseball £ 5A more sophisticated way to format information is with parsing and templates. Information about parsingappea

3. Evaluate 0&1is 0Exercises - Priority of Operators1. What are the answers to the following examples?a. 22 + (12 * 1)b. -6/-2>(45%7/2)-1c. 10*

When you run the example, the SAY instruction produces:9*-*IFa+1>5*y>V> "9">L> "1">O> "10">L>

When you run this program, it produces:12*-*IF(a>z)|(c<2*d)>V> "1">V> "2">O> "0">V> "

Using Variables and Expressions32CICS TS for VSE/ESA: REXX Guide

Chapter 4. Controlling the Flow within a programThis chapter introduces instructions that alter the sequential execution of a program and demonstrates

As a REXX instruction, the flowchart example looks like:IF expression THEN instructionELSE instructionYou can also arrange the clauses in one of the f

Looking at the program you might assume the ELSE belongs to the first IF. However, the languageprocessor associates an ELSE with the nearest unpaired

Exercise - Using the IF...THEN...ELSE InstructionWrite the REXX instructions for the following flowchart:ANSWERIFa=0THENIFc=2THENz=1ELSE NOPELSEIFz=2T

SELECT WHEN...OTHERWISE...END InstructionTo select one of any number of choices, use the SELECT WHEN...OTHERWISE...END instruction. In aflowchart it a

Tracing Results ...30Exercises - Using the TRACE Instruction ...30Chapter 4. Controlling the Flow wit

Each SELECT must end with an END. Indenting each WHEN makes a program easier to read.Exercises - Using SELECT WHEN...OTHERWISE...END"Thirty days

Using Looping InstructionsThere are two types of looping instructions, repetitive loops and conditional loops. Repetitive loops letyou repeat instruct

DO number=1TO5SAY 'Loop' numberSAY 'Hello!'ENDSAY 'Dropped out of the loop when number reached' numberThis example resul

This example sends strings to a user-written function for processing and then issues a message that theprocessing completed successfully or failed. Wh

Number 1Number 2Number 3Number 4Number 5Number 6Number 7Number 9Number 10Exercises - Using Loops1. What are the results of the following loops?a.DO di

DO WHILE LoopsDO WHILE loops in a flowchart appear as follows:DO WHILETr ueinstruction(s)expressionFalseENDAs REXX instructions, the flowchart example

DO UNTIL LoopsDO UNTIL loops in a flowchart appear as follows:FalseDO UNTILTr ueinstruction(s)expressionENDAs REXX instructions, the flowchart example

Exercise - Using a DO UNTIL LoopChange the program in the previous exercise on page “Exercise - Using a DO WHILE Loop” on page 43from a DO WHILE to a

ANSWERCombining Types of LoopsYou can combine repetitive and conditional loops to create a compound loop. The following loop is set torepeat 10 times

DO outer=1TO2DO inner=1TO2SAY 'HIP'ENDSAY 'HURRAH'ENDThe output from this example is:HIPHIPHURRAHHIPHIPHURRAHIf you need to leave

What is a Host Command Environment? ...82How Is a Command Passed to the Host Environment?...83Changing the Host Com

Outer 1 Inner 1Outer 1 Inner 2Outer 1 Inner 3Outer 2 Inner 1Outer 2 Inner 2Outer 2 Inner 3Outer 3 Inner 1Outer 3 Inner 2Outer 3 Inner 32. The result i

CALL and RETURN InstructionsThe CALL instruction interrupts the flow of a program by passing control to an internal or externalsubroutine. An internal

SIGNAL InstructionThe SIGNAL instruction, like CALL, interrupts the usual flow of a program and causes control to pass to aspecified label. The label

Chapter 5. Using FunctionsThis chapter defines what a function is and describes how to use the built-in functions.What is a Function?A function is a s

Rather than writing multiple instructions every time you want to find the maximum of a group of threenumbers, you can use a built-in function that doe

Arithmetic FunctionsFunction DescriptionABS Returns the absolute value of the input number.DIGITS Returns the current setting of NUMERIC DIGITS.FORM R

Formatting FunctionsFunction DescriptionCENTER orCENTREReturns a string of a specified length with the input string centered in it, with pad character

Function DescriptionWORDPOS Returns the word number of the first word of a specified phrase in the input string.WORDS Returns the number of words in t

Other useful built-in functions to test input are WORDS, VERIFY, LENGTH, and SIGN.Exercise - Writing a program with Built-In FunctionsWrite a program

Chapter 6. Writing Subroutines and FunctionsThis chapter shows how to write subroutines and functions and discusses their differences and similarities

Operators ...115Parentheses and Operator Precedence ...118Clauses and Instructions ...

CALL SUBSTR 'verylongword', 1, 8a = RESULT /* a is set to 'verylong' */When deciding whether to write a subroutine or a function,

instruction(s)EXITinstruction(s)instruction(s)RETURNz=func1(arg1, arg2)Both subroutines and functions can be internal (designated by a label) or exter

FUNC2ARG var1instruction(s)RETURN valueMAINinstruction(s)z=func2(arg1)instruction(s)………exitWhen to Use Internal Versus External Subroutines or Functio

The next example is the same, except it passes information to a function rather than a subroutine. Thesubroutine includes the variable answer on the R

The next example is the same, except it passes information using a function instead of a subroutine.To avoid this kind of problem in an internal subro

The following examples show how results differ when a subroutine or function uses or does not usePROCEDURE.The next two examples are the same, except

Exposing Variables with PROCEDURE EXPOSE: To protect all but specific variables, use the EXPOSEoption with the PROCEDURE instruction, followed by the

In a function call, you can pass up to 20 arguments separated by commas.function(argument1,argument2,argument3,...)Using the ARG Instruction: A subrou

In the two preceding examples, notice the positional relationships between long and length, and wide andwidth. Also notice how information is received

Exercise - Writing an Internal and an External SubroutineWrite a program that plays a simulated coin toss game and produces the accumulated scores.The

OPTIONS ...151PARSE ...152PROCEDURE ...155PULL ...

Exercise - Writing a FunctionWrite a function named AVG that receives a list of numbers separated by blanks and computes theiraverage. The final answe

/******************************* REXX ********************************//* This function receives a list of numbers, adds them, computes *//* their ave

Subroutines and Functions—Similarities and DifferencesThe following tables highlight similarities and differences between subroutines and functions:Si

Chapter 7. Manipulating DataThis chapter describes how to use compound variables and stems and explains parsing.Using Compound Variables and StemsSome

DOi=1TO6PARSE PULL employee.iENDIf you use the same names used in the example of the employee array, you have a group of compoundvariables as follows:

h. SAY a.firsti. SAY z.a.42. After these assignment instructions, what output do the SAY instructions produce?hole.1 = 'full'hole. = 'e

/* This REXX program parses the string: "Knowledge is power." */PARSE PULL word1 word2 word3/* word1 contains 'Knowledge' *//* wor

quote = 'Knowledge is power.'PARSE VAR quote word1 word2 word3/* word1 contains 'Knowledge' *//* word2 contains 'is' *//

StringIf you use a string in a template, parsing checks the input data for a matching string. When assigning datainto variables, parsing generally ski

/* part1 contains 'Igno' *//* part2 contains 'rance' *//* part3 contains ' is bliss.' *//* part4 contains 'Ignoranc