Troubleshooting
To troubleshoot Sterling Connect:Direct® File Agent, check the following details to identify and resolve issues:
- Format Sterling Connect:Direct File Agent variables as described in z/OS® Process Arguments Example
- Set appropriate permissions for watched directories
- Specify valid Sterling Connect:Direct server parameters in the Sterling Connect:Direct File Agent configuration
- Check for inactivity from files arriving in watched directories before Sterling Connect:Direct File Agent starts
- Check that required Sterling Connect:Direct File Agent rules are enabled
- Confirm that the most specific rule is in first position
- Confirm that all Sterling Connect:Direct File Agent rules specify a Process to perform actions
- Correct syntax errors in Processes
Refer to the problems and solutions that follow to identify and resolve other issues that occur when you use Sterling Connect:Direct File Agent.
- Sterling Connect:Direct File Agent does not start and displays a Cannot run without a valid configuration message.
The configuration (.ser) file is missing. See A Default Configuration to create a configuration file.
- Unable to determine the version of Sterling Connect:Direct File Agent running on Microsoft Windows.
Click the Start Menu. Click Programs>Accessories>Command Prompt. At the MS-DOS prompt, use the cd command to change to the Sterling Connect:Direct File Agent installation directory. Type cdfa -v -cdefault_config.ser and press Enter. A message including the Sterling Connect:Direct File Agent version is displayed.
Arguments on entry:
Arguments listing complete
November 22,2010 :16:32 PM CDT 783 Thread[Thread-0,5,main] Product IBM® Sterling Connect:Direct File Agent Version 1.3.01 Copyright IBM Corp. 2003, 2010, GA fix 00000000 Date 2010/10/27
- Sterling Connect:Direct File Agent runs with the wrong configuration file.
Sterling Connect:Direct File Agent uses the following hierarchy when determining what configuration file to use:
- If you specify the cdfa command with the -c option, Sterling Connect:Direct File Agent uses the specified configuration file. For example, cdfa -cmonthend.ser starts Sterling Connect:Direct File Agent with the configuration file named monthend.ser.
- If you do not specify the -c option at startup, Sterling Connect:Direct File Agent looks
for a configuration file that matches the name of the computer it
is running on. For example, if Sterling Connect:Direct File Agent runs
on a computer named Host1, and a configuration file named Host1.ser
exists in the cdfa directory, Sterling Connect:Direct File Agent uses
the Host1 configuration file.
On a Microsoft Windows computer, you can determine the computer name by selecting Start<Settings>Control Panel>System and selecting the Network Identification tab.
On a UNIX or Linux® computer, see the operating system documentation to determine how to find the computer name.
- If you do not specify the -c option and no configuration file exists that matches the computer name, Sterling Connect:Direct File Agent uses the Default_Config configuration file.
- Sterling Connect:Direct File Agent starts, but no activity occurs.
- Type cdfa -v to start Sterling Connect:Direct File Agent in verbose mode to obtain more details.
- Verify with the Sterling Connect:Direct system administrator that the Sterling Connect:Direct server is active.
- Run the Sterling Connect:Direct File Agent Configuration Interface to check that you have specified watched directories in the Sterling Connect:Direct File Agent configuration.
- Check that no other application is accessing a file that Sterling Connect:Direct File Agent should detect. Sterling Connect:Direct File Agent cannot process files that are in use by other applications.
- Verify that the Sterling Connect:Direct File Agent is running with exclusive access to the specified gate keeper port number.
- The Sterling Connect:Direct system administrator should verify that the Sterling Connect:Direct server is properly configured for a connection with Sterling Connect:Direct File Agent. See the Installation Guide for your platform for information about configuring the Sterling Connect:Direct server for Sterling Connect:Direct File Agent.
- Sterling Connect:Direct File Agent compares the Compare String for a rule against the fully qualified path of the file found, not just against the file name
- Sterling Connect:Direct File Agent is
designed to compare the Compare String against the fully qualified
path of the file found, but if necessary, you can redefine your match
criteria to have it match against the file name, for example:
In UNIX, specify: '*/abc*' or '/my_watchdir/abc*' Microsoft Windows: '*\abc*' or 'C:\My_Watchdir\abc*'
This forces pattern matching at the file name level only.
- Sterling Connect:Direct File Agent is
designed to compare the Compare String against the fully qualified
path of the file found, but if necessary, you can redefine your match
criteria to have it match against the file name, for example:
- A rule should produce a match, but does not occur.
This could be caused by several conditions:
- Sterling Connect:Direct File Agent supports
multiple rules in a configuration. If more than one rule applies,
only the first rule encountered produces a match. When a match occurs,
rules processing ends.
The first rule should always contain the most specific criterion because rules are searched in the order listed on the Rules tab. If the first rule is too general, then it will always match and subsequent rules will never be processed.
- Match criteria are case-sensitive. For example, USER1 will not match User1 or user1.
- Verify that the match criteria and the rule are enabled.
- If the rule has multiple match criteria, all match criteria must match for the rule to apply.
- Sterling Connect:Direct File Agent supports
multiple rules in a configuration. If more than one rule applies,
only the first rule encountered produces a match. When a match occurs,
rules processing ends.
- Security properties not found, using default message is displayed when Sterling Connect:Direct File Agent starts.
This message is produced by the Java™ Virtual Machine (JVM), not Sterling Connect:Direct File Agent. It may be caused by having more than one JVM installed on your computer. It does not affect Sterling Connect:Direct File Agent operation and can be ignored.
- When monitoring a watched directory, Sterling Connect:Direct File Agent scans the subdirectories of the watched directory, although this is not required.
Edit the rule to use the Matches operator to force Sterling Connect:Direct File Agent to detect only the directory specified in the path and ignore the subdirectories. To prevent unpredictable operation, be sure to specify this rule first.
- Sterling Connect:Direct File Agent causes a parser error instead of operating as configured.
Early versions of Sterling Connect:Direct File Agent experienced parser errors when filenames or directory names specified in the configuration contained embedded spaces.
You can download Sterling Connect:Direct File Agent from the IBM Support Portal.
- On z/OS, SCBC085I is received during an attempt to resolve a symbolic in a Sterling Connect:Direct File Agent rule.
This error occurs when a symbolic is enclosed in double quotes in the Sterling Connect:Direct File Agent rule. To remove the double quotes from the symbolic, run the Sterling Connect:Direct File Agent Configuration Interface and access the Sterling Connect:Direct File Agent rules fields as described in Editing a Rule .
- On z/OS, Sterling Connect:Direct File Agent scans GDG files that are managed by SMS, and causes two destination files to be written for one source file.
You will need to apply software fixes to resolve this problem. For V4R4, apply fix T035471 (PUT4402). For V4R5, apply fix T035648 (PUT4501).
- Sterling Connect:Direct File Agent is detecting files and submitting a Process, but no other action occurs.
Sterling Connect:Direct File Agent works with the Sterling Connect:Direct Processes you create, but this Sterling Connect:Direct component performs no actions other than detecting files in a specified location and submitting the specified Process. The actions you need to perform in response to file detection are performed by your Sterling Connect:Direct Processes. Refer to IBM Sterling Connect:Direct Process Lanuage Web site at http://www.sterlingcommerce.com/Documentation/processes/processhome.html.
- After restarting Sterling Connect:Direct File Agent, files in the watched directory are not processed, even though processing was interrupted before it was completed.
Sterling Connect:Direct File Agent detects a file in a watched directory only one time. If processing is interrupted, files must be removed and replaced with a new timestamp, or in the case of UNIX systems, you can use the touch command to alter the timestamp so that Sterling Connect:Direct File Agent will detect the files.
- Some files moved into the watched directory are not processed according to the Sterling Connect:Direct File Agent configuration, although other files are processed as expected.
Confirm that no other application is accessing the files that Sterling Connect:Direct File Agent should detect in the watched directory.
Test the files in the watched directory for file corruption.
Determine whether a synchronization problem is occurring because files are copied into the watched directory before Sterling Connect:Direct File Agent starts. For Sterling Connect:Direct File Agent to detect files in a watched directory, files must be transferred into the watched directory after Sterling Connect:Direct File Agent starts. Sterling Connect:Direct File Agent starts and assumes that any files already in watched directories were sent previously and should not be detected as a change in the watched directory.
To determine whether synchronization of the agent and the transfer of the files in question is the issue:
Stop Sterling Connect:Direct File Agent and remove all files from the monitored directory (or directories).
Start Sterling Connect:Direct File Agent from the command prompt. (For example, in Microsoft Windows, from the \Program Files\Sterling Connect:Direct File Agent directory, type: cdfa -v > cdfa.log to turn on verbose logging and send the output to a file.)
Place the files that were not processed according to the configuration into the monitored directory (or directories) and let Sterling Connect:Direct File Agent run for a few minutes.
Check to see if Sterling Connect:Direct File Agent processed the files according to the configuration and check the logging details output to the file.
If the files that were not processed according to the configuration are now processed, the issue was caused by certain files being copied into the watched directory before Sterling Connect:Direct File Agent started monitoring.
- Sterling Connect:Direct File Agent is detecting files, but Sterling Connect:Direct File Agent is not submitting the Process that it should submit after detecting a file.
Check the user identification and password information. The user ID and password used to Submit the Process must be the same as the user ID and password used when Sterling Connect:Direct File Agent connected to the Sterling Connect:Direct server.
- After disabling a rule in the configuration, Sterling Connect:Direct File Agent is still processing files as if the rule is enabled.
You must restart Sterling Connect:Direct File Agent before it can recognize that the rule has been disabled.
- Spaces in the graphical interface display as boxes when Sterling Connect:Direct File Agent runs in an X Microsoft Windows emulator.
This is due to X Microsoft Windows configuration and behavior. Contact the X Microsoft Windows emulator vendor for a solution.
- Receive the following error during a z/OS batch configuration job:Can't connect to X11 window server using 'hostname:0.0' as the value of the DISPLAY variable.
Please make sure that your setup environment variable DISPLAY correctly or issue xhost command on X server to include this host. Then restart the configurator.
Verify that the Alias provide in the DISPLAY is accessible to both the Sterling Connect:Direct File Agent mainframe and PC platforms. Use NSLOOKUP command on the mainframe or Microsoft Windows PC and Sterling Connect:Direct IUI NM gethostname function on the mainframe to look up the alias name.
- Receive the following error during a z/OS batch configuration job:Can't connect to X11 window server using 'hostname:0.0' as the value of the DISPLAY variable.
Please make sure that your setup environment variable DISPLAY correctly or issue xhost command on X server to include this host. Then restart the configurator.
Verify the following:
- Mainframe to PC connection is passing through Firewall. Exceed uses ports 6000 - 6063. These ports must be allowed to come through the firewall.
- Exceed is allowing the Mainframe host access because of Exceed Security setting. Use Exceed Xconfig utility to set Security to allow DISPLAY host access or allow all hosts access.