NAME: READ_ASCII_CMDLINE PURPOSE: Read data from an ASCII file into IDL. CATEGORY: Input/Output. CALLING SEQUENCE: data = READ_ASCII(file) INPUTS: file - Name of file to read. INPUT KEYWORD PARAMETERS: record_start - 1st sequential "record" (see DESCRIPTION) to read. Default = 0 (the first record of the file). num_records - Number of records to read. Default = 0 = Read up to and including the last record. template - ASCII file template (e.g., generated by function ASCII_TEMPLATE) describing attributes of the file to read. Specific attributes contained in the template may be overridden by keywords below. Default = (see the keywords below). start_line - Number of lines of header to skip. Default (if no template) = 0L. (NOTE: this keyword name has been changed from the IDL read_ascii routine. It was data_start.) delimiter - Character that delimits fields. Default (if no template) = '' = use fields(*).loc. missing_value - Value to replace any missing/invalid data. Default (if no template) = !VALUES.F_NAN. comment_symbol - String identifying comments (from comment_symbol to the next end-of-line). Default (if no template) = '' = no comments. field_types - An array of the field (column) IDL data type. This array can be either a string array or a long array. Example: ['string', 'double', 'double'] or [7,5,5]. Valid types are ['int', 'long', 'float', 'double', 'string', 'structure'] or [2, 3, 4, 5, 7, 8] field_names - An array of the names for each field or column. Default values are Field01, Field02, Field03, ..... Fieldnn. field_locations - An array of the start positions of each column. Default values are zero and the procedure will try to figure it out. field_groups - An array of fields that are common to a group. [Note: The 'fields' keyword has not been implemented yet.] fields - Descriptions of the data fields, formatted as an array of structures containing the tags: name = name of the field (string) type = type of field as returned by SIZE (long) loc = offset from the beginning of line to the start of the field (long) group = sequential group the field is in (int) Default (if no template) = {name:'field', type:4L, loc:0L, group:0}. verbose - If set, print runtime messages. Default = Do not print them. OUTPUT KEYWORD PARAMETERS: header - The header read (string array of length data_start). If no header, empty string returned. count - The number of records read. OUTPUTS: The function returns an anonymous structure, where each field in the structure is a "field" of the data read (see DESCRIPTION). If no records are read, 0 is returned. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: See DESCRIPTION. DESCRIPTION: ASCII files handled by this routine consist of an optional header of a fixed number of lines, followed by columnar data. Files may also contain comments, which exist between a user-specified comment string and the corresponding end-of-line. One or more rows of data constitute a "record." Each data element within a record is considered to be in a different column, or "field." Adjacent fields may be "grouped" into multi-column fields. The data in one field must be of, or promotable to, a single type (e.g., FLOAT). EXAMPLES: ; Using default file attributes. data = READ_ASCII(file) ; Setting specific file attributes. data = READ_ASCII(file, START_LINE=10) ; Using a template to define file attributes. data = READ_ASCII(file, TEMPLATE=template) ; Using a template to define file attributes, ; and overriding some of those attributes. data = READ_ASCII(file, TEMPLATE=template, START_LINE=10) ; Using the ASCII_TEMPLATE GUI to generate a template in place. data = READ_ASCII(file, TEMPLATE=ASCII_TEMPLATE(file)) [Note: The 'fields' keyword has not been implemented yet.] ; An example defining fields by hand. fields = REPLICATE({name:'', type:0L, loc:0L, group:0}, 2, 3) num = N_ELEMENTS(fields) fields(*).name = 'field' + STRTRIM(STRING(INDGEN(num) + 1), 2) fields(*).type = REPLICATE(4L, num) fields(*).loc = [0L,10L, 0L,15L, 0L,12L] fields(*).group = INDGEN(num) data = READ_ASCII(file, FIELDS=fields) [Note: The 'fields' keyword has not been implemented yet.] ; Another example defining fields by hand. void = {sMyStructName, name:'', type:0L, loc:0L, group:0} fields = [ [ {sMyStructName, 'frog', (SIZE(''))(1), 0L, 0}, $ {sMyStructName, 'bird', (SIZE(0 ))(1), 15L, 1} ], $ [ {sMyStructName, 'fish', (SIZE(0.))(1), 0L, 2}, $ {sMyStructName, 'bear', (SIZE(0D))(1), 15L, 3} ], $ [ {sMyStructName, 'boar', (SIZE(0B))(1), 0L, 4}, $ {sMyStructName, 'nerd', (SIZE(OL))(1), 15L, 5} ] ] data = READ_ASCII(file, FIELDS=fields) DEVELOPMENT NOTES: - See ???,xxx in the code. - Error check input 'delimiter' to be a string (not a byte). - Implement the 'fields' keyword. MODIFICATION HISTORY: AL & RPM, 8/96 - Written. PCS, 3/99 - Deploy STRTOK and other new commands. Gain some speed. CT, Aug 2003: Free up temp pointers if an error occurs. clrussell 10-01-12 - Added five keywords field_count, field_types, field_names, field_locations, field_groups. These keywords were added so the user could specify these mixed data types without having to use a template.