ITM System REXX - IBM WWW PageFILE/ITM_System_REXX.pdfInvoking System REXX Programs from IBM Tivoli Monitoring Command and Automation Functions Page 1 of 11 Invoking System REXX Programs

©2010 IBM Advanced Technical Skills Techdocs: http://www.ibm.com/support/TechDocs Version 5/14/2010 Invoking System REXX Programs from IBM Tivoli Monitoring Command and Automation Functions Page 1 of 11

Invoking System REXX Programs from IBM Tivoli

Monitoring Command and Automation Functions

Mike Bonett

IBM Corporation

Advanced Technical Skills, Gaithersburg, MD

[email protected] System REXX™ is a z/OS® component (z/OS 1.8 and higher) that allows REXX programs to be executed outside of conventional TSO/E and batch environments, such as from an operator console. This now allows automation products to issue console commands to directly run REXX programs without the need for a JCL “wrapper” or via another subsystem such as NetView®. IBM Tivoli Monitoring (ITM) provides two methods of invoking commands via z/OS console facilities:

• Manually, by defining and executing a “Take Action” command from the Tivoli Enterprise Portal graphical or command line interfaces.

• Automatically, in either a Situation action definition or a Workflow Policy “take action” definition.

With System REXX, ITM can directly invoke REXX programs on z/OS using either of these methods. Attributes from monitored metrics or the situation attributes can be passed from ITM to the REXX program, which can process that information as desired. Since REXX can interface with many application subsystems (DB2®, MQ®, WebSphere®, etc.), ITM can send information that the REXX program can place into the subsystem, or have the REXX program extract information from the subsystem. This document will provide a few examples of how that can be done. System REXX Basic Setup

Details on System REXX can be found in the z/OS (version 1.8 and above) documentation. The System REXX address space is named AXR, and is started automatically after an IPL. Parameters to customize AXR and the System REXX environment are defined in the SYS1.PARMLIB(AXRxx) and SYS1.PARMLIB(CTIAXRxx) members. Requests can be issued to System REXX via the MODIFY AXR command. This can be used to either gather status information or to invoke a REXX exec. For example, F AXR,SYSREXX,STATUS returns status information on the System REXX environment:


F AXR,SYSREXX,STATUS

AXR0200I SYSREXX STATUS DISPLAY 877

SYSTEM REXX STARTED AT 12.45.08 ON 04/01/2010

PARMLIB MEMBERS: AXR00

CPF: REXXCB (SYSPLEX) AXRUSER: *NONE*

TIMEINT: 30

SUBSYSTEM: AXR

REQUESTS QUEUED: 0 ACCEPTING NEW WORK

REXX WORKER TASKS: ACTIVE: 0 TOTAL: 4

IDLE: 4 MAX: 64

ASYNC: 0 SYNC: 0

UNTIMED: 0

TSO SERVER SPACES: ACTIVE: 0 TOTAL: 1

IDLE: 1 MAX: 8

ASYNC: 0 SYNC: 0

UNTIMED: 0

A command prefix is defined in AXRxx as an easy way to issue the SYSREXX STATUS command or to invoke a REXX program. The default command prefix is REXX&SYSCLONE, where &SYSCLONE is a z/OS variable that represents the system name. For example, a REXX program HELLO can be executed in the following manner, on a system whose &SYSCLONE value is ‘CB’: REXXCB HELLO

AXR0500I AXREXX OUTPUT DISPLAY 773

EXECNAME=HELLO REQTOKEN=0000400000000000C5F795A8A897D920

Hello From System REXX

System REXX retrieves the requested REXX programs by default from SYS1.SAXREXEC. APAR OA26802 adds the ability to specify additional datasets in the AXRxx parmlib member(s) from which System REXX will look for REXX programs. There are additional security and programming considerations that are outside of the scope of this paper, but are covered in the z/OS System REXX documentation. When REXX programs are run under System REXX, by default any output from “say” commands will appear on the SYSLOG and operator consoles. REXX programs run by System REXX should minimize the amount of information output in this manner, as to not add to the current console traffic. The REXX programs used in this document send output to the console to show the result of the command execution, for illustrative purposes. IBM Tivoli Monitoring – Manual Take Action

ITM Take Action commands are defined via the Tivoli Enterprise Portal or the tacmd command line interface (tacmd createAction). This document will show the Take Action command definition and execution from the Tivoli Enterprise Portal.


A Take Action is created by right clicking on either the Tivoli Enterprise Portal navigator tree or a table/chart data in a workspace view and selecting Take Action->Create or Edit->Create New Action. This brings up a dialog where the Take Action name, description, target monitored system type, and command (and any associated parameters) are defined. The following picture shows the definition of a Take Action command called “System REXX – Hello”. MVS is the monitored system type where the Take Action will execute, and the command is what is sent for execution:

In the above dialog the parameter “IBM Tivoli Monitoring” will be passed to the REXX program. The Take Action is then executed via Take Action->Select and then selecting System REXX – Hello action (from the command line interface the tacmd

executeAction command is used). The following menu appears:


The Take Action command can be sent to one or more z/OS systems. For this example it is sent to the HIVASYSL:HCB$:MVSSYS system. After selecting OK, a return code of zero indicates the command was executed successfully:

The results of the Take Action can be seen in the z/OS SYSLOG or on a console: REXXCB HELLO IBM TIVOLI MONITORING


EXECNAME=HELLO REQTOKEN=0000400000000000C5F7A53EEDB0FCE8

Hello From System REXX to IBM TIVOLI MONITORING

Data that is resolved at Take Action execution time (either from monitored data or manually entered) can also be passed as parameters. Here the Take Action has been modified to include the current CPU utilization (from the OMEGAMON® XE on z/OS System CPU attributes) as part of the command string:


When the Take Action is launched from a table or chart view containing the attribute, the current attribute value will be filled in. Here it is launched from the OMEGAMON XE on z/OS System CPU Utilization workspace, from a table view containing the Average CPU Percent attribute:

The result can be seen in the z/OS SYSLOG:


REXXCB HELLO IBM TIVOLI MONITORING WITH 4 PCT CPU USAGE


EXECNAME=HELLO REQTOKEN=0000400000000000C5F7A7835A0E7728

Hello From System REXX to IBM TIVOLI MONITORING WITH 4 PCT CPU USAGE

IBM Tivoli Monitoring – Situation Command Automation

An ITM situation can issue a command when the situation is triggered. Here a situation named MWB_test_situation_1, that triggers a warning when the current day is Wednesday, is defined. In the situation editor, the “Action” tab of the situation is where the command string to be executed when the situation becomes true is defined:

When the situation is true, a warning appears in the Tivoli Enterprise Portal Situation Event Console:


The command execution result can be seen on the z/OS SYSLOG: REXXCB HELLO FROM ITM SITUATION


EXECNAME=HELLO REQTOKEN=0000400000000000C5F7B887B710C2A8

Hello From System REXX to FROM ITM SITUATION

As with Take Action commands, attributes from the object the situation is associated with can be used as parameters in the command string, and will be resolved when the situation triggers and executes the command. Here the situation is modified to include the current day of the month, current month, and current timestamp:

The result of this execution can be seen on the z/OS SYSLOG:


REXXCB HELLO FROM ITM SITUATION 12 , MAY , 1100512201650000


EXECNAME=HELLO REQTOKEN=0000400000000000C5F7B9B3CCB68764

Hello From System REXX to FROM ITM SITUATION 12 , MAY , 1100512201+

650000

Subsystem Integration Examples

REXX can interface with many application subsystems. ITM can pass information to those subsystems using System REXX. When REXX is run in a batch job, started task, or under TSO, the modules required to access the subsystem might normally be made available via STEPLIB in the JCL or the TSO logon procedure. Since System REXX runs as a system service, the modules required to allow that interface must be accessible via the z/OS module search order. The best options are either the link pack area (LPA) or the link list. The LPA is searched before the link list; LPA modules are loaded in common storage and shared among address spaces, but they must be reentrant. Link list modules are loaded into the private area of the requesting address space and executed there. In most cases the link list is a good option to choose. Subsystem Integration Example: WebSphere MQ

WebSphere MQ Support Pac MA95 provides modules that allow REXX programs to access MQ and put/get messages. To allow System REXX to find these modules the MA95 load library can be placed in the link list. Here a Take Action command is defined that will invoke a REXX program called TESTMQ1 that will place a message on a queue:

When this Take Action is run, a prompt appears for the queue manager, queue, and message information:


The results of the Take Action can be seen in the SYSLOG. The TESTMQ1 program echoes the return codes for each step involved in connecting to a queue manager and placing a message: REXXCB TESTMQ1 CSQ3 MWBQUEUE1 HELLO FROM ITM TAKE COMMAND


EXECNAME=TESTMQ1 REQTOKEN=0000400000000000C5F7C3603D1ACAE8

MQS Initialization RESULT: 0 0 0 RXMQINIT OK WMQ Support Pac MA95. Ve+

rsion 1.0.2 (C) Copyright IBM Corporation. 1997, 2010.

CSQ3 QUEUE MANAGER CONNECT RESULT: 0 0 0 RXMQCONN OK

MWBQUEUE1 QUEUE OPEN CALL RESULT: 0 0 0 RXMQOPEN OK

PUT MESSAGE RETURN CODE: 0 0 0 RXMQPUT OK

CLOSE MESSAGE RETURN CODE: 0 0 0 RXMQCLOS OK

DISCONNECT QUEUE MANAGER RETURN CODE: 0 0 0 RXMQDISC OK

TERMINATION RETURN CODE: 0 0 0 RXMQTERM OK

The OMEGAMON XE for Messaging agent workspace views can be used to examine the message information and contents:


A situation or workflow policy can invoke the TESTMQ1 REXX program in the same manner.

Subsystem Integration Example: DB2

DB2 provides the DSNREXX interface for REXX access to DB2. System REXX can use this interface if the DB2 SDSNLOAD and SDSNEXIT load libraries are placed in the link list. Here an OMEGAMON XE for CICS situation is defined that, when true, will invoke a REXX program called TESTDB1. The program will take the situation attributes passed to it and insert a record into a DB2 table. The first two parameters are the target DB2 subsystem and table, and the rest is data from the situation attributes that will be inserted as a record:


When the situation triggers and issues the command, the following is seen on the SYSLOG. The TESTDB1 program prints the status for each step involved in connecting to DB2 and inserting the record into the table: REXXCB TESTDB1 DSN9 BONETT.MWBTEST1 6460079 CICS31A 2 19 6


EXECNAME=TESTDB1 REQTOKEN=0000400000000000C5F7D006B5CB6EE4

20100512 17:56:43 table BONETT.MWBTEST1 record insertion started

ADDRESS TSO RC: 1

RXSUBCOM RC: 0

DB2 CONNECT RC: 0

SQL STATEMENT: INSERT INTO BONETT.MWBTEST1

VALUES('6460079','CICS31A','2','19',' 6')

INSERT SQLCODE SQLSTATE: 0 00000

COMMIT SQLCODE SQLSTATE: 0 00000

DISCONNECT RC: 0

20100512 17:56:43 table BONETT.MWBTEST1 record insertion completed

Using the DB2 ISPF interface the table data can be displayed: SELECT * FROM BONETT.MWBTEST1;

---------+---------+---------+---------+---------+---------

FIELD1 FIELD2 FIELD3 FIELD4 FIELD5

---------+---------+---------+---------+---------+---------

6460079 CICS31A 2 19 6

6460263 CMAS410A 0 0 5

6472190 CMAS410A 0 0 5

DSNE610I NUMBER OF ROWS DISPLAYED IS 3

DSNE616I STATEMENT EXECUTION WAS SUCCESSFUL, SQLCODE IS 100

Summary

These examples just scratch the surface of what is possible with System REXX and IBM Tivoli Monitoring. The use of System REXX provides a simple but powerful method to increase the manual or automated control integration with z/OS from the IBM Tivoli Monitoring environment.

Documents

ITM System REXX - IBM WWW PageFILE/ITM_System_REXX.pdfInvoking System REXX Programs from IBM Tivoli Monitoring Command and Automation Functions Page 1 of 11 Invoking System REXX Programs