Contents Developing Windows Clients  

FormatService Object

A service that performs data conversion using SAS formats and informats.

FormatService Full Description

Attributes

Parent Property
SearchPath Property
YearCutoff Property

Methods

EnumerateFormats Method
Load Method
Unload Method
FormatNumericValues Method
FormatDateTimeValues Method
FormatCharacterValues Method
InformatNumericValues Method
InformatDateTimeValues Method
InformatCharacterValues Method

Exceptions

FormatServiceInvalidID Error
FormatServiceWrongType Error

Enumerations

IFType Enumeration
ImplType Enumeration
DTType Enumeration
FormattingMethod Enumeration
NameMatchOp Enumeration

Description

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.

Clients Unload formats when finished with them.

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

Type: Utilities

Description

Navigate back to Utilities.

Example

Usage


Property SearchPath

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

Type: String

Description

Default:

Example

Usage


Property YearCutoff

Year cutoff for determining the century of two-digit year values.

Type: Integer

Description

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.

Example

Usage


Method EnumerateFormats

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

Description

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.

Usage

Parameters

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.  

Returns FormatEnumerator

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.

Example

See Also

Close


Method Load

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

Description

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.

Usage

Parameters

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.  

Example

See Also

Unload, EnumerateFormats


Method Unload

Unload the indicated formats to free up server resources.

Description

Every loaded format should be unloaded.

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.

Usage

Parameters

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

Errors Returned

FormatServiceInvalidID

Example

See Also

Load


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.

Description

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.

Usage

Parameters

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.  

Errors Returned

FormatServiceInvalidID

FormatServiceWrongType

Example

See Also

Load, InformatNumericValues


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.

Description

Convert client datetime values to string form using SAS numeric formats.

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

Usage

Parameters

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.  

Errors Returned

FormatServiceInvalidID

FormatServiceWrongType

Example

See Also

Load, InformatDateTimeValues


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.

Description

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.

Usage

Parameters

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.  

Errors Returned

FormatServiceInvalidID

FormatServiceWrongType

Example

See Also

Load, InformatCharacterValues


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.

Description

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.

Usage

Parameters

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.  

Errors Returned

FormatServiceInvalidID

FormatServiceWrongType

Example

See Also

Load, FormatNumericValues


Method InformatDateTimeValues

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 datetime values.

Description

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.

Usage

Parameters

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.  

Errors Returned

FormatServiceInvalidID

FormatServiceWrongType

Example

See Also

Load, FormatDateTimeValues


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.

Description

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.

Usage

Parameters

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.  

Errors Returned

FormatServiceInvalidID

FormatServiceWrongType

Example

See Also

Load, FormatCharacterValues


Enum FormatServiceERRORS

FormatServiceInvalidID

Description

FormatServiceWrongType

Description


Enum IFType

Indicates format or informat.

Description

Usage

Member Description
IFTypeFormat   
IFTypeInformat   


Enum ImplType

The implementation of the format.

Description

Usage

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.

Description

Usage

Member Description
DTTypeDate   
DTTypeTime   
DTTypeDateTime   


Enum FormattingMethod

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

Description

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.

Usage

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

The way to use the name filtering string when enumerating formats.

Description

Usage

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.  

Contents Developing Windows Clients