This section contains the following topics:
Volume Pool Monitor Usage and Components
The Volume Pool Monitor (VPM) feature is customizable and provides notification capabilities that are integrated with CA 1 daily processing. These capabilities are implemented using z/OS standard components such as ISPF and the CTS started task.
The VPM feature is optional and does not change any TMC or Audit records. The existing Audit Type 5 record passes data from various CA 1 daily utilities (TMSCOPY, TMSCLEAN, and TMSVMUPD) to the VPM subtask of CTS. You can include this data in the emails and WTOs that VPM generates.
The VPM feature enables you to do the following actions:
VPM provides this new capabilities through the integration of multiple components:
Note: For more information about the VDB and CAI.SEND data sets, see the Programming Guide. For more information about the CTSMAIL program, see the Utilities and Reports Reference Guide.
A volume pool consists of one or more volume ranges. You can view the data in a volume pool by specific volume range or you can view all ranges for a volume pool summarized together. The VPM subtask processes the range definitions and determines how many volumes are found in each defined range and their status. Each volume can be in Active, Scratch, or Out of Service status. VPM monitors status changes of each volume. VPM examines the CA 1 Audit file for updates that change the status of a volume and it updates the volume range counters in real time. These counters are then written back to the VDB. You create the volume pools through the CTS ISPF application.
Use ISPF to view the volume pool status. You can also use the DISPLAY POOL command of VPM to show the higher-level pool information on the z/OS console. The following example shows a volume pool named STK_High_Capacity with three ranges defined:
|
Volume Pool Name |
Volume Range |
|---|---|
|
STK_High_Capacity |
210000 – 219999 |
|
STK_High_Capacity |
800000 – 899999 |
|
STK_High_Capacity |
STK000 – STK999 |
VPM uses the volume pool name alone to assign all three ranges to the same volume pool STK_High_Capacity. The volume pool names are case-sensitive. STK_High_Capacity is a different volume pool than STK_HIGH_CAPACITY. VPM counts and classifies all volumes in the three ranges separately. To see the range information separately, enter R on the Volume Pool List ISPF display for the volume pool that you want to view. To see the combined total counts for all ranges in the volume pool, enter S on the Volume Pool List ISPF display. You can also use the DISPLAY POOL command of the VPM subtask.
A volume pool alert is a condition that you define to be monitored by the VPM subtask. If the condition is met, you can cause an email to be sent or a WTO to be issued.
You create the volume pool alerts through the CTS ISPF application.
You can customize the VPM using variables. VPM supports four different types of variables:
Variables that the user can enter to customize emails and WTOs.
Variables to control the VPM subtask of CTS and how email is configured on your system.
Variables that CA 1 utilities update that you can use in your emails and WTOs.
System variables that describe the systems where CA 1 is installed.
The CTS VDB task and several CA 1 utilities create the variables. You can also create your own user variables. All variable types are saved in the VDB. The option, product, and system variables are created with defaults when the VDB is first initialized using the CTSVDBU utility. The variables are then updated with current information from the most recent run of CA 1 utilities. The VDB task also updates selected variables that are associated with alert processing being triggered.
Both emails and WTOs support variable substitution. You can specify all types of variables – user, option, product, and system variables. Every line in the body of an email or WTO is examined for variables. Variables must begin and end with the substitution character (default is &). A variable must begin and end on the same line. If you do not specify a substitution character in the email header or WTO using the x-SUB: field, the variable uses the value that is defined in OPT_EMAIL_DEFAULT_SUBCHAR. Emails also allow the specification of variables in the header fields.
When a variable is found in an email or WTO, the VDB is searched for an exact match on the variable name. If the exact match is found, the value that is associated with that variable replaces the variable name. If the variable is not found in the VDB, the variable name stays the same in the email or WTO.
Variable names are case-sensitive. If the case does not match exactly between the variable in the email or WTO and the variable in the database, they are considered to be different variables. For example, &Thisvar& is not the same as &THISVAR&.
To make you emails and WTOs more meaningful for your site, you can specify user variables and option variables. Option variables control the VPM subtask and configure email support for your environment.
To more completely customize your emails and WTOs, you can create user variables. For example, you can reference a user variable On_Call_Manager in an email. You can create or update the variable On_Call_Manager with the name of your on-call manager each month. The name appears in emails or WTOs in place of the variable name. User variables can have any name except for the following restricted prefixes: OPT-, CTS-, SYS-, and TMS-. Variables are case-sensitive and must match exactly the variable in ISPF.
Selected CA 1 utilities create product variables for use in email and WTO customization. These utilities include TMSCLEAN, TMSCOPY, and TMSVMUPD. These utilities update the product variables by writing them to Audit file Type 5 (Exception) records, which the VPM subtask reads. VPM makes them available to alert processing and also writes them to the VDB. VPM uses two type 5 audit records:
Specifies the volume pool monitor record that is created to update volume status counters.
Specifies the volume pool monitor record that is created to update product variables that various CA 1 utilities create.
Note: You can print the Type 5 records with the TMSAUDIT utility. For more information about TMSAUDIT, see the Utilities and Reports Guide.
You can use the product variables to send emails or WTOs to key personnel supporting your tape environment, informing them of CA 1 processing. For example, you can create an email to send to the tape librarian. The email informs them that the TMSCLEAN utility has run and nn tapes were updated to scratch status. You reference the TMSCLEAN_CURRENT_SCRATCH_TAPES product variable.
The following variables are updated every time the TMSCLEAN utility runs. These values can also be found in Report 85. If the program runs using the TEST parameter, these parameters are not updated.
Specifies the completion code from the last run of TMSCLEAN.
Specifies the total number of scratch tapes that TMSCLEAN found.
Specifies the total number of data sets that TMSCLEAN uncataloged.
Specifies the completion date of the last run of TMSCLEAN.
Specifies the completion time of the last run of TMSCLEAN.
Specifies the total number of tape volumes that TMSCLEAN scratched.
Specifies the total number of unexpired tape volumes that TMSCLEAN found.
The TMSCOPY utility updates the following variables every time the TMSCOPY utility runs. These values are the same values as are reported in Report 31. If the program is run using the TEST parameter, these parameters are not updated.
Specifies the total number of active or used DSNB records that TMSCOPY backed up.
Specifies the total number of audit records that TMSCOPY found in the TMC.
Specifies the total number of audit records that TMSCOPY backed up.
Specifies the total number of unused or available DSNB records that TMSCOPY backed up.
Specifies the completion code from the last run of TMSCOPY.
Specifies the date that TMSCOPY backed up the TMC.
Specifies the total number of DSNB records that TMSCOPY backed up.
Specifies the completion date of the last run of TMSCOPY.
Specifies the completion time of the last run of TMSCOPY.
Specifies the time that TMSCOPY backed up the TMC.
Specifies the total number of volume records that TMSCOPY backed up.
Specifies the tape volume serial number that the TMC backup is on.
The following variables are updated every time the TMSVMUPD utility runs. If the program runs using the TEST parameter, these parameters are not updated.
Specifies the completion code from the last run of TMSVMUPD.
Specifies the completion date of the last run of TMSVMUPD.
Specifies the completion time of the last run of TMSVMUPD.
Specifies the total number of tape volumes returning from an offsite location. This value is new and is not on any report.
Specifies the total number of tape volumes moved to an offsite location. This value is new and is not on any report.
Specifies the total number of tape volumes that changed vault locations. You can find this value in Report 26 in the field TMC RECORDS UPDATED too.
The VPM subtask updates the following product variables when an alert is triggered. They allow you to create emails and WTOs showing you the values in the alert that caused it to trigger. These product variables are updated in the VDB and always reflect the most recent alert that was triggered.
The value is taken from the Interval field on the VPD Alert Detail Panel. Valid intervals are ONCE, WHILE, or a number of hours (1-99).
The value is taken from the Alert ID field on the VPD Alert Detail Panel. This value is basically the name that the user chose for the alert.
The value is taken from the Oper field on the VPD Alert Detail Panel. Valid Intervals are LT, LE, EQ, GE, or GT.
The value is taken from the Pool ID field on the VPD Alert Detail Panel. If the alert is associated with a volume pool, the field contains the name of the volume pool that was triggered. If the alert is for a user variable, this field is blank.
The value is taken from the Send field on the VPD Alert Detail Panel. This field contains the name of the email or WTO member in CAI.SEND that is issued when the alert is triggered.
The value is taken from the Value field on the VPD Alert Detail Panel. This value is constant and it is the value that the CTS_Alert_Variable is compared to.
The value is taken from the Variable field on the VPD Alert Detail Panel. If the alert is for a volume pool, the field contains the name of the counter or percentage field that is being tested against. For volume pool alerts, the permitted values are:
If the alert is testing a numeric user variable, the user variable name displays here.
The VPM subtask calculates this value. The value reflects the actual value of the tested field that triggered the alert. For example, if an alert is created to monitor the number of scratch tapes in a volume pool (Scratch_Count LT 500), the CTS_Alert_Variable_Value is the number of scratch tapes in the volume pool (499 or fewer).
System variables are provided to describe basic information about the systems where CA 1 components are running. The values for the system variables are updated with current system information any time they are referenced (used in an email or WTO) by the VPM task, CTS ISPF application, or the CTSMAIL utility. A user cannot update these variables.
To make your emails and WTOs more meaningful, use the system variables. For example, you can identify the z/OS system where the email program CTSMAIL ran to create an email.
Specifies the current system date of when the variables were referenced in MM/DD/YYYY format.
Specifies the level of DFSMS that is installed on your system.
Specifies the current system date of when the variables were referenced in DD/MM/YYYY format.
Specifies the SMF ID of the system you are running on.
Specifies the name of the job that referenced the variables. If the variables are being referenced through the CTS System Variable List panels, this variable contains your TSO user ID.
Specifies the z/OS version, release, modification level, and FMID.
Specifies the name of the program that appears on the EXEC statement.
Specifies the job-step PROC name.
Specifies the actual program name that referenced the variables.
Specifies the step name in the job that referenced the variables.
Specifies the current system time of when the variables were referenced in HH:MM:SS format.
To notify users of specific conditions that are tested for in VPM alerts, create a write-to-operator message (WTO) to the system consoles. Use the Volume Pool Monitor feature. You define WTOs in the CAI.SEND data set.
Follow these steps:
The ROUTCDE parameter is a list of message routing codes that identify what types of consoles the WTO should be sent to. Enter at least one numeric code from 1 through 12 in parentheses. If you need more than one routing code, separate the values by commas only. The following IBM message routing codes are associated with tape consoles:
Specifies the operator information.
Specifies the tape pool.
Specifies the tape library.
Note: For a complete list of message routing codes, see the z/OS System Messages Vol 1 guide.
You can include variables that begin and end with the substitution character (default is &) in the WTO text. If the variables match the values in the VDB, the current values of the variables replace the variable names. If a variable is not found in the VDB, the variable name stays in the WTO text.
Text is reformatted to remove any extra blanks between words and variables. The reformatting results in a formatted WTO of one or more lines. The number of the lines depends upon the length of the data value that is associated with the variable.
Terminates this line and insert a blank line.
Turn off text formatting until the next &FM& is found.
Note: This keyword must begin in Column 1 of input. All other text on the same line is ignored.
Terminates this line.
The WTO is created.
Every WTO that the VPM or the CTSMAIL utility issues has the same message identifier – CA$F501I. The identifier is fixed to prevent the misuse of this utility. With the identifier in place, messages that appear to be issued by another product or system component are not created.
The ability to create a WTO can be used for other needs unrelated to tape management. If the VDB is allocated and available, the CTSMAIL utility can create WTOs for any purpose. You can use the system variables and any user variables in the text of these emails. You can include any product variable in a WTO only if the CTS VPM task updates the CA 1 product variables in the VDB.
For this example, member WTO001 is created in the CAI.SEND data set containing the following statements:
EDIT CAI.SEND(WTO001) - 01.00 Columns 00001 00072 Command ===> Scroll ===> CSR ****** ***************************** Top of Data ***************************** 000001 WTO ROUTCDE=(2,5) 000002 TEXT 000003 A scratch tape alert has been triggered for &NL& 000004 Volume Pool = &CTS_Alert_Pool_ID& &NL& 000005 Scratch tapes available = &CTS_Alert_Variable_Value& ****** **************************** Bottom of Data ****************************
Assuming that an alert was created which specified member WTO001 as the value for the Send field in the alert. When the alert condition is met, the following output is created from the WTO text.
17.10.56 JOB06069 CA$F501I CTSWTO Informational message 397 397 A scratch tape alert has been triggered for 397 Volume Pool = POOL_ABC 397 Scratch tapes available = 499
You can create an email in the CAI.SEND data set using the ISPF editor. You can send emails by VPM alert processing or by the CTSMAIL utility. You can test that the email looks and is distributed as you intended it to. Specify the email member as input to the CTSMAIL utility.
Follow these steps:
The header section includes information such as the sender, recipient, and title of the email. The email body is the actual text that you send. All header fields observe the MIME x- token convention and begin with x-. For example, the recipient of the email is identified with the following header statement:
x-TO: john.smith@xyzcorp.com
Create emails in HTML format or in plain text format. Text is the default format. To create an HTML format email, specify x-FMT: HTML in the header section. All header fields allow variable substitution except where specifically noted.
Note: For more information about the CTSMAIL utility, see the Utilities and Reports Reference guide.
Use the following rules in creating email members in the CAI.SEND data set. Any valid PDS member name can be used.
Follow these steps:
Every header field contains one value. You can specify selected header fields multiple times. Specify these header field records consecutively. If you do not specify the records, default header fields are used. The OPT_EMAIL_ variables provide default values for all required header fields.
x-TO: &MY_COMPANY_TAPE_LIBRARIAN&
The first record that does not begin with a x- header field initiates the start of the email body. Emails that are constructed correctly cause a WTO error in the range CA$F560E to CA$F565E.
The following email header fields are supported:
Defines the recipients of the email. You can replicate this field to specify more recipients. If you do not specify the value in the email, this header field uses the value that is set in the variable OPT_EMAIL_DEFAULT_TO.
Limits: 50 characters
Specifies the display name in the To: position for the sent email. If not specified, the x-TO: parameter appears by default.
Limits: 50 characters
Specifies the address that defines the sender of the email. Specify a valid email address. Otherwise, the email address uses the default value from the variable OPT_EMAIL_DEFAULT_FROM.
Limits: 50 characters
Specifies the display name that appears in the From: position for the sent email. If not specified, the x-FROM: parameter is shown by default.
Limits: 50 characters
Specifies the format of the email. Valid entries are HTML and TEXT. If not specified in the email, this header field uses the value that is set in the variable OPT_EMAIL_DEFAULT_FMT.
Limits: Four characters
Specifies the title for the Subject: line of the email. If not specified in the email, this header field uses the value that is set in the variable OPT_EMAIL_DEFAULT_TITLE.
Limits: 60 characters
Specifies the substitution character that is used to delimit variables. Variables that you want to specify in header fields or the body of the email must begin and end with this substitution character. If not specified in the email, the value defined in OPT_EMAIL_DEFAULT_SUBCHAR is used.
Limits: One character
Specifies the TCP/IP HOST NAME of the service that is used to send the email. In multisystem environments, the service typically vary. If you do not specify x-HELO: in the email, the system uses the value that is defined in EMAIL_xxxx_HOSTNAME (where xxx is the SMF ID).
Limits: 60 characters
The first record in the member that does not have a x- header field is considered the start of the body of the email. How the body of the email is constructed depends on the value that you specify for the x-FMT: header field and the use of variables and special formatting keywords. You can use two format types for the body of the email, HTML and TEXT. You control the format by the x-FMT: header field.
To create an email that permits the use of HTML in formatting the body of the email, specify x-FMT: HTML in the header section. The HTML tags can control the detailed formatting. Unless another font is explicitly specified in the body of the email, the default font is used.
An email is constructed using plain text formatting when you specify x-FMT: TEXT or leave the default. In plain text, the formatting text wraps from line to line. Unless you specify either of the following formatting keywords, any extra blanks are removed.
Specifies manual formatting. When you specify the &BL& keyword, the current line terminates and a blank line is inserted in the body of the email.
Specifies manual formatting. Enter this keyword in column one of the email body. Any text on the same line as the keyword specification is ignored. When you specify the &FM& keyword, all text afterwards preserves the formatting and no variable substitution is performed. You can use this keyword to format small tables, reports, or data dumps that need original formatting preserved. To end the manual formatting mode, declare the FM keyword again. If not declared a second time, the format is preserved for the remainder of the email.
Specifies a new line. Any text following this keyword prints on the next line.
If the substitution character changes with the x-SUB: header field, begin and end the formatting keywords with the new substitution character.
Variable substitution is supported in header fields and the body of both HTML and Plain Text format emails. You can specify all types of variables – user, option, product, and system variables.
Every line of text in the email body is examined for the presence of variables. Variables must begin and end with the substitution character and must begin and end on the same line. If you do not specify a substitution character in the email header using the x-SUB: header field, the value that is defined in OPT_EMAIL_DEFAULT_SUBCHAR is used. When a variable is found in the email body, the VDB is searched for an exact match on the variable name. If the match is found, the value that is associated with that variable is included in the email body in place of the variable name. If the variable is not found in the VDB, the variable name is left unchanged in the email body. All variable substitution is performed before any HTML or Plain Text formatting. No variable substitution is performed in a block of text that is being manually formatted with the &FM& keyword.
Variable names are case-sensitive. If the case does not match exactly between the variable in the email and the variable in the database, they are considered to be different variables.
For this example, member EMAIL001 is created in the CAI.SEND data set containing the following statements:
EDIT CAI.SEND(EMAIL001) - 01.00 Columns 00001 00072 Command ===> Scroll ===> CSR ****** ***************************** Top of Data ****************************** 000001 EMAIL 000002 x-TO: bill@example.com 000003 x-TITLE: Scratch tapes are low! 000004 Warning! There are only &CTS_Alert_Variable_Value& tapes 000005 left in volume pool 000006 &CTS_Alert_Pool_ID&. 000007 Please take action now to insure we have sufficient tapes for daily 000008 processing. Note - do not 000009 reply to this email. ****** **************************** Bottom of Data ****************************
Assume that an alert was created which specified member EMAIL001 as the value for the "Send" field in the alert. The following email is created when the alert condition is met. The email information is defined in the headers and specified in the preceding illustration.
From: joe@example.com
To: bill@example.com
Cc:
Subject: Scratch tapes are low!
Warning! There are only 499 tapes left in volume pool ABC_Pool. Please take action now to insure we have sufficient tapes for daily processing. Note - do not reply to this email.
The VPM subtask used the email defaults for x-FMT: and x-FROM: defined in the VDB.
The value for OPT_EMAIL_DEFAULT_FORMAT is HTML. This value is used to select HTML formatting (although HTML tags are not included in the email body). The Sender (joe@example.com) was created using the value for the email option variable OPT_EMAIL_DEFAULT_FROM in the VDB.
The two variables in the text of the email (&CTS_Alert_Variable_Value& and &CTS_Alert_Pool_ID&) have been replaced with the actual values. The values are associated with the alert that was triggered because the condition in the alert was met.
For this example, member EMAIL002 is created in the CAI.SEND data set containing the following statements:
EDIT CAI.SEND(EMAIL002) - 01.00 Columns 00001 00072 Command ===> Scroll ===> CSR ****** ***************************** Top of Data ****************************** 000001 EMAIL 000002 x-SUB: - 000003 x-FROM: -MARIE_EMAIL- 000004 x-TO: bill@example.com 000005 x-TITLE: Tapes sent offsite on -SYSDATE- 000006 This email is generated nightly every 12 hours to list the number 000007 of tapes sent off site by CA 1. The most recent run of TMSVMVLT 000008 identified -TMSVMUPD_TAPES_TO_OFF_SITE- tapes to be sent offsite. 000009 -FM- 000010 Contact list for CA 1 for this month 000011 000012 Joe Smith 866 555-1212 000013 Amber Logan 877 555-6789 000014 -FM- 000015 If the primary and secondary contacts listed above do not respond 000016 please contact the on call manager below: -NL- 000017 -On_Call_Manager- ****** **************************** Bottom of Data ****************************
Assume that an alert was created with the member EMAIL002 as the value for the Send field. The following email is created from the email information in the headers when the alert condition is met.
From: marie@example.com
To: bill@example.com
Cc:
Subject: Tapes sent offsite on 08/13/2012
This email is generated nightly every 12 hours to list the number of tapes that CA 1 sends offsite. The most recent run of TMSVMUPD identified 32 tapes to send offsite.
Contact list for CA 1 for this month
Joe Smith 866 555-1212
Amber Logan 877 555-6789
If the primary and secondary contacts that are listed do not respond, contact the on-call manager:
Robert Smith at 877 555-4567
The VPM subtask used the email default for the x-FMT: parameter. You define the x-FMT: in the VDB that you set to HTML. The x-SUB: header field was used to change the substitution character to use dashes (-). Begin and end all variables and formatting keywords (NL and FM) with a dash (-). Do not use ampersands. The From: header field was created by replacing the user variable MARIE_EMAIL with the value in the VDB. The -FM- keyword starts and ends block formatting, which turns off all formatting in between the keywords. Block formatting is helpful when you format an email with a table or section of text that you do not want to format automatically. The last entry in the table reflects the user variable -On_Call_Manager-.
|
Copyright © 2013 CA Technologies.
All rights reserved.
|
|