The SASEBLS Interface Engine

The LIBNAME libref SASEBLS Statement

LIBNAME libref SASEBLS 'physical-name' options;

The LIBNAME statement assigns a SAS library reference (libref) to the physical path of the directory where the SASEBLS interface engine stores the BLS economic data. The required physical-name argument specifies the final location of the folder where your BLS data reside in a SAS data set that is named in the OUT= option. The physical-name should end with a backslash (for example, C:\physical_name\) when you are in a Windows environment or a forward slash (for example, /user/physical_name/) when you are in a UNIX environment.

You can specify the following options:

ANNUALAVERAGE=TRUE | FALSE

specifies whether or not to retrieve the annual average observations in addition to the specified frequency.

TRUE: retrieves the annual average observations in addition to the specified frequency. For annual data, the A02 observations are selected in addition to the A01 observations. For semiannual data, the S03 observations are selected in addition to the S01 and S02 observations. For quarterly data, the Q05 observations are selected in addition to the Q01–Q04 observations. For monthly frequency, the M13 observations are selected in addition to the M01–M12 observations.
FALSE: specifies that the annual data keep only the A01 observations, the semiannual data keep only the S01 and S02 observations, the quarterly data keep only the Q01–Q04 observations, and the monthly data keep only the M01–M12 observations.

By default, ANNUALAVERAGE=FALSE. See Example 20.2 for an example of ANNUALAVERAGE=TRUE. Because Example 20.1 does not specify the ANNUALAVERAGE= option, it defaults to FALSE, so the M13 frequency is omitted from the output, and only the monthly (M01-M12) observations are returned.

ASPECTS=TRUE | FALSE

specifies whether or not to retrieve the aspects data that are associated with a given data point for a specified BLS series ID. For each observation, the associated aspects data consist of one or more name-value pairs of variables along with footnotes. When ASPECTS=true and an aspect data file exists for the requested time series, the SASEBLS engine creates an auxiliary data set containing the aspects data. This auxiliary data set is named using the same name specified in the OUTJSON= option, which is then concatenated with "_data_aspects". For example, if OUTJSON=MYCPI, then the aspects data set is named mycpi_data_aspects.sas7bdat.

TRUE: specifies that the aspects data be retrieved.
FALSE: specifies that no aspects data be retrieved.

By default, ASPECTS=FALSE.

CALCULATIONS=TRUE | FALSE

specifies whether or not to retrieve the net change and percentage change calculations available for 1, 2, 3, 6, or 12 months. Depending on the frequency of the data and the availability of the data, there may not be calculations for all of the intervals (1, 2, 3, 6, or 12 months).

TRUE: retrieves the calculations.
FALSE: does not retrieve the calculations.

By default, CALCULATIONS=FALSE. When a catalog is available for the requested time series, and CALCULATIONS=TRUE is specified, each calculation series will be labelled appropriately. To see the labels, use the CONTENTS procedure on the OUTPUT data set.

CASLIB=bls_caslib_name

specifies the name of the CAS library (caslib) where the in-memory CAS table is stored when the JSON data from the BLS website are read into SAS. You can use this option to name your caslib where the in-memory CAS table is stored. The default value is the name of the active caslib. The GOCAS=ON option is required when you specify the CASLIB= option.

CASOUT=CAS-libref.data-table OUTCAS=CAS-libref.data-table

specifies the name of the in-memory CAS table that is created when the JSON data from BLS are read into SAS. The default value is the name that you specify in the OUT= option. The in-memory table is created only when you also specify the GOCAS=ON option. CAS-libref.data-table is a two-level name, where CAS-libref refers to the caslib and session identifier, and data-table specifies the name of the output data table. For more information about this two-level name, see the section Using CAS Sessions and CAS Engine Librefs.

CATALOG=TRUE | FALSE

specifies whether or not to retrieve additional descriptive data about the requested time series. This catalog information includes the series description (series title); the seasonality description; the survey name description; the survey abbreviation; and (where appropriate) descriptions such as measure data type, commerce industry, occupation, and regional area. When CATALOG=true and a catalog exists for the requested time series, the SASEBLS engine creates an auxiliary data set containing the catalog data. This auxiliary data set is named using the same name specified in the OUTJSON= option, which is then concatenated with "_catalog". For example, if OUTJSON=MYCPI, then the catalog data set is named mycpi_catalog.sas7bdat.

TRUE: retrieves additional descriptive data about the requested time series.
FALSE: does not retrieve additional descriptive data about the requested time series.

By default, CATALOG=FALSE.

CONNECT=ON | OFF

specifies whether to use (ON) or not use (OFF) the connect method along with the PROXY= option. Note: To use the connect method, you must use the PROXY= option and specify your proxy server in addition to the CONNECT=ON option. For more information about a secure connection, see the PROXY= option.

DEBUG=ON | OFF

specifies whether or not to include diagnostic message logging in the SAS log window. This information can be useful for troubleshooting. Specify DEBUG=ON to see all the log messages (including debugging information) in the SAS log. By default, DEBUG=OFF.

ENDYEAR='bls_endyear'

specifies the ending year of the time series in the format YYYY.

FORMAT=bls_jsonformat

specifies the format of the file to be retrieved from the BLS website. Although BLS can report data in many formats, the SASEBLS engine supports only the JSON format (the default).

FREQ='bls_frequency'

specifies the frequency of the data that you want to retrieve. The BLS annual average feature (ANNUALAVERAGE=TRUE) selects annual average time series data. Specify FREQ=A02 to retrieve only the annual averages for annual frequency data. Specify FREQ=S03 to retrieve only the annual averages for semiannual frequency data. Specify FREQ=Q05 to retrieve only the annual averages for quarterly frequency data. Specify FREQ=M13 to retrieve only the annual averages for monthly data. See Example 20.2 for an example that retrieves M13 (monthly annual average) data. For an example that retrieves monthly data see Example 20.1.

By default, ANNUALAVERAGE=FALSE, which disallows the retrieval of FREQ=A02, FREQ=S03, FREQ=Q05, and FREQ=M13 annual averages, but the months M01–M12 are still retrieved for FREQ=MONTH, the years A0 are retrieved for FREQ=ANNUAL, the semi-years S01–S02 are retrieved for FREQ=SEMI_ANNUAL, and the quarters Q01–Q04 are retrieved for FREQ=QUARTER. If you want both the normal time periods and the annual averages, specify ANNUALAVERAGE=TRUE, and specify the frequency that you want to retrieve: FREQ=ANNUAL, FREQ=SEMI_ANNUAL, FREQ=QTR, or FREQ=MONTH. The valid frequency arguments are shown in Table 2 in order from high to low frequency.

Table 2: BLS Frequency Codes

Frequency Code	Description
M	Displays data on a monthly basis
M13	Displays annual averages for monthly data
Mon	Displays data on a monthly basis
Month	Displays data on a monthly basis
Monthly	Displays data on a monthly basis
Q	Displays data on a quarterly basis
Q05	Displays annual averages for quarterly data
QTR	Displays data on a quarterly basis
Quarter	Displays data on a quarterly basis
Quarterly	Displays data on a quarterly basis
S	Displays data on a semiannual basis
S03	Displays annual averages for semiannual data
Semiannual	Displays data on a semiannual basis
A	Displays data on an annual basis
A02	Displays annual averages for annual data
Annual	Displays data on an annual basis
Annual_avg	Displays data for annual averages
Year	Displays data on an annual basis
Yearly	Displays data on an annual basis

GOCAS=ON | OFF

specifies whether to create (ON) or not create (OFF) an in-memory CAS table of the BLS data (in addition to the SAS data set that is created). When GOCAS=ON, the SASEBLS engine assumes that there is an active CAS session running before the LIBNAME statement is used. By default, GOCAS=OFF.

INSET=bls_input_SAS_dataset_name

specifies the name of the input SAS data set that contains a list of time series to include in the output SAS data set. The list is in the following format:

DATA \Argument{bls\_input\_SAS\_dataset\_name};
   seriesid = \Argument{\Squotes{bls\_seriesid\_name1}}; output;
   seriesid = \Argument{\Squotes{bls\_seriesid\_name2}}; output;
    .
    .
    .
   seriesid = \Argument{\Squotes{bls\_seriesid\_nameN}}; output;
run;

The BLS API allows up to 50 series IDs to be retrieved in one request. To see a list of all series IDs for a particular survey, such as CU, visit the web page at the following URL: https://download.bls.gov/pub/time.series/cu/cu.series

CPI and PPI survey names are: CU, CW, SU, AP, LI, MU, MW, ND, PC, PD, WP, and WD. You can replace the 'CU' with a different survey name to see a list of that survey’s series IDs. For example, for survey WD, use the following URL: https://download.bls.gov/pub/time.series/wd/wd.series

For an example that retrieves CPI data, see Example 20.1, and for PPI data see Example 20.2.

OUTJSON=bls_json_file_name

specifies the name of the JSON file (downloaded to the SAS Work library) and the name of the SAS data set that is created when the JSON data are read into SAS. The SAS data set is stored in the folder that is specified by physical-name.

PAYPATH="bls_payload_path_and_filename"

specifies the physical path and filename for the payload.txt file. Do not specify the '.txt' file extension because the SASEBLS engine automatically adds '.txt' to the end of the PAYPATH. The payload file is created by the engine, and contains information from the INSET= option, in addition to other options such as STARTYR=, ENDYR=, CATALOG=, and ASPECTS= options.

PROXY="bls_proxyserver"

specifies which proxy server to use. This option is not required. The specified proxy server is used only when a connection-refused error or a connection-timed-out error occurs. For bls_proxyserver, specify the server’s HTTP address followed by a colon and the port number, and enclose that string in double quotation marks; for example, PROXY="http://inetgw.unx.sas.com:8118". See also the CONNECT= option.

SETNAME=bls_setname DATASETNAME=bls_setname DATASET=bls_setname SETID=bls_setname

specifies the BLS data set name to retrieve the BLS data from. Table 3 shows the list of available BLS data set names. This release of SASEBLS supports the data set names shown in Table 4. See Example 20.1 for a CPI example, Example 20.2 for a PPI example, and Example 20.3 for an IPP example.

STARTYEAR='bls_startyear'

specifies the starting year of the time series in the format YYYY.

USER='bls_user' APIKEY='bls_user' REGISTRATIONKEY='bls_user'

specifies the unique user registration key, enclosed in quotation marks, that the BLS assigns to the user (subscriber) to allow access to the data provided by the BLS website. The BLS access key is a 32-character alphanumeric lowercase string that you can request from the website at the following URL:

https://data.bls.gov/registrationEngine/

Last updated: September 15, 2022