Options for Commands, Statements, and Procedures for NLS

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 Z/0S
See Also:	LIBNAME, SAS/ACCESS

Syntax
Options
Example
	Using the CVP (Character Variable Padding) Engine

Syntax

LIBNAME libref <CVPBYTES=bytes> <CVPENGINE=engine> <CVPMULTIPLIER=multiplier> 'SAS data-library';

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.
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.
Restriction:	The CVP engine supports SAS data files only; that is, no SAS views, catalogs, item stores, and so on.
Restriction:	The CVP engine is available for input (read) processing only.
Limitation:	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.
Interaction:	You cannot specify both CVPBYTES= and CVPMULTIPLIER=. Specify one of these options.
Featured in:	Using the CVP (Character Variable Padding) Engine
See also:	Avoiding Character Data Truncation by Using the CVP Engine

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:	CVPENG
Default:	SAS uses the default SAS engine.
See also:	Avoiding Character Data Truncation by Using the CVP 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:	CVPMULT
Default:	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.
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.
Restriction:	The CVP engine supports SAS data files only; that is, no SAS views, catalogs, item stores, and so on.
Restriction:	The CVP engine is available for input (read) processing only.
Limitation:	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.
Interaction:	You cannot specify both CVPMULTIPLIER= and CVPBYTES=. Specify one of these options.
See also:	Avoiding Character Data Truncation by Using the CVP Engine

Example

Example 1: 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.

[untitled graphic]

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      1

The 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

Top of Page