REXX SPOC API for IBM IMS

© 2009 IBM Corporation

IMS REXX SPOC API ….everything you always wanted to know

Stan Sun – IMS Developer11/[email protected]


ReThink IMS!

2

Trademarks

IBM, IBM eServer, IBM logo, e-business logo, CICS, DB2, MQ, ESCON, Enterprise Storage Server, GDPS, IMS, MVS, OS/390, Parallel Sysplex, Redbook, Resource Link, S/390, System z9.iSeries, pSeries, System p,xSeries, System x, OS/400, i5OS, System Storage, TotalStorage,VM/ESA, VSE/ESA, WebSphere, z/OS, z/VM, z/VSE, and zSeries are trademarks or registered trademarks of International Business Machines Corp. in the United States, other countries, or both.

Linux is a registered trademark of Linux Torvalds in the United States, other countries, or both.

Microsoft is a registered trademark of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States, other countries, or both.


ReThink IMS!

3

DisclaimersCopyright © 2009 by International Business Machines Corporation.

No part of this document may be reproduced or transmitted in any form without written permission from IBM Corporation or except as expressly provided in a contract between you and IBM.

Product data has been reviewed for accuracy as of the date of initial publication. Product data is subject to change without notice. This information could include technical inaccuracies or typographical errors. IBM may make improvements and/or changes in the product(s) and/or programs(s) at any time without notice.

Any statements regarding IBM's future direction and intent are subject to change or withdrawal without notice, and represent goals and objectives only.

References in this document to IBM products, programs, or services does not imply that IBM intends to make such products, programs or services available in all countries in which IBM operates or does business. Any reference to an IBM Program Product in this document is not intended to state or imply that only that program product may be used. Any functionally equivalent program, that does not infringe IBM’s intellectually property rights, may be used instead. It is theuser’s responsibility to evaluate and verify the operation of any on-IBM product, program or service.

THE INFORMATION PROVIDED IN THIS DOCUMENT IS DISTRIBUTED "AS IS" WITHOUT ANY WARRANTY, EITHER EXPRESS OR IMPLIED. IBM EXPRESSLY DISCLAIMS ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. IBM shall have no responsibility to update this information. IBM products are warranted according to the terms and conditions of the agreements (e.g., IBM Customer Agreement, Statement of Limited Warranty, International Program License Agreement, etc.) under which they are provided. IBM is not responsible for the performance or interoperability of any non-IBM products discussed herein.

The provision of the information contained herein is not intended to, and does not, grant any right or license under any IBM patents or copyrights. Inquiries regarding patent or copyright licenses should be made, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.


ReThink IMS!

4

Agenda

� Overview of the REXX SPOC API

� How the REXX SPOC API fits into an IMSplex environment

� Using the REXX SPOC API–Set up the REXX and IMSplex environment–REXX SPOC API subcommands–Hello World demo–Retrieving unsolicited messages

� How to invoke a REXX SPOC program with a batch JCL

� Autonomic computing example and demo


ReThink IMS!

5

What is the REXX SPOC?

� The REXX SPOC is actually an API that allows REXX programs to:– Submit type-1 or type-2 IMS commands to one or more IMS systems

in an IMSplex– Retrieve command responses– Subscribe to the Operations Manager (OM) for unsolicited system

messages, which can include responses to commands issued from any SPOC in an IMSplex that are routed back through OM.

Source: If applicable, describe source origin


ReThink IMS!

6

IMSplex Operations


Operations Manager

(OM)

SCI

z/OSa z/OSb

z/OSx

SCIAutomation - SPOC

Single Point of Control(SPOC)

IMS Control Region

SCI

IMS Controlregion

SCI

IMS Control Region

SCIREXX

SPOCAPI


ReThink IMS!

7

Advantages over other IMS automation tools like AOI and TCO

The REXX SPOC API has several advantages: � It can issue IMS type-1 or type-2 commands in an IMSplex. In addition,

REXX programs can also issue other commands, such as z/OS operator commands or TSO commands, to manage the system.

� It can examine command responses, unlike TCO, and take further action based on those responses. Those responses are in the form of XMLstatements and are easier to parse than the command responses that are returned to the AOI interface.

� It is independent of IMS, and therefore easier to implement and run.� It can run in Tivoli NetView for z/OS� It can issue /NRE and /ERE commands, unlike TCO.



ReThink IMS!

8

Using the REXX SPOC API environment with the CSL OM

� You can use the REXX SPOC API with the CSL OM to: – Set up the REXX environment– Set up the IMSplex environment and issue commands– Retrieve the command responses

� Each of these phases will be described in detail in the following charts.



ReThink IMS!

9

Setting up the REXX environment in a CSL

� To set up the REXX environment, use the ADDRESS command to call the program CSLULXSB. This program establishes the REXX subcommand environment for the REXX SPOC API.

>>--- ADDRESS --- LINK --- ‘CSLULXSB’ -------------------------------- ><



ReThink IMS!

10

Setting up the IMSplex environment

� After setting up the REXX environment using the CSLULXSB program, you can set up the IMSplex environment.

� To set up the IMSplex environment and begin to issue commands, switch the default host command to IMSSPOC using the ADDRESS command.

>>--- ADDRESS --- IMSSPOC --------------------------------------------------- ><



ReThink IMS!

11

Subcommands in REXX SPOC API

� Required subcommands– IMS– CART– END

� Optional subcommands–ROUTE–WAIT

� Detailed description of above subcommands will be illustrated in later charts.



ReThink IMS!

12

Issuing IMS commands

� You can issue IMS commands, including type-2 commands, by including them in the REXX program stream as quoted strings or as REXX variables that resolve to quoted strings.

� Example– “QUERY IMSPLEX SHOW(ALL)”– “DIS DB F13A0”

– namelist = “name1,name2”“QUERY TRAN NAME(“ namelist “)”



ReThink IMS!

13

Build a Hello World program

� Try to build a Hello World program now before knowing all the details.

� We talked about the REXX and IMSplex setup commands.

� We talked about some REXX SPOC API subcommands.

� We talked about issuing IMS commands as quoted strings.



ReThink IMS!

14

Hello World program (simplified)



ReThink IMS!

15

Run the program

� Before you can run the Hello World program, you’ll need to first complete these set up steps:

– Allocate the program to SYSPROC

–Allocate the LOADLIB to the TSO user ID

� An example is shown on the next chart.



ReThink IMS!

16

Hello World Demo (simplified)



ReThink IMS!

17

IMS subcommand - required

� The IMS subcommand establishes the name of the IMSplex.

� The IMSplex name must be established before any other commands can be issued.

� Note: A prefix of “CSL” is automatically added to the name that you specify.

>>--- IMS --- IMSplex_name ---------------------------------------------------- ><



ReThink IMS!

18

CART subcommand - required

� Use the Command and Response Token (CART) subcommand to set the name of the command and response token.

� The 16-character text string token is used to retrieve the command response.

� The CART subcommand is required before you can successfully issue any IMS commands

>>--- CART --- token_name --------------------------------------------------- ><



ReThink IMS!

19

ROUTE subcommand - optional� Use the ROUTE subcommand to set the name of the command processors.

If you do not specify a command processor:– Commands are routed to all members of the IMSplex. This is the default.– The previous routing value is removed

� Specifying “*” causes the command to be routed to all registered command processing clients in the IMSplex.

� Specifying “%” causes the command to be routed to only one command processing client in the IMSplex that is registered for the command and that has MASTER capability. The OM chooses the command processing client.

---- , ----------------------------->>--- ROUTE ------------------------------------------------------------------------- ><

--- command_processor ------ * ------------------------------ % --------------------------



ReThink IMS!

20

WAIT subcommand - optional

� Use the WAIT subcommand to provide a timeout value to OM.

� This WAIT value is the maximum time you want to wait for OM to complete your command.

� The time value must be in the form MMM:SS or ssss. The maximum value you can specify is 999:59.

>>--- WAIT --- time_value --------------------------------------------------- ><



ReThink IMS!

21

END subcommand

You can end the IMS SPOC environment when you no longer want to execute IMS commands.

� Use the END subcommand to signify that the SPOC environment is no longer needed.

� After the END subcommand is issued, the control blocks associated with the SPOC environment are freed

>>--- END ---------------------------------------------------------------------------- ><



ReThink IMS!

22

Hello World program



ReThink IMS!

23

Hello World Demo



ReThink IMS!

24

Hello World Demo (continue)



ReThink IMS!

25

Retrieving command responses in XML

� Use the CSLULGTS request to retrieve command responses.

� The CSLULGTS request puts the command responses to a stem variable so that REXX can access them.

>>--- CSLULGTS ( stem_name, token_name, “wait_time” ) ------------- ><



ReThink IMS!

26

CSLULGTS parameters

� stem_name– The REXX stem variable is populated with the command response

that is returned by OM.� token_name

– The name of the command and response token (CART).– The token name should match the name specified on the CART

subcommand.� wait_time

– A timeout value for the CSLULGTS request.– The format is MMM:SS or ssss. The maximum value is 999:59.– This wait_time should be at least as long as the value specified on the

WAIT subcommand.



ReThink IMS!

27

Hello World program with CSLULGTS request


matchas long as WAIT

subcommand

any stem variable name

match


ReThink IMS!

28

Retrieving command responses in XML and parsing to stem variablenames directlyCSLULGTP is a newer feature which was first introduced in IMS V10.

� Use the CSLULGTP request to retrieve command responses from OM and put them into a REXX stem variable.

� The REXX program then refers to the information in the stem variable directly, rather than parsing XML statements, as it does with the CSLULGTS command.

>>--- CSLULGTP ( stem_name, token_name, “wait_time” ) ------------- ><



ReThink IMS!

29

CSLULGTP parameters

� stem_name– The REXX stem variable is populated with the command response

that is returned by OM.� token_name

– The name of the command and response token (CART).– The token name should match the name specified on the CART

subcommand.� wait_time

– A timeout value for the CSLULGTP request.– The format is MMM:SS or ssss. The maximum value is 999:59.– This wait_time should be at least as long as the value specified on the

WAIT subcommand.



ReThink IMS!

30

Demo code with CSLULGTP



ReThink IMS!

31

Demo code with CSLULGTP (continue)



ReThink IMS!

32

CSLULGTP demo



ReThink IMS!

33

CSLULGTP suffix variable names table (abbreviated)


N/A</ctl>

stem.ctl.rsn<rsn> </rsn>

stem.ctl.rc<rc> </rc>

stem.ctl.rqsttkn1<rqsttkn1> </rqsttkn1>

stem.ctl.stotime<stotime> </stotime>

stem.ctl.statime<statime> </statime>

stem.ctl.xmlvsn<xmlvsn> </xmlvsn>

stem.ctl.omvsn<omvsn> </omvsn>

stem.ctl.omname<omname> </omname>

N/A<ctl>

N/A<imsout>

stem.dtd<!DOCTYPE imsout SYSTEM “imsout.dtd”>

stem.xmlversion<?xml version=“1.0”?>

Variable nameXML tag


ReThink IMS!

34

CSLULGTP suffix variable names table (continue)


N/A</msgdata>

N/A</mbr>

stem.msgdata.msg.y.0 (num of msgs / sys)stem.msgdata.msg.y.x (1 message line)

<msg> </msg>

stem.msgdata.name.0 (num of systems)stem.msgdata.name.y (1 member name)

<mbr name=“membername”>

N/A<msgdata>

……

Variable nameXML tag

� There are many other useful stem variable name suffix set by CSLULGTP request.

� Complete information can be found in the IMS System Programming API Reference or the IMS Information Center.


ReThink IMS!

35

CSLULOPT – including format identifiers for the /DISPLAY command

� Use CSLULOPT to specify whether a command response should contain format IDs.

� Automated operator programs (AOPs) use format identifiers (FID) to identify the record format of specific lines of a command response.

� Invoke CSLULOPT before IMS commands. The setting remains in effect until you change it.



ReThink IMS!

36

CSLULOPT – including format identifiers (continue)

� Syntax----- FID ----

>>--- CSLULOPT ( --- NOFID --- ) -------------------------------------------- ><

– FID• Specifies that the command response includes the FID.• This is the default

– NOFID• Specifies that the command response does not include the FID.



ReThink IMS!

37

Retrieving unsolicited messages

Use REXX SPOC API to retrieve unsolicited messages from OM

� Use the following functions to retrieve unsolicited output messages:

–CSLULSUB request to subscribe to OM

–CSLULGUM request to get unsolicited messages

–CSLULUSB request to unsubscribe



ReThink IMS!

38

Start a subscription using the CSLULSUB request

� Use the CSLULSUB request to start the subscription and monitor OM for unsolicited messages.

>>--- CSLULSUB ( IMSplex_name, member_list, type_list ) ------------- ><

� Note: If both member_list and type_list are specified, member_list will take precedence and type_list will be ignored.



ReThink IMS!

39

CSLULSUB parameters

� IMSplex_name– Name of the IMSplex.– Do not use the ‘CSL’ prefix.

� member_list– One or more IMSplex member names.– Enclose the list in quotes and separate names by commas.– member_list is optional.

� type_list– List of types of IMSplex members, such as OM, RM, and IMS.– Enclose the list in quotes and separate names by commas.– type_list is optional.



ReThink IMS!

40

Copy unsolicited output messages using the CSLULGUM request

� Use the CSLULGUM request to copy unsolicited output messages to the REXX stem variable.

� The REXX program can then examine the messages and take appropriate action.

>>--- CSLULGUM ( IMSplex_name, stem_name ) ------------------------ ><



ReThink IMS!

41

CSLULGUM parameters

� IMSplex_name– Name of the IMSplex.– Do not use the ‘CSL’ prefix.

� stem_name– Name of a REXX variable that contains any unsolicited messages that

are received.



ReThink IMS!

42

End the subscriptions using the CSLULUSB request

� Use the CSLULUSB request to end the subscription.

� If a subscription does not exist, OM is no longer monitored for unsolicited messages.

>>--- CSLULUSB ( IMSplex_name ) ------------------------------------------- ><

IMSplex_nameName of the IMSplex. Do not use the ‘CSL’ prefix.



ReThink IMS!

43

Demo code to retrieve unsolicited messages



ReThink IMS!

44

Demo code to retrieve unsolicited messages (continue)



ReThink IMS!

45

Retrieve unsolicited messages demo



ReThink IMS!

46

Batch job to call REXX SPOC program

� REXX SPOC program can be called in a batch JCL.

� Batch job output can be held in SDSF output queue.

� Load library and SYSPROC can be set in JCL.



ReThink IMS!

47

Batch job sample



ReThink IMS!

48

DD names in the batch job

� STEPLIB– Contains the load modules.

� SYSPROC– Contains the REXX programs.

� SYSTSPRT– Contains the output produced by the REXX program.

� SYSTSIN– Contains the command to execute, including its parameters.



ReThink IMS!

49

Autonomic computing

� Autonomic indicates that the code is responsive and can take certain actions to correct what it determines to be incorrect.

� Problem– A transaction in an IMS is stopped unexpectedly.– No one is around to take care this problem.

� Solution– A REXX SPOC program can be used to detect this problem and

attempt to restart the transaction.



ReThink IMS!

50

Autonomic computing sample code



ReThink IMS!

51

Autonomic computing sample code (continue)



ReThink IMS!

52

Autonomic computing demo


Bring up a TSO SPOC session


ReThink IMS!

53



Enter a QRY TRAN command


ReThink IMS!

54



ADDPART is active


ReThink IMS!

55



Bring up another TSO session and run the REXX

SPOC program


ReThink IMS!

56



Stop the transaction


ReThink IMS!

57



CC = 0


ReThink IMS!

58



Detected the problem


ReThink IMS!

59



ADDPART is re-started


ReThink IMS!

60

Thanks for listening!

� Thank you for listening!

� Questions?

Technology

REXX SPOC API for IBM IMS