Interface Fileref

CORBA Interface IFileref

Represents an assigned fileref in the associated SAS Workspace.

Definition

CORBA Module SAS

IFileref Description

This component represents a fileref that has been assigned in the SAS Workspace. The FileService maintains a list of Fileref components 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 component lives until the fileref is deassigned or the Workspace is closed.

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

CORBA Definitions

attribute Parent The FileService of the workspace containing this fileref.

attribute FilerefName The name of the fileref.

method OpenTextStream Creates a TextStream component for reading and writing the associated file.

method OpenBinaryStream Creates a BinaryStream component for reading and writing the associated file.

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

method ListMembers Returns all the members of a given fileref.

method AssignMember Creates a new fileref from a member of this fileref.

method DeleteFile Deletes the file or directory referenced by this fileref.

Java Classes

IFilerefHelper Used to manipulate the IFileref type

IFilerefHolder Used to process the IFileref type as an out parameter

Java Interfaces

IFileref Represents an assigned fileref in the associated SAS Workspace.

Java Interface IFileref

Represents an assigned fileref in the associated SAS Workspace.

Package com.sas.iom.SAS

IFileref Description
This component represents a fileref that has been assigned in the SAS Workspace. The FileService maintains a list of Fileref components 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 component lives until the fileref is deassigned or the Workspace is closed.

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

public interface IFileref extends org.omg.CORBA.Object

Method Summary

ITextStream OpenTextStream ( StreamOpenMode mode , int maxLineLength )
throws ( GenericError );

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

IBinaryStream OpenBinaryStream ( StreamOpenMode mode )
throws ( GenericError );

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

IBinaryStream OpenTranscodedBinaryStream ( StreamOpenMode mode , java.lang.String streamEncoding , java.lang.String callerEncoding )
throws ( GenericError );

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

void ListMembers ( boolean[] fieldInclusionMask , StringSeqHolder names , IntSeqHolder sizes , StringSeqHolder typenames , DateTimeSeqHolder modtimes )
throws ( GenericError );

Returns all the members of a given fileref.

IFileref AssignMember ( java.lang.String requestedName , java.lang.String memberName , java.lang.String accessMethodOrDevice , java.lang.String hostOptions , org.omg.CORBA.StringHolder assignedName )
throws ( GenericError );

Creates a new fileref from a member of this fileref.

void DeleteFile ()
Deletes the file or directory referenced by this fileref.

Java Class IFilerefHelper

public class IFilerefHelper

Description
Implementing class for methods (insert, extract, type, id, read, write, narrow) used to manipulate the IFileref type.

java.lang.Object
  |
  +--com.sas.iom.SAS.IFilerefHelper

Java Class IFilerefHolder

public class IFilerefHolder

Description
Implementing class for methods (_read, _write, _type) used to process the IFileref type as an out parameter.

java.lang.Object
  |
  +--com.sas.iom.SAS.IFilerefHolder

CORBA Attribute Parent (readonly)

The FileService of the workspace containing this fileref.

Description
The FileService of the SAS workspace containing this fileref.

Usage

Java Method Parent

public IFileService Parent ();

CORBA Attribute FilerefName (readonly)

The name of the fileref.

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.

Usage

Java Method FilerefName

public java.lang.String FilerefName ();

CORBA Method OpenTextStream

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

Description
Creates a TextStream component for reading and writing the associated file.

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

Usage

Java Method OpenTextStream

public ITextStreamOpenTextStream (

    StreamOpenMode mode ,
    int maxLineLength 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description

mode in StreamOpenMode Specifies whether the stream will allow reading, writing, or update.
maxLineLength in int The maximum 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 that the system is unable to handle, SAS will adjust it to a smaller value. However, even if the system can handle a very large number, it is possible that the limiting factor will be available system memory. In this case, an OutOfMemory exception will be thrown. The TruncationLength attribute of the created TextStream shows the value that was chosen.

Parameter	Direction	Type	Description
mode	in	StreamOpenMode	Specifies whether the stream will allow reading, writing, or update.
maxLineLength	in	int	The maximum 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 that the system is unable to handle, SAS will adjust it to a smaller value. However, even if the system can handle a very large number, it is possible that the limiting factor will be available system memory. In this case, an OutOfMemory exception will be thrown. The TruncationLength attribute of the created TextStream shows the value that was chosen.

Example

CORBA Method OpenBinaryStream

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

Description
Creates a BinaryStream component for reading and writing the associated file.

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

Usage

Java Method OpenBinaryStream

public IBinaryStreamOpenBinaryStream (

    StreamOpenMode mode 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description

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

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

Example

CORBA Method OpenTranscodedBinaryStream

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

Description
This operation 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 operation may be helpful.

Java Method OpenTranscodedBinaryStream

public IBinaryStreamOpenTranscodedBinaryStream (

    StreamOpenMode mode ,
    java.lang.String streamEncoding ,
    java.lang.String callerEncoding 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description

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

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

Example

CORBA Method ListMembers

Returns all the members of a given fileref.

Description
This operation 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 directory 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

Java Method ListMembers

voidListMembers (

    boolean[] fieldInclusionMask ,
    StringSeqHolder names ,
    IntSeqHolder sizes ,
    StringSeqHolder typenames ,
    DateTimeSeqHolder modtimes 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description

fieldInclusionMask in boolean[] 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 StringSeqHolder Returns the name of each member in this Fileref.
sizes out IntSeqHolder Returns the size in bytes of each member in this Fileref.
typenames out StringSeqHolder Returns the type of each member in this Fileref.
The returned type is a best guess by SAS. SAS 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 operation 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 DateTimeSeqHolder 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 base date of midnight, January 1 1960 will generally be returned.
Given the number of filesystems with which SAS interacts, the accuracy of this datetime may vary.

Parameter	Direction	Type	Description
fieldInclusionMask	in	boolean[]	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	StringSeqHolder	Returns the name of each member in this Fileref.
sizes	out	IntSeqHolder	Returns the size in bytes of each member in this Fileref.
typenames	out	StringSeqHolder	Returns the type of each member in this Fileref. The returned type is a best guess by SAS. SAS 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 operation 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	DateTimeSeqHolder	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 base date of midnight, January 1 1960 will generally be returned. Given the number of filesystems with which SAS interacts, the accuracy of this datetime may vary.

Example

CORBA 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

Java Method AssignMember

public IFilerefAssignMember (

    java.lang.String requestedName ,
    java.lang.String memberName ,
    java.lang.String accessMethodOrDevice ,
    java.lang.String hostOptions ,
    org.omg.CORBA.StringHolder assignedName 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description

requestedName in java.lang.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 java.lang.String The member of this Fileref that is to be assigned to the new Fileref.
accessMethodOrDevice in java.lang.String The access method to use. This will usually be the same as the access method of the target Fileref of this operation.
hostOptions in java.lang.String The options to use when creating the fileref.
assignedName out org.omg.CORBA.StringHolder Returns the fileref name that was actually assigned. This differs from the AssignMember::requestedName for temporary filerefs.

Parameter	Direction	Type	Description
requestedName	in	java.lang.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	java.lang.String	The member of this Fileref that is to be assigned to the new Fileref.
accessMethodOrDevice	in	java.lang.String	The access method to use. This will usually be the same as the access method of the target Fileref of this operation.
hostOptions	in	java.lang.String	The options to use when creating the fileref.
assignedName	out	org.omg.CORBA.StringHolder	Returns the fileref name that was actually assigned. This differs from the AssignMember::requestedName for temporary filerefs.

Example

CORBA Method DeleteFile

Deletes the file or directory referenced by this fileref.

Description

Usage

Java Method DeleteFile

voidDeleteFile ( )

Example

CORBA Definitions
attribute Parent	The FileService of the workspace containing this fileref.
attribute FilerefName	The name of the fileref.
method OpenTextStream	Creates a TextStream component for reading and writing the associated file.
method OpenBinaryStream	Creates a BinaryStream component for reading and writing the associated file.
method OpenTranscodedBinaryStream	Creates a BinaryStream for this fileref and transcodes data according using the specified encodings.
method ListMembers	Returns all the members of a given fileref.
method AssignMember	Creates a new fileref from a member of this fileref.
method DeleteFile	Deletes the file or directory referenced by this fileref.

Java Classes
IFilerefHelper	Used to manipulate the IFileref type
IFilerefHolder	Used to process the IFileref type as an out parameter

Java Interfaces
IFileref	Represents an assigned fileref in the associated SAS Workspace.

ITextStream	OpenTextStream ( StreamOpenMode mode , int maxLineLength ) throws ( GenericError ); Creates a TextStream component for reading and writing the associated file.
IBinaryStream	OpenBinaryStream ( StreamOpenMode mode ) throws ( GenericError ); Creates a BinaryStream component for reading and writing the associated file.
IBinaryStream	OpenTranscodedBinaryStream ( StreamOpenMode mode , java.lang.String streamEncoding , java.lang.String callerEncoding ) throws ( GenericError ); Creates a BinaryStream for this fileref and transcodes data according using the specified encodings.
void	ListMembers ( boolean[] fieldInclusionMask , StringSeqHolder names , IntSeqHolder sizes , StringSeqHolder typenames , DateTimeSeqHolder modtimes ) throws ( GenericError ); Returns all the members of a given fileref.
IFileref	AssignMember ( java.lang.String requestedName , java.lang.String memberName , java.lang.String accessMethodOrDevice , java.lang.String hostOptions , org.omg.CORBA.StringHolder assignedName ) throws ( GenericError ); Creates a new fileref from a member of this fileref.
void	DeleteFile () Deletes the file or directory referenced by this fileref.