Introduction z/OS 1.9 System REXX

IBM Deutschland GmbHIntroduction z/OS 1.9 System REXXLutz KühnerLutz.Kuehner@de.ibm.com+49 172 6346546© 2008 IBM Corporation

TrademarksIBM Deutschland GmbHThe following terms are trademarks of the IBM Corporation in the United States, other countries, or both:•AD/Cycle•AnyNet•BatchPipes•BookManager•BookMaster•C/370•CICS•CICS/ESA•DB2•DB2 Universal Database•DFS•DFSMSdfp•DFSMSdss•DFSMShsm•DFSMSrmm•DFSORT•Encina•ESCON•eServer•FICON•HiperSockets•HyperSwap•IBM•IBMLink•IMS•Infoprint•Language Environment•Multiprise•MQSeries•MVS•MVS/ESA•NetSpool•NetView•Open Class•OS/390•Parallel Sysplex•PR/SM•Print Services Facility•PrintWay•ProductPac•RACF•Redbooks•Resource Link•RMF•S/390•SecureWay•Sysplex Timer•SystemPac•System REXX•SYSREXX•System z•System z9•Tivoli•TotalStorage•Virtualization EngineSystem REXXSYSREXX•VisualAge•VSE/ESA•VTAM•WebSphere•z/Architecture•z/OS•z/VM•Z9•zSeries• zSeriesJava is a registered trademark of Sun Microsystems, Inc. in the United States, other countries, or both.• Microsoft, Windows, and Windows NT are registered trademarks of Microsoft Corporation in the United States, other countries, orboth.• Pentium is a registered trademark of Intel Corporation in the United States, other countries, or both. (For a complete list of Inteltrademarks, see http://www.intel.com/sites/corporate/tradmarx.htm.)• Unicode is a trademark of Unicode, Inc.• UNIX is a registered trademark of The Open Group in the United States and other countries.• Linux is a trademark of Linus Torvalds in the United States, other countries, or both.• Other company, product, and service names may be trademarks or service marks of others. IBM Confidential Notices2System REXX© 2008 IBM Corporation

IBM Deutschland GmbHAgenda• Test• Introduction and Design• Implementation and Customization• Getting started• Migration & Coexistence Considerations3System REXX© 2008 IBM Corporation

IBM Deutschland GmbHTestST 13,SAVE+4LA 14,SAVEST 14,8(13)LR 13,14MODESET KEY=ZERO,MODE=SUP,RELATED=(TERM1)LA 13,SAVE1L 6,TCBADDRL 7,ASIDNUMTERM1 TYPE=ABTERM,COMPCOD=X'FFF',TCB=(6),ASID=(7),DUMP=NOLA 13,SAVEL 13,SAVE+4LM 14,12,12(13)SR 15,15BR 14DS 0FTCBADDR DC X'00000000'ASIDNUM DC X'00000000'4System REXX© 2008 IBM Corporation

IBM Deutschland GmbHIntroduction - SimplificationThe role of SYSREXX in “New Face of z/OS” is to provide aninfrastructure through which REXX execs may be run outside the normalTSO/E or Batch environments, using a simple programming interface.This enables the leveraging of base operating system components bynew style applications that will, over time, lead to simplified interactionand more intuitive system management capabilities on z/OS.The ability to initiate REXX execs directly from an operator console hasbeen long overdue on z/OS and is a drag along benefit of this initiative.The possibilities for exploiting existing REXX code through the use ofSYSREXX are vast, whether to provide operator assists or to provideroutines that can be leveraged by new strategic initiatives.5System REXX© 2008 IBM Corporation

IntroductionIBM Deutschland GmbH‣ A straightforward mechanism for Common Information Model (CIM)Server Indication, Instance and Method Providers to request executionof REXX routines and z/OS System Commands and for the return ofparsed operational information in support of the Business Resiliencyeffort.‣ A way for system and application components to leverage the parsingstrengths of REXX.‣ Because REXX coding skills are relatively abundant and span theprimary operating systems there is the possibility that code developedon one platform could be shared on others with minimal change.‣ Faster and simpler development of new Health Checker routines.‣ Can be leveraged to provide simplified operator assist functions andquick fixes to niggling problems‣ Assembler skill is becoming rare6System REXX© 2008 IBM Corporation

IBM Deutschland GmbHLogical Overview – cont• LINK, LINKMVS, ATTACH, ATTCHMVS, ATTCHPGM, CPICOMM,LU62, APPCMVS environments supported• No USS function supported this time• Only documented functions available, full functionallity R11• When TSO=NO‣ When TSO=NO up to 63 worker tasks running in AXR AS‣ Dataset Allocation no other than in AXREXX macro provided• When TSO=YES‣ REXX runs in a isolated AS AXR01-AXR04‣ More Dataset allocations than TSO=NO‣ Does not support all TSO functions‣ Some TSO control blocks missing or imcomplete‣ Storage function to prevent storage manipulations8System REXX© 2008 IBM Corporation

IBM Deutschland GmbHLogical Overview – Problems• Some authorized commands do not tolerate a dynamic environment• TSO/E control blocks unavailable or incomplete• Cannot tolerate the default userid “*”• Link, Load, or Attach unauthorized modules … ABEND306• JES facilities unavailable in sub-system MASTER• Resources not cleaned up & may influence subsequent execs9System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization - Checklist• Install System REXX on rel 8 systems, if needed HBB77SR• Setup parmlib member AXR00 (copy from SAMPLIB)• Setup parmlib member CTIAXR00• Customize SYS1.SAXREXEC library• Setting up AXRPSTRT procedure• Setting up security10System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – get baseFMID: HBB77SRPGMDIR: GI10-0793-00PSP: ZOSV1R8 / SYSREXXDownload for System REXX Web Deliverable FMID HBB77SRhttps://www14.software.ibm.com/webapp/iwm/web/preLogin.do?lang=en_US&source=sysrexx11System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – AXR00• CPF definescommand prefixoraction characterandscope of prefix• AXRUSERdefines the defaultusers if AXREXXis invoked13System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – CTIAXR00• CustomizeComponentTraceSettings• Defaultprovided inIBM.PARMLIB14System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – SAXREXEC• SYS1.SAXREXEC shipped by IBM• Contains IBM provided REXX‘s (starting with A through I)• User defined REXX must reside in SYS1.SAXREXEC• REXX can placed either compiled or as script• Do not rename this libraryAttention: Do not use REXX names beginning with A through I15System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – AXRPSTRT• Make AXRPSTRT available (Proclib concatination)• Used to Restart AXR Adress Space• Only FORCE AXR,ARM will work to terminate AXR AS• Shipped in IBM PROCLIBIEF403I IEESYSAS - STARTED - TIME=05.38.02 - ASID=006C - SC70IEE252I MEMBER AXR00 FOUND IN SYS1.SYSPROG.PARMLIBIEF196I IEF285I SYS1.SYSPROG.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= SBOX01.IEF196I IEF285I SYS1.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= SBOX00.IEF196I IEF285I CPAC.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= Z19CAT.IEF196I IEF285I SYS1.IBM.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= Z19RD1.IEE252I MEMBER CTIAXR00 FOUND IN SYS1.IBM.PARMLIBIEF196I IEF285I SYS1.SYSPROG.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= SBOX01.IEF196I IEF285I SYS1.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= SBOX00.IEF196I IEF285I CPAC.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= Z19CAT.IEF196I IEF285I SYS1.IBM.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= Z19RD1.AXR0102I SYSTEM REXX INITIALIZATION COMPLETE16System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – SecuritySetup Adress SpacesAU AXR DFLTGRP(OMVSGRP) OWNER(LUTZ)NOPASSWORDALU AXR OMVS (PROGRAM('/bin/sh')UID( &UID ))RDEFINE STARTED AXR.*STDATA(USER(BPXSTC)GROUP(OMVSGRP)AU AXRPSTRT DFLTGRP(OMVSGRP) OWNER(LUTZ)NOPASSWORDRDEFINE STARTED AXR.*STDATA(USER(BPXSTC)GROUP(OMVSGRP)17System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – Security cont.Setup AXR Adress Space functional groupAG AXRSTC SUPGRGP(SYS1) OWNER(LUTZ)CO AXR GROUP(AXRSTC)PE ‘SYS1.PARMLIB’ ACC(READ) ID(AXRSTC)PE ‘SYS1.SAXREXEC’ ACC(READ) ID(AXRSTC)18System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – Security cont.Setup Surrogat classRDEFINE SURROGAT SYSREXX.AXRUSER UACC(NONE)SETROPTS GENERIC (SURROGAT) REFRESHPERMIT SYSREXX.AXRUSER CL(SURROGAT)ACCESS(ALTER) ID(permitteduserid|group)19System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – Security AXR• AXREXX is an Authorized System Service– Security Controls Essential– Access to APF Library– Permissions• EXECs by default use Invoker’s Security– Alternatively may use:– Authority of a 3 rd party – a surrogat– Special userid assigned to AXRUSER• EXECs use Invoker’s Enclave service class– Prevent CPU priority inversion & excessive resource usage– Resource usage is charged back20System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – Startup• AXR startup early during Master Scheduler Initialization• No STOP capability but AXR address space can be forcedIEF403I IEESYSAS - STARTED - TIME=05.38.02 - ASID=006C - SC70IEE252I MEMBER AXR00 FOUND IN SYS1.SYSPROG.PARMLIBIEF196I IEF285I SYS1.SYSPROG.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= SBOX01.IEF196I IEF285I SYS1.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= SBOX00.IEF196I IEF285I CPAC.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= Z19CAT.IEF196I IEF285I SYS1.IBM.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= Z19RD1.IEE252I MEMBER CTIAXR00 FOUND IN SYS1.IBM.PARMLIBIEF196I IEF285I SYS1.SYSPROG.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= SBOX01.IEF196I IEF285I SYS1.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= SBOX00.IEF196I IEF285I CPAC.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= Z19CAT.IEF196I IEF285I SYS1.IBM.PARMLIBKEPTIEF196I IEF285I VOL SER NOS= Z19RD1.AXR0102I SYSTEM REXX INITIALIZATION COMPLETE21System REXX© 2008 IBM Corporation

IBM Deutschland GmbHImplementation and Customization – Startup• AXR ASup & running• AXR01TSO=YESAS active22System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – console command• Operator Command Support– Detected by System REXX SSI Listener– Uses a customizable Command Prefix (cpf)– Administrative Support– cpfSYSREXX STATUS[,DETAIL]– Seamless operator interface for REXX execs– cpfRexxExecName Arg1 Arg2 … Argn23System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – REXX API‘s• AXRCMD Issue a console command and return commandresponses• AXRWTO Issue a single line message to a console• AXRMLWTO Issue a multiline line message to a console24System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – REXX API‘s example25System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – REXX API‘s example USS ?26System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – AXREXX service• New API is AXREXX– Caller must be authorized– Two Modes of Execution– TSO=NO Limited Data Set Support– TSO=YES Full Data Set Support Permitted (no sysout)– Two Operations are supported– REQUEST=EXECUTE | CANCEL– Arguments & Variables are used to pass input to and receiveoutput from the REXX exec– Parameter List is mapped by the AXRZARG macro27System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – AXREXX service cont.• New API is AXREXX– Data Types supported:– Input is converted to strings– Output is returned as signed/unsigned, char, binary, hex– Security Environment of Requester is used• Time Limitations are Applied to Execs– Default is 30 seconds• Cancellation of REXX Exec using API– OREQTOKEN parameter• REXX Execs Read From SYS1.SAXREXEC28System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – AXREXX service cont.[xlabel]AXREXXREQUEST={EXECUTE|CANCEL}[,SECURITY={BYUTOKEN|BYAXRUSER}][,UTOKEN={utoken|TASK}][,TSO={NO|YES}][,REXXINDSN={rexxindsn|NO_REXXINDSN}][,REXXINMEMNAME={rexxinmemname|NO_REXXINMEMNAME}][,CONSDATA={NO|YES}][,CART=cart][,CONSNAME=consname][,TIMELIMIT={YES|NO}][,TIMEINT={timeint|SYSTEM}],NAME=name[,REXXARGS={rexxargs|NO_ARGS}][,REXXVARS={rexxvars|NO_VARS}][,REXXOUTDSN={rexxoutdsn|NO_REXXOUTDSN}][,REXXOUTMEMNAME={rexxoutmemname|NO_REXXOUTMEMNAME}] [,REXXDIAG=rexxdiag][,SYNC={YES|NO}][OREQTOKEN=oreqtoken][REQTOKEN=reqtoken][RETCODE=retcode][RSNCODE=rsncode][PLISTVER={0|MAX|IMPLIED_VERSION}][MF=S)][MF=(L,list_addr)][MF=(L,list_addr,attr)][MF=(L,list_addr,0D)][MF=(E,list_addr)][MF=(E,list_addr,COMPLETE)]29System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – AXREXX service cont.• 20 ARGs and 256 VARs are Supported– Maximum supported length of each is currently 512 bytes– Total variable storage available to each request is 128KB• Allocated to storage designated by the requester– Requester’s or other Address Space– High virtual is supported– Data Spaces• ALET qualified addresses are supported• AXRZARG macro provides argument list mapping• Special Variables set by AXR– AXRREQTOKEN 32 Hex Request Token– AXRINDD 8 Char If RexxInDsn Specified– AXROUTDD 8 Char If RexxOutDsn Specified30System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – AXREXX example• define AXRZARG macro• Fill AXRZARG fields31System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – AXREXX example• Call AXREXX macro• AXREXX&AXRZARGMacros found inSYS1.MACLIB32System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – AXREXX Display@SYSREXX STATUS OR @SR STAXR0200I SYSREXX STATUS DISPLAYSYSTEM REXX STARTED AT 11.00.30 ON 09/18/2006PARMLIB MEMBERS: AXR00CPF: @ (SYSTEM) AXRUSER: MEGATIMEINT: 30SUBSYSTEM: AXRREQUESTS QUEUED: 0 ACCEPTING NEW WORKREXX WORKER TASKS: ACTIVE: 0 TOTAL: 4IDLE: 4 MAX: 64ASYNC: 0 SYNC: 0UNTIMED: 0TSO SERVER SPACES: ACTIVE: 0 TOTAL: 0IDLE: 0 MAX: 8ASYNC: 0 SYNC: 0UNTIMED: 0The STATUS sub-function results in a summarydisplay of System REXX environmentalinformation:• time and date the AXR address space was started• parmlib member/s used at startup• command prefix used to identify console initiated REXX execs• scope of the command prefix• special userid against which SYSREXX requests may be invoked• default timeout interval• number of queued REXX execs requests• REXX worker tasks available to process REXX execs– Number of tasks actively processing requests– Number of idle tasks– Total number of tasks (active+idle)– Maximum number of tasks that may be started– Number of synchronous and asynchronous requests– Number of untimed requests• TSO server address spaces available to process REXX execs– Number of address spaces actively processing requests– Number of idle address spaces– Total number of address spaces (active+idle)– Maximum number of address spaces that may bestarted– Number of synchronous and asynchronous requests– Number of untimed requests33System REXX© 2008 IBM Corporation

IBM Deutschland GmbHUsage – AXREXX Display cont.@SYSREXX STATUS,DETAILORAXR0201I SYSREXX STATUS DETAIL@SR ST,DEXEC=WAITLOOP CJBN=AXR CASID=0015 TSO=YT/L=00.00.30REQTOKEN=0000520000000000BF3A704A6511A3B5EJBN=AXR02 EASID=0033 TCB=006FF098CPU=000.004S TIME=005.739SEXEC=INFINITE CJBN=AXR CASID=0015 TSO=YT/L=00.00.30REQTOKEN=0000540000000000BF3A704C2088405CEJBN=AXR03 EASID=0032 TCB=006FF098CPU=000.006S TIME=003.925SThe DETAIL parameter causes detailedinformation about executing REXX execs to bedisplayed:• name of the REXX exec• requester Jobname and ASID• type of request - TSO=N or TSO=Y• time limit for the request• unique request token associated with the request• execution Jobname, ASID and TCB address forTSO=Y requests• cpu seconds currently used• current elapse time seconds34System REXX© 2008 IBM Corporation

IBM Deutschland GmbHMigration & Coexistence Considerations• No Hardware Dependencies• Software Dependencies– To Process Compiled REXX Code– IBM Library for REXX on zSeries OR– IBM Library for REXX on zSeries Alternate Library• Exploiters– CIM Server .. Cluster Instrumentation– Health Checker, SDSF REXX– Open to exploitation by IBM, ISV and Customer Code• As SYSREXX is a new element there are no migration considerations• Please be aware that not every command, function or service that runsunder the TSO/E Terminal Monitor Program is supported in the SYSREXXTSO=Y environment.• Only commands documented will be supported35System REXX© 2008 IBM Corporation

IBM Deutschland GmbHExploiting SYSREXX• Implement automation tasks that could be carried out fromSYSREXX• Perhaps launch from exits• Implement operator tasks that can be launched from the consolevia SYSREXX (Couple DS movement)• Implement health checks in SYSREXX36System REXX© 2008 IBM Corporation

IBM Deutschland GmbH37System REXX© 2008 IBM Corporation

IBM Deutschland GmbHAppendix• Publication References• Examples38System REXX© 2008 IBM Corporation

IBM Deutschland GmbHPublication References• MVS Initialization & Tuning Reference– SA22-7592• MVS System Commands– SA22-7627• Authorized Assembler Services Guide– SA22-7605• Authorized Assembler Services Reference Volume 1– SA22-7609• MVS System Codes– SA22-7626• MVS Diagnosis: Tools and Service Aids– GA22-7589• MVS System Messages Volume 3– SA22-763339System REXX© 2008 IBM Corporation

IBM Deutschland GmbHQuestions40System REXX© 2008 IBM Corporation