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:

  CZA1196I $AGENT task attached: CZAGENT – AMI z/OS Agent
  CZA1009I $PRT AMI z/OS Print Manager task initialization complete.
  CZA1196I VMRACF task attached: CZATSERV – AMI Datastream for z/VM RACF
  CZA1196I VMCON task attached: CZATSERV – AMI Datastream for z/VM CONSOLE
  CZA1196I VMSECURE task attached: CZATSERV – AMI Datastream for z/VM Secure
  CZA1196I $AUTO task attached: CZAECXCF – AMI Datastream Alert Automation
  CZA1196I $IPAUTO task attached: CZAIPMGR – AMI Datastream Alert Automation TCP/IP Interface

The task manager has its own task identifier:

CZA1009I $MGR BMC AMI Datastream task initialization complete.

$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

MODIFY-zos_6.2.00.png

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

Enable a new license

MODIFY_LICENSE_5.9.02.png

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

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 czagent,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 czagent,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 (SPE2207)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 czagent,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
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

Because the parameter file is an input file, specifiying * (SYSOUT) is invalid and the output variable symbols are not supported. CZAJOBLG processes uppercase, unquoted command operands, so you can specify a zFS file as one of the examples:

F CZAGENT,PARMS('/u/myfiles/czaparms')
F CZAGENT,'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 CZAGENT,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 SSL/TLS 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 of SMF records processed and similar statistics on the console and in the listing on CZAPRINT

In addition, counts by SMF record subtype are displayed only in the CZAPRINT listing. If RESET is specified, then the various statistical counters are reset to zero after being displayed. If Send is specified, then the statistics (not including the subtype counts) are also transmitted to the BMC Defender Server or another syslog console as syslog messages. Send can be abbreviated as S. For more information about various statistics except the subtypes, see Counters. See Messages CZA0300 through CZA0399 for information about the subtype statistics in messages CZA0323I through CZA0327I.

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 CZAGENT,TRACE()

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

MODIFY command for the print manager

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

MODIFY_taskmanager_6.2.00.png

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:

CZA1008I $MGR task processing LIST command.
CZA1012I Task ID TCB      START Date/Time     END Date/Time       Description
CZA1011I $MGR     006EE588 11/03/2021 09:18:46 --- Active Task --- AMI z/OS Task Manager
CZA1011I $IPAUTO 006B67B8 11/03/2021 09:19:22 --- Active Task --- Alert Automation TCP/IP Interface
CZA1011I $REXX    006B6A60 11/03/2021 09:19:22 --- Active Task --- Alert Automation REXX Manager
CZA1011I $AUTO    006B6D90 11/03/2021 09:19:22 --- Active Task --- Alert Automation
CZA1011I VMSECURE 006C6138 11/03/2021 09:19:22 --- Active Task --- AMI Datastream for z/VM Secure
CZA1011I VMCON    006C63E0 11/03/2021 09:19:22 --- Active Task --- AMI Datastream for z/VM CONSOLE
CZA1011I VMRACF   006C6BB8 11/03/2021 09:19:22 --- Active Task --- AMI Datastream for z/VM RACF
CZA1011I $EMCS    006CA0C0 11/03/2021 09:19:22 --- Active Task --- E/MCS Console
CZA1011I $AGENT   006CA430 11/03/2021 09:18:47 --- Active Task --- AMI z/OS Agent
CZA1011I $PRT     006E58B8 11/03/2021 09:18:46 --- Active Task --- Print Manager
CZA1014I 10 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.
LIST ALL \| ACTIVE \| INACTIVE	Lists the tasks 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.
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.
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.
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.