Object FormatEnumerator

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.

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.

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

Developing Windows Clients