Object Fileref

Developing Windows Clients

Fileref Object

Represents an assigned fileref in the associated SAS Workspace.

Attributes

Parent Property
FilerefName Property

Methods

OpenTextStream Method
OpenBinaryStream Method
OpenTranscodedBinaryStream Method
ListMembers Method
AssignMember Method
DeleteFile Method

Description

This object represents a fileref that has been assigned in the SAS Workspace. The FileService maintains a list of Fileref objects for every fileref in the workspace regardless of how the fileref was assigned. This includes filerefs assigned by invoking AssignFileref and those assigned by submitting the SAS language FILENAME statement.

This object lives until the fileref is deassigned or the Workspace is closed.

Note that this object also supports the IFileInfo interface, which provides information about the physical file associated with this fileref.

Readonly Property Parent

The FileService of the workspace containing this fileref.

Type: FileService

Description

The FileService of the SAS workspace containing this fileref.

Example

Usage

Readonly Property FilerefName

The name of the fileref.

Type: String

Description

The name of the fileref.

If the fileref was created by AssignFileref, then this name matches the one that was returned by that call. If the fileref was created by a SAS language FILENAME statement, then this is the name supplied on that statement.

Example

Usage

Method OpenTextStream

Creates a TextStream object for reading and writing the associated file.

Description

Creates a TextStream object for reading and writing the associated file.

There can be multiple stream objects that are reading from the same fileref, but only one stream component can be writing to it.

Usage

Parameters

Name Direction Type Description

mode in StreamOpenMode Specifies whether the stream will allow reading, writing, or update.

maxLineLength in Long The maxium length of any line that will be in the file. This determines where truncation begins. You can set this to a larger value than is actually used. If you pass a very large number, the SAS system will adjust it to a smaller value. The TruncationLength property of the created TextStream shows the value that was chosen.

Name	Direction	Type	Description
mode	in	StreamOpenMode	Specifies whether the stream will allow reading, writing, or update.
maxLineLength	in	Long	The maxium length of any line that will be in the file. This determines where truncation begins. You can set this to a larger value than is actually used. If you pass a very large number, the SAS system will adjust it to a smaller value. The TruncationLength property of the created TextStream shows the value that was chosen.

Returns TextStream

The newly created TextStream object.

Example

See Also

Method OpenBinaryStream

Creates a BinaryStream object for reading and writing the associated file.

Description

Creates a BinaryStream object for reading and writing the associated file.

There can be multiple stream objects that are reading from the same fileref, but only one stream component can be writing to it.

Usage

Parameters

Name Direction Type Description

mode in StreamOpenMode Specifies whether the stream will allow reading, writing, or update.

Name	Direction	Type	Description
mode	in	StreamOpenMode	Specifies whether the stream will allow reading, writing, or update.

Returns BinaryStream

The newly created BinaryStream object.

Example

See Also

Method OpenTranscodedBinaryStream

Creates a BinaryStream for this fileref and transcodes data according using the specified encodings.

Description

This method creates a BinaryStream for this fileref and transcodes data according to the specified encodings.

Usage

This is designed for use with HTML pages, where the encoding of the page is specified in the page itself and may not match the system encoding that will be used in a TextStream transfer. In most such cases you can use OpenBinaryStream because no additional transcoding will be needed. In some cases, however, particularly when transferring between mainframes and ASCII-based systems, the custom transcoding provided by this method may be helpful.

Parameters

Name Direction Type Description

mode in StreamOpenMode Specifies whether the stream will allow reading, writing, or update.

streamEncoding in String The encoding of the data as it exists in the stream, before reading or after writing.

callerEncoding in String Encoding of the data desired by the caller in a read operation, or supplied by the caller in a write operation.

Name	Direction	Type	Description
mode	in	StreamOpenMode	Specifies whether the stream will allow reading, writing, or update.
streamEncoding	in	String	The encoding of the data as it exists in the stream, before reading or after writing.
callerEncoding	in	String	Encoding of the data desired by the caller in a read operation, or supplied by the caller in a write operation.

Returns BinaryStream

Returns the newly create BinaryStream component.

Example

See Also

Method ListMembers

Returns all the members of a given fileref.

Description

This method returns information about all the members of a given fileref (if any). For example, a fileref to a directory would have one member for each file in the directory.

The ListMembers::fieldInclusionMask parameter indicates which of the individual output arrays are filled by the call. A filled output array contains one element for each member of the fileref. Thus, all the filled output arrays are the same size and the complete information about a directoy member 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.

Usage

Parameters

Name Direction Type Description

fieldInclusionMask in Boolean(index) This input parameter determines which of the four following output parameters are filled by the call. You must supply an array of either zero or four 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 somewhat more efficient by indicating which output parameters need to be filled and which don't. If you supply a four-element array, then each element indicates whether or not the corresponding output parameter will be filled by the call. Mask elements 0 through 3 correspond to the parameters "names", "sizes", "typenames" and "modtimes" in that order. Setting an element true indicates that the corresponding array should be filled.

names out String(index) Returns the name of each member in this Fileref.

sizes out Long(index) Returns the size in bytes of each member in this Fileref.

typenames out String(index) Returns the type of each member in this Fileref.
The returned type is a best guess by the SAS System. The SAS System will return a few standard file types (such as "LOG", "LISTING" and "SAS") based on the host-specific file extension and other information. When the member does not appear to be one of these standard types, then the actual file extension will generally be returned. ListFiles is another method that can return the types of files. It is often more useful because it also identifies SAS data library file types and their engines and because it returns an indicator of whether the returned type is a standard type or is simply the filename's extension.

modtimes out Date(index) The last-modified time for each member of the fileref, 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.

Name	Direction	Type	Description
fieldInclusionMask	in	Boolean(index)	This input parameter determines which of the four following output parameters are filled by the call. You must supply an array of either zero or four 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 somewhat more efficient by indicating which output parameters need to be filled and which don't. If you supply a four-element array, then each element indicates whether or not the corresponding output parameter will be filled by the call. Mask elements 0 through 3 correspond to the parameters "names", "sizes", "typenames" and "modtimes" in that order. Setting an element true indicates that the corresponding array should be filled.
names	out	String(index)	Returns the name of each member in this Fileref.
sizes	out	Long(index)	Returns the size in bytes of each member in this Fileref.
typenames	out	String(index)	Returns the type of each member in this Fileref. The returned type is a best guess by the SAS System. The SAS System will return a few standard file types (such as "LOG", "LISTING" and "SAS") based on the host-specific file extension and other information. When the member does not appear to be one of these standard types, then the actual file extension will generally be returned. ListFiles is another method that can return the types of files. It is often more useful because it also identifies SAS data library file types and their engines and because it returns an indicator of whether the returned type is a standard type or is simply the filename's extension.
modtimes	out	Date(index)	The last-modified time for each member of the fileref, 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.

Example

See Also

Method AssignMember

Creates a new fileref from a member of this fileref.

Description

Creates a new fileref from a member of this fileref.

If AssignMember::memberName is empty, a new fileref that is the same as this fileref is created.

Usage

Parameters

Name Direction Type Description

requestedName in String The name to use for the fileref. This name can also be used in the SAS Language. If RequestedName is blank, a unique fileref name is generated.

memberName in String The member of this Fileref that is to be assigned to the new Fileref.

accessMethodOrDevice in String The access method to use. This will usually be the same as the access method of the target Fileref of this method.

hostOptions in String The options to use when creating the fileref.

assignedName out String Returns the fileref name that was actually assigned. This differs from the AssignMember::requestedName for temporary filerefs.

Name	Direction	Type	Description
requestedName	in	String	The name to use for the fileref. This name can also be used in the SAS Language. If RequestedName is blank, a unique fileref name is generated.
memberName	in	String	The member of this Fileref that is to be assigned to the new Fileref.
accessMethodOrDevice	in	String	The access method to use. This will usually be the same as the access method of the target Fileref of this method.
hostOptions	in	String	The options to use when creating the fileref.
assignedName	out	String	Returns the fileref name that was actually assigned. This differs from the AssignMember::requestedName for temporary filerefs.

Returns Fileref

Returns the newly created Fileref component.

Example

See Also

Method DeleteFile

Deletes the file or directory referenced by this fileref.

Description

Usage

Parameters: None

Example

See Also

Developing Windows Clients