Object FormatService

This object provides methods for enumerating the formats and informats that are available in a Workspace and for using those formats and informats to convert data.

The EnumerateFormats method lists formats and informats that are available in the Workspace. It provides numerous ways to filter the list, including by data type, by category (such as date or currency), and by name matching.

After the desired set of formats has been identified, you must load them via Load. This method returns format IDs that can then be used in the formatting calls.

There are three formatting and three informatting methods. Each supports a different data type: numeric, character, or datetime. These methods support the conversion of a two-dimensional array of data values in a single call. Numeric and datetime formatting handle SAS missing values. All of the methods provide detailed failure information for any individual conversion operation that fails.

The three formatting methods follow similar conventions in the use of their parameters. The input values should be presented in a two-dimensional array that represents tabular data (such as values from a SAS data set or from an SQL result set). The columns in this array represent a specifc field or variable. All items in a given column use the same format.

For numeric or datetime formatting, missing value indicators can also be specified for each data item using a separate two-dimensional array, or a zero-sized array can be used to accept the missing value indications that are transmitted within the floating point data itself.

The formats to be used for each column of data must have been loaded previously (see Load) and are indicated by an array of format IDs. Because an ID represents a format independent of the width and decimals (w.d), additional input arrays are available to specify them.

Because data formatting can sometimes fail, the formatting methods include four output array parameters whose elements describe each individual warning or error that occurred during formatting. These four output arrays are all the same length. Corresponding elements in each array refer to the same failure. If these arrays are zero length, then there were no errors or warnings.

The three informatting methods are analogous in their use of parameters, although the input arrays are always strings, whereas the output arrays are the conversion type (numeric, datetime or character string). For conversions to numeric or datetime, missing value indicators are returned.

Readonly Property Parent

Property SearchPath

Search path for formats or informats implemented by PROC FORMAT. This is the equivalent of the FMTSEARCH SAS system option.

Property YearCutoff

Year cutoff for determining the century of two-digit year values. This property controls the YEARCUTOFF SAS System option for the workspace. The option and this property are two equivalent ways to set this value.

If you are processing two-digit year values, it is important that you consider the implied range of years for your application and set this value accordingly.

Default: This is dependent on the version of the SAS System and is affected by any use of the YEARCUTOFF option when you invoke SAS.

Method EnumerateFormats

Given filtering criteria to search for formats and informats, returns an enumerator object which can list those that matched the filter.

This call returns an enumerator which lists formats and informats available to the Workspace. Numerous filtering criteria are available to locate subsets of interest.

When the filtering criteria are arrays, you can supply a zero length array to indicate that you do not want to filter (restrict items) based on that criterion. Otherwise, the array elements represent target values to return.

Selected formats or informats must match all criteria specified by parameters to this call. If a format or informat does not match even one of the criteria, then it will not be included in the enumerator.

Name	Direction	Type	Description
IFTypesFilter	in	IFType(index)	An array of IFType values. Specify a zero-length array to get both formats and informats. Specify a single-element array to obtain one or the other.
op	in	NameMatchOp	This parameter is a constant from the NameMatchOp enumeration. It controls the way the EnumerateFormats::nameFilterString parameter will be used. To avoid any name matching, specify NameMatchOpContains with an empty (zero-length) string for the EnumerateFormats::nameFilterString.
nameFilterString	in	String	A string used to match format and informat names according to the EnumerateFormats::op parameter.
baseTypesFilter	in	BaseType(index)	This parameter is an array of BaseType values, which is used to filter formats by data type. Specify a zero-length array to get both character and numeric formats. Specify a single-element array to obtain one or the other.
implTypesFilter	in	ImplType(index)	This parameter is an array of ImplType values, which is used to filter by implementation type. Specify a zero-length array to get both SAS installed and PROC FORMAT formats and informats. Specify a single-element array to obtain one or the other.
keyword	in	String	SAS installed formats 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 or informat can be labeled with more than one keyword.
formattingMethodsFilter	in	FormattingMethod(index)	An array of FormattingMethod values. Specify a zero-length array to avoid filtering on this criterion. Otherwise, specify an element that contains the appropriate enumeration value for each formatting method to select on. For some formats (such as user-written formats), the SAS System does not have enough information to know which formatting methods will work. In other cases, such as for formats like IB4, that process binary data, none of the formatting method calls can be used (those formats are not supported via this interface). For example, if you want to list only formats and informats that are known to work with the methods in this interface, then you would provide a three-elements array with the values: FormattingMethodNumeric, FormattingMethodCharacter, and FormattingMethodDateTime
numFound	out	Long	The number of formats selected.

A FormatEnumerator object that can list the selected formats and informats.

You must call Close to close this enumerator when you are finished with it.

Method Load

Load formats and informats to obtain IDs that can be used in other formatting calls.

Given two matching input arrays of IFType and name, attempt to load those formats or informats and return an ID array of the same length as the input arrays. Unsuccessful loads are indicated with an ID value of -1.

An array of failure messages is returned. There is one element for each failure (-1 value) in the IDs array.

The same name may be loaded more than once. The same ID will be returned each time for the same name. Names may be aliases and also return the same code. Formats should be unloaded subsequently by ID. If an ID is returned more than once by Load, it should be passed more than once to Unload.

You must specify the format names without w and d values. For example, "dollar" is correct, but "dollar8" and "dollar8.2" are not. The names may either be well known format and informat names from the SAS Language, or may be discovered through EnumerateFormats.

Name	Direction	Type	Description
IFTypes	in	IFType(index)	An array to distinguish whether the item to be loaded is a format or an informat.
names	in	String(index)	An array of names of formats and informats to be loaded.
IDs	out	Long(index)	An array of IDs returned by the load function.
failureMessages	out	String(index)	An array of messages explaining each load failure.

Method Unload

The same name may be loaded more than once. The same ID will be returned each time for the same name. Names may be aliases and also return the same code. Formats should be subsequently unloaded by code. If a code is returned more than once by Load, it should be passed more than once to Unload.

Name	Direction	Type	Description
IDs	in	Long(index)	An array of IDs that specify previously loaded formats that should now be unloaded.

FormatServiceInvalidID

Method FormatNumericValues

Given a list of specific formats, format a two-dimensional array of doubles that contains one column for each specified format and one row for each observation.

Convert double-precision floating-point values to string form using SAS numeric formats.

See FormatService Description for an explanation of conventions for the parameters of formatting methods.

Date and time formats may also be used with this method if the values are supplied as double-precision floating-point using the standard SAS encoding (seconds since midnight, January 1, 1960). The FormatServiceWrongType exception is raised only when a character format or any informat is provided.

Name	Direction	Type	Description
IDs	in	Long(index)	The IDs of the formats to be used for each column of data.
widths	in	Long(index)	The widths (w) to be used for each column of data. This is an array of the same size as the FormatNumericValues::IDs parameter. Passing -1 indicates that the format's default should be used. Passing a zero-length array requests that all columns use the default width.
decimals	in	Long(index)	The "decimals" (d) to be used for each column of data. This is an array of the same size as the FormatNumericValues::IDs parameter. Many formats do not use "decimals". For such formats, this parameter is ignored. Passing -1 indicates that the informat's default should be used. Passing a zero length array requests that all columns use the default decimals.
values	in	Double(row,col)	A two-dimensional array of input values to be formatted (converted to string).
missings	in	Byte(row,col)	The NumericMissingIgnore indicates that the numeric data value itself is used to determine whether the value is missing or not missing. Use this approach either when your data will not contain missing values, or when it does contain them, but you are confident that they will be preserved correctly in your client environment and over your middleware transports. Passing a zero-length array is equivalent to passing an array filled with NumericMissingIgnore indicators. If you want to supply missing values to the server, but your client programming environment or middleware transport configurations cannot be relied on to preserve them in the data, then you can use NumericMissingDot, NumericMissingUnderscore or a value in the range of the constants NumericMissingA through NumericMissingZ to indicate a missing value. When these are passed as values for elements in this array parameter, the corresponding value in the actual numeric data is ignored. When using missing value indicators to identify missing values, you use NotMissing or NumericMissingIgnore for data elements that you want to be recognized as non-missing. These two values have the same effect for non-missing data. If, however, you pass a missing value in conjunction with the NotMissing indicator, then the missing will be scrubbed by the server and the data item will be treated as a regular (non-missing) zero.
formattedValues	out	String(row,col)	A two-dimensional array that returns the strings created by the formatting process.
exceptionRowIndices	out	Long(index)	This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value had problems.
exceptionColumnIndices	out	Long(index)	The input column index for each formatting warning or error. This together with the row index will indicate which input value had problems.
exceptionIsError	out	Boolean(index)	A warning versus failure indicator for each formatting warning or error.
exceptionMessages	out	String(index)	A message describing each formatting warning or error.

FormatServiceInvalidID

FormatServiceWrongType

Method FormatDateTimeValues

Given a list of specific formats, format a two-dimensional array of datetime values that contains one column for each specified format and one row for each observation.

See FormatService Description for an explanation of conventions for the parameters of formatting methods.

Name	Direction	Type	Description
IDs	in	Long(index)	The IDs of the formats to be used for each column of data.
dateTimeTypes	in	DTType(index)	The input value is first converted to a SAS numeric value in datetime format (seconds since 12:00 a.m. January 1, 1960). For each column of data, the DTType is then considered. If the DTType is DTTypeDateTime, no further conversion is needed. If the DTType is DTTypeDate, the SAS datetime is converted into a SAS date value (number of days since January 1, 1960). Any excess hours and minutes are ignored (they are truncated, not rounded). Use of DTTypeTime with this call is discouraged because it requires an intermixing of client datetime encoding and SAS time-of-day conventions. When you use The SAS DTTypeTime, the input datetime is converted into a SAS time value (number of days since January 1, 1960) Any excess hours and minutes are ignored (they are truncated not rounded). Time-of-day value is computed as elapsed time since 12:00 a.m. January 1, 1960. Thus, for values less than 24 hours, you should generally specify (in the client's native datetime encoding) some time on the day of January 1, 1960. It is more consistent to use the FormatNumericValues in these cases because then both the datetime encoding and the time of day would use SAS conventions.
widths	in	Long(index)	The widths to be used for each column of data. This is an array of the same size as the FormatDateTimeValues::IDs parameter. Passing -1 indicates that the informat's default should be used. Passing a zero-length array requests that all columns use the default width.
decimals	in	Long(index)	The decimals (d) to be used for each column of data. This is an array of the same size as the FormatDateTimeValues::IDs parameter. Many formats do not use "decimals". For such formats, this parameter is ignored. Passing -1 indicates that the format's default should be used. Passing a zero-length array requests that all columns use the default width.
values	in	Date(row,col)	A two-dimensional array of input values to be formatted (converted to string).
missings	in	Byte(row,col)	A zero-sized array (either or both dimensions) indicates that missing values are indicated by the floating point data itself. See NumericMissingIgnore for a discussion of how missing value indicators can be used to specify missing values.
formattedValues	out	String(row,col)	A two-dimensional array that returns the strings created by the formatting process.
exceptionRowIndices	out	Long(index)	This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.
exceptionColumnIndices	out	Long(index)	The input column index for each formatting warning or error. This together with the row index will indicate which input value had problems.
exceptionIsError	out	Boolean(index)	A warning versus failure indicator for each formatting warning or error.
exceptionMessages	out	String(index)	A message that describes each formatting warning or error.

FormatServiceInvalidID

FormatServiceWrongType

Method FormatCharacterValues

Given a list of specific formats, format a two-dimensional array of strings that contains one column for each specified format and one row for each observation.

Convert raw character string values to formatted character string values using SAS character formats.

See FormatService Description for an explanation of conventions for the parameters of formatting methods.

Name	Direction	Type	Description
IDs	in	Long(index)	The IDs of the formats to be used for each column of data.
widths	in	Long(index)	The widths (w) to be used for each column of data. This is an array of the same size as the FormatCharacterValues::IDs parameter. Passing -1 indicates that the format's default should be used. Passing a zero-length array requests that all columns use the default width.
values	in	String(row,col)	A two-dimensional array of input values to be formatted (converted to string).
formattedValues	out	String(row,col)	A two-dimensional array that returns the strings created by the formatting process.
exceptionRowIndices	out	Long(index)	This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.
exceptionColumnIndices	out	Long(index)	This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.
exceptionIsError	out	Boolean(index)	A warning versus failure indicator for each formatting warning or error.
exceptionMessages	out	String(index)	A message that describes each formatting warning or error.

FormatServiceInvalidID

FormatServiceWrongType

Method InformatNumericValues

Given a list of specific informats, convert a two-dimensional array of strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array of doubles.

Convert character string values to double-precision floating-point (SAS numeric) values using SAS numeric informats.

See FormatService Description for an explanation of conventions for the parameters of informatting methods.

Name	Direction	Type	Description
IDs	in	Long(index)	The IDs of the informats to be used for each column of data.
widths	in	Long(index)	The widths (w) to be used for each column of data. This is an array of the same size as the InformatNumericValues::IDs parameter. Passing -1 indicates that the informat's default should be used. Passing a zero length array requests that all columns of data get the default width.
decimals	in	Long(index)	The decimals (d) to be used for each column of data. This is an array of the same size as the InformatNumericValues::IDs parameter. Many informats do not use "decimals". For such informats, this parameter is ignored. Passing -1 indicates that the informat's default should be used. Passing a zero length array requests that all columns of data get the default decimals.
inputValues	in	String(row,col)	A two-dimensional array of strings to be converted to floating point.
values	out	Double(row,col)	A two-dimensional array of output values from the informatting operation.
missings	out	Byte(row,col)	Some client programming environments do not give convenient access to missing value indicators within a numeric (floating point) data value. Some middleware environments might not translate SAS missing values properly in cross-architecture data translations. For these reasons, IOM calls that return numeric values typically return an extra missing value indication for each value. NotMissing indicates that the value is not missing. NumericMissingDot indicates the numeric (dot) missing. The underscore special missing is indicated by NumericMissingUnderscore. The A-Z special missings are indicated by values in the range between NumericMissingA and NumericMissingZ (inclusive).
exceptionRowIndices	out	Long(index)	This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.
exceptionColumnIndices	out	Long(index)	This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.
exceptionIsError	out	Boolean(index)	A warning versus failure indicator for each formatting warning or error.
exceptionMessages	out	String(index)	A message that describes each formatting warning or error.

FormatServiceInvalidID

FormatServiceWrongType

Method InformatDateTimeValues

Convert character string values to datetime values using SAS datetime informats.

See FormatService Description for an explanation of conventions for the parameters of informatting methods.

Name	Direction	Type	Description
IDs	in	Long(index)	The IDs of the informats to be used for each column of data.
dateTimeTypes	in	DTType(index)	A date, time or datetime informat produces a SAS numeric value. The interpretation of that value as a SAS date, SAS datetime, or SAS time, depends on the particular format being used. The client must specify which interpretation to expect of the informat (because this information is not, in general, defined to the SAS System). If the DTType is DTTypeDateTime or DTTypeDate, then the output value is converted to a datetime in the client's format. Use of the DTTypeTime with this call is discouraged because it requires an intermixing of client datetime encoding and SAS time-of-day conventions. When you use the SAS DTTypeTime, the SAS time is converted to a native datetime as an offset from January 1, 1960. Thus, for values less than 24 hours, the resultant datetime is some time on the day of January 1, 1960. In most client environments, time of day is not stored relative to January 1, 1960, therefore, it would be more consistent to use the InformatNumericValues in these cases because then both the datetime encoding and the time of day would use SAS conventions (seconds since 12:00 a.m. January 1, 1960).
widths	in	Long(index)	The widths (w) to be used for each column of data. This is an array of the same size as the InformatDateTimeValues::IDs parameter. Passing -1 indicates that the informat's default should be used. Passing a zero-length array requests that all columns use the default width.
inputValues	in	String(row,col)	A two-dimensional array of strings to be converted to datetime.
values	out	Date(row,col)	A two-dimensional array of output values from the informatting operation.
missings	out	Byte(row,col)	See NumericMissingIgnore for a discussion of how missing value indicators are returned.
exceptionRowIndices	out	Long(index)	This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.
exceptionColumnIndices	out	Long(index)	The input column index for each formatting warning or error. This together with the row index indicates which input value has problems.
exceptionIsError	out	Boolean(index)	A warning versus failure indicator for each formatting warning or error.
exceptionMessages	out	String(index)	A message describing each formatting warning or error.

FormatServiceInvalidID

FormatServiceWrongType

Method InformatCharacterValues

Given a list of specific informats, convert a two-dimensional array of formatted strings where there is one column for each specified informat and one row for each observation. The result is a a two-dimensional array of unformatted strings.

Convert formatted character string values to unformatted character string values using SAS character informats.

See FormatService Description for an explanation of conventions for the parameters of informatting methods.

Name	Direction	Type	Description
IDs	in	Long(index)	The IDs of the informats to be used for each column of data.
widths	in	Long(index)	The widths (w) to be used for each column of data. This is an array of the same size as the FormatCharacterValues::IDs parameter. Passing -1 indicates that the informat's default should be used. Passing a zero-length array requests that all columns use the default width.
inputValues	in	String(row,col)	A two-dimensional array of formatted strings to be converted to unformatted strings.
values	out	String(row,col)	A two-dimensional array of output values from the informatting operation.
exceptionRowIndices	out	Long(index)	This parameter gives the row index for each error or warning. This, together with the column index, indicates which input value has problems.
exceptionColumnIndices	out	Long(index)	The input column index for each formatting warning or error. This together with the row index indicates which input value has problems.
exceptionIsError	out	Boolean(index)	A warning versus failure indicator for each formatting warning or error.
exceptionMessages	out	String(index)	A message that describes each formatting warning or error.

FormatServiceInvalidID

FormatServiceWrongType

Enum FormatServiceERRORS

Enum IFType

Member	Description
IFTypeFormat
IFTypeInformat

Enum ImplType

Member	Description
ImplTypeSASInstalled	This format or informat is provided by the SAS System. This includes formats implemented in UWF load modules and informats implemented in UWI load modules.
ImplTypePROCFormat	This format or informat was created by PROC FORMAT.

Enum DTType

Used for controlling the handling of date and time values in a particular formatting operation.

Member	Description
DTTypeDate
DTTypeTime
DTTypeDateTime

Enum FormattingMethod

When known, the formatting or informatting method call that the format or informat is compatible with.

When known, the formatting or informatting method call that the format or informat is compatible with. When the method is <>, the user must know enough about the format to select the correct method. Only one of these values is associated with a given format or informat.

Member	Description
FormattingMethodNumeric	Identifies formats that work with FormatNumericValues and informats that work with InformatNumericValues.
FormattingMethodDateTime	Identifies formats that work with FormatDateTimeValues and informats that work with InformatDateTimeValues.
FormattingMethodCharacter	Identifies formats that work with FormatCharacterValues and informats that work with InformatCharacterValues.
FormattingMethodUnknown	The SAS System does not know enough about the format or informat to determine which formatting or informatting method you should use.
FormattingMethodNone	This format or informat processes binary data or data that is otherwise incompatible with any of the three formatting methods.

Enum NameMatchOp

Member	Description
NameMatchOpAll	The format or informat name must match the entire filter string.
NameMatchOpBeginning	The filter string must match the beginning of the format or informat name.
NameMatchOpBeginningDollarOptional	The filter string must match the beginning of the format or informat name, but the dollar sign that is used at the beginning of character formats or informats is excluded from the comparison. Do not pass a dollar sign in the matching string.
NameMatchOpContains	The filter string can be contained anywhere in the format or informat name.

FormatService Object