Object FileService

Developing Windows Clients

FileService Object

A service for manipulating files and filerefs in a SAS Workspace.

Attributes

Parent Property

Methods

ListFiles Method
DeleteFile Method
MakeDirectory Method
RenameFile Method
FullName Method
SplitName Method
ListFilerefs Method
AssignFileref Method
DeassignFileref Method
UseFileref Method

Enumerations

ListFilesMode Enumeration
AssignmentContext Enumeration
TypeCategory Enumeration
ListFilesIndex Enumeration
ListFilerefsIndex Enumeration

Description

This object provides access to the files and filerefs that are accessible to a SAS Workspace. Each workspace has a single file service, which can be found in its FileService property.

The FileService and the related Fileref, IFileInfo, BinaryStream and TextStream interfaces are implemented by the underlying Multi-Vendor Architecture of the SAS System so that the same interfaces can be supported on different host platforms. If you avoid host-specific assumptions in your code, you can write client applications that will operate correctly across different types of host filesystems.

While you can list and manage files and filerefs through this interface, you use the Fileref interface to read or write the data itself. Furthermore, there are no interfaces that manipulate physical files directly. In order to read from or write to a file, you must first create a fileref.

Users of the FileService should be familiar with SAS files and filerefs. Note that an "Access Method" and a "Device" are synonymous; the FileService uses the term "Access Method."

Readonly Property Parent

The workspace containing this file service.

Type: Workspace

Description

This property allows you to navigate back to the Workspace of this FileService object. All files and filerefs accessed through this service are those visible in the parent workspace.

Example

Usage

Method ListFiles

Lists all files in a directory.

Description

This method lists all files in the specified directory. It returns six output arrays. The ListFiles::fieldInclusionMask parameter indicates which of the individual output arrays are filled by the call. A filled output array contains one element for each file in the directory. Thus, all the filled output arrays are the same size and the complete information about a particular file in the directoy is available from the corresponding (same index) elements of each array. When an output array is not filled, it contains zero elements on return from the call.

The semantics of this method are based on the model of a hierarchical, directory-based filesystem as popularized by Unix and adopted by PC operating systems. For some host filesystems, notably mainframes, the native filesystems do not conform to this model. In these cases, the SAS System provides an emulation of a hierarchical, directory-based system.

For the SAS System under OS/390, this method has only experimental status. Its behaviour may change in future releases.

Usage

Parameters

Name Direction Type Description

path in String This parameter is used together with the ListFiles::mode parameter to determine which directory is listed.

mode in ListFilesMode One of the ListFilesMode enumeration values.

fieldInclusionMask in Boolean(index) This input parameter determines which of the six array output parameters are filled by the call. You must supply an array of either zero or six (ListFilesIndexNumIndices) elements.
The simplest approach is to supply a zero-element array for the mask. If you do this, then all of the output arrays will be filled.
You can make the call more efficient by indicating which output parameters need to be filled and which don't. The potential efficiency improvement is partly a result of reduced network traffic, but comes primarily from reducing the amount of work required on the server.
If you supply a six-element mask array, then each element indicates whether or not the corresponding output parameter will be filled by the call. The correspondence between mask array elements and output parameters is defined by the ListFilesIndex enumeration. If, for example, you don't need the file modification times, then you should set mask[ListFilesIndexModTimes] to false.

listedPath out String Returns the name of the directory selected by the ListFiles::path and ListFiles::mode.
Note that the returned value of this output parameter will only be the same directory as the ListFiles::path parameter when you to set ListFiles::mode to ListFilesModePath.

names out String(index) This array output parameter returns the names of all files and directories in the requested directory. These names are "short names" in that the full pathname is not provided. The names do include any extension (such as ".sas").
In order to create a full pathname, combine the returned ListFiles::listedPath parameter with an entry in this array using FullName.

typenames out String(index) Indicates the type of each file. It will be blank for subdirectories.
This should be used in conjunction with the following parameter (ListFiles::typeCategories).

typeCategories out TypeCategory(index) The elements of this array output parameter define the interpretation of the corresponding elements in the output array of type names. See TypeCategory for details.

sizes out Long(index) The number of bytes in each file or subdirectory.
Note that the meaning of this parameter is host-dependent and does not necessarily correspond to the size of the contents of the directory.

modtimes out Date(index) The last-modified time for each file or subdirectory, generally in terms of local time.
A particular local time value may be based on the time zone of the SAS IOM server, or it may be the local time of the computer that stored the timestamp. There is no way to determine whose local time is represented. Besides geography, time zone is also set by Daylight Savings Time changes. Thus, the same computer can read and write timestamps in different time zones in different parts of the year.
For some files on some hosts, it may be possible to retrieve a date, but not time-of-day. In some other cases, even the date may be unknown. For unknown dates, the SAS System base date of midnight, January 1 1960 will generally be returned.
Given the number of filesystems with which SAS Software interacts, the accuracy of this datetime may vary.

engines out String(index) Returns the SAS library engine associated with each SAS file in a SAS data library. If the file is not a member of a SAS data library, the engine value will be an empty string.

Name	Direction	Type	Description
path	in	String	This parameter is used together with the ListFiles::mode parameter to determine which directory is listed.
mode	in	ListFilesMode	One of the ListFilesMode enumeration values.
fieldInclusionMask	in	Boolean(index)	This input parameter determines which of the six array output parameters are filled by the call. You must supply an array of either zero or six (ListFilesIndexNumIndices) elements. The simplest approach is to supply a zero-element array for the mask. If you do this, then all of the output arrays will be filled. You can make the call more efficient by indicating which output parameters need to be filled and which don't. The potential efficiency improvement is partly a result of reduced network traffic, but comes primarily from reducing the amount of work required on the server. If you supply a six-element mask array, then each element indicates whether or not the corresponding output parameter will be filled by the call. The correspondence between mask array elements and output parameters is defined by the ListFilesIndex enumeration. If, for example, you don't need the file modification times, then you should set mask[ListFilesIndexModTimes] to false.
listedPath	out	String	Returns the name of the directory selected by the ListFiles::path and ListFiles::mode. Note that the returned value of this output parameter will only be the same directory as the ListFiles::path parameter when you to set ListFiles::mode to ListFilesModePath.
names	out	String(index)	This array output parameter returns the names of all files and directories in the requested directory. These names are "short names" in that the full pathname is not provided. The names do include any extension (such as ".sas"). In order to create a full pathname, combine the returned ListFiles::listedPath parameter with an entry in this array using FullName.
typenames	out	String(index)	Indicates the type of each file. It will be blank for subdirectories. This should be used in conjunction with the following parameter (ListFiles::typeCategories).
typeCategories	out	TypeCategory(index)	The elements of this array output parameter define the interpretation of the corresponding elements in the output array of type names. See TypeCategory for details.
sizes	out	Long(index)	The number of bytes in each file or subdirectory. Note that the meaning of this parameter is host-dependent and does not necessarily correspond to the size of the contents of the directory.
modtimes	out	Date(index)	The last-modified time for each file or subdirectory, generally in terms of local time. A particular local time value may be based on the time zone of the SAS IOM server, or it may be the local time of the computer that stored the timestamp. There is no way to determine whose local time is represented. Besides geography, time zone is also set by Daylight Savings Time changes. Thus, the same computer can read and write timestamps in different time zones in different parts of the year. For some files on some hosts, it may be possible to retrieve a date, but not time-of-day. In some other cases, even the date may be unknown. For unknown dates, the SAS System base date of midnight, January 1 1960 will generally be returned. Given the number of filesystems with which SAS Software interacts, the accuracy of this datetime may vary.
engines	out	String(index)	Returns the SAS library engine associated with each SAS file in a SAS data library. If the file is not a member of a SAS data library, the engine value will be an empty string.

Errors Returned

InvalidFieldMask

Example

Dim sizes() As Long
Dim typeCategories() As Long
Dim typenames() As String
Dim engines() As String
Dim modtimes() As Date
Dim fieldInclusionMask() As Boolean
obSAS.FileService.ListFiles path, mode, fieldInclusionMask, currentPath _
 , fileNames, typenames, typeCategories, sizes, modtimes, engines
for i=0 to ubound(names)-1
  debug.print files(i) & ":" & typenames(i) & ":" & str(typeCategories(i)) _
           & ":" & str(sizes(i)) &  format(modtimes(i)) & ":" & engines(i)
next

See Also

Method DeleteFile

Deletes a file or directory.

Description

Usage

Parameters

Name Direction Type Description

path in String If the file was located using ListFiles, then you should use FullName to form the path.

Name	Direction	Type	Description
path	in	String	If the file was located using ListFiles, then you should use FullName to form the path.

Example

See Also

Method MakeDirectory

Creates a new directory.

Description

This method creates a new directory. The call combines the input parameters to create the full pathname of the directory to be created and then returns that full path.

Note that not all access methods support the creation of a directory.

Usage

Parameters

Name Direction Type Description

parentDirectory in String The operating system-dependent full pathname of the directory that is to contain the new directory.

directoryName in String The name of the new directory.

Name	Direction	Type	Description
parentDirectory	in	String	The operating system-dependent full pathname of the directory that is to contain the new directory.
directoryName	in	String	The name of the new directory.

Returns String

Returns the full pathname of the newly created directory.

Example

dim newpath as string
' For a Unix server...
newpath = obSAS.FileService.MakeDirectory("/tmp", "MyNewDir")
debug.print newpath ' should be /tmp/MyNewDir

See Also

Method RenameFile

Renames an existing file or directory.

Description

This method renames an existing file or directory.

Usage

Parameters

Name Direction Type Description

oldPath in String The full pathname of the existing file or directory that is to be renamed. For best operation with servers on different operating systems, if the file was located using ListFiles, then you should use FullName to form the path.

newPath in String The full pathname of the new file or directory. For best operation with servers on different operating systems, if the new file name will be created by combining a "short name" with a directory located using ListFiles, then you should use FullName to form the path.

Name	Direction	Type	Description
oldPath	in	String	The full pathname of the existing file or directory that is to be renamed. For best operation with servers on different operating systems, if the file was located using ListFiles, then you should use FullName to form the path.
newPath	in	String	The full pathname of the new file or directory. For best operation with servers on different operating systems, if the new file name will be created by combining a "short name" with a directory located using ListFiles, then you should use FullName to form the path.

Example

obSAS.FileService.RenameFile "/tmp/oldName", "/tmp/newName"

See Also

Method FullName

Returns the full pathname given a file name and directory name.

Description

This method returns the full pathname given a file name and directory name. It accommodates the fact that not all host platforms and filesystems use the same syntax for indicating directory hierarchy relationships.

This method is typically called to create a full pathname from one of the names returned from ListFiles.

For the SAS System under OS/390, this method has only experimental status. Its behaviour may change in future releases.

Usage

Parameters

Name Direction Type Description

shortName in String The name of the file or directory that needs to be combined into a full pathname.

parentName in String A pathname of the directory to contain the shortName.

Name	Direction	Type	Description
shortName	in	String	The name of the file or directory that needs to be combined into a full pathname.
parentName	in	String	A pathname of the directory to contain the shortName.

Returns String

The full pathname with the parentName and shortName combined as appropriate for the host system.

Example

' Assumes Unix server
fullPathName = obFileService.FullName("aFile", "/tmp")
' fullPathName will be /tmp/aFile; this is a Unix example

See Also

Method SplitName

Breaks a pathname into a directory and member. Useful for creating a libname.

Description

Break a pathname into a directory and member.

For the SAS System under OS/390, this method has only experimental status. Its behaviour may change in future releases.

Usage

Parameters

Name Direction Type Description

path in String The operating system-dependent pathname that needs to be broken out into the containing directory and the contained file or subdirectory.

shortName out String The returned file or subdirectory that is specified by SplitName::path.

parentName out String The returned directory that contains SplitName::shortName.

Name	Direction	Type	Description
path	in	String	The operating system-dependent pathname that needs to be broken out into the containing directory and the contained file or subdirectory.
shortName	out	String	The returned file or subdirectory that is specified by SplitName::path.
parentName	out	String	The returned directory that contains SplitName::shortName.

Example

dim shortName as string
dim parentName as string
obSAS.FileService.SplitName "/tmp/aFile", shortName, parentName
' shortName will be aFile, parentName will be /tmp

See Also

Method ListFilerefs

Returns a list of all assigned filerefs on the current SAS Workspace.

Description

This method returns information about the assigned filerefs in the Workspace. It returns four output arrays. The ListFilerefs::fieldInclusionMask parameter indicates which of the individual output arrays are filled by the call. A filled output array contains one element for each fileref in the workspace. Thus, all the filled output arrays are the same size and the complete information about a particular fileref is available from the corresponding (same index) elements of each array. When an output array is not filled, it contains zero elements on return from the call.

In the case of a concatenated fileref, multiple entries for the same fileref will be returned, corresponding to each concatenated member.

Usage

Note that there is not enough information returned in this method to fully recreate the original fileref; the original options are not available.

Parameters

Name Direction Type Description

fieldInclusionMask in Boolean(index) This input parameter determines which of the four array output parameters are filled by the call. You must supply an array of either zero or four (ListFilerefsIndexNumIndices) elements.
The simplest approach is to supply a zero-element array for the mask. If you do this, then all of the output arrays will be filled.
You can make the call a little more efficient by indicating which output parameters need to be filled and which don't. If you supply a four-element mask array, then each element indicates whether or not the corresponding output parameter will be filled by the call. The correspondence between mask array elements and output parameters is defined by the ListFilerefsIndex enumeration. If, for example, you don't need the access method names, then you should set mask[ListFilerefsIndexAccessMethods] to false.

names out String(index) The name of each fileref assigned in the workspace.

assignmentContexts out AssignmentContext(index) This array output parameter indicates how each fileref was assigned. See AssignmentContext for details.
Do not rely on the naming scheme for temporary filerefs; these can change between hosts and between releases of the SAS System.

paths out String(index) Indicates the pathname associated with each fileref.

accessMethods out String(index) Indicates the accessMethod (also called device by some documentation) that was used when each fileref was created.

Name	Direction	Type	Description
fieldInclusionMask	in	Boolean(index)	This input parameter determines which of the four array output parameters are filled by the call. You must supply an array of either zero or four (ListFilerefsIndexNumIndices) elements. The simplest approach is to supply a zero-element array for the mask. If you do this, then all of the output arrays will be filled. You can make the call a little more efficient by indicating which output parameters need to be filled and which don't. If you supply a four-element mask array, then each element indicates whether or not the corresponding output parameter will be filled by the call. The correspondence between mask array elements and output parameters is defined by the ListFilerefsIndex enumeration. If, for example, you don't need the access method names, then you should set mask[ListFilerefsIndexAccessMethods] to false.
names	out	String(index)	The name of each fileref assigned in the workspace.
assignmentContexts	out	AssignmentContext(index)	This array output parameter indicates how each fileref was assigned. See AssignmentContext for details. Do not rely on the naming scheme for temporary filerefs; these can change between hosts and between releases of the SAS System.
paths	out	String(index)	Indicates the pathname associated with each fileref.
accessMethods	out	String(index)	Indicates the accessMethod (also called device by some documentation) that was used when each fileref was created.

Errors Returned

InvalidFieldMask

Example

Dim names() As String
Dim paths() As String
Dim accessMethods() As String
Dim fieldInclusionMask() As Boolean
Dim assignmentContexts() As Long
' Since we didn't set fieldInclusionMask, all 4 arrays are returned
obSAS.FileService.ListFilerefs fieldInclusionMask, names _
                               , assignmentContexts , paths, accessMethods

See Also

Method AssignFileref

Assign a SAS fileref.

Description

This method assigns a fileref in a manner analogous to the SAS language FILENAME statement. This call creates and returns a Fileref object to represent the new fileref.

Usage

Parameters

Name Direction Type Description

requestedName in String The name to use for this fileref.
This should be 8 or fewer characters. If you pass in an empty string, an access method value of "TEMP", then the call will create a temporary file.

accessMethodOrDevice in String Indicates the access method that will handle fileref.
You can use PROC NICKNAME to get a list of all access methods supported on your host. Different hosts support a different set of access methods.

externalFile in String The file or directory (or access method-specific string) with which to associate the fileref. Note that this can be a concatenated list of files using the same syntax as in the SAS language FILENAME statement.

hostOptions in String The options to use when creating the fileref. Most of these are specific to the host or access method.

assignedName out String Returns the assignedName. The assignedName will differ from the requested name when a temporary fileref is requested.

Name	Direction	Type	Description
requestedName	in	String	The name to use for this fileref. This should be 8 or fewer characters. If you pass in an empty string, an access method value of "TEMP", then the call will create a temporary file.
accessMethodOrDevice	in	String	Indicates the access method that will handle fileref. You can use PROC NICKNAME to get a list of all access methods supported on your host. Different hosts support a different set of access methods.
externalFile	in	String	The file or directory (or access method-specific string) with which to associate the fileref. Note that this can be a concatenated list of files using the same syntax as in the SAS language FILENAME statement.
hostOptions	in	String	The options to use when creating the fileref. Most of these are specific to the host or access method.
assignedName	out	String	Returns the assignedName. The assignedName will differ from the requested name when a temporary fileref is requested.

Returns Fileref

Returns a fileref object.

Example

' Create a temporary fileref
dim assignedName as string
Set obFileref = obSAS.FileService.AssignFileref("", "TEMP", "", "", assignedName)

See Also

Method DeassignFileref

Deassigns a fileref.

Description

This method deassigns the specified fileref. and destroys the associated fileref object. It is analogous to the FILENAME CLEAR statement in the SAS language.

Usage

Parameters

Name Direction Type Description

name in String The name of the fileref to deassign.

Name	Direction	Type	Description
name	in	String	The name of the fileref to deassign.

Example

See Also

Method UseFileref

Obtains the fileref object for the specified fileref name.

Description

This method locates and returns the Fileref object for a given fileref name.

Usage

You should you call this method when the fileref has already been assigned within the SAS Workspace and you are simply trying to retieve the Fileref object. If you need to perform the assignment first, call AssignFileref.

Parameters

Name Direction Type Description

name in String The name of the previously assigned fileref to obtain. An error will occur if the requested fileref has not been previously assigned.

Name	Direction	Type	Description
name	in	String	The name of the previously assigned fileref to obtain. An error will occur if the requested fileref has not been previously assigned.

Returns Fileref

Returns the requested fileref.

Example

See Also

Enum ListFilesMode

Indicates the type of directory list to be performed by the ListFiles method.

Description

This enumeration indicates the type of directory list to be performed by the ListFiles method. It determines whether or not the ListFiles::path parameter is used and how it is interpreted.

Usage

Member Description

ListFilesModeRoot The ListFiles method will list the host-specific system root directory. The ListFiles::path parameter is ignored.
ListFilesModeUser The ListFiles method will list the host-specific user home directory. The ListFiles::path parameter is ignored.
ListFilesModePath The ListFiles method will list the directory specified in the path parameter.
ListFilesModeParentOfPath The ListFiles method will list the directory that is the parent of the directory specified in path.

Member	Description
ListFilesModeRoot	The ListFiles method will list the host-specific system root directory. The ListFiles::path parameter is ignored.
ListFilesModeUser	The ListFiles method will list the host-specific user home directory. The ListFiles::path parameter is ignored.
ListFilesModePath	The ListFiles method will list the directory specified in the path parameter.
ListFilesModeParentOfPath	The ListFiles method will list the directory that is the parent of the directory specified in path.

Enum AssignmentContext

Indicates how a fileref assignment was made.

Description

This enumeration indicates how a fileref assignment was made.

Usage

Member Description

AssignmentContextRegular A user created the name and assignment. Filerefs created by the FILENAME statement are in this category, as are ones created by the AssignFileref method when you pass a non-empty AssignFileref::requestedName parameter.
AssignmentContextTemporary The fileref name was generated by the system; often as a result of a user action.
Since temporary filerefs are programming mechanisms, not user-chosen logical names, it often better to suppress them when presenting lists of filerefs back to a user.

AssignmentContextSystem The SAS System created this fileref through a host-specific mechanism such as a DD statement under OS/390 or an environment variable on Unix.

Member	Description
AssignmentContextRegular	A user created the name and assignment. Filerefs created by the FILENAME statement are in this category, as are ones created by the AssignFileref method when you pass a non-empty AssignFileref::requestedName parameter.
AssignmentContextTemporary	The fileref name was generated by the system; often as a result of a user action. Since temporary filerefs are programming mechanisms, not user-chosen logical names, it often better to suppress them when presenting lists of filerefs back to a user.
AssignmentContextSystem	The SAS System created this fileref through a host-specific mechanism such as a DD statement under OS/390 or an environment variable on Unix.

Enum TypeCategory

Describes how to interpret the type name that is returned by the ListFiles method.

Description

This enumeration describes how to interpret the type name that is returned by the ListFiles method.

Usage

Member Description

TypeCategoryDirectory The type name should be ignored; the filename is a directory.
TypeCategorySASType SAS has recognized the file as being of a well-known type. The type name is a standard file type name in the SAS System and is portable across hosts.
TypeCategoryExtension SAS has not recognized the file as being of one of its well-known types. The type name is the file name's extension or it is blank if the file name has no extension.

Member	Description
TypeCategoryDirectory	The type name should be ignored; the filename is a directory.
TypeCategorySASType	SAS has recognized the file as being of a well-known type. The type name is a standard file type name in the SAS System and is portable across hosts.
TypeCategoryExtension	SAS has not recognized the file as being of one of its well-known types. The type name is the file name's extension or it is blank if the file name has no extension.

Enum ListFilesIndex

Indices to the fieldInclusionMask array parameter of the ListFiles method.

Description

This enumeration defines indices to the ListFiles::fieldInclusionMask array parameter. When passed, this mask indicates whether or not each of the corresponding output parameters should be filled.

Usage

Member Description

ListFilesIndexNames The mask element which corresponds to the array of file names (ListFiles::names).
ListFilesIndexTypeNames The mask element which corresponds to the array of type names (ListFiles::typenames).
ListFilesIndexTypeCategories The mask element which corresponds to the array of type categories (ListFiles::typeCategories).
ListFilesIndexSizes The mask element which corresponds to the array of file sizes (ListFiles::sizes).
ListFilesIndexModTimes The mask element which corresponds to the array of last-modified times (ListFiles::modtimes).
ListFilesIndexEngines The mask element which corresponds to the array of engine names (ListFiles::engines).
ListFilesIndexNumIndices The number of elements in the field inclusion mask for the ListFiles method.

Member	Description
ListFilesIndexNames	The mask element which corresponds to the array of file names (ListFiles::names).
ListFilesIndexTypeNames	The mask element which corresponds to the array of type names (ListFiles::typenames).
ListFilesIndexTypeCategories	The mask element which corresponds to the array of type categories (ListFiles::typeCategories).
ListFilesIndexSizes	The mask element which corresponds to the array of file sizes (ListFiles::sizes).
ListFilesIndexModTimes	The mask element which corresponds to the array of last-modified times (ListFiles::modtimes).
ListFilesIndexEngines	The mask element which corresponds to the array of engine names (ListFiles::engines).
ListFilesIndexNumIndices	The number of elements in the field inclusion mask for the ListFiles method.

Enum ListFilerefsIndex

Indices to the fieldInclusionMask array parameter to the ListFileref method.

Description

This enumeration defines indices to the ListFilerefs::fieldInclusionMask array parameter. When passed, this mask indicates whether or not each of the corresponding output parameters should be filled.

Usage

Member Description

ListFilerefsIndexNames The mask element which corresponds to the array of fileref names (ListFilerefs::names).
ListFilerefsIndexAssignmentContexts The mask element which corresponds to the array of fileref assignment contexts (ListFilerefs::assignmentContexts).
ListFilerefsIndexPaths The mask element which corresponds to the array of fileref physical file paths (ListFilerefs::paths).
ListFilerefsIndexAccessMethods The mask element which corresponds to the array of fileref access method names (ListFilerefs::accessMethods).
ListFilerefsIndexNumIndices The number of elements in the field inclusion mask for the ListFilerefs method.

Member	Description
ListFilerefsIndexNames	The mask element which corresponds to the array of fileref names (ListFilerefs::names).
ListFilerefsIndexAssignmentContexts	The mask element which corresponds to the array of fileref assignment contexts (ListFilerefs::assignmentContexts).
ListFilerefsIndexPaths	The mask element which corresponds to the array of fileref physical file paths (ListFilerefs::paths).
ListFilerefsIndexAccessMethods	The mask element which corresponds to the array of fileref access method names (ListFilerefs::accessMethods).
ListFilerefsIndexNumIndices	The number of elements in the field inclusion mask for the ListFilerefs method.

Developing Windows Clients