REXX SPOC API for IBM IMS

1,919 views
1,774 views

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,919
On SlideShare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
79
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

REXX SPOC API for IBM IMS

  1. 1. Stan Sun – IMS Developer 11/2009 stansun@us.ibm.com IMS REXX SPOC API ….everything you always wanted to know © 2009 IBM Corporation
  2. 2. ReThink IMS! 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. 2 © 2009 IBM Corporation
  3. 3. ReThink IMS! Disclaimers Copyright © 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 the user’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 Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. 3 © 2009 IBM Corporation
  4. 4. ReThink IMS! 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 4 © 2009 IBM Corporation
  5. 5. ReThink IMS! 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 5 © 2009 IBM Corporation
  6. 6. ReThink IMS! IMSplex Operations z/OSa z/OSb Operations S IMS Control Manager C Region (OM) I SCI z/OSx Single Point of Control (SPOC) S C Automation - SPOC I IMS Control S S IMS Control Region C C region REXX I I SPOC API Source: If applicable, describe source origin 6 © 2009 IBM Corporation
  7. 7. ReThink IMS! 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 XML statements 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. Source: If applicable, describe source origin 7 © 2009 IBM Corporation
  8. 8. ReThink IMS! 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. Source: If applicable, describe source origin 8 © 2009 IBM Corporation
  9. 9. ReThink IMS! 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’ -------------------------------- >< Source: If applicable, describe source origin 9 © 2009 IBM Corporation
  10. 10. ReThink IMS! 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 --------------------------------------------------- >< Source: If applicable, describe source origin 10 © 2009 IBM Corporation
  11. 11. ReThink IMS! 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. Source: If applicable, describe source origin 11 © 2009 IBM Corporation
  12. 12. ReThink IMS! 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 “)” Source: If applicable, describe source origin 12 © 2009 IBM Corporation
  13. 13. ReThink IMS! 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. Source: If applicable, describe source origin 13 © 2009 IBM Corporation
  14. 14. ReThink IMS! Hello World program (simplified) Source: If applicable, describe source origin 14 © 2009 IBM Corporation
  15. 15. ReThink IMS! 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. Source: If applicable, describe source origin 15 © 2009 IBM Corporation
  16. 16. ReThink IMS! Hello World Demo (simplified) Source: If applicable, describe source origin 16 © 2009 IBM Corporation
  17. 17. ReThink IMS! 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 ---------------------------------------------------- >< Source: If applicable, describe source origin 17 © 2009 IBM Corporation
  18. 18. ReThink IMS! 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 --------------------------------------------------- >< Source: If applicable, describe source origin 18 © 2009 IBM Corporation
  19. 19. ReThink IMS! 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 --- --- * --------------------------- --- % -------------------------- Source: If applicable, describe source origin 19 © 2009 IBM Corporation
  20. 20. ReThink IMS! 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 --------------------------------------------------- >< Source: If applicable, describe source origin 20 © 2009 IBM Corporation
  21. 21. ReThink IMS! 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 ---------------------------------------------------------------------------- >< Source: If applicable, describe source origin 21 © 2009 IBM Corporation
  22. 22. ReThink IMS! Hello World program Source: If applicable, describe source origin 22 © 2009 IBM Corporation
  23. 23. ReThink IMS! Hello World Demo Source: If applicable, describe source origin 23 © 2009 IBM Corporation
  24. 24. ReThink IMS! Hello World Demo (continue) Source: If applicable, describe source origin 24 © 2009 IBM Corporation
  25. 25. ReThink IMS! 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” ) ------------- >< Source: If applicable, describe source origin 25 © 2009 IBM Corporation
  26. 26. ReThink IMS! 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. Source: If applicable, describe source origin 26 © 2009 IBM Corporation
  27. 27. ReThink IMS! Hello World program with CSLULGTS request match as long as WAIT subcommand any stem variable name Source: If applicable, describe source origin 27 © 2009 IBM Corporation
  28. 28. ReThink IMS! Retrieving command responses in XML and parsing to stem variable names directly CSLULGTP 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” ) ------------- >< Source: If applicable, describe source origin 28 © 2009 IBM Corporation
  29. 29. ReThink IMS! 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. Source: If applicable, describe source origin 29 © 2009 IBM Corporation
  30. 30. ReThink IMS! Demo code with CSLULGTP Source: If applicable, describe source origin 30 © 2009 IBM Corporation
  31. 31. ReThink IMS! Demo code with CSLULGTP (continue) Source: If applicable, describe source origin 31 © 2009 IBM Corporation
  32. 32. ReThink IMS! CSLULGTP demo Source: If applicable, describe source origin 32 © 2009 IBM Corporation
  33. 33. ReThink IMS! CSLULGTP suffix variable names table (abbreviated) XML tag Variable name <?xml version=“1.0”?> stem.xmlversion <!DOCTYPE imsout SYSTEM “imsout.dtd”> stem.dtd <imsout> N/A <ctl> N/A <omname> </omname> stem.ctl.omname <omvsn> </omvsn> stem.ctl.omvsn <xmlvsn> </xmlvsn> stem.ctl.xmlvsn <statime> </statime> stem.ctl.statime <stotime> </stotime> stem.ctl.stotime <rqsttkn1> </rqsttkn1> stem.ctl.rqsttkn1 <rc> </rc> stem.ctl.rc <rsn> </rsn> stem.ctl.rsn </ctl> N/A Source: If applicable, describe source origin 33 © 2009 IBM Corporation
  34. 34. ReThink IMS! CSLULGTP suffix variable names table (continue) XML tag Variable name … … <msgdata> N/A <mbr name=“membername”> stem.msgdata.name.0 (num of systems) stem.msgdata.name.y (1 member name) <msg> </msg> stem.msgdata.msg.y.0 (num of msgs / sys) stem.msgdata.msg.y.x (1 message line) </mbr> N/A </msgdata> N/A 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. Source: If applicable, describe source origin 34 © 2009 IBM Corporation
  35. 35. ReThink IMS! 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. Source: If applicable, describe source origin 35 © 2009 IBM Corporation
  36. 36. ReThink IMS! 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. Source: If applicable, describe source origin 36 © 2009 IBM Corporation
  37. 37. ReThink IMS! 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 Source: If applicable, describe source origin 37 © 2009 IBM Corporation
  38. 38. ReThink IMS! 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. Source: If applicable, describe source origin 38 © 2009 IBM Corporation
  39. 39. ReThink IMS! 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. Source: If applicable, describe source origin 39 © 2009 IBM Corporation
  40. 40. ReThink IMS! 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 ) ------------------------ >< Source: If applicable, describe source origin 40 © 2009 IBM Corporation
  41. 41. ReThink IMS! 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. Source: If applicable, describe source origin 41 © 2009 IBM Corporation
  42. 42. ReThink IMS! 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_name Name of the IMSplex. Do not use the ‘CSL’ prefix. Source: If applicable, describe source origin 42 © 2009 IBM Corporation
  43. 43. ReThink IMS! Demo code to retrieve unsolicited messages Source: If applicable, describe source origin 43 © 2009 IBM Corporation
  44. 44. ReThink IMS! Demo code to retrieve unsolicited messages (continue) Source: If applicable, describe source origin 44 © 2009 IBM Corporation
  45. 45. ReThink IMS! Retrieve unsolicited messages demo Source: If applicable, describe source origin 45 © 2009 IBM Corporation
  46. 46. ReThink IMS! 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. Source: If applicable, describe source origin 46 © 2009 IBM Corporation
  47. 47. ReThink IMS! Batch job sample Source: If applicable, describe source origin 47 © 2009 IBM Corporation
  48. 48. ReThink IMS! 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. Source: If applicable, describe source origin 48 © 2009 IBM Corporation
  49. 49. ReThink IMS! 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. Source: If applicable, describe source origin 49 © 2009 IBM Corporation
  50. 50. ReThink IMS! Autonomic computing sample code Source: If applicable, describe source origin 50 © 2009 IBM Corporation
  51. 51. ReThink IMS! Autonomic computing sample code (continue) Source: If applicable, describe source origin 51 © 2009 IBM Corporation
  52. 52. ReThink IMS! Autonomic computing demo Bring up a TSO SPOC session Source: If applicable, describe source origin 52 © 2009 IBM Corporation
  53. 53. ReThink IMS! Autonomic computing demo Enter a QRY TRAN command Source: If applicable, describe source origin 53 © 2009 IBM Corporation
  54. 54. ReThink IMS! Autonomic computing demo ADDPART is active Source: If applicable, describe source origin 54 © 2009 IBM Corporation
  55. 55. ReThink IMS! Autonomic computing demo Bring up another TSO session and run the REXX SPOC program Source: If applicable, describe source origin 55 © 2009 IBM Corporation
  56. 56. ReThink IMS! Autonomic computing demo Stop the transaction Source: If applicable, describe source origin 56 © 2009 IBM Corporation
  57. 57. ReThink IMS! Autonomic computing demo CC = 0 Source: If applicable, describe source origin 57 © 2009 IBM Corporation
  58. 58. ReThink IMS! Autonomic computing demo Detected the problem Source: If applicable, describe source origin 58 © 2009 IBM Corporation
  59. 59. ReThink IMS! Autonomic computing demo ADDPART is re-started Source: If applicable, describe source origin 59 © 2009 IBM Corporation
  60. 60. ReThink IMS! Thanks for listening! Thank you for listening! Questions? 60 © 2009 IBM Corporation

×