OPS/REXX Built-in Functions › OPSCAWTO Function

OPSCAWTO Function

The OPSCAWTO function can send a message to the CA Event Manager in the form of an SNMP trap. Using Event Manager message rules, CA NSM can take an action. OPSCAWTO uses the CAIENF component of CCS for z/OS to asynchronously send the SNMP trap. CA NSM does not return a response.

For a list of the CCS for z/OS components required to run OPSCAWTO, see the appendix “CCS for z/OS Component Requirements” in the Installation Guide.

Note: You may use the OPSCAWTO function in any OPS/REXX program or AOF rules.

This function has the following format:

var = OPSCAWTO('ipaddress','message text',['DE'],OID modifier')

ipaddress

The TCP/IP address (ipaddress) or host name defines the destination node of the TCP/IP network to which the SNMP trap is sent. The OPSCAWTO function receives no notification that the SNMP trap arrived at the specified node successfully. Consult your network communication personnel to obtain the correct IP address or host name of the desired destination.

message text

The message text argument is the text of the message to be sent as an SNMP trap to the desired TCP/IP address. The argument may not contain the quotation mark (“) character as part of the sent message data.

Message buffer space must be allocated for fixed length protocol overhead elements, as well as variable length fields which contain the IP address and the OID structure. If the IP address is coded in the basic 15-byte dotted notation format, and the default OID is adequate, the available text length allows up to 432 characters, and might be reduced to 284 if OPSCAWTO is running as a rule. If either the IP address or OID string should change, the available text length may fluctuate. If this limit is exceeded, then the message text is automatically truncated by the amount necessary to stay within the limit. A return code of 1 is returned by the function to indicate that truncation has occurred.

options

(Optional) The options characters can be used to request special handling features of the function. You can specify the following options separately or together in any order as a string:

D (Debug)

The debug option causes the CA Common Services for z/OS ENFSNMPM task to produce detailed trace messages about sending the SNMP trap to the target destination. The trace messages should be your main source of information about problem resolution.

To view the trace messages:

• Display the JESMSGLG ddname or SYSPRINT ddname of the ENFSNMPM started task using CA SYSVIEW or SDSF.
• Verify that the trap message was received, processed, and sent by ENFSNMPM.

Note: If the target host is running the Event Manager component of CA NSM, the CATRAPD service must be running for the trap to appear as a message in the Event Manager GUI console.

E (Enterprise)

The enterprise option inserts the CA OPS/MVS OID (1.3.6.1.4.1.791.2.4.2) into the enterprise ID portion of SNMP trap. If not specified, the default enterprise ID specified for the ENFSNMPM task is used. Specify this option when the receiving SNMP manager uses the enterprise ID of the trap to uniquely identify the sender. An additional 19 characters of the maximum message space is used for this option.

OID modifier

The OID (Object Identifier) is used by SNMP to identify the origin and type of information in a message. The default OID used by OPSCAWTO is '1.3.6.1.4.1.791.2.4.2'. This OID indicates to OPSCAWTO that the SNMP trap comes from CA OPS/MVS. Other software products that need to receive and interpret SNMP traps may require different or additional identifiers to properly use the information in a message. To address this, the OID modifier argument lets you replace or add on to the '2.4.2' portion of the default OID used by OPSCAWTO. The '1.3.6.1.4.1.791.' portion of the default OID remains fixed. See the examples below.

To replace the '2.4.2' portion of the OID with a different identifier, you must replace the '2.4.2' portion with an identifier that does not begin with a period. For example, '1.3.6.1.4.1.791.2.4.2' can be changed to '1.3.6.1.4.1.791.1.2.3.4' by replacing '2.4.2' with '1.2.3.4'.

To add on to the '2.4.2' portion of the OID, the identifier added must be preceded by a period. For example, '1.3.6.1.4.1.791.2.4.2' can be changed to '1.3.6.1.4.1.791.2.4.2.3.2.1' by adding '.3.2.1'.

Note: When the OID modifier argument causes the length of the OID to increase, the space available for the IP address and message text is reduced to compensate.