ERP Pro v9 File Locks

Viewing and unlocking ACUCOBOL-GT file locks

ERP Pro v9 File Locks

The ERP Pro v9 File Locks feature allows you to view and manage file locks on ACUCOBOL-GT servers running on EC2 instances. This is essential for troubleshooting application issues, identifying stuck processes, and resolving file contention problems.

Overview

ACUCOBOL-GT maintains file locks when users access database files. Sometimes these locks become “stuck” when:

• User sessions crash without cleanup
• Network interruptions occur
• Application errors prevent proper lock release
• Processes terminate abnormally

The Locks Viewer helps you:

• See all active file locks on a server
• Identify which users and processes hold locks
• Determine which files are locked
• Unlock stuck locks safely

Accessing the Locks Viewer

From Client Operations

The primary way to access the locks viewer:

1. Navigate to Product → ERP Pro → Client Manager
2. Locate the client in the table
3. Click the Actions menu (three dots) in the rightmost column
4. Select View Locks

The page automatically loads with the client’s instance information pre-populated.

Direct Access

You can also navigate directly to the locks viewer, though you’ll need to manually enter instance details:

URL Pattern:

/product/erppro/locks?instanceId=i-xxx&region=us-east-1&clientName=CLIENT_NAME

Page Layout

Client Context Header

When navigating from Client Operations, the header displays:

• Host: Instance name and instance ID
• Region: AWS region badge
• Client: Client name and reference ID (if filtered)

This context remains visible while viewing and managing locks.

Summary Section

After locks are loaded, a summary panel displays key metrics:

• Total Locks: Total number of file locks currently held
• Unique Users: Number of distinct users with locks
• Unique Files: Number of distinct files being locked
• Data Source: Shows if data is cached or fresh
• Cache Age: Time since data was last refreshed (if cached)

Refresh Button: Click to bypass cache and fetch fresh lock data from the server.

Filters

The filter panel helps you narrow down locks by:

User (multi-select)

• Filter by username
• Shows all usernames currently holding locks
• Dynamically populated from lock data

Database (multi-select)

• Filter by database/schema name
• Extracted from file path (e.g., “SCM”, “FIN”)
• Useful for focusing on specific application areas

Lock Type (multi-select)

• I (Input): Read lock
• O (Output): Write lock
• IO: Read-write lock

Server Name (multi-select)

• Filter by file server hostname
• Extracted from UNC paths (e.g., //SERVER/path)
• Useful for multi-server environments

Search

• Free-text search across all fields
• Searches: username, session ID, file path, process ID
• Real-time filtering as you type

Data Table

The main table displays lock information with the following columns:

Actions Menu

Each lock row has an Actions menu (three dots) with unlock options:

Unlock by Client

• Unlocks ALL locks held by this client/session
• Use when a user’s entire session is stuck
• More aggressive, affects all files for that user

Unlock by Process ID

• Unlocks only locks held by this specific process
• More targeted approach
• Recommended for surgical lock removal

Viewing Locks

Initial Load

When you navigate to the locks viewer from Client Operations:

1. Page automatically detects instance information from navigation state
2. Loading spinner appears with instance details
3. System queries ACUCOBOL server via SSM (Systems Manager)
4. Locks are displayed in the table (typically 5-15 seconds)

Understanding the Data

File Paths

• Format: //SERVER/SHARE/DATABASE/DATA/FILENAME
• Example: //CWPINFA05/SCM/DATA/COADDRF
• Server: CWPINFA05
• Database: SCM
• File: COADDRF

Lock Types

• I (Input): Read-only access, multiple users can hold simultaneously
• O (Output): Exclusive write access, blocks other users
• IO: Combined read-write access

Session IDs

• Format varies by client configuration
• Often includes client identifier and random string
• Used to group locks by user session

Cached vs Fresh Data

The system uses S3 caching to improve performance:

Cached Data Indicators:

• “Cached - Last Refreshed” label in summary
• Timestamp showing when data was retrieved
• Age warning badges:
  • Orange: Data is more than 1 hour old
  • Red: Data is more than 24 hours old

Why Caching Matters:

• Fresh queries take 10-13 seconds (SSM + parsing)
• Cached queries take 1-2 seconds (90% faster)
• Reduces load on ACUCOBOL servers
• Avoids SSM rate limits

When to Refresh:

• If you need current lock state
• After unlocking operations
• When troubleshooting active issues
• If cache age warning appears

Unlocking Locks

Prerequisites

Permissions Required:

• ERPPRO_LOCKS_UNLOCK permission
• Granted via TOC Cloudscape role assignments
• Contact administrators if unlock actions are not visible

Important Safety Notes:

• Unlocking removes locks immediately and permanently
• Users may lose unsaved work
• Coordinate with users before unlocking their sessions
• Document reason for unlock in support tickets

Unlock by Client (Session)

Use when an entire user session is stuck:

1. Locate the lock row for the affected user
2. Click Actions menu (three dots)
3. Select Unlock by Client
4. Review the confirmation modal:
   • Client/session ID
   • Number of locks that will be removed
   • Warning about user impact
5. Type UNLOCK in the confirmation box
6. Click Confirm Unlock

What Happens:

• Lambda invokes SSM command: acuserve.exe -kill {clientId}
• All locks held by that session are released
• User’s application session terminates
• User must log back in

When to Use:

• User’s session is completely frozen
• User has logged out but locks remain
• Network disconnect left locks orphaned
• Multiple files locked by same stuck session

Unlock by Process ID

Use for targeted lock removal:

1. Locate the specific lock row
2. Click Actions menu (three dots)
3. Select Unlock by Process ID
4. Review the confirmation modal:
   • Process ID
   • Specific file path affected
   • Username
5. Type UNLOCK in the confirmation box
6. Click Confirm Unlock

What Happens:

• Lambda invokes SSM command: acuserve.exe -kill {processId}
• Only locks held by that specific process are released
• Other processes in same session may continue
• More surgical than client unlock

When to Use:

• Single file is locked, others are fine
• Specific process known to be stuck
• Want to minimize impact to user
• User is still actively working in other modules

Confirmation Modal

Both unlock operations require explicit confirmation:

Modal Contents:

• Operation type (By Client or By PID)
• Target identifier (Client ID or Process ID)
• File path (for PID unlock)
• Lock count (for Client unlock)
• Warning message about consequences
• Text input requiring “UNLOCK” to proceed

Why Strict Confirmation:

• Unlock operations are irreversible
• Can cause data loss if user has unsaved work
• May interrupt active business processes
• Should only be used after due diligence

After Unlocking

Success:

1. Success notification appears (green)
2. Confirmation modal closes
3. Automatically refreshes lock data to show current state
4. Unlocked locks disappear from table

Failure:

1. Error notification appears (red)
2. Error message from SSM/Lambda shown
3. Modal remains open for retry
4. Locks remain in place

Common Failure Reasons:

• Instance unreachable or stopped
• SSM agent not running
• Permissions issue
• Network connectivity problem
• Invalid client/process ID

Advanced Features

Filtering by Multiple Criteria

Combine filters for precise results:

Example: Find specific user’s locks in one database

1. Select user in User filter
2. Select database in Database filter
3. Table shows only matching locks

Example: Find all write locks

1. Select “O” in Lock Type filter
2. See all files being actively written to
3. Identify potential contention points

Sorting

Click column headers to sort:

• Username: Alphabetical grouping of users
• Process ID: Numeric sorting
• File Path: Alphabetical file ordering
• Database: Group locks by database

Useful for identifying patterns and finding outliers.

Search

The search box provides quick filtering:

Search by Username:

nca.jwilliam

Search by File:

COADDRF

Search by Server:

CWPINFA05

Search by Session:

CWPINE1

Search is case-insensitive and matches partial strings.

Troubleshooting Common Issues

No Locks Displayed

Possible Causes:

• No locks currently exist (normal state)
• SSM command failed
• Instance is stopped or unreachable
• Permissions issue

Solutions:

1. Check error messages in banner
2. Verify instance is running
3. Check SSM agent status on instance
4. Retry with Refresh button
5. Check CloudWatch Logs for Lambda errors

Unlock Operation Fails

Error: “Instance not found”

• Instance may be stopped or terminated
• Verify instance ID is correct
• Check instance status in EC2 console

Error: “Permission denied”

• Check IAM roles and policies
• Verify SSM document exists in region
• Ensure cross-account role is assumed correctly

Error: “Command timed out”

• Instance may be under heavy load
• SSM agent may be unresponsive
• Network connectivity issue
• Retry after a few minutes

Stale Cache Data

Symptoms:

• Lock count doesn’t match expectation
• Unlocked locks still appear
• Recently locked files not shown

Solution:

1. Click Refresh button in summary section
2. Wait for fresh query to complete
3. Verify cache age shows current time

Large Result Sets (3000+ Locks)

Performance:

• Table pagination handles large datasets efficiently
• Filters and search apply across all pages
• Sorting works across entire dataset

Best Practices:

• Use filters to narrow results before analyzing
• Focus on specific users or databases
• Look for patterns in lock distribution
• Identify high-frequency file locks

How It Works (Behind the Scenes)

Getting Lock Data

When you click “View Locks” from Client Operations:

1. System connects to the ACUCOBOL server on the EC2 instance
2. Queries the server for all active file locks
3. Returns the lock information to display in the table
4. Stores a copy in cache for faster access next time

First time (no cache): Takes about 10-15 seconds
Subsequent views (cached): Takes about 1-2 seconds

Why Caching Matters

The system caches lock data to make viewing faster:

• Fresh queries take longer (connecting to server, running commands)
• Cached data loads almost instantly
• Click “Refresh” button anytime to get current data

Cache age indicators help you know:

• Green/no warning: Data is recent (< 1 hour old)
• Orange warning: Data is getting old (> 1 hour)
• Red warning: Data is very old (> 24 hours) - should refresh

Unlock Operations

When you unlock locks:

1. System connects to the ACUCOBOL server
2. Sends command to release the locks (by Client ID or Process ID)
3. Server immediately removes the locks
4. User’s session may terminate (for client unlock)
5. Page automatically refreshes to show current state

This is why confirmation is strict - there’s no undo once you unlock!

Cross-Account Access

The system operates across multiple AWS accounts:

• Cloudscape Platform: Where you’re logged in
• Product Account: Where ERP Pro servers actually run

The system securely connects between accounts to retrieve lock data and perform unlock operations. This is managed automatically - you don’t need to think about it, but it explains why the initial query takes a few seconds.

Best Practices

Before Unlocking

1. Verify with User: Contact user if possible to confirm session is stuck
2. Check Application: Look at application logs for errors
3. Document: Note reason in support ticket or runbook
4. Least Privilege: Use Process ID unlock when possible (more targeted)

During Troubleshooting

1. Start with View: Always view locks first, don’t unlock blindly
2. Look for Patterns: Are multiple users affected? Same file?
3. Check Timing: When did locks start? Related to deployment?
4. Consider Impact: Will unlocking disrupt active work?

After Resolution

1. Verify: Refresh lock view to confirm unlock succeeded
2. Monitor: Watch for recurrence of same lock pattern
3. Communicate: Inform users that locks were cleared
4. Document: Update incident ticket with actions taken

Regular Maintenance

• Review lock patterns periodically
• Identify frequently locked files
• Consider application changes to reduce lock contention
• Train users on proper logout procedures
• Monitor for abnormal lock accumulation

Related Documentation

• Architecture Documentation - Technical deep dive (for developers)
• Client Operations - Accessing locks viewer

Support and Troubleshooting

Common Questions

Q: How long does lock data take to load?
A: First load (no cache): 10-13 seconds. Cached load: 1-2 seconds.

Q: Can I unlock multiple sessions at once?
A: No, unlock operations are one at a time for safety. Use filters to identify affected sessions.

Q: What happens to users when I unlock their session?
A: Their session terminates immediately. They’ll need to log back in. Any unsaved work is lost.

Q: Why don’t I see unlock actions?
A: You need the ERPPRO_LOCKS_UNLOCK permission. Contact administrators.

Q: Can I undo an unlock?
A: No, unlock operations are permanent. Locks must be re-established by users logging back in.

Getting Help

• Support Ticket: Open a ticket with TOC CloudOps team
• Include: Client name, instance ID, error messages, what you tried
• Urgent Issues: Contact on-call support for production-down scenarios

See Also

ERP Pro Features

• Client Manager Overview
• Client Operations
• Form Exchange

Related SEP Features

For School ERP Pro clients with update management needs:

• SEP Client Manager
• Client Updates
• Update Groups