Example 4. Issuing OMEGAMON Minor Commands

/* REXX-Routine EXMINOR */                                                           
cmd.1 = "CMD=SYS"   /* Major command, issued ahead of its minors   */
cmd.2 = "CMD=FCSA"  /* Minor: CSA frames below 16M                 */
cmd.3 = "CMD=FCOM"  /* Minor: CSA, LPA, SQA, and nucleus below 16M */
cmd.0 = 3                                                            
'PIPE STEM cmd. COLLECT',                                            
'| NETV INGOMX EXECUTE,NAME=OMSY4MVS,CMD=*',                         
'| CONSOLE ONLY'                                                    
* IPXNG    EXMINOR                                                
| IPXNG     SYS    >> WLM Goal mode OPT=00 SYSRES=(150526,8812) <<
| IPXNG     fcsa       328     1312 K                             
| IPXNG     fcom       849     3396 K

There is no need to explicitly establish a session between an operator and a particular OMEGAMON monitor before using INGOMX; such sessions are established automatically on their first use.

Selective protection of individual OMEGAMON sessions and commands, or both, is possible based on the NetView Command Authorization Table. Details can be found in the appendix, Security and Authorization, in IBM Z® System Automation Planning and Installation.

To use a SOAP service, for example to obtain certain attributes from an OMEGAMON XE object, you first have to describe the request's parameters in the form of an XML document. The XML document is validated and rejected by the SOAP server if it is found to be incorrect or incomplete. The spelling of the names enclosed in '<' and '>' is significant because XML is a case-sensitive document description language. Also, because the structure of every XML document is hierarchical, each element must be enclosed by an opening name (for example, '<CT_Get>') and a corresponding closing name denoted by a forward slash preceding the name (for example, '</CT_Get>').

The following is an example that describes the request parameters to retrieve the Job_Name, the address space ID (ASID), and the CPU_Percent attributes from the OMEGAMON XE for z/OS object, Address_Space_CPU_Utilization, for all jobs with a CPU percentage greater than 1.0. In this example, the object that has been queried is collected on the TEMS called KEYAS:CMS.

<CT_Get>
  <target>KEYAS:CMS</target>
  <object>Address_Space_CPU_Utilization</object>
  <attribute>Job_Name</attribute>
  <attribute>ASID</attribute>
  <attribute>CPU_Percent</attribute>
  <afilter>CPU_Percent;GT;10</afilter>
</CT_Get>

You can pass this XML document either by pointing INGOMX to a sequential or partitioned data set, or in the default SAFE, assuming INGOMX is invoked in a NetView PIPE.

When INGOMX is invoked, the SOAP server that is connected to must be specified. In the following example, it is assumed that you have defined a SOAP server called KEYAYA in the SOAP SERVER policy item of the Network (NTW) entry type using the SA z/OS customization dialog. This definition includes the host name or IP address, the SOAP server's port and the path name of the SOAP service. The request parameters as shown above are located in the member GETCPU in the partitioned data set SYS1.SOAP.DATA:

soapds = 'SYS1.SOAP.DATA(GETCPU)'
soapsrv = 'KEYAYA'
Address NETVASIS 'PIPE (END % NAME GETCPU)',           
'| NETV (MOE) INGOMX SOAPREQ SERVER='soapsrv' DATA='soapds, 
'| L: LOC 1.8 'd||'DWO369I '||d,                       
'| EDIT SKIPTO 'd||'RETURN CODE'||d,                   
'       UPTO 'd||'.'||d,                               
'       WORD 3 1',                                     
'| VAR omx_rc',                                        
'%L:',                 
'| CON ONLY'

On the successful return of INGOMX, the output of the SOAP server is returned in the multiline ING160I message:

ING160I RESPONSE FROM SOAP SERVER: 9.xxx.xxx.xxx:1920///cms/soap
Job_Name:ASID:CPU_Percent                                     
IXGLOGR:20:2.1                                                
NET:59:2.1                                                    
RMFGAT:89:6.9                                                 
SDM1IRLM:108:1.7                                              
BBOS001S:113:22.1                                             
YANAMSJH:117:3.9

The first row of this message documents the IP address of the SOAP server that responded, that is, KEYAYA in the example (IP address anonymized).

The second row describes the names of the attributes returned by the SOAP server. The attribute names are separated from each other by the non-printable character X'FF' (represented by a :).

The third and all following rows contain the actual data that has been requested. The attribute values are presented in the same sequence as the corresponding attribute names in the second row. Also, like the attribute names, the attribute values are separated from each other by the non-printable character X'FF' (represented by a :).

The tabular structure of this message allows you to easily process it in a NetView PIPE.