In December 2012, we introduced the IMS Single Point of Control, or SPOC
, to the Destination z community. You may recall visions of Star Trek as we discussed the various types of SPOC and the benefits of using it to simplify IMSplex management.
We discussed the value of type-2 commands and how they’re more powerful than type-1 commands in terms of breadth, usefulness and value. After reading the article, surely, you couldn’t wait to start trying out the different types of IMS SPOCs in your shop. But you weren’t sure where to start in terms of setting up its required environmental components. We’re here to help.
We may not have as much of the same planetary, TV-based theme this time around, but we’ll try to connect the dots so we can boldly go where no system programmer or database administrator has gone before. We’d previously introduced the time-sharing option (TSO) SPOC application, the Batch SPOC Utility and the REXX SPOC API. Now let’s delve into the details of what a SPOC environment looks like—components, setup and a brief peek at usage—in this sequel!
We’ll begin with an examination of establishing the environment in which SPOC can be used. The major required components are:
Structured Call Interface (SCI)
is the component of the Common Service Layer that provides communication ability among the various members of an IMSplex. It routes messages among these members, and manages IMSplex registration and deregistration for its various members like a boss. SCI does a lot more, but to keep it simple, we'll just focus on its functions that apply to a SPOC environment.
Operations Manager (OM)
is the component of the Common Service Layer that routes commands to one or more IMS systems for processing, and then wrangles up all of the responses and presents consolidated command output into a single response or display for the user. An OM API is also available if a user wants to write command automation. Programs that utilize the OM API are called automated operator programs (AOPs), and they send commands to an IMSplex via the SPOC. A user can write an AOP in either REXX using the REXX SPOC API or in High Level Assembly Language that directly invokes the OM macros.
, in the world of SPOC, is known as a command-processing client. It receives commands from the SPOC (an automated-operations client) and processes them, returning the result of the command back to the SPOC using SCI and OM.
As a single point of control from which an IMSplex is managed, a SPOC enables a user to submit commands to an IMSplex and receive the consolidated command response, which can then be exploited based on business need. In the case of the TSO SPOC application, the command response will be displayed on a single system image. For Batch SPOC, this command response can be viewed in the SYSIN data set. A REXX program that has leveraged the REXX SPOC API can actually examine the command response, and then drive the next action to take based on the details. The SPOC is known as an automated-operations client because it can be used with both type-1 and type-2 command automation.
Once the environment has been established, you’ll launch the TSO SPOC application, set the IMSplex name and you’ll be off! Now, let’s take a closer look at how to set up the environmental components.
Enhanced Command Environment Setup
The SCI and OM address spaces can be automatically started during IMS initialization by using the enhanced command environment. All you need to do is:
• Activate the enhanced command environment with a single parameter
• Define the SCI and OM startup procedures
• Define SCI’s and OM’s initialization PROCLIB members
An IMS system’s DFSDFxxx PROCLIB member contains settings that determine processing options for its various capabilities such as the Common Service Layer. You’ll need to specify the same “xxx” suffix in DFSDFxxx as the value defined by the DFSDF= parameter in the startup procedure for IMS. To activate the enhanced command environment, specify RMENV=N in the Common Service Layer section of the member. This signifies that the resource manager component of the Common Service Layer is not being used, which means the IMS system is eligible to utilize this enhanced environment where SCI and OM are automatically started. Figure 1 includes an example of setting the RMENV parameter in this way. Another noteworthy parameter in the DFSDFxxx member is IMSPLEX, which specifies the name of the IMSplex in which the IMS will exist. Keep in mind that this IMSplex name must be defined with the same name in the SCI and OM settings, which we’ll review next.
Figure 1: Sample DFSDFxxx PROCLIB Member
Now that you’ve activated the enhanced command environment, you must instruct IMS how to automatically start SCI and OM. To do this, specify the name of a procedure that should be invoked to start each of these address spaces. The OMPROC and SCIPROC parameters are shown in Figure 1, define the OM and SCI procedure names, respectively, and will be called to start each of these address spaces during IMS initialization. As you can see in Figure 1, the procedures are CSLOM for OM and CSLSCI for SCI. Let’s take a look at an example for each of these procedures.
Our sample SCI startup procedure named CSLSCI is shown in Figure 2. When this Job Control Language (JCL) executes, the SCI address space will be initialized and the settings specified in SCI’s initialization PROCLIB member will be applied. The SCI initialization PROCLIB member is named CSLSIxxx, and the “xxx” suffix is defined in the startup procedure JCL as shown in Figure 2.
Figure 2: Sample SCI Startup Procedure
Note that the SCIINIT parameter specifies a suffix called 00D. This means when SCI is initialized, the settings specified in the PROCLIB member named CSLDI00D will be applied to it. To override any of the settings you originally specified in this member, use the PARM1 parameter as shown in Figure 2. What kinds of settings you might ask? Let’s review them.
Figure 3 shows a screenshot of the CSLSI00D member that contains the SCI settings.
Figure 3: Sample SCI Initialization PROCLIB Member
In this member, you can specify the:
• ARMRST parameter, which indicates whether the SCI address space should be restarted in the event of a failure
• SCINAME, the name of the SCI
• IMSPLEX(NAME) sub-parameter, which defines the name of the IMSplex that SCI will reside in. It’s important that the IMSplex name is the same as the name specified in the DFSDFxxx PROCLIB member and the CSLOIxxx OM initialization member that we’ll discuss shortly.
Just like SCI, OM has a procedure that IMS calls while it’s initializing that starts the OM address space. In Figure 4, our example OM startup procedure called CSLOM is shown.
Figure 4: Sample OM Startup Procedure
The concepts pertaining to SCI startup apply to the OM startup procedure as well. The OMINIT parameter specifies the three-character suffix that will be substituted for the “xxx” in the CSLOIxxx PROCLIB member. The example shown in Figure 4 indicates that the settings contained in the CSLOI00D member will be applied to the OM address space when it initializes. If you’d like to override any of the settings originally specified in this member, use the PARM1 parameter as shown in the screenshot above. Figure 5 shows an example screenshot of the CSLOI00D member.
Figure 5: Sample OM Startup Procedure
Here, you can specify the following settings:
• ARMRST indicates whether the OM address space should be restarted in the event of a failure.
• CMDLANG defines the language that should be used for the commands that OM will work with.
• CMDSEC specifies whether OM command security will be used.
• OMNAME indicates the name of the OM instance.
• IMSPLEX(NAME) is the name of the IMSplex that OM will reside in.
• IMSPLEX(AUDITLOG) is the name of the z/OS system logger log stream that will be used with the OM audit trail, which logs all IMSplex activity including command I/O.
That’s it. Now all you need to do is start IMS, invoke the SPOC and you’ll be ready to blast off!
TSO SPOC Invocation and Setup
The TSO SPOC application can be launched from the IMS application menu. This menu can be invoked from the DFSAPPL command, using either a TSO command or an EXEC command. Each of these are shown here:
• TSO %DFSAPPL HLQ(myhlq)
• EXEC 'IMS.SDFSEXEC(DFSAPPL)' 'HLQ(myhlq)'
Figure 6 shows a screenshot of the IMS Application Menu.
Figure 6: IMS Application Menu
Once you’ve launched the IMS Application Menu, select option 1 to invoke the TSO SPOC application, which will appear as in Figure 7.
Figure 7: TSO SPOC Application Command Entry Panel
You must first specify the name of your IMSplex before you can use the TSO SPOC application to issue type-2 commands to it. This name will be the same name that you specified in the DFSDFxxx, CSLSIxxx and CSLOIxxx. To do this from the TSO SPOC home screen, go to the options menu by positioning your cursor under the word “Options” and press Enter. Then enter a “1” for Preferences, as shown in Figure 8.
Figure 8: Navigating to the Preferences Panel Within the TSO
Recall that the name of the IMSplex used in the previous environment setup steps is DEMOD. Enter this in the Default IMSplex field, then tab down to the Waiting preference field and enter a “1” here to ensure you see responses for commands that you enter, as shown in Figure 9.
Figure 9: Designating the IMSplex Name the TSO SPOC Application
Will Route Commands To
After pressing Enter, you’ll be taken back to the TSO SPOC home screen, shown once again in Figure 10, this time with the IMSplex name displayed in the upper left corner.
Figure 10: TSO SPOC Application Command Entry Panel With
IMSplex Name Set
At this point, you’re ready to go! You can now begin issuing commands using the TSO SPOC. For example, say you wanted to display the status for all of your databases to determine whether they’re currently opened or closed. Simply use a type-2 QUERY command as shown in Figure 11, and you’ll see all of the information in one place.
Figure 11: A Type-2 QUERY Command Displaying Database Status
Or maybe you’d like to display the status for a transaction known to several IMS systems. You could either individually issue a type-1 /DISPLAY command on each IMS system’s console, for example IMS1 and IMS2, as shown in Figures 12 and 13. Alternatively, you could use a type-2 QUERY command to display all of this information on a single panel using the TSO SPOC, as shown in Figure 14. Clearly, using the SPOC is more efficient and displays simplified, clear output … and ultimately makes your IMSplex resources a lot easier to manage.
Figure 12: Example of a Type-1 /DISPLAY Command
Displaying Transaction Status on the IMS1's Console
Figure 13: Example of a Type-1 /DISPLAY Command
Displaying Transaction Status on the IMS2's Console
Figure 14: A Type-2 QUERY Command Displaying Transaction
Status for Multiple IMS Systems
Now that you’re up and running with a TSO SPOC environment, try issuing some commands to see how much easier it is to manage all of your IMS systems in one place. The other types of SPOCs are ready to go now, too! If your shop’s processes are automated, you can try out the Batch SPOC utility to submit several commands to your IMSplex using batch job steps. You can also autonomize your processes with the REXX SPOC API, in which your program can examine command responses, take corrective action if need be, or otherwise behave in an intelligent way in determining next steps.
Angelique Greenhaw is a senior solutions architect with IBM System z Software’s IMS Tools group. www.linkedin.com/in/angiegreenhaw