Troubleshooting ACFNRULE and RECKEY deletion failures with system symbols such as &SYSUID

Products

ACF2 ACF2 for z/OS ACF2 for z/VM ACF2 for z/VSE WEB ADMINISTRATOR FOR ACF2 ACF2 for Db2 ACF2 - MISC

Issue/Introduction

When utilizing z/OS system symbols (such as &SYSUID) within ACF2 resource rule statements, scenarios may occur where the symbol appears to resolve to a user ID. Conversely, administrators often report that ACFNRULE or RECKEY deletion commands fail with "NO MATCHING RULES FOUND" or "NO MATCHING RULE LINE FOUND" when these symbols are used.

Environment

Product : ACF2 for z/OS

Cause

It is a common misconception that ACF2 natively resolves z/OS system symbols (such as &SYSUID) to a Logon ID (LID) when compiling or processing rules. ACF2 does not perform this resolution internally.

If a symbol such as &SYSUID appears to resolve to a specific user ID within ACF2 rule statements, this resolution is occurring externally to the ACF2 product. This is typically due to the following factors:

External scripting: An external process such as a CLIST, REXX EXEC, or ISPF panel routine is parsing the command string and substituting the system symbol with an actual user ID before the command is submitted to ACF2.
Expansion errors: Because the ACFNRULE and RECKEY utilities require an exact, character-for-character match of the rule line to perform a deletion, any padding, extra spaces, or truncation introduced by the external script during the substitution process will cause the match to fail.

Resolution

Since ACF2 does not perform this resolution internally, ensuring external processes correctly handle the substitution is essential.

Validate external scripts: If a CLIST or REXX script is used to automate rule deletions using &SYSUID, review the script logic to ensure it does not inject unintended spaces, trailing characters, or padding when it substitutes the variable with the LID.
Verify the exact string: Since ACFNRULE performs a character-for-character comparison, the output string generated by the script must match the current rule entry exactly. Verify the stored rule format by running a DECOMP of the rule set.
Utilize RECKEY for deletions: If string-matching with ACFNRULE continues to be problematic due to variations in external substitution, utilize the RECKEY command. RECKEY is designed for precise, exact-match deletions of rule entries and is the recommended utility when precise control is required.

Example: Using RECKEY for deletion If use RECKEY, it can be run it via ACFBATCH. The following is a sample JCL:

//ACFBATCH EXEC PGM=ACFBATCH
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
SET RULE
RECKEY ruleid DEL(rule-entry)
//* rule-entry is the exact rule entry line to delete. <--- Remember
/*

Troubleshooting and best practices

1. Identifying the discrepancy. If a deletion fails, do not assume the rule does not exist. Instead, identify the discrepancy by comparing the rule as it is stored versus the rule in the script submits it:

Run a DECOMP of the rule set to view the exact format of the rule as stored in the ACF2 database.
Check for hidden characters. Sometimes script substitution results in trailing spaces that are not visible in a standard TSO print but are present in the command string.
Use a hex editor or a LIST command with hex on, if possible, to verify that the length of the expanded variable matches the rule entry's expected length.

2. Understanding tool behavior

ACFNRULE: This utility checks if the rule entry contains the string specified in DELETE command.This method requires caution if the string is not specific enough, ACFNRULE may delete multiple rules that contain that substring refer to article " ACFNRULE utility delete multiple rule entries" .
RECKEY: This utility performs an exact match of the entire rule line. It is significantly safer and more precise for deleting single, specific rule entries.

Additional Information

System symbols like &SYSUID do not resolve in ACF2.

1. The first example below shows that RECKEY Del worked because there is an exact character match for UID(&SYSUID) in the rules.

RULE

DECOMP TESTKEY

ACF75052 ACCESS RULE TESTKEY STORED BY USER01 ON 08/26/26-08:55

$KEY(TESTKEY)
TEST UID(&SYSUID) READ(A) EXEC(A) <------------ Will delete this rule line
TEST UID(ABCDEFG) READ(A) EXEC(A)
TEST UID(ABCDE) READ(A) EXEC(A)
TEST UID(ABC) READ(A) EXEC(A)
ACF75051 TOTAL RECORD LENGTH= 328 BYTES, 2 PERCENT UTILIZED

RULE

RECKEY TESTKEY DEL(TEST UID(&SYSUID) READ(A) EXEC(A))

ACF75052 ACCESS RULE TESTKEY STORED BY USER01 ON 08/26/26-08:55
ACF60202 THE FOLLOWING RULE LINE(S) WILL BE DELETED
TEST UID(&SYSUID) READ(A) EXEC(A)
ACF70010 ACF COMPILER ENTERED
******** ACCESS RULE TESTKEY STORED BY USER01 ON 08/26/26-08:55

$KEY(TESTKEY)
TEST UID(ABCDEFG) READ(A) EXEC(A)
TEST UID(ABCDE) READ(A) EXEC(A)
TEST UID(ABC) READ(A) EXEC(A)
ACF70051 TOTAL RECORD LENGTH= 278 BYTES, 1 PERCENT UTILIZED
ACF60207 RULE TESTKEY REPLACED

2. The second screenshot shows that RECKEY DEL failed " ACF60203 NO MATCHING RULE LINE FOUND - PROCESSING TERMINATING "because there is no exact character-to-character matching line present in rule TESTKEY.

RULE

DECOMP TESTKEY
ACF75052 ACCESS RULE TESTKEY STORED BY USER01 ON 08/26/26-08:01
$KEY(TESTKEY)
TEST UID(ABCDEFG) READ(A) EXEC(A)
TEST UID(ABCDE) READ(A) EXEC(A)
TEST UID(ABC) READ(A) EXEC(A)
ACF75051 TOTAL RECORD LENGTH= 278 BYTES, 1 PERCENT UTILIZED

RULE

RECKEY TESTKEY DEL(TEST UID(&SYSUID) READ(A) EXEC(A)) <======= This exact rule line does not exist.

ACF75052 ACCESS RULE TESTKEY STORED BY USER01 ON 08/26/26-08:01
ACF60203 NO MATCHING RULE LINE FOUND - PROCESSING TERMINATING

For guidance on troubleshooting rule deletion failures or using RECKEY as an alternative, refer to article " ACFNRULE utility delete multiple rule entries"