Dynamic Variable Management
SETHEXDV: Set hex value in a Dynamic Variable
The purpose of the SETHEXDV command is to make it possible to store low-level hexadecimal character values as the Value of a Dynamic Variable, so that a {DynVar} token can be used to insert these special values into any field that already supports translating Dynamic Variable tokens, such as the Response Rule Command field, or the CPYMSGIN Event command string of the CPYTOMSGIN command.
One of the most useful purposes for hexadecimal values is to format the message body of a text message generated by the OpCon $NOTIFY:EMAIL Event command. Except for the start of the first line of message text, a Dynamic Variable token could be used to insert a CR (carriage return) and LF (line feed) character pair, wherever the user wants the message body to continue at a new line. This makes it possible to produce nicely formatted information lists, as well as separate paragraphs within the message body of an eMail message.
To prepare the CR+LF value, use the SETHEXDV command to store the value string represented by this notation: X'0D25' as two characters that will be the value used to replace a token such as {CRLF}. Users who understand EBCDIC hexadecimal characters and their uses can create many other types of formatting sequences; however, it will be necessary to test whether these will pass through the OpCon Event command processor program in the OpCon server, after the EBCDIC hex values have been translated to the ASCII character set that OpCon uses.
Use the command SMAGPL/CPYTOMSGIN to test any Event command, since that LSAM command supports translating Dynamic Variable tokens. The LSAM sub-menu 3, option 1, supports a sub-prompt of most OpCon Event commands within the CPYMSGIN keyword field of the CPYTOMSGIN command, so it's easy to correctly format the OpCon Event command string. Insert a {DynVar} token anywhere within the Event command text string, although the hex values are only useful in the Subject Line or the Message Body parameters of the $NOTIFY:EMAIL Event command.
Using The SETHEXDV Command
The IBM i LSAM command SETHEXDV requires that the job's library list include the LSAM environment library names. So it's easiest to use this command from the IBM i command entry line in the LSAM menu system.
Here is an example of how to use this command to store the CR + LF characters:
SETHEXDV VARNAM(CRLF) VALUE(0D25) DESC('Carriage Return + Line Feed characters')
One of the limitations of storing low-level hex characters as a Value for a Dynamic Variable is that the DSPDYNVAR value test command does not produce readable results. This means that testing these types of values would have to be performed by sending them to OpCon as part of an Event command where it makes sense to use them. You can view the results both in the SMA.log file of the OpCon database, as well as in an email message that is sent to a test email account.
For further assistance with the SETHEXDV command, please contact SMA Support.
LOGDYNVAR: Set hex value in a Dynamic Variable
The LSAM utility command named LOGDYNVAR is located in the SMAPGM library. This command and the table of values that it maintains (a file named LOGDYNVAR in library SMADTA) was created to store a series of captured data values that would each be stored into the same Dynamic Variable, at different times. If this command is used to record a copy of the Value each time the Dynamic Variable is updated, then the series of values could later be queried to produce statistical results such as an average, for example, of system CPU or Disk utilization.
The LOGDYNVAR table adds value to the data store by automatically assigning a time stamp to each entry. This makes it possible to limit value surveys within any specified range of times. The table also supports a 12-character Key field (originally designed to match the longest possible Dynamic Variable name), a 20-character user-defined CODE column (field) and a 32-character Description column. All three of these fields could contribute to isolation of data when SQL query techniques are used.
One goal of gathering a series of Values from one Dynamic Variable is to make it possible for another Dynamic Variable of type *DB2 to use SQL SELECT statements to query that series of values. The new Dynamic Variable would, at run time, produce a single result that might be, for example, either a MAX value or an AVG (average) value, deduced from the series of values within a given range of dates/times. Values exceeding user-defined thresholds could trigger OpCon Events, including notification actions and possibly also automated remedial jobs executed by an OpCon Schedule.
Using the LOGDYNVAR Command and Table
Values captured from messages, reports, and workstation displays can be easily stored into Dynamic Variables using the "Store to ->" field of an LSAM Response Rule that can be associated with any Capture Rule. If the Response Rule also executes the new LOGDYNVAR command, then a series of values for the same Dynamic Variable name can be stored with a timestamp and the name of the Dynamic Variable (plus the optional assignment of text values to the CODE and DESC fields) by specifying the Dynamic Variable as a token for the DVVALUE parameter of the LOGDYNVAR command (as illustrated below).
Here is the layout of the LOGDYNVAR table:
| Field | Type | Length | Description |
|---|---|---|---|
| DVRECDATE | TIMESTAMP | 26 | Automatically assigned |
| DVPRIMARY | NUMERIC | 9 | Automatically assigned |
| DVNAME | CHARACTER | 12 | Dynamic Variable name or other name |
| DVVALUE | CHARACTER | 128 | Current (or any) captured value |
| DVCODE | CHARACTER | 20 | User-defined category, for SQL Select |
| DVDESC | CHARACTER | 32 | User-defined description, opt for Select |
Here is the syntax of the LOGDYNVAR command:
SMAPGM/LOGDYNVAR DVNAME(DVORKEYNAME1) +
VALUE('Any value string contained within a pair of single -
quotes.') +
CODE('MY-CODEA-CPU-UTIL') +
DESC('CPU utilization from DSPSYSSTS')
Any value can be used for the DVNAME key value, but if it contains special characters or spaces, or it begins with a non-alpha character, then it must be contained within a pair of single quotes.
After one or more values has been stored in association with the same key value (which could be the Dynamic Variable name), then another Dynamic Variable can be used to query the series of values by using the User Program special value of *DB2. This allows a predefined SQL SELECT statement to be executed whenever the new Dynamic Variable token will be replaced.
Following is an example of the SQL syntax that can be used to produce a single average value for the new Dynamic Variable. The data and SQL clauses used in this example are explained in the notes that follow the example.
SELECT 'CPU avg: ' CONCAT AVG(DEC(DVVALUE,4,1))
FROM SMADTA/LOGDYNVAR
WHERE DVNAME LIKE 'CPU%'
AND DVRECDATE >= '2017-07-10-00.00.00.000'
AND DVRECDATE <= '2017-07-12-23.59.59.000'
EXAMPLE RESULT:
CPU avg: 15.2
Example Notes:
- The SQL statement above can be typed entirely into the WHERE field of a DB2 extension to a Dynamic Variable master record, if the "field/col" field is set to a value of "WHERE". REMEMBER: The value returned to the Dynamic Variable token replacement module must be a single character string that does not exceed 128 characters in length. The example above shows the SQL operator CONCAT being used to blend a hard-coded label with the average value into a single character string. (CONCAT forces the numeric average to be handled as part of an overall, single character string.)
- The example above assumes that the CPU utilization was captured from the DSPSYSSTS display on a screen format, and that its maximum value could be 999.9. The captured character string is converted to a Decimal value using the SQL DEC keyword and its associated numeric size parameters (4 digits, of which 1 is to the right of the decimal point).
- The LOGDYNVAR command and table support two other user-defined fields (table columns): CODE = up to 20 characters of a category code DESC = up to 32 characters describing the stored value These columns could also be used in the SQL WHERE clause to group logged values according to any user-defined scheme.
- The LSAM does not support any automatic purging of the LOGDYNVAR table. This is entirely up to the user. The table could be purged by using an SQL statement that deletes all records with timestamps older than a user-specified value.