Item Access Functions

crsp_itm_init

Prepare a handle for item handling operations

Prototype: int crsp_itm_init(CRSP_ITM_HNDL **hndl, char *dbpath, init app_id, char *hndl_name))
Description: Prepare a handle for item handling operation for one database and one application id. The handle will be initialized and the database set type and set id identified, allowing loading of reference data and allocation of a set structure.
Arguments:

CRSP_ITM_HNDL **hndl -
Double pointer to the item handle that will be used to manage the database information and item lists.

char *dbpath -
Pointer to the database containing the data to load and the applicable reference data.

int app_id -
Identifier of a defined application organizing data items into groups for access. Available app_ids can be found in the reference array, crsp_itm_app. Common app_ids have defined constants:

  • CRSP_CCMITEMS_ID = 7 (generic CCM usage application)

char *hndl name –
Name to assign to the handle.

Return Values: CRSP_SUCCESS:

If initialized successfully

CRSP_FAIL:
If there is an error in the parameter, database cannot be opened, reference data unavailable, incompatibility between database and app_id.

Side Effects: If successful, the handle data are loaded:
  • The handle itself is lallocated if not already allocated.
  • The handle fields are initialized, including all lists and arrays.
  • The ca_ref structure is loaded with the reference data in the database. If an old database with no reference data, it will use a global reference file with a standard name based on the app_id in the CRSP_LIB directory.
  • Itm_grp and itm_avail arrays in the handle are loaded with available tables and items
  • Set_list element is allocated using the database path and setid. The database is opened with a 0 wanted, which loads reference data but allocates no module space. The root information is loaded to the set’s CRSP_ROOT_INFO structure.
Preconditions: The item handle must be initialized to NULL or point to an allocated handle that can be re-initialized. The app_id must exist in the reference data of the database opened.

crsp_itm_open

Opens databases indicated by a handle and registers selected items.

Prototype: int crsp_itm_open (CRSP_ITM_HNDL **hndl)
Description: Registers selected items in a handle by expanding structures and keysets, preparing keys, determining modules needed to access items, opens the needed modules, and binds data in the item lists to the data structure locations. It also builds a master index of all items available in the handle.
Arguments: CRSP_ITM_HNDL **hndl -
Pointer to the item handle containing the needed set structure information and the current item list.
Return Values:

SUCCESS:
If opens successfully and binds the data

CRSP_FAIL:
If error in parameters, inconsistent handle, error opening databases or binding items.

Side Effects: If successful, the handle is ready for access:
  • The itm_set element for the database will be updated with the wanted needed.
  • Prepare supplementary lists for table keyset and calendar items, and handle key items.
  • The itm_set database will be opened with the needed wanted.
  • The itm_idx master list of items will be built from selected items.
  • All items in the list will have object pointer set to the data location in the set data structure.
  • If the handle grp_fill_cd is “Y”, then the item lists are filled to ensure full tables. Filling creates items to ensure that every itm_name and keyset present in a group each combination is present even if not specified. Filling also arranges the lists so if multiple keysets, each is sorted in the same order as the first keyset seen.
Preconditions: The item handle must be previously initialized with crsp_itm_init. It generally follows one or more instances of item load functions.

crsp_itm_clear

Sets missing values in objects for all items in the handle.

Prototype: int crsp_itm_clear (CRSP_ITM_HNDL *hndl, int clear_flag)
Description: Sets missing values in the objects for all items in a handle. A flag determines how the missing values are set.
Arguments:

CRSP_ITM_HNDL *hndl -
Pointer to the item handle containing the needed set structure information and the current item list.

int clear_flag -
Code determining how the object will be cleared. Possible values are:

  • CRSP_CLEAR_INIT – only reset num for CRSP_ARRAYs and beg and end for CRSP_TIMESERIES, nothing for CRSP_ROWs.
  • CRSP_CLEAR_LOADED – only set missing values in a time series or array if non-empty.
  • CRSP_CLEAR_RANGE – set missing values for elements between beg and end for CRSP_TIMESERIES, between 0 and num – 1 for CRSP_ARRAYs, and all for CRSP_ROWs.
  • CRSP_CLEAR_ALL – set range to missing and set missing values for all elements in the object arrays.
  • CRSP_CLEAR_SET – place missing values in the 0th element of a CRSP_TIMESERIES array or the maxarr-1th element of a CRSP_ARRAY to missing values specific to the array type, or all missing values in a CRSP_ROW element.
Return Values: CRSP_SUCCESS:
If data loaded successfully

CRSP_FAIL:
If error with parameters, inconsistent handle, or unknown object type, array type, or all missing values in a CRSP ROW element.
Side Effects: Object pointers found in the handle will be cleared based on the clear_flag.
Preconditions: The item handle must be previously opened and objects bound with crsp_itm_open.

crsp_itm_load_key

Sets the key to be used for reads.

Prototype: int crsp_itm_load_key(CRSP_ITM_HNDL *hndl, char *keytype)
Description: Defines the keytype that will be used for subsequent reads.
Arguments:

CRSP_ITM_HNDL *hndl -
Pointer to the item handle containing the needed set structure information and the current item list.

char * keytype -
Name of the key to initialize. Values are:

  • gvkey – Compustat company key (default)
  • gvkeyx – Compustat index key
  • ccmid – gvkey or gvkeyx
  • permno – CRSP permno found in any links
  • permco – CRSP permco found in any links
  • apermno – CRSP-centric composite records by permno
  • ppermco – CRSP-centric composite records by permno – primary links only
  • sic – Compustat company SIC code
  • ticker – Compustat security ticker symbol
  • cusip – security CUSIP
Return Values:

CRSP_SUCCESS:
If successful

CRSP_FAIL:
Error in parameters, handle not initialized, or keytype not found.

Side Effects: If successful, the handle is prepared to handle reads.
Preconditions: The item handle must be initialized. Keytype must be known for the app_id.

crsp_itm_set_key

Sets the key specifications to be used with selecting data.

Prototype: int crsp_itm_set_key (CRSP_ITM_HNDL *hndl, char *key_itm, void *keyval)int crsp_itm_set_key (CRSP_ITM_HNDL *hndl, char *key_itm, void *keyval)
Description: Loads key information that will be used to load data in a crsp_itm_read call. The key is setup during the crsp_itm_open based on the active keytype. The value passed to this function and entered into the handle attached to the input key item.
Arguments: CRSP_ITM_HNDL *hndl -
Pointer to the item handle containing the needed set structure information and the current item list.

Char *key_itm –
String containing an itm_name of an input key item to be loaded.

Void keyval -
Data to be loaded into the key item. Data must agree with the item’s type.
Return Values: CRSP_SUCCESS:
If data loaded successfully

CRSP_FAIL:
If error in parameters, handle not open, key item.
Side Effects: If successful, the keyval is copied into the data location for the input key item element in the handle.
Preconditions: The item handle must be initialized and opened. The item key array must be initialized based on a keytype with the crsp_itm_open or crsp_itm_init_key functions. The key_itm must be a valid item for that keytype, and the keyval data must agree with the type of that item.

crsp_itm_get_key

Gets the key found by crsp_itm_read for a named key item.

Prototype: int crsp_itm_get_key (CRSP_ITM_HNDL *hndl, char *key_itm, void *keyval)
Description: Retrieves key information for data loaded by a crsp_itm_read call. An output key item list is prepared when the key is initialized, and loaded by crsp_itm_read. This function finds the key_itm in the list and copies ithe value into the user’s location.
Arguments: CRSP_ITM_HNDL *hndl -
Pointer to the item handle containing the needed set structure information and the current item list.

Char *key_itm -
String containing an itm_name of a loaded key to be retrieved.

Void *keyval -
Location to place the key value. Location must agree with the item’s type and size.
Return Values: CRSP_SUCCESS:
If data loaded successfully

CRSP_FAIL:
If error in parameters, handle not open, key item.
Side Effects: If successful, the keyval is loaded based on the item and key value type.
Preconditions: The item handle must be initialized and opened. The item key array must be initialized based on a keytype with the crsp_irtm_open or crsp_itm_init_key functions. The key_itm must be a valid item for that keytype, and the keyval data must agree with the type of that item.

crsp_itm_parse_key

Sets the key specifications to be used when selecting data based on a text string.

Prototype: int crsp_itm_parse_key (CRSP_ITM_HNDL *hndl, char *key_text)
Description: Loads key information in text format that will be used to load data in a crsp_itm_read call. The key is setup during crsp_itm_open based on the keytype identifier. The key_text string is parsed in the prescribed mapping order of the keytype and loaded into the handle.

The key_text is in the form key1.key2…, where input key items are separated by periods. If an input key is not provided it will be set with a missing value. For example, if the keytype is gvkey, to access IBM company and security data of its primary security, key_text will be set to “6066.01”. IID is optional if only company items are selected. In this case, “6066” may be used.
Arguments: CRSP_ITM_HNDL *hndl -
Pointer to the item handle containing the needed set structure information and the current item list.

Void *key_text -
String containing key information on interest, in order of keys, with each item separated by a period.
Return Values: CRSP_SUCCESS:
If successfully loaded.

CRSP_FAIL:
If bad parameter, handle not open, key item.
Side Effects: If successful, the values are copied into the handle input key item data locations for each input key item from the key_text string.
Preconditions: The item handle must be initialized and opened. The item key array must e initialized based on a keytype with the crsp_itm_open or crsp_itm_init_key functions.

crsp_itm_read

Loads data into a handle based on provided keys, supporting possible secondary indexes.

Prototype: int crsp_itm_read (CRSP_ITM_HNDL *hndl, int keyflag, init *status)
Description: Loads data from handle based on item keys specified in prior crsp_itm_key calls and keyflag. Depending on the level of the entity class, the operation may include reading data from the database into structures and/or specifying data already loaded. This allows a direct or positional read based on keyflag.

If the handle fiscal_disp_cd is C, any fiscal-based time series are shifted to a calendar basis as part of the read operation.
Arguments: CRSP_ITM_HNDL *hndl -
Pointer to the item handle containing the needed set structure information and the current item list.

int keyflag -
Code determining how the key is interpreted. CRSP_EXACT to look for a specific value, CRSP_BACK ir CRSP_FORWARD for direct selection when partial matches are allowed, or a positional qualifier to base selection on the position relative to the last key accessed. Qualifiers include:
  • CRSP_NEXT (=-99)– read next key in sequence
  • CRSP_PREV (=-96)– read previous key in sequence
  • CRSP_SAME (=-98) – read same key, possibly with different information
  • CRSP_FIRST (=-95)– read first key in the database
  • CRSP_LAST (=-97) – read last key in the database

Int *status -
User provided location to load with the level of the read. It will be loaded with a 0 if the load results in reading new master data. It will be loaded with a number greater than 0 if the load impacts detail or global data, but no master data are affected.

Return Values: CRSP_SUCCESS:
If data loaded successfully

CRSP_EOF:
If positional read reaches the end of the file

CRSP_NOT_FOUND:
If key not found on exact read. If a detal input key is not provided and no items of that entity class are selected, the return is CRSP_SUCCESS as long as the primary key matches.

CRSP_FAIL:
If error in parameters, handle not opened, error in read operations.
Side Effects: If successful, the wanted data for the key are loaded into the handle set structure which allows item objects to point to the loaded data. The key found for each level is loaded into the outkey item list. If the handle fiscal_disp_cd is set to calendar-based and items are fiscal-based, shifted calendars are created and time series are converted to calendar basis. The status argument is loaded based on whether the primary key changed. Handle primkey field and readlvl are set. Readlvl is set to the rank of the first entity class changed. If the primary key changed, getlvl is set to 0.
Preconditions: The item handle must be initialized and opened. The item key must be initialized based on the key type, key element, and the entity class. If not a positional qualifier, the item key inpkey list must be loaded.

crsp_itm_close

Closes databases indicated by a handle, frees all item list structures, and frees the handle itself.

Prototype: int crsp_itm_close (CRSP_ITM_HNDL **hndl)
Description: Frees all item lists and item indexes, clears all calendar and key lists, closes the database, frees the handle set, and frees the handle itself. On completion, the handle will be set to NULL.
Arguments: CRSP_ITM_HNDL **hndl -
Pointer to the item handle to close.
Return Values: CRSP_SUCCESS:
If the database is successfully closed and all handle data are free

CRSP_FAIL:
If there is an error in the parameters, inconsistent handle, error closing databases.
Side Effects: If successful, the handle data are emptied:
  • The itm_set database will be closed and the structure cleared.
  • The itm_grp, itm_idx, and itm_avail arrays will be emptied and all item lists will be freed.
  • Itm_key and cal_avail arrays will be freed.
  • The handle itself will be freed and its pointer set to NULL.
Preconditions: The item handle must be previously opened with crsp_itm_init.