C$CHDIR Routine

The C$CHDIR routine is used to change the current working directory.

Usage

CALL "C$CHDIR" USING DIR-NAME, ERR-NUM

Parameters

DIR-NAME PIC X(n)

Contains the name of the new directory, or spaces.

ERR-NUM (optional) PIC 9(9) COMP-4

Holds the returned error number, or zero on success.

Comments

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 MS-DOS, Windows, and Windows NT 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.

Note that on some systems (such as VMS), it is legal to switch to a directory that does not exist, while other machines (MS-DOS, UNIX) do not allow this.

Also Note: The behavior of this library routine is affected by the setting of the FILENAME-SPACES configuration variable. See the documentation in Appendix H, Configuration File Entries, for information about the terminating character for path names.

IMPORTANT

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.

Considerations for Workbench Users

When you import a screen with the Screen Import Utility, a file called "import.out" is created in the current working directory. The Screen Designer uses this file to load the description(s) of the imported screen(s) into its designer grid and property sheet.

When you invoke the Screen Import Utility from within the Workbench, the act of exiting the runtime also causes the Screen Designer to load the import.out file which is located in the root directory of the project currently open.

If your application changes the current working directory, the import.out file will not be created in the root directory of the currently open project, so different, perhaps unexpected behaviors can occur.

Import.out files will be generated correctly, and the Screen Designer will be able to import them correctly, but you will have to locate the files for the Screen Designer and open them "manually" using the File/Open dialog box in the Screen Designer.