CORBA Interface IFormatEnumerator

Provide information about a client-selected list of formats and informats.

Definition

CORBA Module SAS

IFormatEnumerator Description

The EnumerateFormats operation accepts a variety of filtering criteria and returns this component to represent the list of formats and informats which were selected.

The enumerator lets you move, in blocks (for better performance) through the returned list to get information about the formats. As you move through the list, it remembers you position.

When initially returned, it is at index 0 in the list. You can move it explicitly by changing the CurrentIndex attribute. The current index moves implicitly each time you call GetInfo to read information about a block of formats.

CORBA Definitions
 attribute Factory  A link back to the FormatService
 method Close  Done with enumerator.
 method GetFilter  Examine the filters that were used to create the enumerator.
 attribute NumFormats  Number of formats being enumerated. (The number found after filtering.)
 attribute CurrentIndex  Current read position in the enumeration.
 method GetInfo  Read info on formats associated with the enumerator.

Java Classes
 IFormatEnumeratorHelper  Used to manipulate the IFormatEnumerator type
 IFormatEnumeratorHolder  Used to process the IFormatEnumerator type as an out parameter

Java Interfaces
 IFormatEnumerator  Provide information about a client-selected list of formats and informats.

Java Interface IFormatEnumerator

Provide information about a client-selected list of formats and informats.

Package com.sas.iom.SAS

IFormatEnumerator Description
The EnumerateFormats operation accepts a variety of filtering criteria and returns this component to represent the list of formats and informats which were selected.

The enumerator lets you move, in blocks (for better performance) through the returned list to get information about the formats. As you move through the list, it remembers you position.

When initially returned, it is at index 0 in the list. You can move it explicitly by changing the CurrentIndex attribute. The current index moves implicitly each time you call GetInfo to read information about a block of formats.

public interface IFormatEnumerator
extends org.omg.CORBA.Object

Method Summary

 void Close ()

Done with enumerator.

 void GetFilter ( IFTypeSeqHolder IFTypesFilter , NameMatchOpHolder matchOp , org.omg.CORBA.StringHolder nameFilterString , BaseTypeSeqHolder baseTypesFilter , ImplTypeSeqHolder implTypesFilter , org.omg.CORBA.StringHolder keywordsFilter , FormattingMethodSeqHolder formattingMethodsFilter )
throws ( GenericError );

Examine the filters that were used to create the enumerator.

 void GetInfo ( int startIndex , int numToRead , IFTypeSeqHolder IFTypes , StringSeqHolder canonicalNames , BaseTypeSeqHolder baseTypes , IntSeqHolder minimumWidths , IntSeqHolder maximumWidths , IntSeqHolder defaultWidths , IntSeqHolder minimumDecimals , IntSeqHolder maximumDecimals , IntSeqHolder defaultDecimals , IntSeqHolder justifications , ImplTypeSeqHolder implTypes , FormattingMethodSeqHolder formattingMethods , StringSeqHolder correspondings , StringSeqHolder keywords , StringSeqHolder descriptions , StringSeqHolder examples )
throws ( GenericError );

Read info on formats associated with the enumerator.

Java Class IFormatEnumeratorHelper

public class IFormatEnumeratorHelper

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

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

Java Class IFormatEnumeratorHolder

public class IFormatEnumeratorHolder

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

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

CORBA Attribute Factory (readonly)

A link back to the FormatService

Description
A FormatService which created this component.

Usage

Java Method Factory 

public IFormatService Factory ();

CORBA Method Close

Done with enumerator.

Description
Call this operation when you are done using an enumerator to free up resources within SAS.

Usage

Java Method Close

void Close ( )

Example

CORBA Method GetFilter

Examine the filters that were used to create the enumerator.

Description

Usage

Java Method GetFilter

void GetFilter ( 

    IFTypeSeqHolder IFTypesFilter ,
    NameMatchOpHolder matchOp ,
    org.omg.CORBA.StringHolder nameFilterString ,
    BaseTypeSeqHolder baseTypesFilter ,
    ImplTypeSeqHolder implTypesFilter ,
    org.omg.CORBA.StringHolder keywordsFilter ,
    FormattingMethodSeqHolder formattingMethodsFilter 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description
IFTypesFilter  out  IFTypeSeqHolder  Shows whether filtering was done by formats versus informat. A zero-length array indicates no filtering on this distinction.  
matchOp  out  NameMatchOpHolder  Shows the naming matching operation.  
nameFilterString  out  org.omg.CORBA.StringHolder  The filtering string used to restrict the list according to name. If the string is empty (zero length) and the GetFilter::matchOp is NameMatchOpContains, then no name restriction was used.  
baseTypesFilter  out  BaseTypeSeqHolder  Shows whether filtering was done by numeric versus character. A zero-length array indicates no filtering on this distinction.  
implTypesFilter  out  ImplTypeSeqHolder  Shows whether filtering was done by implementation type (SAS installed versus PROC FORMAT). A zero-length array indicates no filtering on this distinction.  
keywordsFilter  out  org.omg.CORBA.StringHolder  If a keyword was used to filter enumerations, it is returned here. A zero-length string indicates no filtering.  
formattingMethodsFilter  out  FormattingMethodSeqHolder  Shows whether filtering was done according to what formatting method call the formats/informats support. A zero-length array indicates no filtering on this distinction.  

Example

CORBA Attribute NumFormats (readonly)

Number of formats being enumerated. (The number found after filtering.)

Description

Usage

Java Method NumFormats 

public int NumFormats ();

CORBA Attribute CurrentIndex

Current read position in the enumeration.

Description

Usage

Java Method CurrentIndex 

public int CurrentIndex ();
public void CurrentIndex ( int CurrentIndex );

CORBA Method GetInfo

Read info on formats associated with the enumerator.

Description
Get a variety of information about each format in the enumeration.

Some of the information is available only for well-known formats supplied by SAS Institute. Formats and informats created using PROC FORMAT or SAS/Toolkit do not yet have as much descriptive information available.

Usage

Java Method GetInfo

void GetInfo ( 

    int startIndex ,
    int numToRead ,
    IFTypeSeqHolder IFTypes ,
    StringSeqHolder canonicalNames ,
    BaseTypeSeqHolder baseTypes ,
    IntSeqHolder minimumWidths ,
    IntSeqHolder maximumWidths ,
    IntSeqHolder defaultWidths ,
    IntSeqHolder minimumDecimals ,
    IntSeqHolder maximumDecimals ,
    IntSeqHolder defaultDecimals ,
    IntSeqHolder justifications ,
    ImplTypeSeqHolder implTypes ,
    FormattingMethodSeqHolder formattingMethods ,
    StringSeqHolder correspondings ,
    StringSeqHolder keywords ,
    StringSeqHolder descriptions ,
    StringSeqHolder examples 
    )
    throws (
            GenericError
    );

Parameter Details

Parameter Direction Type Description
startIndex  in  int  From 0 to the number of formats, or -1 to indicate starting at the current index.  
numToRead  in  int  For maximum scalability, to handle the possibility of many thousands of formats in an enumerator, you can limit the number of formats read by each method call. For interactive applications, the number of formats that would be listed in user's current window would be a logical choice.

The remaining arrays will be the requested length unless the end of the list is reached first.

Where such performance factors are not a major concern, a value of -1 can be passed to indicate that all remaining formats should be obtained.

After reading, the current index (CurrentIndex) of the enumerator is updated to point to the next item.

 
IFTypes  out  IFTypeSeqHolder  Distinguishes format versus informat for each of the items returned.  
canonicalNames  out  StringSeqHolder  The name of each format or informat. Where a single format has aliases, this is the official name.  
baseTypes  out  BaseTypeSeqHolder  Distinguishes numeric versus character for each of the items returned.  
minimumWidths  out  IntSeqHolder  The minimum legal width (w) value for the format or informat.  
maximumWidths  out  IntSeqHolder  The maximum legal width (w) value for the format or informat.  
defaultWidths  out  IntSeqHolder  The width (w) value used when none is specified.

When a format has not yet been loaded, SAS may not be able to determine the default width efficiently. In this case, a -1 will be returned for these fields. If this information is needed, load the format and enumerate it again.  
minimumDecimals  out  IntSeqHolder  The minimum legal decimals (d) value for the format or informat.  
maximumDecimals  out  IntSeqHolder  The maximum legal decimals (d) value for the format or informat.  
defaultDecimals  out  IntSeqHolder  The decimals (d) value used when none is specified.

When a format has not yet been loaded, SAS may not be able to determine the default width efficiently. In this case, a -1 will be returned for these fields. If this information is needed, load the format and enumerate it again.  
justifications  out  IntSeqHolder   
implTypes  out  ImplTypeSeqHolder  The implementation type (SAS installed versus PROC FORMAT) for each of the items returned.  
formattingMethods  out  FormattingMethodSeqHolder  An indication of the suggested formatting or informatting method call to use with each item being retrieved. Some formats/informats are binary and do not support any of the FormatService formatting methods. For others, SAS does not have enough information to know.  
correspondings  out  StringSeqHolder  For informats, the "corresponding" format is the one most able to create a character string similar to the original input. Often, this will not be the same as the original input. Removal of extra blanks or changes in field justification are examples of common changes. For formats, the "corresponding" informat would be the one most able to approximate the original data value. Because of the difficulties in representing floating point numbers in different forms, the value will often be slightly different from the original. In all cases, there is no guarantee of round-trip conversion or exactness in the results.

For many formats and informats, there is no corresponding format/informat (or if there is one, it is not known). This is indicated by an empty string.  
keywords  out  StringSeqHolder  Lists all keywords with which this format/informat has been labelled.

SAS installed formats and informats can have descriptive keywords to help categorize their intended function. These keywords provide more specific categorizations than the numeric versus character distinction known to the SAS Language. The following keywords have already been standardized: 

   "num" - numbers
   "curr" - currency
   "char" - character
   "date" - date without time-of-day specificity
   "datetime" - both date and time
   "time" - time of day (without indication of any particular day)
Additional keywords may be added in the future. A single format/informat can potentially be labelled with more than one keyword.  
descriptions  out  StringSeqHolder  A description written by the developer of the format or informat.  
examples  out  StringSeqHolder  Conversion examples written by the developer of the format or informat.  

Example