Changes the current working directory.
Note: This ACUCOBOL-GT library routine is available in this COBOL version. Any compatibility issues in this COBOL system are in the Compatibility Issues section at the end of the topic.




DIR-NAME PIC X(n) Contains the name of the new directory, or spaces.

The "@[DISPLAY]:" for Thin Client support is allowed. For example:

C$CHDIR "@[DISPLAY]:C:\path"

In Thin Client environments, to get the current default directory on the display host, DIR_NAME should contain "@[DISPLAY]:" followed by spaces.

ERR-NUM PIC 9(9) COMP-4 (optional)    Holds the returned error number, or zero on success.


If a second USING parameter is passed, it must be described as PIC 9(9) COMP-4. This parameter will be set to ZERO if the directory change is successful. Otherwise, it will contain the operating system's error number.

If DIR-NAME contains spaces, then the current default directory is returned in it. In this case, ERR-NUM is not used. Otherwise, DIR-NAME should contain the name of a directory to make the new default directory. On Windows machines, this can include a drive letter. If you pass ERR-NUM, it will be set to zero if the change was successful. Otherwise, ERR-NUM will contain the error value returned by the operating system.

On some systems (such as VMS), it is legal to switch to a directory that does not exist, while other systems (Windows, UNIX) do not allow it.

The behavior of this routine is affected by the FILENAME_SPACES configuration variable. The value of FILENAME_SPACES determines whether spaces are allowed in a file name.


If you use C$CHDIR, create a CODE_PREFIX configuration entry to locate your object files. Ensure that all of the search locations specified by the CODE-PREFIX are full path names. Do not use the current directory or any relative path names in the CODE_PREFIX. Without a full path name, the runtime system may be unable to find your object files if it needs to re-open them.

For example, the runtime system must occasionally re-open an object file when:

  • you are using the source debugger
  • the program contains segmentation (overlays)
  • you are using object libraries

If the object file was initially found in the current directory or a directory specified relative to the current directory, and you then change the current directory with the C$CHDIR routine, the runtime system will not be able to find the object file if it needs to re-open it. This will cause a fatal error and your program will halt.

If you use C$CHDIR and you are running in debug mode, be sure to set CODE_PREFIX in the configuration file, not in the environment. You may set CODE_PREFIX in the environment when you are not in debug mode.

Compatibility Issues

  • In JVM COBOL, this routine is not supported.
  • "@[DISPLAY]" is not supported in this COBOL system.
  • The FILENAME_SPACES configuration variable is not supported in this COBOL system. To use filenames that contain spaces, enclose them in quotation marks.
  • The CODE_PREFIX configuration variable is not supported in this COBOL system.