GUI ScreenIO for Windows

 ScreenIO.com


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.

 

Multi User Platform note: (2K/XP/NT) If your application uses different files for each user, you would choose APPDATA as the directory, which resolves to the user's specific Application Data directory.  If all users use the same data, you would use the COMMON-APPDATA directory which resolves to the "All Users\Application Data" directory.  On Win9x platforms APPDATA resolves to the same place regardless of who is logged in, because Win9x platforms are not multi-user.

Client/Server issues

This API will return the directory location on the client.

To obtain the directory of the server:

     SET WIN32API-EXECUTE-API-ON-SERVER TO TRUE

Files

Files available to copy to your system: (Click the links below)

Usage

     COPY WIN32API.
     COPY GWINDIR.



*           : Set the type of directory you are
*           : looking for... (see list below)
     SET GFP-PERSONAL TO TRUE
*
* ------------------------: Call the API to get the directory.
*
     SET API-GETFOLDERPATH TO TRUE.
     CALL 'GSWINAPI' USING WIN32API-PARMS
     GFP-DIRECTORY-NAME
     GFP-TYPE-OF-DIRECTORY
     WIN32API-C
     WIN32API-D
     WIN32API-E
     WIN32API-F.
     

Parameters specific to this function

GFP-DIRECTORY-NAME

Buffer that will receive the pathspec of the selected directory.  1024 bytes.

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.

Note: Version 6 items are only guaranteed to exist in WinXP.

 

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.

* ------------------------: If function failed,
*                         :   display the error in a message box.
*
     IF WIN32API-FAILED
       MOVE WIN32API-ERROR-TEXT TO panel-MESSAGE-TEXT
       SET panel-MESSAGE-IN-MESSAGEBOX TO TRUE.

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

Plain-text error message that describes why the operation failed.

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.


2000-2006 Norcom, all rights reserved 

TOC

Send feedback to Norcom