INGOMX

Purpose

INGOMX is a programming interface that provides interaction capabilities with OMEGAMON®. It allows a program or command list to invoke OMEGAMON exception analysis in order to trap one or more exceptions of interest or to issue one or more OMEGAMON commands. The response generated by OMEGAMON on behalf of a request is written to the console but not exposed to automation.

Additionally, it provides an interface to communicate with an IBM Tivoli Monitoring SOAP server to issue SOAP messages and to process the response from the SOAP server. While INGOMX handles the communication and the envelope of the SOAP message, it is the responsibility of the caller to provide an appropriate body either dynamically or in a data set of choice. The body consists of specific elements in XML notation that denote the particular request, the target application for this request, user ID and password, and other request-specific information.

See Example 10 for the usage of placeholders for user ID and password in the body.

Parameters

NETVASIS

Prefix the INGOMX command with NETVASIS if you want to pass the user ID, password, or path in lower or mixed case.

SOAPREQ

The function code to send a SOAP message to the SOAP server designated by server. The SOAP message to be sent can be built dynamically and passed to INGOMX through the default safe or it can be in a user-defined data set.

The STACK, PORT, PATH, USERID, PASSWORD, SAFAPPL, and PROTOCOL parameters are used only when the SOAP server is not defined in the policy. If you use any of them for a SOAP server defined in the policy, the command is rejected with a return code 4.

SERVER=server

server refers to the SOAP server defined in the SOAP SERVER policy of the NETWORK (NTW) entry in the automation policy.

Alternatively, server can be the IP-address (if it starts with a digit or contains ‘:’) or the symbolic host name. If a SOAP SERVER policy is found for server, it will be used preferably.

STACK=ipstack

ipstack refers to the IP stack to be used to connect to the SOAP server. The jobname of the TCP/IP indicates the corresponding IP stack.

Specify this field only if your system is configured for multiple IP stacks. If nothing is specified, the first active TCP/IP is used.

PORT=port

port refers to the port number that the SOAP server is listening to. This is optional and only required if server does not denote a definition in the SOAP SERVER policy.

PATH=path

path refers to the absolute path that, together with the host address and the port number, forms the address of the SOAP service. An absolute path must start with a slash ('/'). This is optional and only required if server does not denote a definition in the SOAP SERVER policy.

The PATH parameter is case-sensitive. To maintain its case-sensitivity, you must enclose path in single or double quotation marks.

TYPE={ITM|NONE}

The type refers to the kind of SOAP request that is being issued. For ITM type SOAP requests, the response document is transformed into messages that can be processed further using NetView PIPEs. For other SOAP requests, the response is returned in XML format instead.

CCSID=ccsid

ccsid refers to the character set identifier used to encode the XML source and target documents. The SOAP request is translated from ccsid to UTF-8 before it is sent to the SOAP server and it is translated back to ccsid upon receipt.

DATA={*|dataset}

If * is specified, the SOAP message is located in the default SAFE. This assumes that the caller has either created the SOAP message dynamically or obtained it from some other source and passed it to INGOMX via a PIPE input stream. See also Example 3.

dataset refers to the name of either a sequential data set or a partitioned data set, including the member name where INGOMX finds the SOAP message.

See paragraph Using INGOMX Directives, Example 8: Using INGOMX Directives for defining SOAP Data, and Example 9: Using Ingomx_SOAP_Envelope Directive for SOAP12 for the usage of the alternate definition of SOAP Body, SOAP Envelope, and HTTP header records using directives.

USERID=userid

The userid is required for authentication to the SOAP server, if security is enabled at the SOAP server. If the server is defined in the SOAP SERVER policy, omit this parameter as the userid in the policy is used.

Specify userid only when the server is not defined in the SOAP SERVER policy. In this case, the PASSWORD parameter is required, too.

PASSWORD=PTKT|SAFPW|password

The password required for authentication. This parameter is valid only when the SOAP server is not defined in the SOAP SERVER policy. You can specify the following options:

Password

Specify the password in clear text.

PTKT

Use keyword PTKT to let SA z/OS generate a PassTicket.

SAFPW

Use keyword SAFPW to let SA z/OS use the password that is deposited in the password data set under the domain name SOAP. In this case, the real password must be specified under NetView using the following SA z/OS command:

INGPW userid SOAP,INIT=password

SAFAPPL=safappl

safappl is the alphanumeric application name used for verifying the user credentials upon logon to the SOAP server. Only used when the SOAP server is running on z/OS. Its maximum length is 8 characters. The default value is CANDLE.

PROTOCOL

The protocol for the socket connection type. TLS/SSL security is selected with HTTPS, and the default is HTTP. It is flagged as an error if you define it in addition to a server object.

EXECUTE

The function code to issue a command to the OMEGAMON session that is specified by session_name. The command and its parameters are specified by the CMD, MOD, and PARM keywords. The output of this command corresponds to the output produced by the OMEGAMON monitor on a 3270 screen.

CMD={command|*}

This is the pure 1 to 4 character OMEGAMON command that is issued on the OMEGAMON session without parameters.

If an asterisk ('*') is passed instead of a command, INGOMX expects a list of up to 22 OMEGAMON commands in the default SAFE. This allows a programmer to issue multiple commands at once, in particular, minor commands that require the presence of an appropriate major command.

When commands are passed within the default SAFE, the same syntax rules apply as denoted in the syntax diagram above, that is, each command is specified with the CMD keyword followed by an optional modifier and optional parameter string.

The command that is specified or the first command in the default SAFE will be logged in the NetView log with message ING083I.

MOD=modifier

modifier is an optional additional character that will be inserted by SA z/OS in front of a command to modify the behavior of that command. For example, a '<' modifies the command ALLJ such that instead of one line of address spaces, all address spaces are returned at once. Refer to the OMEGAMON command manual for a reference of modifiers allowed for each particular command. The default modifier is a blank character.

PARM=parm

parm is an optional parameter string of up to 74 characters. The parameter string will be appended by SA z/OS to the command, if specified. The default parameter is a NULL-string.

OMWAIT=nn

Several OMEGAMON commands begin a process that accumulates data over a small period of time. For example, the OMEGAMON for MVS command MCPU accumulates data about CPU status, and then displays this data. To mimic this functionality, OMWAIT can be used, where nn is the optional time during which data is accumulated before the command is issued again, and can be between 0 and 59 seconds. The default wait time is 0.

TRAP

This is the function code to filter exceptions that are reported by the OMEGAMON session specified by session. The exceptions that should be filtered are specified by the XTYPE keyword. The output of this command corresponds to filtered output produced by the OMEGAMON monitor exception analysis on a 3270 screen, where only the selected exceptions are included.

XTYPE={exception_list|exception}

A list of one or more OMEGAMON exceptions. If the list consists of more than one exception, it must be put in quotation marks or parentheses, and either commas or blanks used to separate the exceptions.

NAME=session

This is the name of the OMEGAMON session as defined in the automation policy.

WAIT={YES|nnn}

This parameter determines the interval after which a request is terminated with a timeout condition.

If WAIT=YES is specified (default), either the default wait time is used as a timeout value (WAITTIME) or, for OMEGAMON sessions, the timeout that is specified in the OMEGAMON SESSION policy. The parameter default variable INGOMX_WAIT can be used to override the default value in WAITTIME.

If WAIT=nnn is specified, nnn denotes a positive number in units of seconds.

ATTACHSESSION

This is the function code to request that an OMEGAMON session with a named set of attributes is established and a user (according to these attributes) is logged on.

DETACHSESSION

This is the function code to request that the user that is currently logged on to the OMEGAMON session is logged off and that the OMEGAMON session specified by session_name is destroyed.

TERMSESSION

This is the function code to end the OMEGAMON session. The function is similar to the DETACHSESSION request but, in addition, the session is locked and ATTACHSESSION is not allowed. This function code is used only by SA z/OS initialization and only SA z/OS initialization can unlock the session.

Return Codes

0

Normal completion. The filtered output of the exception analysis or the response of the OMEGAMON command or the SOAP request, respectively, is written to the console.

-3

The operator invoking INGOMX is not authorized to issue this request for any of the following reasons:

• The caller is not allowed to access the session indicated by session_name
• The caller is not allowed to issue the OMEGAMON command (or commands) specified by CMD
• The caller is not allowed to send the SOAP message to the SOAP server indicated by server_name

Update the NetView command authorization table or the RACF® definitions, or both, for the named session, the named SOAP server, and command (or commands).

NetView issues BNH236E and BNH237E with detailed error information.

1

INGOMX failed to communicate with the session whose session_name was passed as input. The session_name is unknown or does not refer to a valid OMEGAMON session. In case of an invalid OMEGAMON session, message ING084I is written to the netlog.

For reason ATTACHSESSION session_name, ensure that the session that is referenced in the reason is defined in the policy and also linked to this system. See OMEGAMON Policy Item in IBM Z® System Automation Defining Automation Policy for details of how to define a session.

If the target was a SOAP server, the server_name is unknown or does not refer to a host that can be reached through the IP network. Refer to message ING164I for further diagnostic details in the netlog.

2

A session request was not executed as the session is already in the desired state.

3

An internal error occurred. Message ING084I is written to the netlog and provides more detailed error information.

4

Syntax error. Invalid parameters were passed to INGOMX. Refer to the netlog for additional error information.

5

Timeout occurred. The requested operation was interrupted due to a timeout as specified for this session in the customization dialog. The timeout value might be too low or more session operators might be required.

6

The command environment for INGOMX was not appropriately initialized at the time this command was issued. Possible reasons are that the agent is currently being initialized or a cold start of the automation control file is being done.

7

Creation of the NetView Terminal Access Facility (TAF) session failed or VTAM® is not available. Message ING084I is written to the netlog and provides more detailed error information.

A common reason for this return code is that an invalid or non-existent logmode is used for the TAF session or that the logmode refers to a Class-of-Service (COS) that is unknown to this VTAM. Examine the netlog and syslog for further VTAM messages (IST*).

8

The user ID that is specified in the session definition for session_name cannot log on to OMEGAMON. Session creation failed.

Message ING001I is written to the netlog. Examine the preceding messages in the netlog and the syslog for further diagnosis. Typical reasons are:

• The user ID (=which indicates the issuing user) under which an attempt is made to create a session is not allowed to issue the INGPW command to retrieve the password from the password data set. See the security considerations in INGPW of IBM Z System Automation Operator's Commands and ensure that the issuing user is authorized to use the INGPW command to retrieve and set passwords in the password data set. You might need to define class SYSAUTO, if you use another security product rather than IBM Resource Access Control Facility (RACF).
• The user ID (=which indicates the logged on user) defined for this session does not exist or has no permission to log on to OMEGAMON, or the password defined in the password data set is invalid or not set at all but required.

9

The requested function is not allowed within the current session state. Refer to the INGSESS command (in IBM Z System Automation Operator's Commands) for the current state and available options.

10

A SOAP request could be delivered, but the SOAP server failed to interpret the request correctly. Messages ING162I and ING163I are returned to the caller for further information about this failure.

11

A SOAP request could not be delivered to the SOAP server because the service has been moved to a new location. Message ING167I is returned to the caller indicating the new location that must be used instead.

12

The specified data set containing the SOAP request could not be allocated or read. Message ING164I is written to the netlog indicating the code returned from PIPE QSAM.

13

The specified CCSID does not exist. Specify a valid CCSID.

14

The caller is not authorized to generate a PassTicket on behalf of the user required to log on to OMEGAMON or to authenticate at the SOAP server. Message ING168I or ING169I is written to the Netlog. Ensure to meet the security requirements in the Security Considerations section.

Security Consideration

When OMEGAMON security is turned on, any user can authenticate himself using the user ID and a password to log on to an OMEGAMON classic monitor or to perform a SOAP request. With APAR OA64126, System Automation is enhanced to also support authentication using a PassTicket.

If you choose PassTicket over password as the authentication, ensure that the following security requirements are met:

NetView SECOPTS.OPERSEC must be set to either option SAFCHECK or SAFDEF.

A profile for class PTKTDATA is defined for the specified safappl or for the SAF application in the OMEGAMON SESSION or the SOAP SERVER policy, respectively.

Usage

Invoke INGOMX in a PIPE to capture and further analyze the output produced by OMEGAMON. Alternatively, INGOMX can also be called directly from the operator console, but note that INGOMX does not issue any confirmation messages and that output is only written to the console when INGOMX returned with code 0.

Refer to Controlling Access to IBM Tivoli Monitoring Products in IBM Z System Automation Planning and Installation for Command Authorization Table identifiers supported by INGOMX.