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 ITextStream OpenTextStream (

    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.  

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 IBinaryStream OpenBinaryStream (

    StreamOpenMode mode 
    )
    throws (
            GenericError
    );

Parameter Details

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 IBinaryStream OpenTranscodedBinaryStream (

    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.  

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

void ListMembers (

    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.  

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 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
    );

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.  

Example


CORBA Method DeleteFile

Deletes the file or directory referenced by this fileref.

Description

Usage

Java Method DeleteFile

void DeleteFile ( )

Example