OPSCAWTO Function

Use the OPSCAWTO function to send a message to an external system in the form of an SNMP trap. Sending an alert enables the external system to take an action or display the message as an alert.
coema
Purpose
Use the OPSCAWTO function to send a message to an external system in the form of an SNMP trap. Sending an alert enables the external system to take an action or display the message as an alert.
Supported Coding Environments
This function may be coded in these environments:
AOF Rules
OPS/REXX
TSO/E REXX
TSO/E CLIST
USS Script
Yes
Yes
No
No
No
System Requirements
For a list of the CCS for z/OS components that are required to use OPSCAWTO, see CCS for z/OS Component Requirements.
The OPSCAWTO function uses the CAIENF component of CCS for z/OS to send the SNMP trap asynchronously. The installation and activation of the ENFSNMPM component of CCS for z/OS is described in the CCS for z/OS Installation Guide. Add the SNMP data control module (DCM) to the Event Notification Facility (CAIENF) database. Add the starting of the ENFSNMPM task to the CAIENF commands or to the spawn service file of the main CAIENF task.
Coding Syntax
This function is coded using this syntax:
var = OPSCAWTO(
destination
,
message
[,
options
[,
OIDmodifier
]] )
Positional Arguments
This function accepts these positional arguments:
#
Argument
Value
 
1
 
 
destination
 
(Required) The destination node of the TCP/IP network to which the SNMP trap is sent, specified as a TCP/IP address or host name. To obtain the correct IP address or host name of the desired destination, consult your network communication personnel.Example of a TCP/IP address: '123.456.78.90'Example of a TCP/IP host name: 'some.host.name'
 
2
 
 
message
 
(Required) The text of the message to be sent as an SNMP trap. The text cannot contain the double-quotation mark (“) character. Example: 'Hello world, this is OPS/MVS'
If the specified 
message
 text exceeds the maximum allowed length, then it is automatically truncated to the maximum allowed length and the OPSCAWTO function returns a value of 1.
The maximum allowed length of the 
message
 text depends on the calling environment and the length of the values that are specified for positional arguments 
destination
 and 
OIDmodifier
:
If function OPSCAWTO is called in an AOF rule, then:
L'
destination
 + L'
OIDmodifier
 + L'
message
 <= 299 
*
 
If function OPSCAWTO is not called in an AOF rule, then:
L'
destination
 + L'
OIDmodifier
 + L'
message
 <= 447 
*
 
 
*
 If the value specified for positional argument 
options
 contains the option character E, then decrement this value by 19.
 
3
 
 
options
 
(Optional) A one or two character string that specifies the optional processing to be done. You may specify either or both of the following option characters in any order:
Char
Description
 
D
 
Requests debug processing. Causes the CCS for z/OS ENFSNMPM task to produce detailed trace messages about sending the SNMP trap to the target destination. To be used for problem resolution. Verify that the trap message was received, processed, and sent by ENFSNMPM. To view the trace messages, display the JESMSGLG DD or SYSPRINT DD of the ENFSNMPM started task using CA SYSVIEW or SDSF.
 
E
 
Requests enterprise processing. Causes the OID used by the OPSCAWTO function (default of '1.3.6.1.4.1.791.2.4.2') to be inserted 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 identify the sender uniquely.
 
4
 
 
OIDmodifier
 
(Optional) A string of dot and digit characters that are appended to the end of the default SNMP OID (Object Identifier) used by the OPSCAWTO function. Must begin with a dot character.
SNMP uses the OID to identify the origin and type of information in a message. The default OID used by the OPSCAWTO function is '1.3.6.1.4.1.791.2.4.2'. This OID indicates that the SNMP trap that is issued by the OPSCAWTO function comes from 
CA OPS/MVS
. Other software products that receive and interpret SNMP traps require different or extra identifiers to use the information in a message. This option allows you to append characters to the end of the default OID used by the OPSCAWTO function. (The default '1.3.6.1.4.1.791.2.4.2' portion of the OID used by the OPSCAWTO function remains fixed.)
Example: Specifying a value of '.3.2.1' for positional argument 
OIDmodifier
 causes the OPSCAWTO function to use the OID '1.3.6.1.4.1.791.2.4.2.3.2.1'.
We recommend that you create your own OIDs starting with '1.3.6.1.4.1.791.2.4.2.999’ to avoid the possibility of future conflicts with 
CA OPS/MVS
 OIDs.
Keyword Arguments
This function accepts no keyword arguments.
Returned Value
This function returns one of these possible numeric values indicating the success or failure of the request:
Value
Meaning
0
The message was successfully passed to CCS for z/OS ENF.
1
The message text was truncated and successfully passed to CCS for z/OS ENF.
4
CCS for z/OS ENF is inactive.
8
CCS for z/OS and ENF logic error.
12
CCS for z/OS ENF abend occurred.
16
CCS for z/OS ENF unrecoverable error.
20
Invalid CCS for z/OS ENF parameter list.
40
Function syntax error.
The OPSCAWTO function uses the CAIENF component of CCS for z/OS to send the SNMP trap asynchronously. The OPSCAWTO function receives no notification from the external system that the SNMP trap arrived at the specified node successfully.
Returned Variables
This function sets no variables.
Returned EDQ Data
This function adds no data to the EDQ.
Coding Examples
This example sends the message 'OPS/MVS is up' to the TCP/IP node with the host name of 'console':
var = OPSCAWTO('console','OPS/MVS is up')
Usage Notes
None