Item Selection Functions

crsp_itm_load

Prepare a list from a full_list description string.

Prototype: int crsp_itm_load(CRSP_ITM_HNDL *hndl, char *full_list, int match_flag)
Description: Prepare items described by a full list and load them to an item table structure in an item handle. Splits the full list into the global section and the list section and uses crsp_itm_expand_elem on each list element in the list section. This well recursively expand the list elements to fill the structure and apply global qualifiers during the process.
Arguments:

char *full_list -
Pointer to a string describing all items to add, used on standard item notation.

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

int match_flag -
Flag setting the behavior when an item if found but not the keyset. Values are:

  • CRSP_MATCH_REQUIRED (=0: if any indicated item and keyset is not found no further items will be added, and CRSP_NOT_FOUND returned.
  • CRSP_MATCH_FILL (=1): a dummy item will be created for any item if the item exists but the keyset dies not exist for that item in the current database.
  • CRSP_MATCH_IGNORE (=2):  items will not be added if the keyset is not found, but the return remains CRSP_SUCCESS.
Return Values: CRSP_SUCCESS:
If successful, and all indicated items loaded according to match_flag

CRSP_FAIL:
Error in parameters, bad list, handle not initialized, or reference data not available.
Side Effects: If successful, the CRSP_ITM_GRP is loaded with all indicated items. A CRSP_ITM is allocated for each item/keyset pair not already loaded. Object pointers are not set by this function.
Preconditions: The item handle set must be loaded. The item table must be initialized with an available app_id. The first set in the set list must agree with the app_id.

crsp_itm_load_file

Prepare a list from an item list description file

Prototype: int crsp_itm_load_file (CRSP_ITM_HNDL *hndl, char *file_path, char *gbl_list, int match_flag)
Description: Prepare items described by a listfile and load them to an item table structure in an item handle. Identifies a global section and uses crsp_itm_load_elem on each list element in the file. This will recursively expand the list elements to fill the structure and apply global qualifiers during the process.
Arguments: char *file_path -
pointer to a string containing an input file of data items. Each row in the input file must be a list element.

char *gbl_list –
pointer to a string containing the global information to be applied to all list elements.

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

int match_flag -
Flag setting the behavior when an item is found but not the keyset. Values are:
  • CRSP_MATCH_REQUIRED (=0): if any indicated item and keyset is not found no further items will be added, and CRSP_NOT_FOUND returned.
  • CRSP_MATCH_FILL (=1): a dummy item will be created for any item if the item exists but the keyset dies not exist for that item in the current database.
  • CRSP_MATCH_IGNORE (=2): items will not be added if the keyset is not found, but the return remains CRSP_SUCCESS.
Return Values:

CRSP_SUCCESS:
If successful

CRSP_FAIL:
If error in parameters, bad list, handle not initialized, or reference data not available.
Side Effects: If successful, the CRSP_ITM_GRPis loaded with all indicated items. A CRSP_ITM is allocated for each item/keyset pair not already loaded. Object pointers are not set by this function.
Preconditions: The item handle set must be loaded. The item table must be initialized with an available app_id. The first set in the set list must agree with the app_id. The input file must exist with one list element per row.

crsp_itm_load_printopt

Prepare a list from a groupname print option code.

Prototype: int crsp_itm_load_printopt (CRSP_ITM_HNDL *hndl, char *printopt, int match_flag)
Description: Prepare items described by a print option code describing one group and load them to an item table structure in an item handle.
Arguments:

char *printopt -
pointer to a string containing a print option code in the form xx[.keyset_string].

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

int match_flag -
flag setting the behavior when an item if found but not in the keyset Values are:

  • CRSP_MATCH_REQUIRED (=0):if any indicated item and keyset is not found no further items will be added, and CRSP_NOT_FOUND returned
  • CRSP_MATCH_FILL (=1): a dummy item will be created for any item if the item exists but the keyset dies not exist for that item in the current database
  • CRSP_MATCH_IGNORE (=2): items will not be added if the keyset is not found, but the return remains CRSP_SUCCESS
Return Values:

CRSP_SUCCESS:
If successful.

CRSP_FAIL:
Error in parameters, opening input file, bad format of global list or input file, or reference data not available.
Side Effects: If successful, the CRSP_ITM_GRP is loaded with all indicated items. A CRSP_ITM is allocated for each item/keyset pair not already loaded. Object pointers are not set by this function.
Preconditions: The item handle set must be loaded. The item table must be initialized with an available app_id. The first set in the set list must agree with the app_id. The 2-letter print option code must be known to the app_id. Only groups with grptype of S or D will have non-blank printopt codes available.

crsp_itm_find

Access an individual item that was loaded.

Prototype: int crsp_itm_find (CRSP_ITM_HNDL *hndl, char *itm_name, int keyset, CRSP_ITM **foundptr)
Description: Attach a pointer to a CRSP_ITM that was previously loaded. The CRSP_ITM structure describes the data item and contains the underlying time series, array, or row data.
Arguments: CRSP_ITM_HNDL *hndl –
Pointer to the item handle containing the needed set structure information and the current item list.

char *itm_name –
String containing the itm_name to find.

int keyset -
Keyset to find

CRSP_ITM **foundptr –
Pointer that will point to the item data found.
Return Values:

CRSP_SUCCESS:
If successful

CRSP NOT FOUND:
If the itm_name and keyset combination are not available

CRSP_FAIL:
If error in parameters, handle not initialized, or error searching for the item.
Side Effects: If successful, the foundptr will point to a CRSP_ITM with data and information for the desired item and keyset.
Preconditions: The item handle set must be initialized, loaded with a list of items, and opened.

crsp_itm_free_list

Resets all item lists previously loaded into a handle.

Prototype: int crsp_itm_free_list (CRSP_ITM_HNDL *hndl)
Description: Resets the handle by freeing all item lists and item indexes.
Arguments: CRSP_ITM_HNDL *hndl –
pointer to the item handle to reset.
Return Values:

CRSP_SUCCESS:
If successfully frees the data

CRSP_FAIL:
If error in parameters, inconsistent handle, error emptying the lists.
Side Effects: If successful, the item lists are emptied: itm_list, keyset_list, struct_list. The index arrays are also emptied. New items can be loaded.
Preconditions: The item handle must be previously opened with crsp_itm_init.

crsp_itm_is_miss_arrval

Check if a value from a data-object attached to the item is a missing value

Prototype: int crsp_itm_is_miss_arrval (CRSP_ITM *itm, int ind*is_miss)
Description: Checks if the requested element in a data-object attached to the item contains a missing value. is_miss is set to 1 when missing value is detected. Only items of simple (non-structured) types are accepted, while the item’s underlying data-object ca be of structured data-type, in which case the structure offset is used to extract the item value.
Arguments: CRSP_ITM *itm –
Pointer to the item

int ind -
Index of the data array element to check

int *is_miss –
Pointer to the resulting flag value
Return Values: CRSP_SUCCESS:
If successful, the returned value is initialized and set.

CRSP_FAIL:
If error in parameters, bad item or element index is out-of-range (ignored in case of CRSP_ROW)
Side Effects:  
Preconditions: The item has to have a valid bound data-object. Structured items are not allowed. Field items of structures are allowed.