CVPBYTES=, CVPENGINE=, and CVPMULTIPLIER= Options
Specifies attributes for character variables that
are needed in order to transcode a SAS file.
| Valid in: | LIBNAME statement |
| Category: | Data Access |
| PROC OPTIONS GROUP= | LIBNAME statement under Windows, UNIX, and Z/OS in the documentation for your operating environment. |
| See: | LIBNAME, |
Syntax
LIBNAME libref <CVPBYTES=bytes> <CVPENGINE=engine> <CVPMULTIPLIER=multiplier
> 'SAS data-library';
> 'SAS data-library';
Optional Arguments
- CVPBYTES=bytes
-
specifies the number of bytes by which to expand character variable lengths when processing a SAS data file that requires transcoding. The CVP engine expands the lengths so that character data truncation does not occur. The lengths for character variables are increased by adding the specified value to the current length. You can specify a value from 0 to 32766.For example, the following LIBNAME statement implicitly assigns the CVP engine by specifying the CVPBYTES= option.
libname expand 'SAS data-library' cvpbytes=5;Character variable lengths are increased by adding 5 bytes. A character variable with a length of 10 is increased to 15, and a character variable with a length of 100 is increased to 105.Default:If you specify CVPBYTES=, SAS automatically uses the CVP engine in order to expand the character variable lengths according to your specification. If you explicitly assign the CVP engine but do not specify either CVPBYTES= or CVPMULTIPLIER=, then SAS uses CVPMULTIPLIER=1.5 to increase the lengths of the character variables.Restrictions:The CVP engine supports SAS data files only; that is, no SAS views, catalogs, item stores, and so on.The CVP engine is available for input (read) processing only.
For library concatenation with mixed engines that include the CVP engine, only SAS data files are processed. For example, if you execute the COPY procedure, only SAS data files are copied.
Requirement:The number of bytes that you specify must be large enough to accommodate any expansion. Otherwise, truncation will still occur, which results in an error message in the SAS log.Interaction:You cannot specify both CVPBYTES= and CVPMULTIPLIER=. Specify one of these options.
- CVPENGINE=engine
-
specifies the engine to use in order to process a SAS data file that requires transcoding. The CVP engine expands the character variable lengths to transcoding so that character data truncation does not occur. Then the specified engine does the actual file processing.Alias:CVPENGDefault:SAS uses the default SAS engine.
- CVPMULTIPLIER=multiplier
-
specifies a multiplier value in order to expand character variable lengths when you are processing a SAS data file that requires transcoding. The CVP engine expands the lengths so that character data truncation does not occur. The lengths for character variables are increased by multiplying the current length by the specified value. You can specify a multiplier value from 1 to 5.For example, the following LIBNAME statement implicitly assigns the CVP engine by specifying the CVPMULTIPLIER= option.
libname expand 'SAS data-library' cvpmultiplier=2.5;Character variable lengths are increased by multiplying the lengths by 2.5. A character variable with a length of 10 is increased to 25, and a character variable with a length of 100 is increased to 250.Alias:CVPMULTDefault:If you specify CVPMULTIPLIER=, SAS automatically uses the CVP engine in order to expand the character variable lengths according to your specification. If you explicitly specify the CVP engine but do not specify either CVPMULTIPLIER= or CVPBYTES=, then SAS uses CVPMULTIPLIER=1.5 to increase the lengths.Restrictions:The CVP engine supports SAS data files only; that is, no SAS views, catalogs, item stores, and so on.The CVP engine is available for input (read) processing only.
For library concatenation with mixed engines that include the CVP engine, only SAS data files are processed. For example, if you execute the COPY procedure, only SAS data files are copied.
Requirement:The number of bytes that you specify must be large enough to accommodate any expansion. Otherwise, truncation will still occur, which results in an error in the SAS log.Interaction:You cannot specify both CVPMULTIPLIER= and CVPBYTES=. Specify one of these options.
Example: Using the CVP (Character Variable Padding) Engine
The following example
illustrates how to avoid character data truncation by using the CVP
engine. The example uses a SAS data set named MYFILES.WLATIN2, which
contains some national characters in Wlatin2 encoding.
libname myfiles 'C:\Documents and Settings\sasdxw\My Documents\myfiles'; data myfiles.wlatin2 (encoding=wlatin2); var1='41'x; var2='8a'x; var3='9c'x; var4='b3'x; ; proc print data=myfiles.wlatin2; run;
Here is PROC CONTENTS
output for MYFILES.WLATIN2, which shows that the encoding is Wlatin2
and that the length for each character variable is 1 byte:
PROC CONTENTS Output for MYFILES.WLATIN2
The SAS System 1
The CONTENTS Procedure
Data Set Name MYFILES.WLATIN2 Observations 1
Member Type DATA Variables 4
Engine V9 Indexes 0
Created Thursday, November 07, 2003 02:02:36 Observation Length 4
Last Modified Thursday, November 07, 2003 02:02:36 Deleted Observations 0
Protection Compressed NO
Data Set Type Sorted NO
Label
Data Representation WINDOWS_32
Encoding wlatin2 Central Europe (Windows)
Engine/Host Dependent Information
Data Set Page Size 4096
Number of Data Set Pages 1
First Data Page 1
Max Obs per Page 987
Obs in First Data Page 1
Number of Data Set Repairs 0
File Name C:\Documents and Settings\xxxxxx\My
Documents\myfiles\wlatin2.sas7bdat
Release Created 9.0100A0
Host Created XP_PRO
Alphabetic List of Variables and Attributes
# Variable Type Len
1 Var1 Char 1
2 Var2 Char 1
3 Var3 Char 1
4 Var4 Char 1The following code is
executed with the session encoding Wlatin2.
options msglevel=i;
libname myfiles 'SAS data-library';
data myfiles.utf8 (encoding="utf-8");
set myfiles.wlatin2;
run; The DATA step requests a new data set named MYFILES.UTF8,
and requests that the data be read into the new data set in UTF-8
encoding, which means that the data must be transcoded from Wlatin2
to UTF-8. The request results in errors due to character data truncation
that occurs from the transcoding. The new data set MYFILES.UTF8 is
created but does not contain any data. SAS Log with Transcoding Error
1 options msglevel=i; 2 libname myfiles 'C:\Documents and Settings\xxxxxx\My Documents\myfiles'; NOTE: Libref MYFILES was successfully assigned as follows: Engine: V9 Physical Name: C:\Documents and Settings\xxxxxx\My Documents\myfiles 3 data myfiles.utf8 (encoding="utf-8"); 4 set myfiles.wlatin2; 5 run; INFO: Data file MYFILES.UTF8.DATA is in a format native to another host or the file encoding does not match the session encoding. Cross Environment Data Access will be used, which may require additional CPU resources and reduce performance. ERROR: Some character data was lost during transcoding in the data set MYFILES.UTF8. NOTE: The data step has been abnormally terminated. NOTE: The SAS System stopped processing this step because of errors. NOTE: There were 1 observations read from the data set MYFILES.WLATIN2. WARNING: The data set MYFILES.UTF8 may be incomplete. When this step was stopped there were 0 observations and 4 variables.
The following code is
executed again with the session encoding Wlatin2.
options msglevel=i; libname myfiles 'SAS data-library'; libname expand cvp 'SAS data-library' cvpbytes=2; data myfiles.utf8 (encoding="utf-8"); set expand.wlatin2; run;
In this example, the
CVP engine is used to expand character variable lengths by adding
two bytes to each length. The data is read into the new file in UTF-8
encoding by transcoding from Wlatin2 to UTF-8. There is no data truncation
due to the expanded character variable lengths, and the new data set
is successfully created:
SAS Log Output for MYFILES.UTF8
12 options msglevel=i; 13 libname myfiles 'C:\Documents and Settings\xxxxxx\My Documents\myfiles'; NOTE: Directory for library MYFILES contains files of mixed engine types. NOTE: Libref MYFILES was successfully assigned as follows: Engine: V9 Physical Name: C:\Documents and Settings\xxxxxx\My Documents\myfiles 14 libname expand cvp 'C:\Documents and Settings\xxxxxx\My Documents\myfiles' cvpbytes=2; WARNING: Libname EXPAND refers to the same physical library as MYFILES. NOTE: Libref EXPAND was successfully assigned as follows: Engine: CVP Physical Name: C:\Documents and Settings\xxxxxx\My Documents\myfiles 15 data myfiles.utf8 (encoding="utf-8"); 16 set expand.wlatin2; 17 run; INFO: Data file MYFILES.UTF8.DATA is in a format native to another host or the file encoding does not match the session encoding. Cross Environment Data Access will be used, which may require additional CPU resources and reduce performance. NOTE: There were 1 observations read from the data set EXPAND.WLATIN2. NOTE: The data set MYFILES.UTF8 has 1 observations and 4 variables.
Finally, here is PROC
CONTENTS output for MYFILES.UTF8 showing that it is in UTF-8 encoding
and that the length of each character variable is 3:
PROC CONTENTS Output for MYFILES.UTF8
The SAS System 1
The CONTENTS Procedure
Data Set Name MYFILES.UTF8 Observations 1
Member Type DATA Variables 4
Engine V9 Indexes 0
Created Thursday, November 07, 2003 02:40:34 Observation Length 12
Last Modified Thursday, November 07, 2003 02:40:34 Deleted Observations 0
Protection Compressed NO
Data Set Type Sorted NO
Label
Data Representation WINDOWS_32
Encoding utf-8 Unicode (UTF-8)
Engine/Host Dependent Information
Data Set Page Size 4096
Number of Data Set Pages 1
First Data Page 1
Max Obs per Page 335
Obs in First Data Page 1
Number of Data Set Repairs 0
File Name C:\Documents and Settings\xxxxxx\My Documents\myfiles\utf8.sas7bdat
Release Created 9.0100A0
Host Created XP_PRO
Alphabetic List of Variables and Attributes
# Variable Type Len
1 Var1 Char 3
2 Var2 Char 3
3 Var3 Char 3
4 Var4 Char 3