|
|
|
The ADDRESS NETMASTR host environment is used to create, update, replace, annotate, set, close, and clear alerts on the CA NetMaster Alert Monitor screen. This host environment can be used in both OPS/REXX programs and synchronous AOF rules.
Note: The ADDRESS NETMASTR interface is available in CA NetMaster.
This command has the following format:
ADDRESS NETMASTR "function"
{CALLTYPE(ANNOTATE|CLEAR|CLOSE|CREATE|REPLACE|SET|UPDATE)}
[ANUSERID(uid)]
[APPLID(ApplicationID)]
[CLASSID(ClassID)]
[DESC('Description')]
[EXPLAIN('string1','string2',…,'string20')]
[EXPLVAR(GrexxVarPrefix)]
[NMSUBSYS(NetMasterSSID)]
[RECMACTN('string1','string2',…,'string20')]
[RECMAVAR(GrexxVarPrefix)]
[RESCLASS(ResourceClass)]
[RESID(ResourceID)]
[RESOURCE(ResourceName)]
[RESTYPE(ResourceType)]
[SEVERITY(1|2|3|4)]
[SEVUPDT(YES|NO)]
[SYSACTN('string1','string2',…,'string20')]
[SYSACVAR(GrexxVarPrefix)]
[SYSTEMNM(SystemName)]
[TEXT('string1','string2',…,'string20')]
[TEXTUPDT(YES|NO)]
[TEXTVAR(GrexxVarPrefix)]
[TRACKID(TrackingID)]
The required function code is the only positional parameter. Currently, the only supported function code is ALERT.
(Optional) Defines the user ID to be associated with the annotation text that is specified on the TEXT or TEXTVAR keywords. This keyword only has meaning for CALLTYPE(ANNOTATE) and is ignored if specified with any other CALLTYPE value. The uid can be any 1- to 32-character text string representing a user ID. Enclose the string in quotes if it contains any blanks. This string may, but does not necessarily have to, represent a standard TSO USERID.
(Optional) Defines the application ID as it appears in the CA NetMaster Alert Monitor display. The APPLID must be a valid CA OPS/MVS subsystem name. It must be exactly four characters long, begin with the character string OPS, and end with an uppercase alphabetic character.
Example: Specifying an application ID
APPLID(OPSA)
When this keyword is omitted, the current CA OPS/MVS subsystem ID (typically OPSS) is used as the default value. The APPLID value is used for alert correlation in combination with the CLASSID, RESID, and in some cases the TRACKID values, when you perform operations on existing alerts.
Specifies the type of ALERT call. This keyword is required.
Adds notes to an existing alert that matches the APPLID, CLASSID, RESID, and TRACKID specified when the alert was created. ANNOTATE uses keywords ANUSERID and TEXT or TEXTVAR.
Clears one or more alerts that match the values specified in the APPLID, CLASSID, and RESID keywords to identify the alerts you want to clear.
Closes the most recent alert created with the APPLID, CLASSID, RESID, and TRACKID specified when the alert was created.
Creates a new alert.
Replaces one or more active alerts that match the values specified in the APPLID, CLASSID, and RESID keywords with a new alert. All old alerts that match the APPLID, CLASSID, and RESID keywords are closed and annotated with text indicating that they were replaced by a new alert. A new alert will be created if there is no match on APPLID, CLASSID, and RESID.
Sets certain attributes of an alert that was previously created by specifying its APPLID, CLASSID, RESID, and TRACKID. Only the following alert attributes may be changed with a SET command:
Updates a recurring alert that matches the APPLID, CLASSID, and RESID. A recurring alert includes fields that indicate how many times the alert has occurred, the last date/time it occurred, and the elapsed time between the first and most recent occurrences. These fields are also present, but null, in normal alerts. The procedure to update a recurring alert is exactly the same as that to create a recurring alert. This call creates a new alert, if none exist, or updates the alert, if it does exist. The alert severity can optionally be updated by specifying the SEVUPDT keyword. The alert description, text, explanation, system action and recommended action can optionally be updated by specifying the TEXTUPDT keyword.
(Optional) Defines the class of alert. This is used to differentiate between types of alerts. The class ID can be any 1- to 30-character text string. Enclose the string in quotes if it contains any blanks. The CLASSID value is used for alert correlation in combination with the APPLID, RESID, and in some cases the TRACKID values, when you perform operations on existing alerts. For example:
CLASSID('OPS/MVS')
(Optional) Defines the alert description. If this keyword is omitted, then a default description string of 'No description' is used. Specify a text string of up to 80 characters enclosed in single quotes. The text is displayed under the Alert Description heading in the CA NetMaster Alert Monitor display.
(Optional) Specifies up to 20 text strings, each containing up to 75 characters. Each line of text is displayed as a separate line under the Alert Explanation heading in the CA NetMaster Alert Monitor display. Below are sample system action strings:
EXPLAIN('This alert is being displayed because today is Blue Monday','Second explanation string','Third expl string')
You can insert the contents of a REXX variable into the system action string. For example, the sample below inserts the contents of variable EXPLANAT into the explanation text as an explanation string:
EXPLAIN('"||EXPLANAT||"')
Note: The EXPLVAR and EXPLAIN keywords are mutually exclusive.
(Optional) Defines the stem for a set of REXX variables with each variable containing one line of explanation text. You define these variables and assign lines of text to them in separate statements in the OPS/REXX program that invokes the ADDRESS NETMASTR environment. You are limited to a maximum of 20 lines of explanation text and each line can contain up to 75 characters. If you specify more than 20 lines or the lines are longer than 75 characters, then the data beyond the defined limits is ignored. For example, if you specify EXPLVAR(LINE_DATA.), then the names of the variables storing lines of your explanation text will be LINE_DATA.1, LINE_DATA.2, and so on.
The stem name you specify must meet standard REXX conventions for stem names. If you are not familiar with these conventions, then see the book The REXX Language: A Practical Approach to Programming by M. F. Cowlishaw.
Instead of a stem, the EXPLVAR keyword can also specify a valid REXX variable name prefix. For example, if you specify EXPLVAR(PREFIX_DATA), then the names of variables storing your system action text are PREFIX_DATA1, PREFIX_DATA2, and so on.
The number of lines of explanation text produced depends on the number of consecutive variables that meet the criteria. Therefore, in the following example:
explvar.1="'This alert is being displayed because today is Blue Monday." explvar.2="Second explanation string" explvar.3="Third expl string"
A command specifying ADDRESS NETMASTR EXPLVAR(“explvar.”) produces only three lines of explanation text.
Note: The EXPLVAR and EXPLAIN keywords are mutually exclusive.
(Optional) Defines the name of the CA NetMaster EPS subsystem to which the request is directed. The CA NetMaster EPS subsystem name can be any 4-character name of an active CA NetMaster subsystem. This keyword should be specified only if the typical mechanism of automatically finding an active CA NetMaster subsystem does not work or you want to select an alternate CA NetMaster subsystem.
(Optional) Specifies up to 20 text strings, each containing up to 75 characters. Each line of text is displayed as a separate line under the Recommended Action heading in the CA NetMaster Alert Monitor display. Below are some sample system action strings:
RECMACTN('Restart the system to correct the error',",
"'Second recommended action string','Third rec string')
You can insert the contents of a REXX variable into the system action string. For example, the sample below inserts the contents of variable RECACT into the recommended action text as a recommended action string:
RECMACTN('"||RECACT||"')
Note: The RECMAVAR and RECMACTN keywords are mutually exclusive.
(Optional) Defines the stem for a set of REXX variables with each variable containing one line of recommended action text. You define these variables and assign lines of text to them in separate statements in the OPS/REXX program that invokes the ADDRESS NETMASTR environment. You are limited to a maximum of 20 lines of recommended action text and each line can contain up to 75 characters. If you specify more than 20 lines or the lines are longer than 75 characters, then the data beyond the defined limits is ignored. For example, if you specify RECMAVAR(LINE_DATA.), the names of the variables storing lines of your alert text will be LINE_DATA.1, LINE_DATA.2, and so on.
The stem name you specify must meet standard REXX conventions for stem names. If you are not familiar with these conventions, then see the book The REXX Language: A Practical Approach to Programming by M. F. Cowlishaw.
Instead of a stem, the RECMAVAR keyword can also specify a valid REXX variable name prefix. For example, if you specify RECMAVAR(PREFIX_DATA), then the names of variables storing your recommended action text are PREFIX_DATA1, PREFIX_DATA2, and so on.
The number of lines of recommended action text produced depends on the number of consecutive variables that meet the criteria. Therefore, in the following example:
recmavar.1="Restart the system to correct the error" recmavar.2="Second recommended action string" recmavar.3="Third rec string"
A command specifying ADDRESS NETMASTR RECMAVAR(“recmavar.”) produces only three lines of recommended action text.
Note: The RECMAVAR and RECMACTN keywords are mutually exclusive.
(Optional) Defines the logical resource class associated with the alert resource. The resource class can be any 1- to 50-character text string. Enclose the string in quotes if it contains any blanks. The resource class can contain any string that is meaningful to the operator viewing the Alert Monitor. For example:
RESCLASS('System State Manager Resource Class')
(Optional) Defines an identifier that uniquely identifies the resource to the application. The resource identifier can be any 1- to 128-character text string. Enclose the string in quotes if it contains any blanks. The RESID value is used for alert correlation in combination with the APPLID, CLASSID, and in some cases the TRACKID values, when you perform operations on existing alerts. For example:
RESID(SystemStateManager)
(Optional) Defines the logical resource name associated with the alert. The resource name can be any 1- to 50-character text string. Enclose the string in quotes if it contains any blanks. The resource name can be a System State Manager (SSM) resource name or any other name that is meaningful to the operator viewing the Alert Monitor. For example:
RESOURCE(SSMRES1)
(Optional) Defines the logical resource type associated with the alert resource. The resource type can be any 1- to 50-character text string. Enclose the string in quotes if it contains any blanks. The resource type can contain any string that is meaningful to the operator viewing the Alert Monitor. For example:
RESTYPE(STC)
(Optional) Specifies the severity of the alert. When this keyword is not specified, the alert severity defaults to a value of 4 (low). The severity value must be a single numeric digit from the following list of severities:
1-Critical
2-High
3-Medium
4-Low
For example:
SEVERITY(2)
(Optional) Indicates whether the SEVERITY keyword value is used to update the severity of the alert when specified with CALLTYPE(UPDATE). This keyword is ignored with all other CALLTYPE values.
(Optional) Specifies up to 20 text strings, each containing up to 75 characters. Each line of text is displayed as a separate line under the System Action heading in the CA NetMaster Alert Monitor display. Below are sample system action strings:
SYSACTN('The system will shut down if no corrective action is taken','Second system action string','Third sys string')
You can insert the contents of a REXX variable into the system action string. For example, the sample below inserts the contents of variable SYSACT into the system action text as a system action string:
SYSACTN('"||SYSACT||"')
Note: The SYSACVAR and SYSACTN keywords are mutually exclusive.
(Optional) Defines the stem for a set of REXX variables with each variable containing one line of system action text. You define these variables and assign lines of text to them in separate statements in the OPS/REXX program that invokes the ADDRESS NETMASTR environment. You are limited to a maximum of 20 lines of system action text and each line can contain up to 75 characters. If you specify more than 20 lines or the lines are longer than 75 characters, then the data beyond the defined limits is ignored. For example, if you specify SYSACVAR(LINE_DATA.), then the names of the variables storing lines of your system action text will be LINE_DATA.1, LINE_DATA.2, and so on.
The stem name you specify must meet standard REXX conventions for stem names. If you are not familiar with these conventions, then see the book The REXX Language: A Practical Approach to Programming by M. F. Cowlishaw.
Instead of a stem, the SYSACVAR keyword can also specify a valid REXX variable name prefix. For example, if you specify SYSACVAR(PREFIX_DATA), then the names of variables storing your system action text are PREFIX_DATA1, PREFIX_DATA2, and so on.
The number of lines of system action text produced depends on the number of consecutive variables that meet the criteria. Therefore, in the following example:
sysacvar.1="The system will shut down if no corrective action is taken" sysacvar.2="Second system action string" sysacvar.3="Third sys string"
A command specifying ADDRESS NETMASTR SYSACVAR(“sysacvar.”) produces only three lines of system action text.
Note: The SYSACVAR and SYSACTN keywords are mutually exclusive.
(Optional) Defines the system name associated with the alert. The resource type can be any 1- to 8-character text string. For example:
SYSTEMNM(SOMESYS)
(Optional) Specifies up to 20 text strings, each containing up to 75 characters. Each line of text is displayed as a separate line under the Alert Text heading in the CA NetMaster Alert Monitor display. Below are sample text strings:
TEXT('text string1','second text string','third text string')
You can insert the contents of a REXX variable into the message text. For example, the sample below inserts the contents of variable FIELDA into the message text as a text string:
TEXT('"||FIELDA||"')
Note: The TEXTVAR and TEXT keywords are mutually exclusive.
(Optional) Indicates whether the DESC, EXPLAIN, EXPLVAR, RECMACTN, RECMAVAR, SYSACTN, SYSAVAR, TEXT, and TEXTVAR keyword values are used to update the alert when specified with CALLTYPE(UPDATE). This keyword is ignored with all other CALLTYPE values.
(Optional) Defines the stem for a set of REXX variables with each variable containing one line of alert text. You define these variables and assign lines of message text to them in separate statements in the OPS/REXX program that invokes the ADDRESS NETMASTR environment. You are limited to a maximum of 20 lines of message text and each line can contain up to 75 characters. If you specify more than 20 lines or the lines are longer than 75 characters, then the data beyond the defined limits is ignored. For example, if you specify TEXTVAR(LINE_DATA.), then the names of the variables storing lines of your alert text will be LINE_DATA.1, LINE_DATA.2, and so on.
The stem name you specify must meet standard REXX conventions for stem names. If you are not familiar with these conventions, then see the book The REXX Language: A Practical Approach to Programming by M. F. Cowlishaw.
Instead of a stem, the TEXTVAR keyword can also specify a valid REXX variable name prefix. For example, if you specify TEXTVAR(PREFIX_DATA), the names of variables storing your text are PREFIX_DATA1, PREFIX_DATA2, and so on.
The number of lines of alert text produced depends on the number of consecutive variables that meet the criteria. Therefore, in the following example:
LineData.1="Line1" LineData.2="Line2" LineData.3="Line3"
A command specifying ADDRESS NETMASTR TEXTVAR(”LineData.”) produces only three lines of text data.
Note: The TEXTVAR and TEXT keywords are mutually exclusive.
(Optional) Defines a unique 1- to 32-character TrackingID or correlation token that must be specified on the CREATE request, if you want to be able to perform certain operations (ANNOTATE, CLOSE, and SET) on the same alert in the future. To do so, you should save the TrackingID that you specify on the CREATE request for later use. You may choose to define and use a set of unique TrackingIDs for use by your OPS/REXX applications or you may choose to dynamically generate unique tokens on each request. A good mechanism for doing so would be to use OPSINFO("SYSNAME")||C2X(OPSINFO("CLOCK")) as the TRACKID value.
Example:
TRACKID(AnyIDThatYouLike12345)
Note: CA NetMaster internally appends the APPLID to the TRACKID so that you cannot create a token that conflicts with another application.
Examples: ADDRESS NETMASTR
This example uses the ADDRESS NETMASTR host environment to create an alert on the CA NetMaster Alert Monitor screen:
/*Create an alert */
txtvar.1 = "The named resource is in an alert logical state"
txtvar.2 = "Reason: The system needs to be restarted"
recmavar.1 = "Restart the system to correct the error"
recmavar.2 = "Second recommended action string"
recmavar.3 = "Third rec string"
sysacvar.1 = "The system will shut down if no"
sysacvar.2 = "corrective action is taken"
address NETMASTR "Alert callTYPE(CR) TRACKID(MyTrackingID)" ,
"DESC('This is a test alert from CA OPS/MVS')" ,
"RESOURCE(SSMRES1) APPLID(OPSA) Severity(3)" ,
"RESCLASS('System State Manager Resource Class') RESTYPE(STC)" ,
"TEXTVAR(txtvar.)" ,
"RECMAVAR(recmavar.)" ,
"SYSACVAR(sysacvar.)" ,
"SYSTEMNM(SYSA)"
if RC <> 0 then
do
say "address NETMASTR failed, RC="RC
do QUEUED()
parse pull line
say line
end
end
This example uses the ADDRESS NETMASTR host environment to update the severity of the alert created in the previous example:
/* Update the alert */
address NETMASTR "Alert callTYPE(UPD)" ,
"RESOURCE(SSMRES1) APPLID(OPSA) Severity(2) SEVUPDT(YES)" ,
"RESCLASS('System State Manager Resource Class')"
if RC <> 0 then
do
say "address NETMASTR failed, RC="RC
do QUEUED()
parse pull line
say line
end
end
This example uses the ADDRESS NETMASTR host environment to annotate the alert created above:
/* Annotate the alert */
address NETMASTR "Alert callTYPE(AN)" ,
"APPLID(OPSA)" ,
"TRACKID(MyTrackingID)" ,
"ANUSERID(USERID1) ",
"TEXT('Annotating this alert','More annotation text')"
if RC <> 0 then
do
say "address NETMASTR failed, RC="RC
do QUEUED()
parse pull line
say line
end
end
exit
This example uses the ADDRESS NETMASTR host environment to close the alert created above:
/* Close the alert */
address NETMASTR "Alert callTYPE(CLO)" ,
"APPLID(OPSA)" ,
"TRACKID(MyTrackingID)"
if RC <> 0 then
do
say "address NETMASTR failed, RC="RC
do QUEUED()
parse pull line
say line
end
end
Note: In the above examples, only the APPLID and TRACKID keywords are used to correlate alerts.
| Copyright © 2012 CA. All rights reserved. | Tell Technical Publications how we can improve this information |