Windows APIs - GetFolderPath

This API returns the the location of various directories on all versions of Windows. Certain directories, such as "My Documents", do not reside on the hard disk in the locations shown by Windows Explorer, and the actual location may also vary depending on who is logged on in. This API will return the actual location of many such directories in a form useable by COBOL.

The Microsoft recommended location for storing data specific to applications is to locate these in a subdirectory called "Application Data". (Although this may not be the best solution in all cases).

The actual location of this folder varies depending on the version of Windows you are running, and in the case of multi-user platforms such as Windows 2000, XP, and NT, it also varies depending on WHO is logged on. Finding this directory can be difficult.

This API returns the proper location for these special directories regardless of which platform you are using, freeing you of the task of trying to locate it yourself or resorting to an arbitrary directory on the disk.

Client/Server issues

Files

Usage

Parameters specific to this function

GFP-DIRECTORY-NAME

GFP-TYPE-OF-DIRECTORY

This field is set by selecting one of the 88's to specify the directory desired. See the list below.

SPECIAL NOTE: Some directories are referred to as "Virtual Directories". These do not in fact exist. Example: "GFP-MYDOCUMENTS" refers to a virtual directory which appears as "My Documents" in windows explorer, but it appears in the explorer tree view at the same level as the "C:" drive, (it does not appear subordinate to C:) which would lead one to believe that it exists somewhere other than on the local hard drive. You and I know that can not be possible, and Explorer is telling a white lie to the user.

Virtual directories are not useful for COBOL, because you can not open a file there. Therefore, in the following list, those directories that are marked VIRTUAL may not actually return a value (depending on the platform in use). Most Virtual directories are cross referenced with the FILE SYSTEM directory that should be used instead. So to find the file system location of "My Documents" you would use the GFP-PERSONAL 88.

88 Name	Meaning
GFP-ADMINTOOLS	Version 5.0. The file system directory that is used to store administrative tools for an individual user. The Microsoft Management Console (MMC) will save customized consoles to this directory, and it will roam with the user.
GFP-ALTSTARTUP	The file system directory that corresponds to the users nonlocalized Startup program group.
GFP-APPDATA	Version 4.71. The file system directory that serves as a common repository for application-specific data. A typical path is C:\Documents and Settings\username\ Application Data.
GFP-BITBUCKET	The VIRTUAL folder containing the objects in the users Recycle Bin.
GFP-CDBURN-AREA	Version 6.0. The file system directory acting as a staging area for files waiting to be written to CD. A typical path is C:\Documents and Settings\ username\Local Settings\Application Data\Microsoft\CD Burning.
GFP-COMMON-ADMINTOOLS	Version 5.0. The file system directory containing administrative tools for all users of the computer.
GFP-COMMON-ALTSTARTUP	The file system directory that corresponds to the nonlocalized Startup program group for all users. Valid only for Microsoft Windows NT systems.
GFP-COMMON-APPDATA	Version 5.0. The file system directory containing application data for all users. A typical path is C:\Documents and Settings\All Users\Application Data.
GFP-COMMON-DESKTOPDIRECTORY	The file system directory that contains files and folders that appear on the desktop for all users. A typical path is C:\Documents and Settings\All Users\Desktop. Valid only for Windows NT.
GFP-COMMON-DOCUMENTS	The file system directory that contains documents that are common to all users. A typical paths is C:\Documents and Settings\All Users\Documents. Valid for Windows NT systems and Windows 95 and Windows 98 systems with Shfolder.dll installed.
GFP-COMMON-FAVORITES	The file system directory that serves as a common repository for favorite items common to all users. Valid only for Windows NT systems.
GFP-COMMON-MUSIC	Version 6.0. The file system directory that serves as a repository for music files common to all users. A typical path is C:\Documents and Settings\All Users\Documents\My Music.
GFP-COMMON-PICTURES	Version 6.0. The file system directory that serves as a repository for image files common to all users. A typical path is C:\Documents and Settings\All Users\Documents\My Pictures.
GFP-COMMON-PROGRAMS	The file system directory that contains the directories for the common program groups that appear on the Start menu for all users. A typical path is C:\Documents and Settings\All Users\Start Menu\Programs. Valid only for Windows NT systems.
GFP-COMMON-STARTMENU	The file system directory that contains the programs and folders that appear on the Start menu for all users. A typical path is C:\Documents and Settings\All Users\Start Menu. Valid only for Windows NT systems.
GFP-COMMON-STARTUP	The file system directory that contains the programs that appear in the Startup folder for all users. A typical path is C:\Documents and Settings\All Users\Start Menu\Programs\Startup. Valid only for NT.
GFP-COMMON-TEMPLATES	The file system directory that contains the templates that are available to all users. A typical path is C:\Documents and Settings\All Users\Templates. Valid only for Windows NT systems.
GFP-COMMON-VIDEO	Version 6.0. The file system directory that serves as a repository for video files common to all users. A typical path is C:\Documents and Settings\All Users\Documents\My Videos.
GFP-CONTROLS	The VIRTUAL folder containing icons for the Control Panel applications.
GFP-COOKIES	The file system directory that serves as a common repository for Internet cookies. A typical path is C:\Documents and Settings\username\Cookies.
GFP-DESKTOP	The VIRTUAL folder representing the Windows desktop, the root of the namespace. Use GFP-DESKTOPDIRECTORY for cobol.
GFP-DESKTOPDIRECTORY	The file system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself). A typical path is C:\Documents and Settings\username\Desktop.
GFP-DRIVES	The VIRTUAL folder representing My Computer, containing everything on the local computer: storage devices, printers and Control Panel. The folder may also contain mapped network drives.
GFP-FAVORITES	The file system directory that serves as a common repository for the users favorite items. A typical path is C:\Documents and Settings\username\Favorites.
GFP-FONTS	A VIRTUAL folder containing fonts. A typical path is C:\Windows\Fonts.
GFP-HISTORY	The file system directory that serves as a common repository for Internet history items. (URLs).
GFP-INTERNET	A VIRTUAL folder representing the Internet.
GFP-INTERNET-CACHE	Version 4.72. The file system directory that serves as a common repository for temporary Internet files. A typical path is C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
GFP-LOCAL-APPDATA	Version 5.0. The file system directory that serves as a data repository for local (nonroaming) applications. A typical path is C:\Documents and Settings\username\Local Settings\Application Data. You probably want GFP-APPDATA instead of this for most uses.
GFP-MYDOCUMENTS	Version 6.0. The VIRTUAL folder representing the My Documents desktop item. May NOT be directly useable by Cobol for file operations. Use GFP-PERSONAL instead.
GFP-MYMUSIC	The file system directory that serves as a common repository for music files. A typical path is C:\Documents and Settings\User\My Documents\My Music.
GFP-MYPICTURES	Version 5.0. The file system directory that serves as a common repository for image files. A typical path is C:\Documents and Settings\username\My Documents\My Pictures.
GFP-MYVIDEO	Version 6.0. The file system directory that serves as a common repository for video files. A typical path is C:\Documents and Settings\username\My Documents\My Videos.
GFP-NETHOOD	A file system directory containing the link objects that may exist in the My Network Places virtual folder. It is not the same as GFD-NETWORK, which represents the network namespace root. A typical path is C:\Documents and Settings\username\NetHood.
GFP-NETWORK	A VIRTUAL folder representing Network Neighborhood, the root of the network namespace hierarchy. Use GFP-NETHOOD instead.
GFP-PERSONAL	Version 6.0. The VIRTUAL folder representing the My Documents desktop item. This is equivalent to GFP-MYDOCUMENTS . Previous to Version 6.0: The file system directory used to physically store a users common repository of documents. A typical path is C:\Documents and Settings\username \My Documents.
GFP-PRINTERS	The VIRTUAL folder containing installed printers. Use GFP-PRINTHOOD instead.
GFP-PRINTHOOD	The file system directory that contains the link objects that can exist in the Printers virtual folder. A typical path is C:\Documents and Settings\username\PrintHood.
GFP-PROFILE	Version 5.0. The users profile folder. Typical path is C:\Documents and Settings\username. Applications should not create files or folders at this level; they should put their data under the locations referred to by GFD-APPDATA or GFD-LOCAL-APPDATA.
GFP-PROFILES	Version 6.0. The file system directory containing user profile folders. A typical path is C:\Documents and Settings.
GFP-PROGRAM-FILES	Version 5.0. The Program Files folder. A typical path is C:\Program Files.
GFP-PROGRAM-FILES-COMMON	Version 5.0. A folder for components that are shared across applications. A typical path is C:\Program Files\Common. Valid only for Windows NT, Windows 2000, and Windows XP systems. Not valid for Windows Me.
GFP-PROGRAMS	The file system directory that contains the users program groups (which are themselves file system directories). A typical path is C:\Documents and Settings\username\Start Menu\Programs.
GFP-RECENT	The file system directory that contains shortcuts to the users most recently used documents. A typical path is C:\Documents and Settings\username\My Recent Documents.
GFP-SENDTO	The file system directory that contains Send To menu items. A typical path is C:\Documents and Settings\username\SendTo.
GFP-STARTMENU	The file system directory containing Start menu items. A typical path is C:\Documents and Settings\username\Start Menu.
GFP-STARTUP	The file system directory that corresponds to the users Startup program group. The system starts these programs whenever any user logs onto Windows NT or starts Windows 95. A typical path is C:\Documents and Settings\ username\Start Menu\Programs\Startup.
GFP-SYSTEM	Version 5.0. The Windows System folder .A typical path is C:\Windows\System32.
GFP-TEMPLATES	The file system directory that serves as a common repository for document templates. A typical path is C:\Documents and Settings\username\Templates.
GFP-WINDOWS	Version 5.0. The Windows directory or SYSROOT. This corresponds to the %windir% or %SYSTEMROOT% environment variables. A typical path is C:\Windows.

WIN32API-PARMS - Used in all GSWINAPI calls

This argument is standard for all CALLs to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.

WIN32API-RC

Used to return the status of a call to GSWINAPI. A value of zero is a failure, any other value indicates success.

SPECIAL NOTE: If WIN32API-RC = 2, the requested directory was valid for this platform, and the default location was returned, but that directory did not in fact exist (may have been deleted).

Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.

WIN32API-ERROR-CODE

Error code that was returned by Windows. This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

WIN32API-C through WIN32API-F

The number of these present varies depending on how many arguments are used by the desired function. These are not used, but must be present because this CALL requires seven arguments.