## 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