Aug 5 ’14

Monitoring Your z/VSE System With SNMP

by Rene Trumpp in Enterprise Tech Journal

Starting with z/VSE 4.3, IBM has developed an application framework that lets you monitor your z/VSE systems using standard monitoring interfaces. This application framework is based
on the common standards TCP/IP and the Simple Network Management Protocol (SNMP). It includes an open interface that lets you use your own programs to collect other data.

Here we provide a summary of the z/VSE SNMP capabilities and an example you can use to monitor your z/VSE console and inform your monitoring appliance (via an SNMP Trap) when a specific console message occurs.

z/VSE SNMP Capabilities

The z/VSE SNMP capabilities can be seen as two parts:

• The z/VSE Monitoring Agent responding to SNMP v1 requests
• The z/VSE Trap Client sending SNMP v1 traps to any monitoring appliance (that has SNMP capabilities).

The z/VSE Monitoring Agent

The z/VSE Monitoring Agent consists of three logical layers:

• A monitoring appliance or a client; this can be a workstation, server, wireless telephone or personal digital assistant (PDA) where monitoring software is installed
• The z/VSE Monitoring Agent, which lies at the center of the application framework and processes requests from clients and controls access to business logic and data
• Plug-ins that provide access to z/VSE data and other data via your own programs.

The z/VSE Monitoring Agent is a batch application that runs in a z/VSE (static or dynamic) partition. It implements an SNMP agent that replies to SNMP v1 requests from SNMP clients.

The z/VSE Monitoring Agent collects the data (which it provides) from different plug-ins (system plug-ins, CPU plug-ins, vendor plug-ins, etc.). The system plug-in and the CPU plug-in are shipped with z/VSE. If you want to extend the z/VSE Monitoring Agent with your own data, the z/VSE e-business Connectors User’s Guide explains how to write your own plug-in.

You can set up the z/VSE Monitoring Agent using these simple steps: 

1. Create a configuration file. You can use the sample configuration file SKMASCFG and sample job IESMASCFG (both provided in VSE/ICCF Library 59) to create a new/customized configuration file in PRD2.CONFIG.
2. Specify in the configuration file the SNMP communityname, the port and the plug-ins you want to use. We recommend you change the communityname for security reasons. It’s used for authentication of clients (i.e., a type of password), which is transmitted in clear text.
3. To start the z/VSE Monitoring Agent, you can use the sample job SKSTMAS (also provided in VSE/ICCF Library 59), which will use the configuration you previously created.

When the z/VSE Monitoring Agent is started, clients can request data from it using the configured communityname and port.

The z/VSE Trap Client

You can use the z/VSE Trap Client to send SNMP v1 Traps to inform one or more monitoring stations/monitoring appliances of the following conditions (as well as many others):

• The end of a job stream has been reached
• An error has occurred during a job stream
• An error has occurred in a program or CICS transaction
• A CICS transaction ended.

The z/VSE Trap Client has many different interfaces and can be used in your:

Batch jobs. There’s a sample job (SKSTTRAP) that provides an example of how to use the SNMP Trap Client in a batch job. It’s provided in VSE/ICCF Library 59 and executes the program IESMTRAP.PHASE.

LE/C programs. To send SNMP Traps from within your C programs, you must include the Trap API C header (IESMTRPH.H) in your LE/C program and the Trap LE/C interface (IESMTRPO.OBJ) during the link-editing of your LE/C program.

COBOL and PL/I programs. To use the trap client from your COBOL and PL/I programs, your programs must call the COBOL and PL/I Batch interface (IESMTRPB.PHASE) using the copybook provided in the z/VSE e-Business Connectors User’s Guide Version 5 Release 1. Note: Your programs can’t send traps to multiple destinations simultaneously; you must instead call the Trap COBOL and PL/I Batch interface multiple times.

CICS programs. Your CICS programs (written in C, COBOL or PL/I) call the Trap CICS interface (IESMTRPC) via an EXEC CICS LINK command. A COMMAREA is passed that has the same layout as the Trap COBOL and PL/I Batch interface.

Monitoring the z/VSE Console

Figure 1 shows a REXX program that monitors the z/VSE console. If the message “1Q31I ACCOUNT FILE (IJAFILE) MORE THAN 80% FULL” is detected, it automatically sends an SNMP trap to the monitoring appliance using the z/VSE Trap Client interface. This is just a sample; it’s possible to monitor any message. You can download the sample from the download section at the z/VSE Homepage at www.ibm.com/vse/downloads/samples.html.

Let's take a look at the interesting parts of the code in Figure 1. The job consists of two parts. In the first part, the REXX program gets cataloged and in the second part, the program is started. So, once the program is cataloged, it isn’t necessary to catalog it every time you want to start it. However, in a test or prototyping environment, it’s very easy to use it that way.

In the first few lines of the program, the destination for the program is specified and the console is prepared for monitoring. Then we see a forever-loop. In this loop, there’s a check if the user entered “msg xx,data=something”. If this is true, the loop will be left and the program will end (this is the way “MSG BG,DATA=EXIT” works). If there’s no input from the user, the program scans the console for the 1Q31I message. If it finds the message, it calls the SENDTRAP subroutine.

In the SENDTRAP subroutine, we set up the SYSIPT variables for the trap client first. There you set the IP of your Monitoring Appliance, the SNMP community name, the OID that will be used as the originator and the message. These values will be given to the SNMP Trap Client. The output of the trap client is displayed after the invocation finishes.

Summary

As you can see, it’s very easy to use the z/VSE Trap Client interface. Although there are many more possibilities than described here, this article hopefully piqued your interest to learn more about what might be possible in your environment with z/VSE. With simple things like this, you can integrate z/VSE into your network and multiplatform environment.

References

• SNMP RFC (RFC 1157): www.ietf.org/rfc/rfc1157.txt
• z/VSE website: www.ibm.com/vse
• z/VSE e-Business Connectors User’s Guide Version 5 Release 1: www.ibm.com/vse/documentation.