ACF

Purpose

The ACF command loads, displays, and modifies automation control file entries. You can use ACF to refresh data of a particular system if it does not affect automation manager configuration data.

For modification and display actions to work, the automation control file must be loaded into storage. Once loaded, the displays and modifications affect an in-storage version of the automation control file, allowing you to make temporary changes. To make permanent changes, change the automation policy using the customization dialogs, generate the automation control file member, then reload the new version using INGAMS. This ensures that the configuration matches the automation manager and the automation agents.

Recommendations:

  1. Use the INGAMS command rather than the ACF command to load or refresh an automation control file. This ensures that the configuration matches the automation manager and the automation agents.
  2. Changes to automation policy that are made using the SA z/OS command dialogs or the ACF command are temporary. They modify the current in-storage version of the automation control file directly. They do not modify the automation control file that is stored on disk. To change an automation policy setting permanently, make sure you also change the automation policy (using the customization dialogs) that is stored on disk.
  3. If the customization dialogs are used to rebuild the automation control file on disk, the changed data on disk will replace the data in storage at ACF REFRESH.
  4. Use scope-checking to limit operator use of ACF to load and display operations.

The following syntax diagrams show how to use the ACF command to perform the different functions ACF supports. Do not combine syntax from the separate diagrams in the same ACF call.

Note: The ACF command is freeform:
  • Commas are optional
  • More than one space can separate keywords
  • Keywords can be specified in any sequence
  • Any parameters specified must follow the keyword that they apply to

To replace or add information in the automation control file use the following syntax:

Syntax

Read syntax diagramSkip visual syntax diagramACFfunction optionsdisplay request optionsdelete request optionsadd/replace request options
function options
Read syntax diagramSkip visual syntax diagramCOLDREFRESHATLOADSTATUSCHECKTOKEN= current_tokenTOKEN= tokenTOKEN= *DSN= current_dsnDSN= dataset_name
display options
Read syntax diagramSkip visual syntax diagramREQ=DISP1ENTRY= *ENTRY= entryTYPE= *TYPE=(type)
delete options
Read syntax diagramSkip visual syntax diagramREQ=DELENTRY= entryTYPE= type
add/replace options
Read syntax diagramSkip visual syntax diagramREQ=REPLENTRY= entryTYPE= typeparms= value
Notes:
  • 1 The specification of either REQ=DISP or ENTRY=entry is required.

Parameters

COLD
Reloads the currently loaded automation control file data from disk. Automation is disabled while the automation control file load is performed. It deletes all global variables that were associated with the Entry/type pairs defined in the policy database. It also deletes all exceptional messages and disabled timers. Statistical data provided by the INGRPT command is also deleted.
Note: It is not recommended to use ACF COLD. Especially for cleanups, use the INGCLEAN command. For further details, refer to the INGCLEAN command reference in IBM Z® System Automation Programmer's Reference.
REFRESH
Updates the currently loaded automation control file data. Automation is not disabled while the automation control file load is performed. Only data that has been changed will be loaded, everything else remains the same as before. This is the safe way to update the automation control file. Refresh will not load data of a subsystem that is currently in the process of being started or stopped by SA z/OS. SA z/OS will automatically retry the refresh five minutes later for the data that cannot currently be processed.
Note: ACF REFRESH will not delete global variables that were associated with Entry/Type pairs, that were deleted from the policy database before the last build was done, if those Entry/Types were not associated with a subsystem, a monitor resource, or an application group. However, if a keyword/value is removed from the Entry/Type, this is a change to the Entry/Type, and consequently an ACF REFRESH will rebuild the Entry/Type with the result that the deleted keyword/value pair is removed from the global variables. All deleted Entry/Types and their associated global variables will be reset during the next SA z/OS NetView restart or during ACF COLD processing or by using the INGCLEAN command. For further details, refer to the INGCLEAN command reference in IBM Z System Automation Programmer's Reference.
ATLOAD
Reloads the NetView automation tables that are specified in the System Info policy item and the message revision table, depending on the value of AOFSMARTMAT.
STATUS
Displays information about the automation control file that is currently in storage.
CHECK
Verifies the ACF for validity and tests the automation tables that are specified in the System Info policy and also the message revision table, depending on the value of AOFSMARTMAT.
TOKEN
The configuration token that the ACF should be validated against.
current_token
The token that is currently in use (displayed with ACF STATUS). This is the default.
token
The configuration token used as the reference.
*
Specifying an asterisk (*) means that the token validation should be omitted.
DSN
The data set name that contains the ACF data.
current_dsn
The data set that is currently in use (displayed via ACF STATUS). This is the default.
dataset_name
The configuration data set name containing the ACF data.
REQ
The type of request for automation control file information the ACF command performs. This value can be one of the following:
DISP
Displays information in the automation control file. This value is the default if this parameter is not coded.
DEL
Deletes information in the automation control file. This value must be coded when using ACF to delete automation control file information.
REPL
Replaces or adds information in the automation control file. This value must be coded when using ACF to replace automation control file information. REPL adds the entry specified on the ENTRY parameter if the entry does not already exist in the automation control file.

REQ=REPL will update data in place. That is, only data that is to be replaced needs to be specified in the command. All other existing data will be retained.

ENTRY
The entry field of the automation control file. This value can be up to 32 characters long, without imbedded blanks, commas, or quotes.

For messages data of application groups (APGs), the value must be prefixed with 0. For messages data of monitor resources (MTRs), the value must be prefixed with 1.

If information in the automation control file is displayed (REQ=DISP), and no value is specified in the entry field, ENTRY=* is used.

TYPE
The type field in the automation control file. The following values can be specified:
*
Specifying * returns all type fields that are associated with a given entry, for example, all SUBSYSTEM or NTFYOP entries. * is the default value when REQ=DISP (display). REQ=DISP supports the use of * as a wildcard character when specifying type names, with the following restrictions:
  • The wildcard character, *, must be the last character in the type name. If an asterisk appears in any other position in a type name then it will be treated as a literal. If an asterisk appears in any other position in a type name with an asterisk as the last character then no wildcard processing occurs and both asterisks are treated as literals.
  • If you update an entry, you must specify the ENTRY= operand without a wildcard.
  • If no matches are found, a final search is performed with a type name of DEFAULTS.

For other ACF request types (delete and replace), you must specify an actual type name.

type
The name of the type field. REQ=REPL requests allow you to enter only one type.

When ENTRY=SUBSYSTEM, type can be up to 11 bytes long. In all other cases, type can be up to 32 characters long, without imbedded blanks, commas, or quotes.

(type,type,...)
Multiple types may be specified for DISP and DEL requests. Type names should be enclosed in parentheses and separated by commas. For REQ=DISP, only the first type name found is displayed. For REQ=DEL requests, all the type names will be deleted.
parms=value
The data associated with the specified ENTRY and TYPE fields. This field is valid only with the REQ=REPL option. Specify this field as the parameter value, an equal (=) sign, and the value, without any spaces in between; for example, AUTO=NO.

The value can be any character data. It can have imbedded quotes, commas, and blanks, provided that single quotes, double quotes, or parentheses frame the value. If the value contains parentheses, then you cannot use parentheses as delimiters.

SA z/OS defines several ENTRY, TYPE, and parms=value fields. A parms=value example is the JOB=jobname parameter in the SUBSYSTEM automation control file entry.

Note: REQ=REPL will update data in place. That is, only modified data is updated. All data will be retained.

Restrictions and Limitations

  • If you use the COLD parameter, automation is disabled while the ACF LOAD is in progress. If you use the REFRESH parameter, automation continues.
  • An automation control file cannot be loaded by an operator using the ACF command if the automation flag for major resource MVSESA is set to ‘N’. If the automation flag for the MVSESA.RELOAD.CONFIRM minor resource is set to ‘Y’, the operator can reload the ACF.
  • ACF must comply with the automation manager configuration, otherwise message AOF618I is issued.
  • The ACF command should be used with care to change or delete automation policy settings. All changes are only temporary changes and may get lost during the next configuration refresh. The changes are definitely lost during an ACF COLD or after processing the INGCLEAN command.
  • The number of entries in the automation control file is limited only by the amount of storage in the SA z/OS address space or region. If you have a very large configuration, you may have to increase the REGION size in the SA z/OS procedure.
  • Not all data can be changed using ACF REQ=REPL, for example, service periods, events, triggers, and dependencies cannot be changed. ACF REQ=DEL and ACF REQ=REPL cannot be used to add or delete an application (subsystem), an application class, an application group or a monitor resource. It is NOT recommended to change data of existing applications, application groups and monitor resources via ACF REQ=REPL to avoid data mismatch between automation agent and automation manager. Use the customization dialogs to define these items and/or change those data.
  • Changes to System Defaults and Application Defaults policy items are not propagated to the instances that have inherited this data.

Security Considerations

The ACF command supports resource level security. If turned on, the following profiles in class SYSAUTO are checked:
Profile Authority Condition
AGT.sysplex.xcfgrp.RES.resname.restype[.ressys] UPDATE When function option is REFRESH or ATLOAD
CONTROL When function option is COLD and for delete (REQ=DEL) or add/replace requests (REQ=REPL)

Usage other than listed in the table does not cause a resource level security check. For further details, refer to IBM Z System Automation Planning and Installation.

Return Codes

0
Function completed successfully.
1
Control file inactive.
3
ACF token mismatch.
4
Invalid parameters were used in the call.
12
No valid ACF member available.
20
ACF reload not allowed by automation flag settings.
24
Resource level security check failed
100
Other error.

Usage

  • ACF performs two flag checks when the automation control file is reloaded. The checks are of the Automation flags for MVSESA.RELOAD.CONFIRM and MVSESA.RELOAD.ACTION. The action flag is checked only if the reload is to continue.
    MVSESA.RELOAD.CONFIRM
    This lets you:
    • Turn the flag off and thus disable an automation control file reload by an operator.
    • Tell SA z/OS to ask for confirmation by setting the AOFCONFIRM TGLOBAL to YES in a flag exit.
    • Use a flag exit to perform additional checks and processing before deciding to either cancel or proceed with the reload.

    If the flag is found to be off, the operator cannot reload the automation control file.

    Note: You need to be aware of this if you turn the MVSESA automation flag off.

    If the flag is on, the AOFCONFIRM task global is checked. If it is set to YES, SA z/OS will post a message requesting confirmation of the reload request. If AOFCONFIRM is null, SA z/OS will proceed with the reload.

    MVSESA.RELOAD.ACTION
    This provides an opportunity for you to do your own processing once SA z/OS is committed to reloading or restoring the automation control file. You can use a flag exit to call your own code. Your exit should return 0, indicating that the flag is turned on. If you return a nonzero return code, subsequent exits defined for the flag will not be invoked.

    Note that there is no way of preventing the reload from an exit on this flag. See IBM Z System Automation Defining Automation Policy and IBM Z System Automation Customizing and Programming for further information.

  • When you use ACF REQ=DISP to request a certain ENTRY value with one or more specific TYPE values, ACF searches for those types in the order specified in the command. When the first match is found, the information is returned to the requester as a multiline message. If there are no matches, it performs a final search with a type of DEFAULTS for that ENTRY value. If there is still no match, a message is returned to the requester. If the type DEFAULTS is found, that information is returned to the requester.
  • If, when ACF is used to display an automation control file entry, a specific TYPE is found, it is treated as a complete entry. Only that specific entry is displayed.

Messages

The following lists the messages that are issued during the operation of ACF.

For the load function (COLD/REFRESH): 
AOF042I MEMBER ACFZ999 NOT FOUND
AOF100I 16:05:09 : 'ACF REFRESH' COMMAND ISSUED
AOF618I NO VALID ACF FOUND FOR sysname - detail description
AOF782I AUTOMATION CONTROL FILE PROCESSING COMPLETED
For the status function (STATUS): 
AOF005I MEMBER ACFZ992 CURRENTLY BEING USED FOR THE CONTROL FILE
AOF006I BUILT     BY OPER1    ON 07/16/19 AT 11:43:03
AOF006I REFRESHED BY OPER1    ON 07/17/19 AT 08:52:20
AOF006I CONFIGURATION TOKEN   = 2019071607282400227FD72827
AOF006I CONFIGURATION DATASET = SATEST.SAMPLES.V420.RGT#PROD.SCM.ACF
AOF002I END OF MULTI-LINE MESSAGE GROUP
For the delete and replace function (REQ=DEL/REPL): 
AOF001I REQUEST REPL SUCCESSFUL FOR JES2-$HASP098
Note: In a display where the type_name is asterisk (*), multiple sets of AOF112I and AOF113I messages may be displayed. When the type is omitted or specified as asterisk (*), the DESIRED TYPE is not displayed in the AOF112I message.
For the display function (REQ=DISP): 
AOF041I UNABLE TO FIND entry type

AOF111I AUTOMATION CONFIGURATION DISPLAY - ENTRY= entry_name
AOF112I ACTIVE TYPE= act_type, DESIRED TYPE= desired_type ...
AOF113I DATA IS data=value
AOF002I END OF MULTILINE MESSAGE GROUP
For example, the following may occur: 
AOF111I AUTOMATION CONFIGURATION DISPLAY - ENTRY= NTFYOP
AOF112I ACTIVE TYPE= NETOP1
AOF113I DATA IS OPER='OPER 1'
AOF113I DATA IS CLASS=(10,40)
AOF112I ACTIVE TYPE= NETOP2
AOF113I DATA IS CLASS=(10)
AOF002I END OF MULTILINE MESSAGE GROUP
Note: Use of the replace parameter (REPL) adds an entry if none exists, resulting in a successful message.
Generic error messages that can occur: 
AOF013I SPECIFIED OPERAND operand INVALID FOR PARAMETER parameter.
AOF025I SYNTAX ERROR

Examples

The ACF command to display the Start automation flag for the CICST subsystem is: 
ACF REQ=DISP,ENTRY=START,TYPE=CICST
The response is: 
AOF111I AUTOMATION CONFIGURATION DISPLAY - ENTRY= START
AOF112I ACTIVE TYPE= CICST      , DESIRED TYPE= CICST
AOF113I DATA IS AUTO=Y
AOF113I DATA IS NOAUTO=(TUESDAY,10:00,12:00)
AOF002I END OF MULTILINE MESSAGE GROUP

In this example, a Start automation flag exists for the CICST subsystem. The operator or automation procedure processes the command to display the entry, and the associated response is returned as a multiline message.

Use the following automation procedure to update ACF data for an entry. It allows you to modify the automation agent configuration data without affecting other automation agents or the automation manager. 
/* ************************************************* **
** Function:                                         **
**    - Read ACF Fragment                            **
**    - Modify ACF entries                           **
** ***************************************************/
'PIPE (NAME ACFREPL)',                                 
'QSAM (DSN) -dataset-',    /* read ACF fragment      */
'! NLOC 1.1 /*/',          /* skip comments          */
'! COLLECT',               /* collect to multiline   */
'! NETV ACF REQ=REPL',     /* call ACF command       */
'! CONS'                   /* issue msgs to console  */