streamline resource management with the ims spoc function - ims ug july 2013 phoenix

© 2009 IBM Corporation

Streamline Resource Management with the IMS SPOC Function

Phoenix IMS Users Group

July 18, 2013

Diane Goff, IMS Advanced Technical Skills

[email protected]

2

Streamline Resource Management with the IMS SPOC Function 2

Agenda

� IMS SPOC Overview

• Function and use

• Batch SPOC Utility

• REXX SPOC API

• TSO SPOC

• OM Audit Trail

� IMS TSO SPOC Demo

• Configuration/settings

• Type-2 commands

3


IMS SPOC Overview

4


� An architecture to improve the systems management capabilities for IMS systems

• OM provides SPOC for command entry + routes commands/consolidates responses + provides API for automation + has user input/output exits

• RM coordinates IMSplex-wide processes + maintains global resource information in structure

• SCI provides communication ability to IMSplex members, within or cross z/OS images + member registration services

• ODBM allows distributed/local Java applications access to IMS data on mainframe

� Benefits • Provides a single system image (IMSplex)

• Ease of use through a single point of control

• Shared resources across all IMS systems

• Reduces complexity of managing multiple IMS systems

� Many IMS 10/11/12 features use CSL

CSL Components

5


Single

Point of

Control (SPOC)

Single Point

of Control

(SPOC)

Register with SCI

Command entry and response

CSL ArchitectureAddress Spaces

IMS

Control

Region

S

C

I

Structured

Call

Interface

SCI

IMS

Control

Region

S

C

I IMS

Control

Region

S

C

I

Operations

Manager

(OM)

SCI

Resource

Manager

(RM)

SCI

SCI

Communications

Open

Database

Manager

(ODBM)

SCI

SCI

Communications

6


Operations Manager (OM) …

� Provides ‘single point of control’ for command entry into an IMSplex

• Focal point for operations management and automation

� Provides the following services

• Route commands to IMSplex members registered for the command

• Consolidate command responses from individual IMSplex members into a single response to present to the command originator

• Support for new IMSplex commands (type-2 commands) and for existing IMS commands (type-1 commands)

• An API for IMS commands for automation

• Two types of OM clients use this API• Command processing (CP) clients

• Automated operations (AO) clients

7


Operations Manager (OM)

� Command security for authorization using RACF or equivalent plus user exit

� User exit capability for editing command input and responses

� Configuration• One or more OM address spaces required per IMSplex

8


OM Clients

� Two types of OM clients

• Command processing (CP) clients

• Clients which process commands entered by other address spaces

• IMS is a command processing client

• Automated operations (AO) clients

• Clients through which commands are entered to OM and then to the command processing client

• Command may originate from an operator, be received from a network client, or be received generated by an automation process

� OM services are invoked by

• CSLOMxxx macros

• REXX functions

9


Command Processing (CP) Client

� OM client that processes commands

• IMS and RM are CP clients of OM

� CP client

• Registers with SCI• Must be on same z/OS image

• Registers with OM• Identifies commands that it can

process

• Any OM in IMSplex

• Processes commands received

from OM

• Sends command responses back

to OM

• Deregisters from OM

• Deregisters from SCI

Command

Processing

Client

(IMS)

Structured Call Interface

Operations

Manager

10


Automated Operations (AO) Client

� Command originates from

• Operator (TSO SPOC)

• Automation (Netview EXEC)

• Network client with IMS Connect

� AO client

• Registers with SCI

• Accepts or creates command

• Uses CSLOMxxx macro or REXX interface to

• Send command to OM

• Receive reply in XML format

• Processes reply• Processes display

• Forward to network client

• Deregisters from SCI

Command

Processing

Client

(IMS)

Structured Call Interface

Operations

Manager

AO Client

�TSO SPOC

�User-provided automation

�IMS Connect

z/OS

Address Space IMS

Control Center

SCI

SCI Register

Register

11


� A SPOC is a program that interfaces between a user and the OM

� From this single point, user can enter commands to any or all IMSs

• It can run on the mainframe

• Batch SPOC is provided in IMS

• REXX SPOC APIs are provided in IMS

• TSO SPOC is provided in IMS

• It can run on the workstation

• IMS Control Center

IMS Single Point of Control (SPOC)

12


� Functions provided

• Single-system view of an IMSplex using a single console

• Consolidated display of command responses from multiple IMS systems

• Message sending to IMS terminals connected to any IMS in

the IMSplex

� There can be multiple SPOCs in an IMSplex

� SPOC will accept both type-1 and type-2 IMS commands

� Type-2 command equivalents for type-1

• http://pic.dhe.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims12.doc.cr/imscmdsintro/ims_type12cmds.htm

IMS Single Point of Control (SPOC)

13


Commands Supported with SPOC

� Why type-2 commands and SPOC?

• Type-2 commands are more powerful

• Output provides more information (QUERY vs. /DISPLAY)

• Able to use filters to display only targeted information like resource attribute values

• More functionality breadth than type-1

• New IMS functions will only use type-2 commands

• IMS strategic/future direction is to leverage CSL/type-2 commands going through OM

• Several IMS 10, 11, and 12 functions use only type-2 (no type-1)

• Some commands provide coordination among multiple IMS systems (example: global online change versus local)

• Managing entire IMSplex from a single console =

simplified/easier

14


Batch SPOC

� Provides a capability to submit IMS commands from a batch job step

• Uses the Operations Manager (OM) interface

� IMSplex environment defined in execution parameters

• IMSplex name, command routing, wait time

� Commands defined in SYSIN file

• All commands supported by OM API (type-2 and most type-1)

� Output to SYSPRINT

• Responses formatted to look like SPOC screen format

� Benefits

• Batch jobs may include steps with "online" commands• For example, steps to /DBR, reorganize, and /START

databases

15


Batch SPOC Utility – Input Example

� JCL invokes CSLUSPOC program

�Execution parameters specified with PARM=

�SYSIN DD statement includes commands to be issued when utility is run

�Specify DD SYSOUT=* to view utility output with SDSF after utility is run

16


Batch SPOC Utility – Output Example with Wait Time Specified

Command response

included in output

17


Batch SPOC – Conditional Processing

� Common question: Can this utility be used such that subsequent commands are only processed if the prior command completed successfully (or had a certain return/reason code)?

� Answer: Yes, code the COND parameter on the JCL EXEC specifying the conditions under which the step should be bypassed (JES2).

• Each job step will result in either of these return codes:• 0 – the utility completed • 4 – warning messages were issued, check the output file• 8 – a problem was encountered, check the output file;

command failed

• Most job steps will result in either 0 or 8 (test to confirm)

18


Batch SPOC – Conditional Processing Example

//JOBAG JOB ,

// MSGCLASS=H,NOTIFY=&SYSUID,USER=&SYSUID

//SPOC1 EXEC PGM=CSLUSPOC,

// PARM=('IMSPLEX=DEMOC,ROUTE=(IMSC),WAIT=30,F=BYRSC')

//STEPLIB DD DISP=SHR,DSN=IMS.IMSC.SDFSRESL

//SYSPRINT DD SYSOUT=*

//SYSIN DD *

QUERY TRAN NAME(A*) SHOW(PSB)

//SPOC2 EXEC PGM=CSLUSPOC,

// PARM=('IMSPLEX=DEMOC,ROUTE=(IMSC),WAIT=30,F=BYCOL')



//SYSIN DD *

UPDATE TRAN NAME(AUTOTRAN) SET(PGM(DEPOTRAN))

//SPOC3 EXEC PGM=CSLUSPOC,COND=(8,GE,SPOC2),

// PARM=('IMSPLEX=DEMOC,ROUTE=(IMSC),WAIT=30,F=BYRSC')



//SYSIN DD *

UPDATE TRAN NAME(AUTOTRAN) SET(CLASS(1))

/*EOF

This series of job steps first issues a

general query, then

tries to update a transaction to use a

different program. If

this update

command fails, we

do not want to

change the class for

this transaction

afterward.

19


Batch SPOC – Conditional Processing Example Output

00.35.31 JOB00621 $HASP373 JOBAG STARTED - INIT 3 - CLASS A - SYS MVSE

00.35.31 JOB00621 IEF403I JOBAG - STARTED - TIME=00.35.31

00.35.31 JOB00621 - --TIMINGS (MINS.)--

00.35.31 JOB00621 -JOBNAME STEPNAME PROCSTEP RC EXCP CPU SRB CLOCK

00.35.31 JOB00621 -JOBAG SPOC1 00 40 .00 .00 .00

00.35.32 JOB00621 -JOBAG SPOC2 08 40 .00 .00 .00

00.35.32 JOB00621 -JOBAG SPOC3 FLUSH 0 .00 .00 .00

00.35.32 JOB00621 IEF404I JOBAG - ENDED - TIME=00.35.32

.

.

.

IEF142I JOBAG SPOC2 - STEP WAS EXECUTED - COND CODE 0008

IGD104I IMS.IMSC.SDFSRESL RETAINED, DDNAME=STEPLIB

IEF285I DDS1743.JOBAG.JOB00623.D0000105.? SYSOUT

IEF285I DDS1743.JOBAG.JOB00623.D0000102.? SYSIN

IEF373I STEP/SPOC2 /START 2012190.0045

IEF032I STEP/SPOC2 /STOP 2012190.0045

CPU: 0 HR 00 MIN 00.00 SEC SRB: 0 HR 00 MIN 00.00 SEC

VIRT: 32K SYS: 320K EXT: 208K SYS: 10556K

IEF202I JOBAG SPOC3 - STEP WAS NOT RUN BECAUSE OF CONDITION CODES

IEF272I JOBAG SPOC3 - STEP WAS NOT EXECUTED.

.

.

. Job steps that are bypassed are shown in the top part of the output with the

FLUSH keyword. We also see here that the SPOC2 job step failed with a cond

code of 8, causing the SPOC3 job step to be bypassed.

20



Log for: QUERY TRAN NAME(A*) SHOW(PSB)

IMSplex . . . . . : DEMOC

Routing . . . . . : IMSC

Start Time. . . . : 2012.190 00:45:22.91

Stop Time . . . . : 2012.190 00:45:22.91

Return code . . . : 00000000

Reason code . . . : 00000000

Reason text . . . :

Command master. . : IMSC

Response for: QUERY TRAN NAME(A*) SHOW(PSB)

Trancode MbrName CC LPSBname

-------- -------- ---- --------

ADDINV IMSC 0 DFSSAM04

ADDPART IMSC 0 DFSSAM04

ANGTRAN IMSC 0 ANGPGM

AUTOTRAN IMSC 0 AUTOPGM

AUTRAN11 IMSC 0 AUTPSB11

AUTRAN12 IMSC 0 AUTPSB11

Here, we have paged

down within the job

output and now see the response for the query command that

was issued in the

SPOC1 batch job

step.

21



Log for: UPDATE TRAN NAME(AUTOTRAN) SET(PGM(DEPOTRAN))

IMSplex . . . . . : DEMOC

Routing . . . . . : IMSC

Start Time. . . . : 2012.190 00:45:22.94

Stop Time . . . . : 2012.190 00:45:22.95

Return code . . . : 0200000C

Reason code . . . : 00003008

Reason text . . . : None of the clients were successful.

Command master. . : IMSC

Return Reason

MbrName Code Code Reason text

-------- ------ ------ -----------

IMSC 0000000C 00003004 No requests were successful

Response for: UPDATE TRAN NAME(AUTOTRAN) SET(PGM(DEPOTRAN))

Trancode MbrName CC CCText

-------- -------- ---- -------------

AUTOTRAN IMSC 87 TRAN QUEUEING

Here, we discover the reason that the SPOC2 batch job step

failed with a cond code of 8. The attempt to change the program for the AUTOTRAN transaction

failed since it has messages queued to it (seen in the lower portion of the screenshot). The SPOC3 job is skipped, so we do not see any command response for it, since it was never issued.

22


Batch SPOC – Conditional Processing

� Batch job steps can be skipped within the Batch SPOC Utility based on specified conditions

� But…what about the detail in the command response?

� What if you wanted to actually examine the command response (more granular completion codes versus general rc/rsn codes) and build logic into the automation to take action based on the data included in the response?

� Using the Batch SPOC utility, you are limited to bypassing certain job steps if other job steps have failed.

� Answer: code a REXX program using our REXX SPOC API…

23


REXX SPOC API

� Allows REXX programs to submit IMS commands to an IMSplex which can examine response, then decide what next step will be

� REXX program that uses the REXX SPOC API is more powerful than AOI and TCO (traditional automation methods)

• Can also issue z/OS operator commands or TSO commands

• Command response examination abilities

• Easier to parse (XML statements) compared to responses returned

to AOI

• Improved self-healing/self-operating system

� Example:

• REXX program issues the following command to query the system:

QUERY TRAN NAME(prod001) SHOW(QCNT)

• If the command response from the REXX SPOC API shows that work

is delayed (the queue count is greater than you want), the REXX

program can issue additional operator commands to resolve the problem

24


REXX SPOC API – Example /* REXX */

ADDRESS LINK 'CSLULXSB'

ADDRESS IMSSPOC

"IMS DEMOC"

"ROUTE IMSC"

"WAIT 5:00"

"CART QRYPG"

"QRY PGM NAME(AUTPSB11) SHOW(DB)"

SAY "DETERMINING AUTPSB11’S DATABASE"

RESULTS = CSLULGTS("RESP.","QRYPG","3:15")

DO IDX = 1 TO RESP.0

PARSE VAR RESP.IDX . “PGM(AUTPSB11" . ,

"MBR(" IMSNAME ")" . ,

“DB(" DBNAME ")" .

/* ONLY START SCHD FOR PGM IF IT REF’S AUTODB DB */

IF POS(‘AUTO’, DBNAME) > 0 THEN

DO

/* START SCHEDLING FOR PGM */

SAY “AUTPSB11 OK TO START SCHD"

SAY “START SCHEDULING FOR AUTPSB11"

"CART STSCH"

"ROUTE" IMSNAME

“UPD PGM NAME(AUTPSB11) START(SCHD)"

RESULTS = CSLULGTS("RESP.",“STSCH","3:15")

This REXX program verifies that a

particular program

references a

particular database and if so, it starts

the program.

25




ADDRESS IMSSPOC

"IMS DEMOC"

"ROUTE IMSC"

"WAIT 5:00"

"CART QRYPG"









IF POS(‘AUTODB’, DBNAME) > 0 THEN

DO




"CART STSCH"

"ROUTE" IMSNAME



Let’s examine each

piece…

26


REXX SPOC API – Example

"IMS DEMOC"

"ROUTE IMSC"

"WAIT 5:00"

"CART QRYPG"


27




ADDRESS IMSSPOC

"IMS DEMOC"

"ROUTE IMSC"

"WAIT 5:00"

"CART QRYPG"










DO




"CART STSCH"

"ROUTE" IMSNAME




piece…

28






PARSE VAR RESP.IDX . "PGM(AUTPSB11" . ,


"DB(" DBNAME ")" .

29




ADDRESS IMSSPOC

"IMS DEMOC"

"ROUTE IMSC"

"WAIT 5:00"

"CART QRYPG"










DO




"CART STSCH"

"ROUTE" IMSNAME




piece…

30




IF POS('AUTODB', DBNAME) > 0 THEN

DO


SAY "AUTPSB11 OK TO START SCHD"

SAY "START SCHEDULING FOR AUTPSB11"

"CART STSCH"

"ROUTE" IMSNAME

"UPD PGM NAME(AUTPSB11) START(SCHD)"

RESULTS = CSLULGTS("RESP.", " STSCH","3:15")

31




ADDRESS IMSSPOC

"IMS DEMOC"

"ROUTE IMSC"

"WAIT 5:00"

"CART QRYPG"









IF POS(‘AUTO’, DBNAME) > 0 THEN

DO




"CART STSCH"

"ROUTE" IMSNAME



Program would then

continue on to

check that the

program was started for scheduling

successfully…

32


REXX SPOC API

� See “REXX SPOC API and the CSL” section in the IMS V12 System Programming APIs manual

http://pic.dhe.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims12.doc.spr/ims_rexx_spocapi_csl.htm

� Many automation packages and tools products provide a REXX SPOC function

33


� Runs under z/OS as a TSO/ISPF application (DFSSPOC)

� May or may not be on the same z/OS as OM

• Must be on a z/OS with an SCI

� Provides a ‘green screen’ terminal interface from which IMS commands (type-2 or type-1) may be entered by an operator to one or more members of an IMSplex (including DB/DC, DBCTL, DCCTL)

� Formats command responses for display

• OM response encapsulated in XML

� OM provides security checking

• TSO user ID is used to determine RACF authorization

TSO SPOC

34


� Route field only holds space for 2 IMS names

� Define a named group of IMS systems using SPOC Group Definitions panel and route commands to group instead

Defining groups of IMSs in the TSO SPOC

35


Using command shortcuts in the TSO SPOC

� Using the SPOC command shortcuts panel, you can set up shortened versions of commands or nicknames for commands

36


� When a command is issued, it is saved in the TSO SPOC

� Use the command status panel to work with previously

entered commands:

• Display commands/responses

• Delete commands

• Edit commands

• Reissue commands

Displaying command status in the TSO SPOC

37


� After command entry, position the cursor on the entered command, press Enter and the command will be moved to the command line, where you can edit the command or press Enter to issue the command again

� Use the ISPF retrieve key to display commands that were previously entered (includes TSO SPOC commands plus others entered during TSO session)

� Use the ISPF RETP command to list previously entered commands, select a number and press Enter

Reissuing Commands in the TSO SPOC

38


� Use the TSO SPOC command status panel

� Use the TSO SPOC shortcuts panel

� Use the TSO SPOC expand command panel which gives an ISPF edit panel to edit a long command

Issuing Commands in the TSO SPOC

39


� Use the IMS Application menu

� Enter TSO DFSSPOC in any ISPF command line

� Enter DFSSPOC in the ISPF Option 6 command line followed by optional parameters for DFSSPOC

� Call the TSO SPOC from other applications through a command interface

� Further details are in the IMS Operations and Automation

Guide (“Controlling IMS with the TSO SPOC application”):http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/topic/com.ibm.ims12.doc

.oag/ims_controlling_tsospoc.htm#ims_controlling_tsospoc

Starting the TSO SPOC

40


TSO SPOC Operations Manager Audit Trail

� Keeps track of IMSplex activity, including:

• IMS command input from OM clients (TSO SPOC, IMS Control Center)

• Reponses to commands

• Unsolicited messages

� Consists of OM log records written to z/OS System Logger log

stream

� Exit routines provided for various levels of formatting audit log

• OM input and output exits, DFSERA10 exits for printing

� TSO SPOC and REXX have support for reading the audit trail

� Specify AUDITLOG= keyword of the IMSPLEX parameter in the

CSLOIxxx OM initialization PROCLIB member

41


User IDs shown with commands entered


42


User IDs shown with commands entered, filtered by User ID


43


Setting up to use OM Audit Trail

� CSL OM initialization PROCLIB member – CSLOIxxx

• Specifies z/OS logstream name

ARMRST=Y|N <<< ARM restart enabled?OMNAME=OM1 <<< OM Name (OMid = OM1OM)

Name must be unique within IMSplex; shows up on messages from this component.

IMSPLEX(NAME=PLX0, <<< IMSplex nameAUDITLOG=logstreamname) <<< z/OS logstream name

Contains commands, command responses, unsolicited output

CMDSEC=N|E|R|A <<< OM Command Security LevelSAF security rules need to be defined

CMDLANG=ENU <<< US EnglishCMDTEXTDSN=IMS.SDFSDATA <<< Command syntax translation table

44


SPOC Demo

� IMSplex group definitions – routing to 3+ IMS systems

� Command shortcuts – abbreviated command versions

� Command status – display/reissue commands

� Resource management

• Update database attributes

• Stop/start transactions (applies to programs too)

• Using MTO versus TSO SPOC

• Activate individual resources with ACBLIB Member Online

Change

• Dynamically manage (create/delete) MODBLKS Resources

45


IMSplex Group Definitions

46


47


48


49


Command Shortcuts

50


51


52


53


54


Display/Reissue Commands

55


56


57


58


59


60


61


62


63


Querying Databases/Transactions

64


65


66


67


68


69


70


71


72


Queuing/Dequeuing Messages to/from Transactions

73


74


75


76


77


78


79


80


81


82


83


84


85


86


87


88


89


90


Updating Databases

91


92


93


94


95


96


97


98


99


100


101


Starting/Stopping Transactions with Type-1 Commands Using MTO

102


103


104


105


106


107


Starting/Stopping Transactions with Type-2 Commands Using TSO SPOC

108


109


110


111


112


113


Activating Individual Resources with ACBLIB Member Online Change

114


115


116


117


118


119


120


121


Dynamically Managing MODBLKS Resources

122


123


124


125


Reference SectionEquivalent Type-1 and Type-2 Commands

126


Equivalent Type-1 and Type-2 Commands

127


Equivalent type-1 and type-2 commands (1)(IMS 12 Command Reference, Vol.1, table 14, p. 47)

128


Equivalent type-1 and type-2 commands (2)

129



130



131



132



133



134



streamline resource management with the ims spoc function - ims ug july 2013 phoenix

Technology