MODIFY command

You can use MODIFY (abbreviated as F) to issue commands from the z/OS system console to perform tasks on the BMC AMI Datastream address space. For example, you can request configuration or statistical information and display that information or send it as a syslog message. You can also issue commands to the address space.

Each task can support its own command interface and requires a special command format:

F czagentName,taskID,command

The task ID, a 1–8 character value that uniquely identifies each task, is used in the command interface to direct task-specific commands. In the following example, the CZA1196I message indicates that subtasks of the task are started:

$AGENT subtask

Commands are directed to the $AGENT subtask if they are issued without a task identifier or issued with a $AGENT task identifier. For example, the following commands are equivalent:

F czagentName,$AGENT,DISPLAY(OPTIONS)
F czagentName,DISPLAY(OPTIONS)

MODIFY command for BMC AMI Datastream for z/OS

For information about traceSpecification, see Using-the-TRACE-facility.

Enable a new license

Syntax diagram for enabling a new license provides a visual representation of the command syntax and parameters.

CZAGENT for BMC AMI Datastream for z/OS

CZAGENT for BMC AMI Datastream supports the following display specifications:

Parameter

Description

czagentName | taskName

Defines the name of the BMC AMI Datastream job or started task specified on the START command or in the JCL

For a description of how this name is determined and specified, see "MODIFY command" in the "MVS system commands reference" section on the IBM Knowledge Center website.

This parameter is required.

BACKLOG(Send)

(Does not apply to Datastream for Ops)Causes BMC AMI Datastream to display message CZA0386 with queue utilization data on the console and in the listing on CZAPRINT

If you specify Send (or S), then a BACKLOG syslog message is transmitted to the BMC Defender Server or another syslog console as a syslog message.

CLOCKmsg

Causes BMC AMI Datastream to transmit the Clock message CZA0352I to the SIEM server and display the message on the console and in CZAPRINT

CONFig | CONFig(Send)

(SPE2407)

Provides a consolidated display of the currently active configuration settings, which include the following information:

Status of every switch listed in the $$$CONFG PARM member
Status of every API1 and SMF event type configured in the $$$SELCT PARM member
Format settings defined in the OPTIONS statement, such as delimiters, framing, and host name
Local settings defined in the LOCAL statement, such as DATASet, FOLD, MOD, REOPen, and SPACE
Syslog server settings, including any alternative servers
Time settings defined in the TIME statement, such as date and time formats, and time zone

The values are displayed in the console and in CZAPRINT in the following format:

CZA0251I Switches
CZA0251I     DB2       On
CZA0251I     DEFLTCFG On
CZA0251I     FAM       On
CZA0251I     ICF       On
CZA0251I     IFCID002 On

If you specify (Send), BMC AMI Datastream immediately sends the configuration settings to BMC Defender SIEM Correlation Server or other syslog console in the form of multiple syslog messages.

You can also use the SNDAGTCONFSiem parameter in the OPTIONS statement to send the configuration settings automatically after certain events.

If you omit this parameter, the default CONFig is used.

Display(...)

Causes BMC AMI Datastream to display the currently active settings for the indicated parameters

The values are displayed on the console (except for Display(APF)) and in CZAPRINT in the following format:

CZA0251I| LOCAL
CZA0251I| DATASET (*)
CZA0251I| FOLD (133)
CZA0251I| NOMOD

DISPLAY specification	Information displayed
APF (Deprecated, see ENRichment)	APF enrichment data set names, as well as the system PROCLIB, system PARMLIB, encryption, and SAF database data set names. The table is displayed only in CZAPRINT and there is no console output.
COMPILE	BMC AMI Datastream compilation information, including ARCH level, optimization, and tuning
CONSOLE(SETS)	(Does not apply to Datastream for Ops)SELECTed CONSOLE SETs, in the order of selection The information displayed includes the set name, the PREFIX (if any), the SEVerity, and the count of matching console messages.
CPUTime	Total CPU time consumed by BMC AMI Datastream
ENRichment	Names of the following data sets: APF-authorized System PARMLIB System PROCLOB Encryption SAF database
EVENTs	SELECT status for each API1 event For each SMF type, its processing class, selection code, and INHIBIT status.
INSTances	Running BMC AMI Datastream instances with their instance names (if any) and their job or started task names For more information, see START-command.
LICENSE	Current license information and enables new license keys in a running agent LICENSE has two forms: DISPLAY(LICENSE) command and LICENSE command. To display the valid licenses and number of days remaining on the license, run the command: F czagentName,DISPLAY(LICENSE) The following example is similar to what you see after running the command: Click here to see the example. CZA0014I Processing MODIFY command 'DISPLAY(LICENSE)' CZA0472I AMI Datastream for z/OS license expires in 862 days. CZA0472I AMI Datastream for Db2 license expires in 862 days. CZA0472I AMI Datastream for IMS license expires in 862 days. CZA0472I AMI Datastream for Predictive license expires in 862 days. CZA0026I MODIFY processing completed To reprocess the licenses or enable a new license run the command: F czagentName,LICENSE The following example is similar to what you see after running the command: Click here to see the example. CZA0014I Processing MODIFY command 'LICENSE' CZA0460I AMI Datastream for z/OS license verification successful. License expires in 862 days. CZA0460I AMI Datastream for Db2 license verification successful. License expires in 862 days. CZA0460I AMI Datastream for IMS license verification successful. License expires in 862 days. CZA0460I AMI Datastream for Predictive license verification successful. License expires in 862 days. CZA0026I MODIFY processing completed The licenses are validated and processing is adjusted appropriately. License validation automatically occurs at agent startup. Important If a feature is disabled because of an expired license, follow these steps to re-enable the feature: Verify that you have a valid software license key and create a new password by using the valid key. Issue the LICENSE command to reprocess the license. Issue the F czagentName,PARMS command to re-enable the disabled feature.
LOCal	Settings related to LOCAL (see LOCAL-statement ), such as the data set name and FOLD, MOD, REOPEN, and SPACE parameters
MSGLOAD(SPE2301)	Displays statistics related to client subtasks To display the statistics, run the following command: F czagentName,DISPLAY(MSGLOAD) Click here to see the sample output. CZA0014I Processing MODIFY command 'DISPLAY(MSGLOAD)' CZA0341I Task ID Active Msgs sent Avg Msg size Avg Transmission HWM Msglen HWM Transmission (bytes) time(microsecs) (bytes) time(microsecs) CZA0340I $IPCL000 YES 20 1212 17 1825 90 CZA0340I $IPCL001 YES 15 1555 54 1556 589
OPTions	Settings that might be specified on the OPTIONS statement (see OPTIONS-statement), such as delimiters, framing, and host name options
PARMs	Data set equivalent to LOCAL,OPTIONS,SERVER,TIME
SERVers	Settings related to the syslog server, including any alternatives For more information, see Multiple-syslog-server-support and SERVER-statement.
TIME	Settings related to TIME, such as the date and time formats and time zone For more information, see TIME-statement.
TIMERs	Currently pending internal timers, such as for timeouts, alternative server reversion, and automatic parameter refresh For more information, see TIMEout and ALTRevert in SERVER-statement and REFResh in OPTIONS-statement.

IEFU86Disable | IEFU86Enable

Enable or disable capturing of SMF record data with the BMC AMI Datastream IEFU86 exit

IEFU86Disable—When the IEFU86 exit is disabled, the following exits are enabled: IEFU83, IEFU84, and IEFU85.
IEFU86Enable—When the IEFU86 exit is enabled, the following exits are disabled to prevent duplicate SMF record processing: IEFU83, IEFU84, and IEFU85.

If no value is specified, the default is IEFU86Disable.

LOCal(REOPen)

Specifies that BMC AMI Datastream is to close and reopen the LOCAL syslog data set

Before using this command, consider the effect of the use or absence of system variable symbols in the specified data set name, and the use or absence of MOD.

Example

REOPEN might be meaningless for a data set specified with MOD because additional records simply get appended to the already-open data set. If REOPEN is specified for a local MVS data set without the &HHMMSS. variable symbol in its name and without MOD, BMC AMI Datastream overwrites the existing data set and any existing messages are lost.

PARMs
or PARMs(datasetSpecification)

Specifies the data set from which BMC AMI Datastream takes new operating parameters

The parameter file is an input file. //CZAPARMS DD * cannot be specified. Symbolic system variables are not supported when specifying data set names. Unquoted, uppercase commands can be specified however, zFS files must be specified in one of the following formats:

F czagentName,PARMS('/u/myfiles/czaparms')
F czagentName,'PARMS(/u/myfiles/czaparms)'

The default PDS(E) is DD:CZAPARMS, the library specified by the CZAPARMS DD statement.

If you omit this value, it defaults to the last parameter file specified. For example, the data set specified or defaulted to in any preceding MODIFY PARMS or, if none, the data set specified or defaulted to in START PARMS.

For more information about the parameter file, see Parameter-file-statements.

Parameter processing starts over each time you read in a parameter file with MODIFY czagentName,PARMS with the exception of OPTIONS TRACE, SUBSYS, and QUEUE. Every parameter assumes its default value except for the three parameters named.

OPTIONS QUEUE and SUBSYS are ignored during MODIFY processing. To change their values, you must stop and restart BMC AMI Datastream.

To change the setting of TRACE, you must explicitly specify TRACE. So if BMC AMI Datastream is running with a LOCAL data set, FORMAT(ALL), and an SMF 119 statement, and you read in a new parameter file with FORMAT, LOCAL, and SMF 119 omitted, then FORMAT assumes its default value of ERGONOMIC, the LOCAL data set is closed, and no further SMF 119 records are formatted and transmitted.

SET(APF)

Causes BMC AMI Datastream to re-initialize the table of APF-authorized data sets

The table is refreshed from the current APF list and the defined LNKLST sets. BMC AMI Datastream updates this table automatically in most circumstances, so this command is superfluous unless at least one of the following situations occurs:

You are running a release of z/OS below V2R2.
SMF 90 subtype 37 is not enabled for BMC AMI Datastream processing.
You have added non-APF-listed files to the active LNKLST.

SET(CICS(NEWMCT))

(Does not apply to Datastream for Ops)Requires BMC AMI Datastream, for performance reasons, to cache any DFHMCT customization on a per-CICS-applid basis

If you recustomize and stop and start a CICS subsystem, you can force BMC AMI Datastream to purge and refresh its CICS DFHMCT customization cache with the command SET(CICS(NEWMCT)).

SET(DB2(STArt))

(Does not apply to Datastream for Ops)Causes BMC AMI Datastream to reissue any relevant START TRACE commands for DB2

SET(SERVER(RECONnect))

Causes BMC AMI Datastream to attempt to reconnect to the active syslog server

This command is valid only if the syslog server is disconnected (due to an error) and using TCP/IP or TCP transport. This command would be suitable for use when a previously disconnected communication link is restored.

SET(SERVER(USEALT(number)))

SET(SERVER(USEPRImary))

(Does not apply to Datastream for Ops)Causes BMC AMI Datastream to change the active syslog server to the primary or the specified alternate

For more information, see Multiple-syslog-server-support.

USEPRIMary and USEALT(0) are equivalent.

STATs

STATs(RESET,Send)

Causes BMC AMI Datastream to display message CZA0215I with counts for SMF records and events

Counts that are displayed include:

zIIP normalized time
zIIP CPU time
SMF records processed
Statistics on the console
Statistics in the listing on CZAPRINT

Important

Normalized zIIP time determines the amount of time a unit of work would take if it ran on a standard processor. Normalized zIIP time is derived from the actual zIIP time multiplied by the IBM zIIP Normalize Factor.
Counts by SMF record subtype are displayed only in the CZAPRINT listing.

If you specify RESET, the various statistical counters are reset to zero after being displayed.

If you specify Send (or S), the statistics (not including the subtype counts) are also transmitted to the BMC Defender Server or another syslog console as syslog messages.

For more information about various statistics (not including the subtype counts), see Counters.

For information about the subtype statistics in messages CZA0323I through CZA0327I, see Messages CZA0300 through CZA0399.

TRACE (traceSpecification)

Tells BMC AMI Datastream to use one or more trace types (in any order) or no trace type, as described in Using-the-TRACE-facility

TRACE can be useful for diagnosing certain problems. Diagnostic messages of the specified type are output to the CZAPRINT data set. If TRACE is completely omitted or specified as TRACE(), it defaults to the previous state of TRACE. If TRACE(-ALL) is specified, all tracing is turned off.

Prefix any of the trace specifications with a minus sign (-) to indicate negation. The specifications are processed from left to right. In the following example, the statement indicates that all TRACE output is used except that related to translation and the operating environment:

TRACE(ALL -XL -ENV)

After processing TRACE, BMC AMI Datastream displays the trace specifications that are in effect. To display the current trace specifications only, enter the following statement:

F czagentName,TRACE()

For more information about TRACE, see TRACE-facility-syntax.

MODIFY command for the print manager

Syntax diagram for MODIFY command for print manager provides a visual representation of the command syntax and parameters.

The print manager function forces the current CZAZOSLG output log to close and then reopen.

F czagentName,$PRT SPIN

This command is of particular interest when you specify the LOGFREE=EOJ parameter setting in the startup JCL. The parameter setting causes the CZAZOSLG output log to remain open for the duration of the agent address space, which might cause an excessive amount of output data and JES spool space shortages. The command closes the current CZAZOSLG log output file so that it can be archived and removed from the JES spool.

MODIFY command for the task manager

Syntax diagram for MODIFY command for task manager provides a visual representation of the command syntax and parameters.

To issue console commands, use a standard z/OS modify command with a subtask modifier. If you are unsure about the tasks or their task identifiers, you can request a task list from the task manager:

F czagentName,$MGR,LIST ALL

An example of the output from the LIST ALL command is as follows:

CZA1012I Task ID TCB      CPU Time      START Date/Time     END Date/Time       Description
                          (DDD HH:MM:SS)
CZA1011I $MGR     008EF058 000 00:00:01 09/20/2022 00:01:04 — Active Task — AMI z/OS Task Manager
CZA1011I $IPAUTO 008B7998 000 00:00:00 09/20/2022 00:01:07 — Active Task — Alert Automation TCP/IP Interf
CZA1011I $REXX    008B7BD0 000 00:00:01 09/20/2022 00:01:07 — Active Task — Alert Automation REXX Manager
CZA1011I $IPCL000 008B7E88 000 00:00:01 09/20/2022 00:01:07 — Active Task — IP Client IN-pradshah-W3
CZA1011I $PLEX    008B9140 000 00:00:01 09/20/2022 00:01:07 — Active Task — Sysplex Manager
CZA1011I $AUTO    008B9438 000 00:00:01 09/20/2022 00:01:07 — Active Task — Alert Automation
CZA1011I VMSECURE 008B96E0 000 00:00:00 09/20/2022 00:01:07 — Active Task — AMI Defender for z/VM Secure
CZA1011I VMCON   008B9988 000 00:00:00 09/20/2022 00:01:07 — Active Task — AMI Defender for z/VM CONSOLE
CZA1011I VMRACF   008C81F0 000 00:00:00 09/20/2022 00:01:07 — Active Task — AMI Defender for z/VM RACF
CZA1011I $EMCS    008CB108 000 00:00:01 09/20/2022 00:01:07 — Active Task — E/MCS Console
CZA1011I $AGENT   008CB488 000 00:00:01 09/20/2022 00:01:04 — Active Task — AMI z/OS Agent
CZA1011I $UTIL    008CB6C0 000 00:00:01 09/20/2022 00:01:04 — Active Task — Utility Manager
CZA1011I $PRT     008EC268 000 00:00:01 09/20/2022 00:01:04 — Active Task — Print Manager
CZA1014I 13 tasks found matching selection criteria (active or inactive).

The task manager supports the following commands and their parameters:

Parameter	Description
czagentName \| taskName	Defines the name of the BMC AMI Datastream job or started task specified on the START command or in the JCL For a description of how this name is determined and specified, see "MODIFY command" in the "MVS system commands reference" section on the IBM Knowledge Center website. This parameter is required.
ABEND taskID	Terminate an active subtask with abend Include the task identifier of the active subtask that you want to terminate by abend. For example: F czagentName,$MGR,ABEND $IPAUTO The subtask is abended with an S222-10 abend code, forcing termination.
LIST ALL \| ACTIVE \| INACTIVE	Lists the subtasks, and their accumulated CPU time, running in the address space: LIST ALL shows all active and inactive (terminated) subtasks LIST ACTIVE shows only active subtasks LIST INACTIVE shows only inactive subtasks If no value is specified, the default is ALL.
LPAUPD	Installs, updates, or replaces SMF, API0, API1, Logstream, and BMC AMI Datastream Console exits without stopping or restarting the BMC AMI Datastream for Ops agents running on the LPAR The existing exits are disabled and removed from the LPA before installing the new members.
MAINT (SPE2410)	Apply updates to data sets without restarting the BMC AMI Datastream address space Use this parameter to apply updates to the following data sets: LOAD PARM EXEC DBRM Although you can apply updates to a running BMC AMI Datastream address space, all subtasks stop and restart. SMF record collection pauses for a few seconds during the process. For more information, see Non-disruptive-maintenance.
RETRY taskID	Restart an inactive subtask Include the task identifier of the subtask that you want to restart. For example: F czagentName,$MGR,RETRY $IPAUTO
STOP taskID	Terminate an active subtask Include the task identifier of the active subtask that you want to terminate. For example: F czagentName,$MGR,STOP $IPAUTO The standard task termination Event Control Block (ECB) is posted for normal task termination.