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:
| ||||||
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