Contents Developing Windows Clients  

FormatEnumerator Object

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

FormatEnumerator Full Description

Attributes

Factory Property
NumFormats Property
CurrentIndex Property

Methods

Close Method
GetFilter Method
GetInfo Method

Description

The EnumerateFormats method accepts a variety of filtering criteria and returns this object 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 property. The current index moves implicitly each time you call GetInfo to read information about a block of formats.



Readonly Property Factory

A link back to the FormatService

Type: FormatService

Description

A FormatService which created this object.

Example

Usage


Readonly Property NumFormats

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

Type: Long

Description

Example

Usage


Property CurrentIndex

Current read position in the enumeration.

Type: Long

Description

Default: The value is zero when the enumerator is first created.

Example

Usage


Method Close

Done with enumerator.

Description

Call this method when you are done using an enumerator to free up resources within the SAS System.

Usage

Parameters: None

Example

See Also


Method GetFilter

Examine the filters that were used to create the enumerator.

Description

Usage

Parameters

Name Direction Type Description
IFTypesFilter  out  IFType(index)  Shows whether filtering was done by formats versus informat. A zero-length array indicates no filtering on this distinction.  
matchOp  out  NameMatchOp  Shows the naming matching operation.  
nameFilterString  out  String  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  BaseType(index)  Shows whether filtering was done by numeric versus character. A zero-length array indicates no filtering on this distinction.  
implTypesFilter  out  ImplType(index)  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  String  If a keyword was used to filter enumerations, it is returned here. A zero-length string indicates no filtering.  
formattingMethodsFilter  out  FormattingMethod(index)  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

See Also

EnumerateFormats, CurrentIndex


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

Parameters

Name Direction Type Description
startIndex  in  Long  From 0 to the number of formats, or -1 to indicate starting at the current index.  
numToRead  in  Long  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 applicatins, 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 reamining formats should be obtained.

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

 

IFTypes  out  IFType(index)  Distinguishes format versus informat for each of the items returned.  
canonicalNames  out  String(index)  The name of each format or informat. Where a single format has aliases, this is the official name.  
baseTypes  out  BaseType(index)  Distinguishes numeric versus character for each of the items returned.  
minimumWidths  out  Long(index)  The minimum legal width (w) value for the format or informat.  
maximumWidths  out  Long(index)  The maximum legal width (w) value for the format or informat.  
defaultWidths  out  Long(index)  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  Long(index)  The minimum legal decimals (d) value for the format or informat.  
maximumDecimals  out  Long(index)  The maximum legal decimals (d) value for the format or informat.  
defaultDecimals  out  Long(index)  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  Long(index)   
implTypes  out  ImplType(index)  The implementation type (SAS installed versus PROC FORMAT) for each of the items returned.  
formattingMethods  out  FormattingMethod(index)  An indication of the suggested formatting or informatting method call to use with each item being retreived. Some formats/informats are binary and do not support any of the FormatService formatting methods. For others, the SAS System does not have enough information to know.  
correspondings  out  String(index)  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  String(index)  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  String(index)  A description written by the developer of the format or informat.  
examples  out  String(index)  Conversion examples written by the developer of the format or informat.  

Example

See Also

EnumerateFormats, CurrentIndex

Contents Developing Windows Clients