Database access for FORTRAN 95 programs

PLATFORM	F95 MODULES (*.mod)	F95 INCLUDES (*.inc)	F95 LIBRARY	F95 SAMPLES (*.f90)
Windows 32-bit	%CRSP_INCLUDE%\mod	%CRSP_INCLUDE%	%CRSP_LIB%	%CRSP_SAMPLE%
SunOS sparc	$CRSP_INCLUDE/mod	$CRSP_INCLUDE	$CRSP_LIB	$CRSP_SAMPLE
SunOS i86pc	$CRSP_INCLUDE/mod	$CRSP_INCLUDE	$CRSP_LIB	$CRSP_SAMPLE
Linux 32-bit	Lahey F95 compiler: $CRSP_INCLUDE/mod G95 complier: $CRSP_INCLUDE/mod_g95	$CRSP_INCLUDE	$CRSP_LIB	$CRSP_SAMPLE

Platform-specific F95 compiler options used with F95 CRSP API are listed in the table below. Refer to the CRSPAccess Release Notes for specific versions of the supported FORTRAN 95 compilers.

PLATFORM	F95 COMPILER OPTIONS
Windows 32-bit	Intel VisualFortran: ifort /Qvec- /I %CRSP_INCLUDE% /I %CRSP_INCLUDE%\mod
SunOS sparc	Sun Pro FORTRAN 95: f95 -w -ext_names=plain -I$CRSP_INCLUDE -M$CRSP_INCLUDE/mod -xarch=v9 -KPIC
SunOS i86pc	Sun Pro FORTRAN 95: f95 -w -ext_names=plain -I$CRSP_INCLUDE -M$CRSP_INCLUDE/mod -KPIC
Linux 32-bit	Lahey F95: lf95 -w -I$CRSP_INCLUDE -I$CRSP_INCLUDE/mod -Am G95: g95 -w -I$CRSP_INCLUDE -I$CRSP_INCLUDE/mod_g95

Platform-specific F95 libraries and options for linking with F95 CRSP API are listed in the table below:

PLATFORM	F95 LINK LIBRARIES
Windows 32-bit	Intel VisualFortran: %CRSP_LIB%\crsp_lib_f95.lib %CRSP_LIB%\crsp_lib.lib
SunOS sparc	Sun Pro FORTRAN 95: $CRSP_LIB/crsplib_f95.a $CRSP_LIB/crsplib.a -lm -lnsl
SunOS i86pc	Sun Pro FORTRAN 95: $CRSP_LIB/crsplib_f95.a $CRSP_LIB/crsplib.a -lm -lnsl
Linux 32-bit	Lahey F95: $CRSP_LIB/crsplib_f95.a $CRSP_LIB/crsplib.a -lm G95: $CRSP_LIB/crsplib_g95.a $CRSP_LIB/crsplib.a -lm

program my_items
use crsp_f_itm_lib
...

CRSP DATA SET	F95 SAMPLE PROGRAMS	MAKE FILE / PLATFORM .EXT
CCM	ccmitm_fsamp1.f90 sequential item-access to CRSP Compustat dataset	Windows / SunOS / Linux Lahey F95 / Linux G95 f95_samp_ccm.mak / .mk / .mk5 / .mkg5
	ccmitm_fsamp2.f90 direct item-access to CRSP Compustat dataset by GVKEY list
	ccmitm_fsamp3.f90 direct item-access to CRSP Compustat securities data by GVKEY.IID
	ccmitm_fsamp4.f90 use of CRSP Link for Compustat, item-access by CRSP permno.
STK	stkitm_fsamp1.f90 sequential item-access to CRSP Stock dataset.	Windows / SunOS / Linux Lahey F95 / Linux G95 f95_samp_stkitm.mak / .mk / .mk5 / .mkg5
	stkitm_fsamp2.f90 direct item-access to CRSP Stock dataset by CRSP permno.
	stkitm_fsamp4.f90 use of regular and derived data-items for CRSP Stock dataset.
IND	inditm_fsamp1.f90 sequential item-access to CRSP Stock Ind dataset.	Windows / SunOS / Linux Lahey F95 / Linux G95 f95_samp_inditm.mak / .mk / .mk5 / .mkg5
	inditm_fsamp2.f90 direct item-access to CRSP Stock Ind dataset by CRSP indno.

NAME	F95 TYPE	DESCRIPTION
CRSP_ITM_HNDL_T		item access handle object
keytype	character(LEN=CRSP_NAME_LEN)	cfg: determines the keys used to select data in read functions. Supported keytypes for the application are included in the reference data. A default will be set.
keyset_disp_cd	character(LEN=CRSP_TYPE_LEN)	cfg: determined whether keyset items are labeled by the keyset number (NUM), the keyset tag (TAG), or the expanded list of all items comprising the keyset (EXP). The default display is TAG.
fiscal_disp_cd	character(LEN=CRSP_TYPE_LEN)	cfg: determines whether fiscal-based time series items are reported on a calendar basis (C) or a fiscal basis (F). The default it C.
curr_disp_cd	character(LEN=CRSP_TYPE_LEN)	cfg: determines whether monetary values are reported in the currency reported by Compustat (REP) or in US Dollars (USD). The default currency display code is REP.
grp_fill_cd	character(LEN=CRSP_TYPE_LEN)	cfg: determines whether group item lists are filled so that every selected item is included for every selected keyset (Y or N). The default is Yes (Y).
dataset	CRSP_ITM_SET_T	pointer to descriptor of currently attached CRSP dataset; includes root info for the CRSP dataset.

In a user-program the access handle objects are normally declared and allocated directly then passed to F95 itm-API functions as a parameter. Call to crsp_f_itm_init function will initialize the contents of the access handle and connect it to the specified CRSP dataset.

Item object, type(CRSP_ITM_T), represents a generic container for a single data item defined in a given CRSP dataset. It unifies the data types defined for each of the supported CRSP datasets and allows a uniform access to the associated CRSP data containers from the user-program.

The main properties of the item object are listed in the following table:

NAME	F95 TYPE	DESCRIPTION
CRSP_ITM_T		item object
itm_name	character(LEN=CRSP_NAME_LEN)	name of the item from a CRSP dataset.
keyset	integer	number of the keyset defined in a CRSP dataset.
itm_info	CRSP_ITM_INFO_T	item metadata; includes description, default keyset, and stored data type.
obj	CRSP_ITM_OBJ_T	describes the underlying CRSP data-object.
arr	CRSP_ITM_OBJARR_T	describes the F95 container associated with the defined CRSP data-object.
itmkeyset	CRSP_ITM_KEYSET_T	describes the details of the keyset (when non-zero and loaded), including its number, name, tag, and array of composing items of same CRSP_ITM_T type.
itmcal	CRSP_ITM_CAL_T	for calendar-bound items, describes the details of the attached calendar, including its id, keyset ,frequency, and attached calendar object of CRSP_CAL_T type. When requested, the calendar may be 'shifted', based on the currently loaded company's FYE to attribute properly the item's period data.

In a user-program the item objects are normally declared as F95 pointers and then attached to the actual defined item objects by calling crsp_f_itm_find function for the given access handle and the specified item name and keyset.

Item data is accessed from the data-object itm%obj and associated to it F95 container itm%arr. Item data container object, type(CRSP_ITM_OBJ_T), describes an instance of a CRSP data-object (time-series, array, row) that is defined for the specific item. Only a single data-object can be defined for a given item, and is identified by the objtype property.

Main properties of item data-object are listed in the following table:

NAME	F95 TYPE	DESCRIPTION
CRSP_ITM_OBJ_T		item data-object.
objtype	integer	type of the defined and allocated object: CRSP_TS_OTID: CRSP time-series CRSP_ARRAY_OTID: CRSP array CRSP_ROW_OTID: CRSP row
ts	CRSP_TS_T	pointer to allocated CRSP time-series data-object.
arr	CRSP_ARRAY_T	pointer to allocated CRSP array data-object.
row	CRSP_ROW_T	pointer to allocated CRSP row data-object.
is_empty	logical	indicates whether the allocated CRSP data-object contains no data.

Item data-object normally has an associated F95 container, which is either F95 array or scalar of the data type corresponding to the actual stored data, as identified by arrtype property. The relevant details of the CRSP container objects are listed in the reference section.

Item data array, type(CRSP_ITM_OBJARR_T), describes the associated to the data-object F95 container. The F95 container is allocated based on the object's type (objtype ) and contained data type (arrtype). The respective scalar member has suffix _val to its name, and _arr for the array type. Time-series and array data are stored in array type, while row data is kept in scalar type:

itm%arr%arrtype:
	CRSP_TS_OTID: itm%arr%<arrtype_name>_arr  - time-series object data array
	CRSP_ARARY_OTID: itm%arr%<arrtype_name>_arr  - array object data array
	CRSP_ROW_OTID: itm%arr%<arrtype_name>_val  - row object data scalar.

NOTE: throughout the implementation of the CRSP F95 itm-API, the F95 array indexing is 0-based, thus the first element of an array is data_arr(0).

Refer to the description of the defined data types for the specific CRSP dataset.

Main properties of item data array for the item data types that are common to all of the supported CRSP datasets are listed in the following table:

NAME	F95 TYPE	DESCRIPTION
CRSP_ITM_OBJARR_T		descriptor of the F95 data container associated to item data-object.
arrtype	integer	data type of the defined and allocated F95 container. Common data types: CRSP_INTEGER_TID: integer CRSP_FLOAT_TID: real CRSP_DOUBLE_TID: double precision CRSP_CHAR_TID: character(1) CRSP_CHARACTER_TID: CRSP_VARSTRING_T type
int_val / arr	integer / dimension (:)	pointer to allocated scalar / array of integer type
flt_val / arr	real / dimension (:)	pointer to allocated scalar / array of real type
dbl_val / arr	double precision / dimension (:)	pointer to allocated scalar / array of double precision type
char_val / arr	character(LEN=1) / dimension (:)	pointer to allocated scalar / array of single-character type
vstr_val / arr	CRSP_VARSTRING_T / dimension (:)	pointer to allocated scalar / array of variable-length string type
structured types specific to CRSP datasets		Refer to the description of data types for the specific CRSP dataset.

In a user-program the item container data is usually accessed directly as defined by item's data type, eg:

print *, sale_itm%arr%dbl_arr(i)

Item data container is normally accessed in association with its item data-object.

NOTE: If an incorrect data container is referenced, access violation error should occur on the referenced null-pointer. In such situation the recommended action is to verify in the user-program if the appropriate containers are being accessed for the selected items.

Data for items of CRSP array type is accessed in the valid [0..num-1] index range, as defined in the corresponding arr data-object, e.g.:

itm%arr%dbl_arr(i), i=0..itm%obj%arr%num-1

Data for items of CRSP time-series type is accessed in the valid [beg,end] index range, as defined in the corresponding ts data-object, e.g.:

itm%arr%dbl_arr(i), i=itm%obj%ts%beg..itm%obj%ts%end

Data for items of CRSP row type is not indexed and is accessed directly from the value as defined by the corresponding scalar/structured type, e.g.:

itm%arr%master_val%ccmid

To verify if an element of an array item contains a missing value, call crsp_f_itm_is_miss_arrval function.

The described object types and properties together with the supplied F95 samples should cover most of the practical aspects of using F95 itm-API. For more details on the full set of F95 data types used in the F95 itm-API refer to the supplied F95 include-files.

CRSP F95 itm-API SUPPORTING INFORMATION

Various supporting information about database, item, keyset and other item-access objects is stored in the following derived types:

F95 TYPE NAME	DESCRIPTION	ACCESS VIA TYPE NAME	USAGE
CRSP_ITM_INFO_T	Item information; includes item's full name, description, display format, data type and size information. Also includes the default keyset number associated with this item.	CRSP_ITM_T	itm%itm_info
CRSP_ITM_KEYSET_T	Keyset descriptor; includes keyset information and the array of items composing the keyset.	CRSP_ITM_T	itm%itmkeyset
CRSP_ITM_CAL_T	Calendar descriptor; includes calendar's id, associated keyset number, base calendar name, and calendar's frequency, also the base calendar object. Additionally, for fiscal calendars indicates whether the calendar has been shifted based on the currently loaded company's FYE.	CRSP_ITM_T	itm%itmcal
CRSP_KEYSET_T	Keyset information; includes keyset's number, name, tag, and description. Indicates whether the keyset has been loaded and associated with any of the requested items.	CRSP_ITM_KEYSET_T	itmkeyset%keyset_info
CRSP_ITM_SET_T	CRSP data set descriptor; includes the set's path, name, id, and database root information.	CRSP_ITM_HNDL_T	hndl%dataset
CRSP_ROOT_INFO_T	CRSP data set root information; includes internal service information about the currently loaded database such as creation/modification date, product code and name, and descriptors of available calendars. Mainly intended for internal use.	CRSP_ITM_SET_T	dataset%root_info

NOTE: While selected supported information is populated on initiating of the connection to a CRSP data set (on return from call to crsp_f_itm_init), the listed supported information becomes available only on opening of the CRSP data set (on return from call to crsp_f_itm_open).

The relevant details of the derived types shown above are listed in the reference section.

CRSP F95 itm-API GENERIC DATA TYPES

All CRSP datasets contain data items of the generic simple F95 data types in addition to data items of dataset-specific structured data types. Moreover, each composing field of the structured data type can instead be requested as an individual data item of the generic simple F95 data type.

The vast majority of the data items defined in CRSP data sets are of CRSP time-series container object type with the stored values commonly of generic F95 data types. A limited set of items is stored in CRSP array and CRSP row container objects; these items are mostly of structured data types and are listed in the following sections per CRSP data set.

The following table lists the supported generic data types and ways to access data from the item-associated container:

ITEM OBJECT TYPE	F95 TYPE NAME	INTERNAL STORAGE	ACCESS VIA CRSP_ITM_T
time-series	CRSP_TS_T		itm%obj%ts
	integer	int(4)	itm%arr%int_arr(i)
	real	float(4)	itm%arr%flt_arr(i)
	double precision	double(8)	itm%arr%dbl_arr(i)
	character(LEN=1)	char (1)	itm%arr%char_arr(i)
	CRSP_VARSTRING_T	char(n)	itm%arr%vstr_arr(i)
array	CRSP_ARRAY_T		itm%obj%arr
	integer	int(4)	itm%arr%int_arr(i)
	real	float(4)	itm%arr%flt_arr(i)
	double precision	double(8)	itm%arr%dbl_arr(i)
	character(LEN=1)	char (1)	itm%arr%char_arr(i)
	CRSP_VARSTRING_T	char(n)	itm%arr%vstr_arr(i)
row	CRSP_ROW_T		itm%obj%row
	integer	int(4)	itm%arr%int_val
	real	float(4)	itm%arr%flt_val
	double precision	double(8)	itm%arr%dbl_val
	character(LEN=1)	char (1)	itm%arr%char_val
	CRSP_VARSTRING_T	char(n)	itm%arr%vstr_val

NOTE: F95 derived type CRSP_VARSTRING_T accommodates varying-length character strings and is used in the context of CRSP F95 itm-API to store data of individual character items that are composing fields of a structured data item (eg. CCM structured item COMPANY has a field for company name, which can be referenced indirectly as company_itm%arr%company_val%conm as a fixed-length character string, alternatively this field can be requested individually as CONM item and then referenced as conm_itm%arr%vstr_val as varying-length string).

See the description of CRSP_VARSTRING_T type for usage details.

ITEM-ACCESS TO CCM/CRSP COMPUSTAT XPRESSFEED

To connect to the specific CRSP CCM database instance the path to its database root should be specified. When installed on your system, CRSP CCM data set will be assigned an environment variable pointing to the CRSP CCM database root.

Additionally, an application ID should be specified on the call to crsp_f_itm_init to indicate the item-universe to be loaded for the session and describes the available items and item groups, eg:

sts = crsp_f_itm_init (hndl,'CRSP_CCM',app_id,'ccm1')

User-programs should access the CRSP CCM data set with the app_id as listed in the following table:

CCM ROOT/APP ID	F95 TYPE	DESCRIPTION
CRSP_CCM		CCM/CRSP Compustat data set
CRSP_CCMITEMS_ID	integer	Compustat Xpressfeed data items and groups

CCM/CRSP COMPUSTAT XPRESSFEED ACCESS KEYS

CRSP Compustat Xpressfeed includes various data on companies, securities, and indexes. Access key is composed of access key items the values of which can be retrieved or set from the user-program to control the direct access to the CCM data.

Default access key for CRPS CCM is loaded automatically on opening the access session to the CRSP CCM data set.

Additionally, a set of alternative access keys (and associated key items) is defined to facilitate access to the data by CRSP PERMNO,CUSIP and other keys.

The current key universe can be retrieved by requesting header information and sequentially traversing the whole data set on the selected access key. The function crsp_f_itm_get_key can also be used to retrieve the value of the access key items for the currently read record.

To switch to access by an alternative key, a user calls crsp_f_itm_load_key to set the access key index, followed by calls to crsp_itm_set_key to set the value of the key items used on subsequent reading of the database.

The defined CCM access keys and associated key items are listed in the following table:

CCM ACCESS KEY/KEY ITEMS	F95 TYPE	DESCRIPTION	NOTES
gvkey		Compustat GVKEY and IID	default
KYGVKEY	integer	Compustat company's GVKEY	primary key item
KYIID	char(CRSP_CCM_IID_LEN)	Compustat company security's IID	secondary key item
gvkeyx		Compustat permanent identifier for indexes
KYGVKEYX	integer	Compustat index's GVKEYX	primary key item
ccmid		Compustat permanent identifier - either GVKEY or GVKEYX
KYCCMID	integer	CRSP CCMID (GVKEY or GVKEYX as reported in MASTER item)	primary key item
KYIID	char(CRSP_CCM_IID_LEN)	Compustat company security's IID	secondary key item
permco		CRSP historical PERMCO Link
KYPERMCO	integer	CRSP company's PERMCO	primary key item
permno		CRSP historical PERMNO Link
KYPERMNO	integer	CRSP company issue's PERMNO	primary key item
cusip		Compustat CUSIP
KYCUSIP	char(CRSP_CCM_CUSIP_LEN)	Compustat issue's CUSIP	primary key item
ticker		Compustat reported Issue Trading Symbol selects GVKEY and security
KYTICKER	char(CRSP_CCM_TIC_LEN)	Compustat issue's ticker	primary key item
sic		Compustat-reported SIC code. Security or Company
KYSIC	integer	Compustat security's SIC	primary key item
KYIID	char(CRSP_CCM_IID_LEN)	Compustat company security's IID	secondary key item
apermno		Link-Used PERMNO
KYPERMNO	integer	CRSP company issue's PERMNO	primary key item
apermco		Link-Used PERMCO
KYPERMCO	integer	CRSP company issue's PERMCO	primary key item
ppermno		CRSP PERMNO when security is marked as primary
KYPERMNO	integer	CRSP company issue's PERMNO	primary key item

See The CRSP Link Guide for details on using CRSP Link.

CCM/CRSP COMPUSTAT XPRESSFEED DATA TYPES

Generally, individual Compustat Xpressfeed data items are of common simple F95 data types and stored data can be accessed through itm%arr and corresponding scalar or array member.

Also additional character data types were introduced to store specific classes of Xpressfeed items, as listed in the following table:

ITEM OBJECT TYPE	F95 TYPE NAME	INTERNAL STORAGE	ACCESS VIA CRSP_ITM_T	NOTES
time-series	CRSP_TS_T		itm%obj%ts
	CRSP_CCM_FTNT_T	char(CRSP_CCM_FTNT_LEN)	itm%arr%ftnt_arr(i)%ftnt	Used for CCM footnote items, mainly time-series
	CRSP_CCM_TEXTITEM_T	char(CRSP_CCM_TEXTITEM_LEN)	itm%arr%text_arr(i)%text	Used for various CCM character string items, mainly time-series
array	CRSP_ARRAY_T		itm%obj%arr
	CRSP_CCM_FTNT_T	char(CRSP_CCM_FTNT_LEN)	itm%arr%ftnt_arr(i)%ftnt
	CRSP_CCM_TEXTITEM_T	char(CRSP_CCM_TEXTITEM_LEN)	itm%arr%text_arr(i)%text
row	CRSP_ROW_T		itm%obj%row
	CRSP_CCM_FTNT_T	char(CRSP_CCM_FTNT_LEN)	itm%arr%ftnt_val%ftnt
	CRSP_CCM_TEXTITEM_T	char(CRSP_CCM_TEXTITEM_LEN)	itm%arr%text_val%text

Additionally, selected Compustat Xpressfeed primary data groups and CRSP supplemental data groups can be accessed by the entire group as a defined structured type rather than as a stand-alone item. These data groups and their elements can both be accessed by itm_name, but recommended programming access is through the itm_name of the structure. To access the structured type and its fields, load the structured type itm_name during initialization, create a CRSP_ITM_T pointer matching the itm_name, attach it to the data, and access the structured type and its fields through the pointer:

sts = crsp_f_itm_load(hndl,'MASTER',match_flag)
sts = crsp_f_itm_find(hndl,'MASTER',0,mstr_itm)
ccmid = mstr_itm%arr%master_val%ccmid
...

CCM STRUCTURED TYPES

ITEM-ACCESS TO STK/CRSP STOCK DATABASE

To connect to the specific CRSP Stock database instance the path to its database root should be specified. When installed on your system, CRSP Stock data set will be assigned an environment variable pointing to the CRSP Stock database root.

Additionally, an application ID should be specified on the call to crsp_f_itm_init to indicate the item-universe to be loaded for the session and describes the available items and item groups, eg:

sts = crsp_f_itm_init (hndl,'CRSP_DSTK',app_id,'stk1')

User-programs should access the CRSP Stock data set with the app_id as listed in the following table:

STK ROOT/APP ID	F95 TYPE	DESCRIPTION
CRSP_DSTK		CRSP Daily Stock data set
CRSP_DSTKITM_ID	integer	CRSP Daily Stock data items and groups
CRSP_MSTK		CRSP Monthly Stock data set
CRSP_MSTKITM_ID	integer	CRSP Monthly Stock data items and groups

STK/CRSP STOCK DATABASE ACCESS KEYS

CRSP Stock data set contains various data on companies and securities. Access key is composed of access key items the values of which can be retrieved or set from the user-program to control the direct access to STK data.

Default access key is loaded automatically on opening the access session to the CRSP STK data set.

Additionally, a set of alternative access keys (and associated key items) is defined to facilitate access to the data by CRSP PERMNO,CUSIP and other keys.

The current key universe can be retrieved by requesting header information and sequentially traversing the whole data set on the selected access key. The function crsp_f_itm_get_key can also be used to retrieve the value of the access key items for the currently read record.

To switch to access by an alternative key, a user calls crsp_f_itm_load_key to set the access key index, followed by calls to crsp_itm_set_key to set the value of the key items used on subsequent reading of the database.

The defined STK access keys and associated key items are listed in the following table:

STK ACCESS KEY/KEY ITEMS	F95 TYPE	DESCRIPTION	NOTES
permno		CRSP historical PERMNO	default
KYPERMNO	integer	CRSP company issue's PERMNO	primary key item
permco		CRSP historical PERMCO
KYPERMCO	integer	CRSP company's PERMCO	primary key item
cusip		CRSP Stock CUSIP
KYCUSIP	char(CRSP_CUSIP_LEN)	CRSP Stock issue's CUSIP	primary key item
hcusip		CRSP Stock hisorical CUSIP
KYHCUSIP	char(CRSP_CUSIP_LEN)	CRSP issue's CUSIP	primary key item
ticker		CRSP Stock ticker
KYTICKER	char(CRSP_STK_TIC_LEN)	CRSP issue's ticker	primary key item
siccd		CRSP Stock SIC code
KYSIC	integer	CRSP Stock security's SIC	primary key item

STK/CRSP STOCK DATABASE DATA TYPES

Generally, individual CRSP Stock database data items are of common simple F95 data types and stored data can be accessed through itm%arr and corresponding scalar or array member.

Additionally, selected CRSP supplemental STK data groups can be accessed by the entire group as a defined structured type rather than as a stand-alone item. These data groups and their elements can both be accessed by itm_name, but recommended programming access is through the itm_name of the structure. To access the structured type and its fields, load the structured type itm_name during initialization, create a CRSP_ITM_T pointer matching the itm_name, attach it to the data, and access the structured type and its fields through the pointer:

sts = crsp_f_itm_load(hndl,'HEADER',match_flag)
sts = crsp_f_itm_find(hndl,'HEADER',0,header_itm)
permno = header_itm%arr%header_val%permno
...

STK STRUCTURED TYPES

ITEM-ACCESS TO IND/CRSP INDEX DATABASE

To connect to the specific CRSP Index database instance the path to its database root should be specified. When installed on your system, CRSP Index data set will be assigned an environment variable pointing to the CRSP Index database root.

Additionally, an application ID should be specified on the call to crsp_f_itm_init to indicate the item-universe to be loaded for the session and describes the available items and item groups, eg:

sts = crsp_f_itm_init (hndl,'CRSP_DSTK',app_id,'ind1')

User-programs should access the CRSP Index data set with the app_id as listed in the following table:

STK ROOT/APP ID	F95 TYPE	DESCRIPTION
CRSP_DSTK		CRSP Daily Stock and Index data set
CRSP_DINDITEMS_ID	integer	CRSP Daily Index series data items and groups
CRSP_DINDGITEMS_ID	integer	CRSP Daily Index group data items and groups
CRSP_MSTK		CRSP Monthly Stock and Index data set
CRSP_MINDITEMS_ID	integer	CRSP Monthly Index series data items and groups
CRSP_MINDGITEMS_ID	integer	CRSP Monthly Index group data items and groups

IND/CRSP INDEX DATABASE ACCESS KEYS

CRSP Index data set includes various data on market indexes. Access key is composed of access key items the values of which can be retrieved or set from the user-program to control the direct access to IND data.

Default access key is loaded automatically on opening the access session to the CRSP IND data set.

The current key universe can be retrieved by requesting header information and sequentially traversing the whole data set on the selected access key. The function crsp_f_itm_get_key can also be used to retrieve the value of the access key items for the currently read record.

The defined IND access keys and associated key items are listed in the following table:

IND ACCESS KEY/KEY ITEMS	F95 TYPE	DESCRIPTION	NOTES
indno		CRSP Index's INDNO	default
KYINDNO	integer	CRSP index's INDNO	primary key item

IND/CRSP INDEX DATABASE DATA TYPES

Generally, individual CRSP Index database data items are of common simple F95 data types and stored data can be accessed through itm%arr and corresponding scalar or array member.

Additionally, selected CRSP supplemental IND data groups can be accessed by the entire group as a defined structured type rather than as a stand-alone item. These data groups and their elements can both be accessed by itm_name, but recommended programming access is through the itm_name of the structure. To access the structured type and its fields, load the structured type itm_name during initialization, create a CRSP_ITM_T pointer matching the itm_name, attach it to the data, and access the structured type and its fields through the pointer:

sts = crsp_f_itm_load(hndl,'INDHDR',match_flag)
sts = crsp_f_itm_find(hndl,'INDHDR',0,indhdr_itm)
indno = indhdr_itm%arr%indhdr_val%indno
...

IND STRUCTURED TYPES

F95 itm-API FUNCTIONS

crsp_f_itm_close

PROTOTYPE

integer function crsp_f_itm_close (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

type(CRSP_ITM_HNDL_T) :: hndl

Access 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 database will be closed and the structure cleared.

• All internal storage allocated for this instance will be freed

PRECONDITIONS

The item handle must be previously opened with function crsp_f_itm_init.

crsp_f_itm_find

PROTOTYPE

integer function crsp_f_itm_find (hndl, itm_name, keyset,itm_foundptr)

DESCRIPTION

Attach a pointer to a CRSP_ITM_T item that was previously loaded. The CRSP_ITM_T structure describes the data item and contains the underlying time series, array, or row data.

ARGUMENTS

type(CRSP_ITM_HNDL_T) :: hndl

Access handle containing the needed set structure information and the current item list.

character(*) :: itm_name

String containing the itm_name to find.

integer :: keyset

Keyset to find

type(CRSP_ITM_T), pointer :: itm_foundptr

User-declared pointer that will point to the data item found.

RETURN VALUES

CRSP_SUCCESS

If successfully found the requested item in the given keyset.

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 itm_foundptr will point to a CRSP_ITM_T item with data and information for the desired item and keyset. Otherwise the null() will be assigned to itm_foundptr.

PRECONDITIONS

The item handle set must be initialized, loaded with a list of items, and opened.

crsp_f_itm_find_itmcal

PROTOTYPE

integer function crsp_f_itm_find_itmcal (hndl, calid, keyset,itmcal_foundptr)

DESCRIPTION

Attach a pointer to a CRSP_ITM_CAL_T item calendar that was previously loaded. The CRSP_ITM_CAL_T structure describes a global calendar or calendar associated with an item and contains the underlying CRSP_CAL_T data.

ARGUMENTS

type(CRSP_ITM_HNDL_T) :: hndl

Access handle containing the needed set structure information and the current item list.

Integer :: calid

Calendar id of the calendar to find:

CRSP_CALID_DAILY

daily calendar

CRSP_CALID_MONTHLY

monthly calendar

CRSP_CALID_ANNUAL

annual calendar

CRSP_CALID_QUARTERLY

quarterly calendar

CRSP_CALID_SEMIANNUAL

semi-annual calendar

CRSP_CALID_WEEKLY

weekly calendar

integer :: keyset

Keyset of the calendar to find.

keyset >= 0

when item-access configured with fiscal_disp_cd='C', the calendars associated with fiscal items will be “shifted”, based on the loaded company's FYE.

keyset = -1

will request the global “non-shifted” calendar with the specified calid.

type(CRSP_ITM_CAL_T), pointer :: itmcal_foundptr

User-declared pointer that will point to the calendar found.

RETURN VALUES

CRSP_SUCCESS

If successfully found the requested item calendar in the given keyset.

CRSP_NOT_FOUND

If the calid and keyset combination are not available

CRSP_FAIL

If error in parameters, handle not initialized, or error searching for the item calendar.

SIDE EFFECTS

If successful, the itmcal_foundptr will point to a CRSP_ITM_CAL_T item calendar with data and information for the desired calendar and keyset. Otherwise the null() will be assigned to itmcal_foundptr.

PRECONDITIONS

The item handle set must be initialized, loaded with a list of items, and opened.

crsp_f_itm_find_itmcal_dt

PROTOTYPE

integer function crsp_f_itm_find_itmcal_dt (itmcal,dt,match_mode,ifound)

DESCRIPTION

Find array index of a date entry in CRSP_ITM_CAL_T item calendar.

ARGUMENTS

type(CRSP_ITM_CAL_T), pointer :: itmcal

Pointer to the item calendar.

integer :: dt

Requested date to be found. Format: yyymmdd.

integer :: match_mode

Matching mode:

CRSP_EXACT

exact match requested

CRSP_NEXT

if exact is not found – return next valid

CRSP_PREV

if exact is not found – return previous valid

integer ::ifound

Array index of the date found. When date is not found, ifound = -1

RETURN VALUES

CRSP_SUCCESS

If successfully found the requested date.

CRSP_NOT_FOUND

If the date is not found with the given matching mode.

CRSP_FAIL

If error in parameters, item calendar is not set or loaded.

SIDE EFFECTS

If successful, the ifound will be set to a valid array index for the caldt array attached to calendar object. The index can be used to directly access the corresponding time-series item data values associated with this calendar.

PRECONDITIONS

The item calendar set must be initialized and loaded.

crsp_f_itm_get_key

PROTOTYPE

integer function crsp_f_itm_get_key (hndl, key_itm_name,keyval)

DESCRIPTION

Retrieves key information for data loaded by a function crsp_f_itm_read call. An output key item list is prepared when the key is initialized, and loaded by function crsp_f_itm_read. This function finds the key_itm_name in the list and copies ithe value into the user's location.

ARGUMENTS

type(CRSP_ITM_HNDL_T) :: hndl

Access handle containing the needed set structure information and the current item list.

character(*) :: key_itm_name

String containing an itm_name of a loaded key to be retrieved.

{integer OR type(CRSP_VARSTRING_T)} :: keyval

Variable to accept the value of the key item. Data type 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 function crsp_f_itm_open or function crsp_f_itm_init_key functions. The key_itm_name must be a valid item for that keytype, and the keyval data must agree with the type of that item.

crsp_f_itm_init

PROTOTYPE

integer function crsp_f_itm_init(hndl, dbpath,app_id, hndl_name)

DESCRIPTION

Prepare a handle for item access 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

type(CRSP_ITM_HNDL_T) :: hndl

Access handle that will be used to manage the database information and item lists.

character(*) :: dbpath

Path to database containing the data to load and the applicable reference data.

integer :: app_id

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

CRSP_CCMITEMS_ID

generic CCM usage application

CRSP_DSTKITM_ID

generic Daily Stock usage application

CRSP_MSTKITM_ID

generic Monthly Stock usage application

CRSP_DINDITEMS_ID

generic Daily Ind Stock usage application

CRSP_MINDITEMS_ID

generic Monthly Ind Stock usage application

character(*) :: 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 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_T structure.

PRECONDITIONS

The item handle object must be declared and not attached to another access instance. The app_id must exist in the reference data of the database opened.

crsp_f_itm_is_miss_arrval

PROTOTYPE

integer function crsp_f_itm_is_miss_arrval (itm, 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 .TRUE. when missing value is detected. Only items of simple (non-structured) types are accepted, while the item's underlying data-object can be of structured data-type, in which case the structure offset is used to extract the item value.

ARGUMENTS

type(CRSP_ITM_T),pointer :: itm

Pointer to the data item

integer :: ind

Index of the data array element to check

logical :: 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_T object)

SIDE EFFECTS

If the requested value contains a missing value, the is_miss is set to .TRUE. Otherwise .FALSE. is assigned.

PRECONDITIONS

The item has to have a valid bound data-object. Structured items are not allowed. Field items of structures are allowed.

crsp_f_itm_open

PROTOTYPE

integer function crsp_f_itm_open (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

type(CRSP_ITM_HNDL_T) :: hndl

Access handle containing the needed set structure information and the current item list.

RETURN VALUES

CRSP_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:

• All items in the loaded 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 function crsp_f_itm_init. It generally follows one or more instances of item load function calls.

crsp_f_itm_load

PROTOTYPE

integer function crsp_f_itm_load(hndl, full_list,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 function crsp_f_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

type(CRSP_ITM_HNDL_T) :: hndl

Access handle containing the needed set structure information and the current item list.

character(*) :: full_list

String describing all items to add, used on standard item notation.

integer :: 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 does 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_f_itm_load_key

PROTOTYPE

integer function crsp_f_itm_load_key(hndl, keytype)

DESCRIPTION

Defines the keytype that will be used for subsequent reads.

ARGUMENTS

type(CRSP_ITM_HNDL_T) :: hndl

Access handle containing the needed set structure information and the current item list.

character(*) :: 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_f_itm_read

PROTOTYPE

integer function crsp_f_itm_read (hndl, integer :: keyflag, key_status)

DESCRIPTION

Loads data from handle based on item keys specified in prior function crsp_f_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

type(CRSP_ITM_HNDL_T) :: hndl

Access handle containing the needed set structure information and the current item list.

integer :: keyflag

Code determining how the key is interpreted. Possible values are:

CRSP_EXACT

look for a specific value

CRSP_BACK or CRSP_FORWARD

direct selection when partial matches are allowed, or a positional qualifier to base selection on the position relative to the last key accessed.

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

integer :: key_status

User provided variable 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 detail 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_f_itm_set_key

PROTOTYPE

integer function crsp_f_itm_set_key (hndl, key_itm_name, keyval)

DESCRIPTION

Loads key information that will be used to load data in a function crsp_f_itm_read call. The key is setup during the function crsp_f_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

type(CRSP_ITM_HNDL_T) :: hndl

Access handle containing the needed set structure information and the current item list.

character(*) :: key_itm_name

String containing an itm_name of an input key item to be loaded.

{integer OR type(CRSP_VARSTRING_T)} :: keyval

Data to be loaded into the key item. Data must agree with the key 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 function crsp_f_itm_open or function crsp_f_itm_init_key functions. The key_itm_name must be a valid item for that keytype, and the keyval data must agree with the type of that item.

REFERENCE

REFERENCE: CRSP F95 itm-API DATA TYPES

All F95 derived types used in CRSP F95 itm-API are defined in crsp_f_itm_types F95 module and are included automatically into user program through the use of crsp_f_itm_lib F95 module.

Present document lists only selected properties of the defined types that are relevant in the user-scope of item-based access. The full individual definitions of the specific F95 derived types can be referenced from respective include files, these files have already been included into crsp_f_itm_lib F95 module and an explicit include statement is not necessary to use the defined types in user-program. The supplied CRSP F95 itm-API include files are listed in the following table:

PLATFORM LOCATION	FILE	DESCRIPTION
Windows 32-bit: %CRSP_INCLUDE% SunOS sparc, SunOS i86pc, Linux 32-bit: $CRSP_INCLUDE	crsp_itm_ccm_types.inc	CRSP CCM/Compustat specific data types
	crsp_itm_stk_types.inc	CRSP Stock specific data types
	crsp_itm_ind_types.inc	CRSP Index specific data types
	crsp_itm_gen_types.inc	CRSP generic data types used in all supported data sets
	crsp_itm_types.inc	Data types used in context of item-access
	crsp_itm_params.inc	Declarations of constant parameters used.

To use the CRSP F95 itm-API library in your program simply include a 'use' statement for the top-level F95 module crsp_f_itm_lib, all necessary underlying modules should be included automatically. The supplied CRSP F95 itm-API module files are listed in the following table:

PLATFORM LOCATION	FILE	DESCRIPTION
Windows 32-bit: %CRSP_INCLUDE%\mod SunOS sparc, SunOS i86pc: $CRSP_INCLUDE/mod Linux 32-bit: $CRSP_INCLUDE/mod $CRSP_INCLUDE/mod_g95	crsp_f_itm_lib.mod	CRSP F95 itm-API user-level module
	crsp_f_varstring.mod	CRSP implementation of varying-length string (CRSP_VARSTRING_T F95 derived type)
	crsp_f_itm_utils.mod	Implementations of CRSP itm-API interfaces
	crsp_f_itm_types.mod	F95 derived types used in context of CRSP F95 itm-API
	crsp_f_itm_xfer.mod	Internal functions and types for CRSP F95/C exchange layer

REFERENCE: CRSP CONTAINER OBJECTS

CRSP container objects are used to uniformly define the storage for various CRSP data types. In the general case the container's data is stored in the associated F95 array, except for the CRSP_ROW_T container, where the storage is allocated for an F95 scalar of the specified data type. The associated storage array is externally allocated with array bounds 0-based.

CRSP time-series object has an associated calendar of the CRSP_CAL_T object type which is aligned with the time-series data array, attributing the date to the values stored in the time-series array.

CRSP calendar data is stored in the CRSP_CAL_T container object, which defines the loaded calendar and also stores the actual calendar data of the defined type. In the context of CRSP F95 itm-API the calendars associated to the time-series items are of day date-type and are accessed with caldt array.

Each container (except CRSP_ROW_T) has a defined availability range, with missing values set beyond the defined range. The missing value is specific to the data type of the stored data and is kept at the pre-defined array index position.

The relevant properties of the CRSP container object types are listed in the following tables:

NAME	F95 TYPE	DESCRIPTION
CRSP_TS_T		CRSP time-series container object definition
objtype	integer	Object type id (CRSP_TS_OTID)
arrtype	integer	Type id of the data stored in the container
subtype	integer	Subtype id of the data stored in the container
maxarr	integer	Maximum bound for the storage array (index is 0-based)
beg	integer	Lower index of the available stored data
end	integer	Upper index of the available stored data
caltype	integer	Calendar type of the associated calendar object
cal	CRSP_CAL_T	Pointer to associated calendar object
miss_val_at = 0		Array index of the missing value for the stored data type

NAME	F95 TYPE	DESCRIPTION
CRSP_ARRAY_T		CRSP array container object definition
objtype	integer	Object type id (CRSP_ARRAY_OTID)
arrtype	integer	Type id of the data stored in the container
subtype	integer	Subtype id of the data stored in the container
maxarr	integer	Maximum bound for the storage array (index is 0-based)
num	integer	Upper index of the available stored data (index is 0-based)
miss_val_at = maxarr - 1		Array index of the missing value for the stored data type

NAME	F95 TYPE	DESCRIPTION
CRSP_ROW_T		CRSP row container object definition
objtype	integer	Object type id (CRSP_ROW_OTID)
arrtype	integer	Type id of the data stored in the container
subtype	integer	Subtype id of the data stored in the container

NAME	F95 TYPE	DESCRIPTION
CRSP_CAL_T		CRSP calendar container object
objtype	integer	Object type id (CRSP_CAL_OTID)
calid	integer	Id code of the loaded calendar: CRSP_CALID_DAILY CRSP_CALID_MONTHLY CRSP_CALID_ANNUAL CRSP_CALID_QUARTERLY CRSP_CALID_SEMIANNUAL CRSP_CALID_WEEKLY
maxarr	integer	Maximum bound of the date storage array
gmtoffset	integer	Minutes offset from GMT
timezone	integer	Code for time zone GMT
relflag	integer	If beg and end absolute or relative
beg	integer	Valid range subset begin
end	integer	Valid range subset end
ndays	integer	Number of periods in calendar
name	character(LEN=CRSP_NAMESIZE)	Calendar name
caldt	integer,dimension(:)	Array of the available day dates (yyyymmdd) in the calendar

REFERENCE: CRSP F95 itm-API SUPPORTING TYPES

The CRSP F95 itm-API supporting types provide additional information about the items and other associated objects in item-based access context.

Item object is usually associated to a keyset and calendar (in case of time-series items). The details of keyset (when non-zero) and calendar are given in CRSP_ITM_KEYSET_T and CRSP_ITM_CAL_T derived types.

Additionally, the details on the current CRSP data set (such as set name, product name, version etc.) are provided in CRSP_ITM_SET_T and CRSP_ROOT_INFO_T derived types.

The relevant fields of the supporting types are listed in the following tables:

REFERENCE: CRSP_VARSTRING_T TYPE

Varying-length string F95 derived type CRSP_VARSTRING_T allows for flexible use of expandable character strings and complements the standard fixed-length F95 character type. The _VARSTRING_T string can be constructed from and converted into regular fixed-length string. The internals of the derived type handle the necessary storage allocation and provide public functions for expected basic string-related operations.

The CRSP_VARSTRING_T derived type is implemented in a separate F95 module crsp_f_varstring which is automatically included into crsp_f_itm_types module and should already be available in the program that uses CRSP F95 itm-API.

F95 MODULE	NAME	F95 TYPE	DESCRIPTION
crsp_f_varstring	CRSP_VARSTRING_T		varying-length character string
no public members

assignment (=)

INTERFACE

assignment(=)
left = right

DESCRIPTION

Extends assignment operator. Allows for construction, assignment and conversion of varying-length string, handled by internal elemental functions.

ARGUMENTS 1

type(CRSP_VARSTRING_T) :: left

type(CRSP_VARSTRING_T) :: right

ARGUMENTS 2

type(CRSP_VARSTRING_T) :: left

character(*) :: right

ARGUMENTS 3

character(*) :: left

type(CRSP_VARSTRING_T) :: right

RETURN VALUES

None

SIDE EFFECTS

Left variable gets assigned the value of the right variable. The left CRSP_VARSTRING_T variable will be re-initialized to accommodate the string value on the right.

PRECONDITIONS

Available heap memory necessary for dynamic allocation of the internal string storage.

EXAMPLE

type(CRSP_VARSTRING_T) ::vstr1, vstr2
character(LEN=10) :: fixstr = '1235'
 
vstr1 =  'TEST'
vstr 2 = fixstr
vstr1 = vstr2

LEN(vstr)

INTERFACE

LEN(vstr)

DESCRIPTION

Extends intrinsic LEN() function to operate on CRSP_VARSTRING_T strings. Returns the current allocated length of the stored string.

ARGUMENTS

type(CRSP_VARSTRING_T) :: vstr

RETURN VALUES

integer :: len

Length of the stored string. If string is not allocated, returned len=0.

SIDE EFFECTS

None

PRECONDITIONS

None

EXAMPLE

type(CRSP_VARSTRING_T) ::vstr
integer :: len
 
vstr = 'TEST'
len = LEN(vstr)

TRIM(vstr)

INTERFACE

TRIM(vstr)

DESCRIPTION

Extends intrinsic TRIM() function to operate on CRSP_VARSTRING_T strings. Returns [right] blank-trimmed stored string as fixed-length string.

ARGUMENTS

type(CRSP_VARSTRING_T) :: vstr

RETURN VALUES

character(*) :: fixstr

Fixed-length string resulting from the stored string with blanks trimmed from the right side.

SIDE EFFECTS

None

PRECONDITIONS

None

EXAMPLE

type(CRSP_VARSTRING_T) ::vstr
character(LEN=10) :: fixstr
 
fixstr='TEST'  !! is blank-padded to allocated length
vstr = fixstr
 
print *,'trimmed_str:[',TRIM(vstr),']'

CHAR(vstr)

INTERFACE

CHAR(vstr)

DESCRIPTION

Explicitly converts stored string into fixed-length string. Often used on string arguments to output statements (PRINT,WRITE)

ARGUMENTS

type(CRSP_VARSTRING_T) :: vstr

RETURN VALUES

character(*) :: fixstr – Fixed-length string from the stored string

SIDE EFFECTS

None

PRECONDITIONS

None

EXAMPLE

type(CRSP_VARSTRING_T) ::vstr
 
vstr = 'TEST'
 
print *,'vstr:[',CHAR(vstr),']'

crsp_f_vstr_free (str,stat)

PROTOTYPE

pure subroutine crsp_f_vstr_free (str,stat)

DESCRIPTION

Frees the internally allocated heap storage. Expected to be called by the user when the CRSP_VARSTRING_T variable goes out of its scope of use, so the allocated memory is released back to the process heap.

ARGUMENTS

type(CRSP_VARSTRING_T) :: vstr

integer, optional :: stat

Error code to indicate status of the operation:

• stat = 0 – SUCCESS
• stat = non-zero – FAILED

RETURN VALUES

None

SIDE EFFECTS

The error code is set to the stat variable when passed as argument.

PRECONDITIONS

None

EXAMPLE

type(CRSP_VARSTRING_T) ::vstr
integer :: errcd
 
vstr = 'TEST'
 
call crsp_fvstr_free(vstr,stat=errcd)
if (errcd /= 0) stop

crsp_f_vstr_init (str,len, stat)

PROTOTYPE

pure subroutine crsp_f_vstr_init (str,len, stat)

DESCRIPTION

Reserves internal storage to hold string of the specified length. Initialized the reserved string with blanks. Normally explicit call to this function is not required from user program as it's called internally by the defined assignment operators.

ARGUMENTS

type(CRSP_VARSTRING_T) :: vstr

resulting varying-length string

integer, intent(in) :: len

Reserved length of the string

integer, optional :: stat

Error code to indicate status of the operation:

• stat = 0 – SUCCESS
• stat = non-zero – FAILED

RETURN VALUES

None

SIDE EFFECTS

The error code is set to the stat variable when passed as argument.

PRECONDITIONS

Available heap memory necessary for dynamic allocation of the internal string storage.

EXAMPLE

type(CRSP_VARSTRING_T) ::vstr
integer :: errcd
 
call crsp_fvstr_init(vstr,10, stat=errcd)
if (errcd /= 0) stop