D-10375 STANDARD FORMATTED DATA UNIT SOFTWARE TOOL KIT VERSION 1.2 PROGRAMMER GUIDE October 27, 1993 This Page Intentionally Left Blank D-10375 STANDARD FORMATTED DATA UNIT SOFTWARE TOOL KIT VERSION 1.2 PROGRAMMER GUIDE October 27, 1993 Prepared by: SFDU SOFTWARE TOOL KIT DEVELOPMENT TEAM ________________________ Ronald A. Green ________________________ Mikael Aronsson Approved by: ________________________ J. Grimes SFDU System Engineer ________________________ C. Wong SFDU System Engineer Jet Propulsion Laboratory California Institute of Technology Pasadena, California Table of Contents 1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . 8 1.1 Identification. . . . . . . . . . . . . . . . . . . . 8 1.2 Overview. . . . . . . . . . . . . . . . . . . . . . . 8 1.3 Document Scope. . . . . . . . . . . . . . . . . . . . 8 1.4 Reading Approach. . . . . . . . . . . . . . . . . . . 8 1.5 Other Documents . . . . . . . . . . . . . . . . . . . 9 1.6 Acronyms and Abbreviations. . . . . . . . . . . . . . 9 2 TOOL KIT OVERVIEW. . . . . . . . . . . . . . . . . . . . . . 9 2.1 Parameter Value Language (PVL) Verifier Application. . . . . . . . . . . . . . . . . . . . . 10 2.2 PVL Libraries . . . . . . . . . . . . . . . . . . . . 10 2.3 MAP Language. . . . . . . . . . . . . . . . . . . . . 10 2.4 SFDU Library . . . . . . . . . . . . . . . . . . . . 10 2.5 WRAP Application . . . . . . . . . . . . . . . . . . 10 2.6 UNWRAP Application . . . . . . . . . . . . . . . . . 10 2.7 EXTRACT Application . . . . . . . . . . . . . . . . . 11 2.8 MACROGEN Application. . . . . . . . . . . . . . . . . 11 2.9 Software Distribution . . . . . . . . . . . . . . . . 11 2.10 Developers . . . . . . . . . . . . . . . . . . . . . 11 3 Tool Kit Development Approach and Philosophy . . . . . . . . 11 4 SAMPLE PROGRAMS. . . . . . . . . . . . . . . . . . . . . . . 14 4.1 Sample SFDU program . . . . . . . . . . . . . . . . . 14 4.1.1 Making the sample SFDU program . . . . . . . . 15 4.1.2 Running the sample SFDU program. . . . . . . . 16 4.2 Sample PVL program. . . . . . . . . . . . . . . . . . 18 4.2.1 Making the sample PVL program. . . . . . . . . 19 4.2.2 Running the sample PVL program . . . . . . . . 19 5 The SFDU Library . . . . . . . . . . . . . . . . . . . . . . 21 5.1 Library Organization. . . . . . . . . . . . . . . . . 21 5.1.1 UNWRAP library . . . . . . . . . . . . . . . . 21 5.1.2 WRAP library . . . . . . . . . . . . . . . . . 22 5.2 SFDU Library Constants. . . . . . . . . . . . . . . . 22 5.2.1 LVO LABEL CONSTANTS. . . . . . . . . . . . . . 22 5.2.2 LVO DELIMITATION CONSTANTS . . . . . . . . . . 23 5.2.3 LVO TYPE CONSTANTS . . . . . . . . . . . . . . 23 5.2.4 MAP LANGUAGE CONSTANTS . . . . . . . . . . . . 24 5.2.5 LVO VALUE CONSTANTS. . . . . . . . . . . . . . 24 5.2.6 REPLACEMENT (R) CLASS CONSTANTS. . . . . . . . 24 5.2.7 FILE TABLE CONSTANTS . . . . . . . . . . . . . 25 5.2.8 USER DEFINABLE CONSTANTS . . . . . . . . . . . 25 5.2.9 SFDU TYPE DEFINITIONS. . . . . . . . . . . . . 26 5.3 SFDU Data Structures. . . . . . . . . . . . . . . . . 26 5.3.1 LABEL structure. . . . . . . . . . . . . . . . 26 5.3.2 LVO structure. . . . . . . . . . . . . . . . . 27 5.3.3 FILE REFERENCE structure . . . . . . . . . . . 30 5.3.4 SFDU structure . . . . . . . . . . . . . . . . 31 5.3.5 SFDU FILE HANDLE structure . . . . . . . . . . 32 5.3.6 STACK structure. . . . . . . . . . . . . . . . 32 5.3.7 SFDU DESCRIPTION structure . . . . . . . . . . 33 5.3.8 The SFDU tree. . . . . . . . . . . . . . . . . 34 5.4 SFDU Library Function Highlights. . . . . . . . . . . 35 5.4.1 LABEL TOOLS (LBLTOOLS.C) . . . . . . . . . . . 36 5.4.1.1 lbl_parse_sfdu_label. . . . . . . . . . 38 5.4.1.2 lbl_get_class_type. . . . . . . . . . . 38 5.4.1.3 lbl_get_delim_type. . . . . . . . . . . 38 5.4.1.4 lbl_get_value_type. . . . . . . . . . . 39 5.4.1.5 lbl_descriptor_id . . . . . . . . . . . 39 5.4.1.6 lbl_description_text. . . . . . . . . . 39 5.4.2 VALUE TOOLS (VALTOOLS.C) . . . . . . . . . . . 41 5.4.2.1 val_compute_length. . . . . . . . . . . 42 5.4.2.2 val_check_adid_spec . . . . . . . . . . 42 5.4.2.3 val_validate_data_admin_stmts . . . . . 42 5.4.2.4 val_validate_reference_stmts. . . . . . 43 5.4.2.5 val_check_DDU_value . . . . . . . . . . 43 5.4.2.6 val_check_IDU_value . . . . . . . . . . 44 5.4.3 BUILD / PARSE SFDU (BLDSFDU.C) . . . . . . . . 45 5.4.3.1 bld_parse_n_lvos. . . . . . . . . . . . 47 5.4.3.2 bld_parse_next_lvo. . . . . . . . . . . 47 5.4.3.3 bld_set_up_PVL_tree . . . . . . . . . . 47 5.4.4 SFDU TOOLS (SFDUTOOL.C). . . . . . . . . . . . 49 5.4.4.1 sfd_initialize_sfdu . . . . . . . . . . 50 5.4.4.2 sfd_get_next_lvo. . . . . . . . . . . . 50 5.4.4.3 sfd_display_lvo_summary_report. . . . . 50 5.4.5 MAP LANGUAGE TOOLS (MAPLTOOL.C). . . . . . . . 51 5.4.5.1 mapl_create_sfdu_from_map . . . . . . . 52 5.4.6 CREATE LVO TOOLS (CREATLVO.C). . . . . . . . . 53 5.4.6.1 create_wrapped_sfdu_file. . . . . . . . 55 5.4.6.2 create_CCSDS_standard_label . . . . . . 55 5.4.6.3 create_version3_label . . . . . . . . . 55 5.4.7 CREATE DATA OBJECTS (CREATDAT.C) . . . . . . . 56 5.4.7.1 create_unwrapped_files. . . . . . . . . 57 5.4.7.2 create_set_up_base_file_name. . . . . . 57 5.4.8 CREATE MAP LANGUAGE FILES (CREATMAP.C) . . . . 58 5.4.8.1 create_map_file . . . . . . . . . . . . 59 5.4.8.2 create_map_statements . . . . . . . . . 59 5.4.9 SFDU FILE TABLE TOOLS (SFDUFTBL.C) . . . . . . 60 5.4.9.1 ftbl_read_sfdu_data . . . . . . . . . . 60 5.4.10 PROGRAM OUTPUT MESSAGES (UTILMSG.C) . . . . . 62 5.4.10.1 util_print_message . . . . . . . . . . 63 5.4.10.2 util_print_error . . . . . . . . . . . 63 5.4.10.3 util_toggle_warnings . . . . . . . . . 63 5.4.10.4 util_toggle_messages . . . . . . . . . 64 5.4.10.5 util_inquire_toggle. . . . . . . . . . 64 5.4.10.6 util_open_message_file . . . . . . . . 64 5.4.10.7 util_close_message_file. . . . . . . . 64 5.4.11 UTILITY FUNCTIONS (UTILITY.C) . . . . . . . . 66 5.4.11.1 util_do_malloc . . . . . . . . . . . . 67 5.4.11.2 util_file_reference_copy . . . . . . . 67 5.4.12 SFDU OPERATION FUNCTIONS (SFDUOPS.C). . . . . 68 5.4.12.1 ops_change_delim_to_length . . . . . . 70 5.4.12.2 ops_change_lvo_file_value. . . . . . . 70 5.4.12.3 ops_change_lvo_buffer_value. . . . . . 70 5.4.12.4 ops_create_lvo_from_buffer_data. . . . 70 5.4.12.5 ops_create_lvo_from_file_data. . . . . 71 5.4.12.6 ops_create_structure_lvo . . . . . . . 71 5.4.12.7 ops_delete_lvo_from_sfdu . . . . . . . 72 5.4.12.8 ops_insert_lvo_into_sfdu . . . . . . . 72 5.4.12.9 ops_copy_lvo_value_to_buffer . . . . . 72 5.4.12.10 ops_copy_lvo_value_to_file. . . . . . 73 5.4.12.11 ops_get_sfdu_structure_from_file. . . 73 5.4.13 COMPARE LVOs (LVOCMPRE.C) . . . . . . . . . . 74 5.4.13.1 compare_lvos . . . . . . . . . . . . . 74 5.5 Error Handling. . . . . . . . . . . . . . . . . . . . 76 5.6 SFDU Function Summary . . . . . . . . . . . . . . . . 77 6 PVL Library. . . . . . . . . . . . . . . . . . . . . . . . . 81 6.1 PVL Library Constants . . . . . . . . . . . . . . . . 81 6.2 PVL Data Structures . . . . . . . . . . . . . . . . . 82 6.2.1 The leaf Structure . . . . . . . . . . . . . . 82 6.2.2 The Value_and_Type Structure . . . . . . . . . 85 6.2.3 The list Structure . . . . . . . . . . . . . . 86 6.3 PVL Library Function Highlights . . . . . . . . . . . 87 6.3.1 PVL Top Level Function Summary . . . . . . . . 87 6.3.2 Parse Calls (PARSCALL.C) . . . . . . . . . . . 90 6.3.2.1 parse_file. . . . . . . . . . . . . . . 92 6.3.2.2 parse_buffer. . . . . . . . . . . . . . 92 6.3.3 Statement Operations (TOPLEVEL.C). . . . . . . 94 6.3.3.1 stmt_to_string. . . . . . . . . . . . . 95 6.3.3.2 get_stmt_value. . . . . . . . . . . . . 95 6.3.3.3 create_statement. . . . . . . . . . . . 95 6.3.3.4 create_aggregation. . . . . . . . . . . 96 6.3.3.5 create_pvl_object . . . . . . . . . . . 96 6.3.3.6 add_statement . . . . . . . . . . . . . 96 6.3.3.7 add_sub_stmt. . . . . . . . . . . . . . 97 6.3.3.8 delete_statement. . . . . . . . . . . . 97 6.3.3.9 insert_statement. . . . . . . . . . . . 97 6.3.3.10 move_statement . . . . . . . . . . . . 98 6.3.4 Get Statement Data (TOPLEVEL.C). . . . . . . . 99 6.3.4.1 get_keyword . . . . . . . . . . . . . . 99 6.3.4.2 get_aggregation_tag . . . . . . . . . . 99 6.3.4.3 get_value_string. . . . . . . . . . . . 99 6.3.4.4 get_stmt_value_type . . . . . . . . . . 99 6.3.4.5 is_aggregation. . . . . . . . . . . . .100 6.3.5 Change Statement Data (TOPLEVEL.C). . . . . .101 6.3.5.1 change_keyword. . . . . . . . . . . . .101 6.3.5.2 change_value. . . . . . . . . . . . . .101 6.3.5.3 change_aggregation_keyword. . . . . . .101 6.3.5.4 change_aggregation_tag. . . . . . . . .102 6.3.5.5 change_one_units. . . . . . . . . . . .102 6.3.5.6 change_all_matched_units. . . . . . . .102 6.3.6 Count Statements (TOPLEVEL.C). . . . . . . . .104 6.3.6.1 count_statements. . . . . . . . . . . .104 6.3.6.2 count_substmts. . . . . . . . . . . . .104 6.3.6.3 count_aggregations. . . . . . . . . . .104 6.3.6.4 count_sub_aggrs . . . . . . . . . . . .104 6.3.7 Search Statements (TOPLEVEL.C) . . . . . . . .106 6.3.7.1 search_name . . . . . . . . . . . . . .106 6.3.7.2 next_matched_aggr . . . . . . . . . . .106 6.3.7.3 search_nth_matched_aggr . . . . . . . .106 6.3.7.4 search_nth_substmt. . . . . . . . . . .107 6.3.7.5 search_parent_aggregation . . . . . . .107 6.3.7.6 predecessor . . . . . . . . . . . . . .107 6.3.7.7 successor . . . . . . . . . . . . . . .108 6.3.8 List Operations (LISTOPS.C). . . . . . . . . .109 6.3.8.1 add_list_element. . . . . . . . . . . .111 6.3.8.2 append_list_element . . . . . . . . . .111 6.3.8.3 change_list_element . . . . . . . . . .111 6.3.8.4 create_list_element . . . . . . . . . .111 6.3.8.5 delete_list_element . . . . . . . . . .112 6.3.8.6 insert_list_element . . . . . . . . . .112 6.3.8.7 count_list_elements . . . . . . . . . .113 6.3.8.8 get_list_element_type . . . . . . . . .113 6.3.8.9 get_list_element_value. . . . . . . . .113 6.3.8.10 get_nth_list_element_value . . . . . .113 6.3.8.11 point_nth_list_element . . . . . . . .114 6.4 Low level routines. . . . . . . . . . . . . . . . . .115 6.4.1 Low Level Parser Support Functions (LEAFOPS1.C). . . . . . . . . . . . . . . . . .115 6.4.1.1 make_leaf . . . . . . . . . . . . . . .115 6.4.1.2 attach_leaf_to_end. . . . . . . . . . .115 6.4.1.3 make_aggregation_branch . . . . . . . .115 6.4.1.4 dump_report . . . . . . . . . . . . . .115 6.4.1.5 new_list. . . . . . . . . . . . . . . .115 6.4.1.6 attr_list . . . . . . . . . . . . . . .115 6.4.2 Additional Low Level Routines (LEAFOPS2.C) . .116 6.4.2.1 kill_leaf . . . . . . . . . . . . . . .116 6.4.2.2 kill_tree . . . . . . . . . . . . . . .116 6.4.2.3 append_leaf . . . . . . . . . . . . . .116 6.4.2.4 detach_leaf . . . . . . . . . . . . . .116 6.4.2.5 insert_leaf . . . . . . . . . . . . . .116 6.4.2.6 tree_copy . . . . . . . . . . . . . . .116 6.4.2.7 previous_pointer. . . . . . . . . . . .116 6.5 PVL Error Handling. . . . . . . . . . . . . . . . . .116 1 INTRODUCTION 1.1 Identification This document is the Programmer's Guide for the Standard Formatted Data Unit (SFDU) Software Tool Kit. The information contained in this document is applicable to Phase I of the development effort. 1.2 Overview The SFDU Software Tool Kit is a collection of software libraries and applications that will allow users the ability to implement data format standards as specified by the Consultative Committee for Space Data Systems (CCSDS). 1.3 Document Scope This document is intended for two classes of users. The first group of users, Library Users, are those interested in incorporating the SFDU functionality into their code. A good amount of detail on internal structures and processing is presented so the user can gain an understanding of how the code works. The second group of users, Developers, are those who will be modifying the Tool Kit libraries and code to work in certain hardware and software environments. Specific areas where changes may be necessary are called out in the document. The document assumes all readers are familiar with the SFDU concept as presented by the CCSDS and has knowledge of the C programming language, operating systems, and makefiles. 1.4 Reading Approach This document presents as much information as possible that may be of use to the intended audiences. There are certain sections that can be skipped if the reader does not need the information contained in the section. The reader can review this section for the appropriate sections to read. If you are unfamiliar with the Tool Kit, the Tool Kit Overview (Section 2) provides a top level look at components of the Tool Kit. Once familiar with the components of the Tool Kit, the sample programs contained in section 4 are practical programming examples on how to use the Tool Kit libraries. The SFDU Library and PVL Library sections provide information on their respective functions. These Library sections consist of details on source code organization, library constants and data structures, and function highlights. The Library Function highlights sections should be of interest to application developers. These sections document the interface to each high level function in the library. This information can be used to check the syntax of function calls, parameters, return values, and other pertinent information. 1.5 Other Documents 1) STANDARD FORMATTED DATA UNIT SOFTWARE TOOL KIT USER'S GUIDE, Ron Green; Mikael Aronsson, October 1993 2) STANDARD FORMATTED DATA UNIT SOFTWARE TOOL KIT SOFTWARE SPECIFICATION DOCUMENT, Ron Green; Norbert Piega, June 1991 3) RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, STANDARD FORMATTED DATA UNITS -- STRUCTURE AND CONSTRUCTION RULES BLUE BOOK Consultative Committee for Space Data Systems (CCSDS) May 1992 4) RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, PARAMETER VALUE LANGUAGE SPECIFICATION (CCSD0006) BLUE BOOK Consultative Committee for Space Data Systems (CCSDS) May 1992 5) RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, STANDARD FORMATTED DATA UNITS -- A TUTORIAL - GREEN BOOK Consultative Committee for Space Data Systems (CCSDS) May 1992 1.6 Acronyms and Abbreviations ADID - Authority Description Identifier CAID - Control Authority Identifier CCSDS - Consultative Committee for Space Data Systems DDID - Data Description Identifier DDU - Description Data Unit IDU - Information Data Unit LVO - Label Value Object PVL - Parameter Value Language SFDU - Standard Formatted Data Unit 2 TOOL KIT OVERVIEW The Standard Formatted Data Unit (SFDU) Software Tool Kit consists of the following eight components: PVL Verifier, PVL Library, SFDU Library, WRAP application, UNWRAP application, EXTRACT application, the MAP Language, and MACROGEN (MAP Language Macro generator) application. The libraries are of the most interest here since they are used to create the applications and are a major focus of this document. Information on usage of the applications can be found in the SFDU Software Tool Kit User's Guide. 2.1 Parameter Value Language (PVL) Verifier Application This application program can be used to parse and verify PVL statements contained in files. This is useful in checking the syntax of Map Language files used in conjunction with the WRAP application of the Tool Kit. 2.2 PVL Libraries The PVL Libraries are a collection of C functions that can be integrated into user applications. These functions were also used to create the PVL Verifier Application. 2.3 MAP Language The MAP Language, based on the PVL syntax, is used to describe SFDUs. PVL statements are contained in MAP files which provide input to the WRAP program on how to create the SFDU. The PVL statements that make up this language are described in Appendix A of the SFDU Tool Kit User's Guide. 2.4 SFDU Library The SFDU Library is a collection of C functions that can be linked into user applications to create and manipulate SFDUs. These functions have also been used to create the WRAP and UNWRAP applications of the Tool Kit. 2.5 WRAP Application WRAP is an application program that can be used to wrap individual data files (catalog data, application data, etc.) into Standard Formatted Data Units. The application makes use of user-specified Map Language statements to build the SFDU. 2.6 UNWRAP Application UNWRAP is an application program that can be used to unwrap data files from Standard Formatted Data Units. UNWRAP removes all SFDU related information (labels, markers, etc.) and leaves the original data that was used to create the SFDU. 2.7 EXTRACT Application The EXTRACT program is a stand alone application that can be used to extract specified data objects from Standard Formatted Data Units. EXTRACT removes all SFDU related information (labels, markers, etc.) and leaves the original data (of specified class) that was used to create the SFDU. 2.8 MACROGEN Application The MACROGEN program can be used to create Map Language macros from generic Map Language files. The macros can then be used to create specific SFDUs (via the WRAP application) that have the same structure as described by the macro statements. 2.9 Software Distribution Copies of the software can be obtained from the ftp anonymous account on binky.jpl.nasa.gov under the pub/sfdutool/current directory. A tar file of all needed files is in the /pub/sfdutool/current/tar directory. There is also a failure report form which can be utilized to report problems. Procedures for reporting problems/questions etc. are contained in the README file contained in the /pub/sfdutool directory. 2.10 Developers In some of the function headers contained in this document, initials are listed next to the change descriptions made. The initials and actual names are as follows. RAG Ron Green / JPL NLP Norbert Piega / JPL MA Mike Aronsson / JPL DW Dave Wagner / JPL (PVL only) 3 Tool Kit Development Approach and Philosophy The development approach of the SFDU Software Tool Kit was to organize functions into separate stand-alone components. One of the main goals of the development is to keep the interdependence between these components at a minimum. Therefore, if a certain component or tool needs to be replaced, only that portion of the Tool Kit is replaced. The separation of components is evident by the use of the libraries (SFDU and PVL). The PVL Library is utilized by the SFDU Library to handle the PVL objects contained in the SFDU. For example, the SFDU will process REPLACEMENT (R) and DATA ADMINISTRATION (C) Class LVOs. If the SFDUs an application processes do not contain these types of LVOs, the SFDU Library can be modified to disable the PVL function calls. In another scenario, the PVL function calls could be replaced with other PVL compatible functions from another source. More separation can be found in the libraries themselves as they consist of libraries based on functionality. For example, the SFDU Library contains a library for WRAP functionality and another for UNWRAP functionality. Applications can make use of these libraries based on the functionality needed. The PVL Library is divided into top level and lower level support functions. The Figure on the next page shows a functional overview of the Tool Kit. The diagram shows how the various tools interact with each other to create data objects, MAP files, SFDUs etc. For example, the BUILD/PARSE tools make use of the LABEL and VALUE tools to create the SFDU tree. The MAP LANGUAGE PROCESSING tools also create the SFDU tree. Once the SFDU tree is created, various data objects can be created and extracted. Note that the PVL processing tools are a separate component that can be removed and replaced. Insert Picture here!!!!!!!!!!!!!!!!!!!! 4 SAMPLE PROGRAMS Some sample programs utilizing the Tool Kit libraries are presented in this section. The purpose of this code is to provide the application developer with specific examples to dissect before reviewing the details of the Tool Kit libraries. The source code and data files are contained in the distribution. Check section 2.9 for details. 4.1 Sample SFDU program The following sample program utilizes the SFDU Tool Kit library to print the labels found in an SFDU. Sections of the program are numbered on the right hand side with comments provided at the end of the listing. /* ** lvo.h is the main include file for the SFDU Library ** It contains structure definitions, defines, and typedefs */ #include "lvo.h" (1) #include #include /* Prototypes */ #ifdef DOS (2) #include "sfdutool.h" #include "bldsfdu.h" #endif void main(argc, argv) unsigned int argc ; char *argv[] ; { SFDU * sfdu ; (3) LVO * lvo ; int status ; int lvos_parsed ; if (argc != 2) { printf("USAGE: showlbls \n") ; exit(0) ; } sfdu = (SFDU *) sfd_initialize_sfdu(argv[1]) ; (4) (5) lvos_parsed = bld_parse_n_lvos(sfdu, 0, &status) ; printf("\n\nNumber of Label-Value Objects parsed: %d\n", lvos_parsed) ; (6) lvo = sfdu->head_lvo ; while (lvo != NULL) { printf("CLASS: %c LABEL: %.20s\n", lvo->label->class_id, lvo->label->string) ; lvo = (LVO *) sfd_get_next_lvo(lvo, FALSE) ; } return(0) ; } /* main */ Below are explanations of the sections numbered above : (1) lvo.h contains the structure and type definitions described in section 5.3 of this document. It also contains most of the preprocessor defines used in the SFDU Tool Kit. (2) The dot h (.h) files included here contain the function prototypes for the SFDU library functions used in this sample program. (3) Variable declarations. The types SFDU and LVO are discussed in section 5.3 of this document. (4) Allocate a SFDU structure and prepare to store data from the SFDU file by initializing the SFDU structure fields. The SFDU file is specified in the command line as argv[1]. (5) Call bld_parse_n_lvos to parse out the LVOs from sfdu. bld_parse_n_lvos is passed the sfdu structure that contains the SFDU file pointer, the number n = 0 which tells it to parse the entire SFDU, and a status variable which it modifies. The number of LVOs parsed successfully is returned by bld_parse_n_lvos and is printed in this program. (6) The while loop prints the labels of all the LVOs found in the SFDU tree. Note that the first LVO in the SFDU is pointed to by sfdu->head_lvo. Succeeding LVOs in the SFDU tree are obtained by calling sfd_get_next_lvo. sfd_get_next_lvo is passed the current LVO and a flag which tells it whether to include R class LVOs when searching - FALSE signifies skip R classes. 4.1.1 Making the sample SFDU program Assuming the sample program above is stored in a file "showlbls.c", the program may be compiled and linked by simply typing the following on the command line : UNIX COMMAND: make -D SFDUPROG=showlbls DOS COMMAND: make -fsfdulib.mak -DDRIVE=d: -DSFDUPROG=showlbls.exe where sfdulib.mak is the make filename, d: is the drive containing the SFDU source files, libraries, and the sample program. Note that the value of SFDUPROG may also be assigned by editing the make file. You can modify the value of SFDUPROG to "showlbls" then type the following on the command line : UNIX COMMAND: make showlbls DOS COMMAND: make -fsfdulib.mak -DDRIVE=d: showlbls.exe The sample program is compiled and linked with the SFDU library and an executable file called "showlbls" ("showlbls.exe" in DOS) is created. The -DDRIVE=d: option is a definition indicating where the Borland C/Turbo C compiler is located. It may not be necessary if the compiler is in the current path. 4.1.2 Running the sample SFDU program To run the sample program, type "showlbls sfdufile" on the command line where sfdufile is the name of an SFDU file. Note that bld_parse_n_lvos already prints each label as it parses the LVOs in the SFDU file. The sample SFDU program shows how the labels may be accessed after they are stored in an SFDU tree. As an example, showlbls may be run on the following SFDU contained in file "sample.sfd". CCSD3ZS00001AAAAAAAANJPL3KS0L015BBBBBBBB MISSION_NAME=MARS_OBSERVER; MISSION_ID=5; SPACECRAFT_NAME=MARS_OBSERVER1; SPACECRAFT_ID=94; DATA_SET_ID=LIGHTTIME; FILE_NAME=/nav/stuart/odp/sfdu/test/lite; PRODUCER_ID=NAV; APPLICABLE_START_TIME=1992-261T00:00:00.000; APPLICABLE_STOP_TIME=1992-262T23:00:00.000; PRODUCT_CREATION_TIME=1990-205T11:34:04; CCSD$$MARKERBBBBBBBBNJPL3IS00351CCCCCCCC$$ LIGHT TIME FILE 1 *LITIME OWLTM( ) 2 *PREP 3 *TITLE 4 *SCID M 5 *RUNID Enter LITIME 24-JUL-1990 11:34:04 linked 9-MAR-1990 14:2 6 *CREATION JPL 90-205/11:34:04 7 *BEGIN SCE 92-261/00:00:00.000 ERT 92-261/00:00:56.472 8 *CUTOFF SCE 92-262/23:00:00.000 9 *PFILE 10 ' SCE DOWN-LEG UP-LEG RUN TIME S 11 $$EOS 12 92-262/05:00:00 1.662 1.663 03 900724113404M 42 92-262/06:00:00 1.707 1.708 03 900724113404M 43 92-262/07:00:00 1.752 1.752 03 900724113404M 44 92-262/08:00:00 1.797 1.797 03 900724113404M 45 92-262/09:00:00 1.841 1.842 03 900724113404M 46 92-262/10:00:00 1.886 1.886 03 900724113404M 47 92-262/11:00:00 1.930 1.931 03 900724113404M 48 92-262/12:00:00 1.975 1.975 03 900724113404M 49 92-262/13:00:00 2.019 2.020 03 900724113404M 50 92-262/14:00:00 2.064 2.064 03 900724113404M 51 92-262/15:00:00 2.108 2.108 03 900724113404M 52 92-262/16:00:00 2.152 2.153 03 900724113404M 53 92-262/17:00:00 2.197 2.197 03 900724113404M 54 92-262/18:00:00 2.241 2.241 03 900724113404M 55 92-262/19:00:00 2.285 2.285 03 900724113404M 56 92-262/20:00:00 2.329 2.329 03 900724113404M 57 92-262/21:00:00 2.373 2.374 03 900724113404M 58 92-262/22:00:00 2.417 2.418 03 900724113404M 59 92-262/23:00:00 2.461 2.462 03 900724113404M 60 $$EOF 61 CCSD$$MARKERCCCCCCCCCCSD$$MARKERAAAAAAAA The output created after typing "showlbls sample.sfd" on the command line would be : Parsing SFDU: \sfdu\test\maps\sample.sfd 1 Parsing SFDU (Z) object (CCSD0001).... 2 Parsed CATALOGUE_DATA (K) object (NJPLL015) 2 Parsed APPLICATION_DATA (I) object (NJPL0351) Number of Label-Value Objects parsed: 3 CLASS: Z LABEL parsed: CCSD3ZS00001AAAAAAAA CLASS: K LABEL parsed: NJPL3KS0L015BBBBBBBB CLASS: I LABEL parsed: NJPL3IS00351CCCCCCCC 4.2 Sample PVL program #include /* ** stmtops.h is the main include file for the PVL Library ** It contains structure definitions and typedefs */ #include "stmtops.h" (1) int main(argc, argv) unsigned int argc ; char *argv[] ; { Statement top_stmt ; (2) Statement my_stmt ; if (argc != 2) { printf("USAGE: add1stmt \n") ; exit(0) ; } top_stmt = (Statement) parse_file(argv[1]) ; (3) (4) my_stmt = (Statement) create_statement("sampleK", "sampleV", "") ; (5) top_stmt = (Statement) add_statement(top_stmt, my_stmt) ; top_stmt = (Statement) renumber(top_stmt) ; (6) dump_report(top_stmt) ; (7) return(0) ; } /* main */ (1) stmtops.h contains the structure definitions discussed in section 6.2 of this document. (2) Declarations. Two statement objects are declared in this sample program. (3) The PVL file specified in the command line through argv[1] is parsed by parse_file and parse_file returns its corresponding PVL tree. The tree starts at top_stmt, the first statement. (4) A new statement object with the keyword "sampleK", value string "sampleV" and empty unit string is created and assigned to my_stmt. (5) my_stmt is added to the PVL tree as the last statement in the tree. (6) renumber updates the statement number fields of the statements in the PVL tree. This is performed here since add_statement does not update the statement numbers. (7) dump_report prints the contents of the PVL tree in "keyword = value" form with statement numbers. 4.2.1 Making the sample PVL program The procedure for making and running the sample PVL program is similar to the procedure for making and running the sample SFDU program. Assuming the sample program above is stored in a file "add1stmt.c", the program may be compiled and linked by typing the following on the command line : UNIX COMMAND: make -D PVLPROG=add1stmt DOS COMMAND: make -fsfdulib.mak -DDRIVE=d: -DPVLPROG=add1stmt.exe where sfdulib.mak is the make filename, d: is the drive containing the SFDU source files, libraries and the sample program. The value of PVLPROG may also be assigned by modifying it in the make file to "add1stmt" then typing the following on the command line : UNIX COMMAND: make add1stmt DOS COMMAND: make -fsfdulib.mak -DDRIVE=d: add1stmt.exe The sample program is compiled and linked with the PVL library and an executable file called "add1stmt" ("add1stmt.exe" in DOS) is created. _^É Running the sample PVL program To run the sample program, type "add1stmt pvlfile" on the command line where pvlfile is the name of a PVL file. For example, the following statements may be stored in a file named "sample.pvl". FIRST = simple_statement SECOND = non_AGGREGATION BEGIN_OBJECT = sample THIS = is_an excellent = EXAMPLE END_OBJECT LAST = PRIOR_TO_ADDITION The output created when you type "add1stmt sample.pvl" on the command line would be : stmt:1 FIRST = simple_statement stmt:2 SECOND = non_AGGREGATION stmt:3 AGGREGATION OBJECT = sample stmt:4 THIS = is_an stmt:5 excellent = EXAMPLE END OBJECT = sample stmt:6 LAST = PRIOR_TO_ADDITION stmt:7 sampleK = sampleV It should be noted the "END OBJECT = sample" statement is not a numbered statement because it signals the end of the "sample" aggregation. When accessing each statement of this PVL tree, there would be no way to access the END OBJECT statement. 5 The SFDU Library The SFDU Library contains functions for creating and manipulating SFDUs. There are also functions for the extraction of data from SFDUs. These functions operate primarily on data structures that represent SFDUs, LVOs, and LABELs. The Libraries of Tool Kit were designed to support processing of multiple SFDUs. Although the applications provided in the Tool Kit operate on one SFDU at a time, new applications can be developed with the libraries to handle more than one SFDU. For example, appending two SFDUs together, comparison of SFDUs, etc. 5.1 Library Organization The SFDU Library is composed of three library files. The first library is the SFDU Library or UNWRAP (SFDU.LIB) library. This library contains the functions used for parsing SFDUs and extracting data from SFDUs. The second library is the WRAP (WRAP.LIB) library which contains functions for wrapping data into SFDUs. These libraries are used to create the UNWRAP and WRAP applications. The third library, SFDU OPERATIONS (SFDUOPS.LIB) contains functions for creating, modifying, and deleting LVOs and SFDUs. The functions are general purpose and are intended for user developed applications. None of the Tool Kit Applications make use of the SFDU OPERATIONS library. The first two libraries (UNWRAP and WRAP) were used to reduce the size of linked code into Tool Kit applications. For example, the UNWRAP application does not need code to WRAP an SFDU. Therefore, the functions needed explicitly for WRAP applications are not included in the SFDU Library. This library scheme should help limit the size of the user developed applications. If code size is not an issue to developers and the functionality of both libraries is desired, the two libraries can be combined into one. Future releases of the Tool Kit will always try to be conscious of library size. The next two sections indicate which source files make up the libraries. The functions of interest in each source file can be found in Section 5.4. 5.1.1 UNWRAP library The UNWRAP library contains functions that support the parsing of SFDUs and generation of unwrapped data files. The object files that make up the UNWRAP library include lbltools.obj valtools.obj bldsfdu.obj sfdutool.obj creatlvo.obj sfduftbl.obj creatmap.obj creatdat.obj utility.obj utilmsg.obj The actual filename of the UNWRAP library is SFDU.LIB on the DOS machines and SFDULIB.A on the UNIX machines. The extensions of the objects files also differ from machine to machine. Check the makefiles contained in the distribution for other details. 5.1.2 WRAP library The WRAP library contains functions that support generation of SFDUs. It includes functions for interpreting Map Language statements which are used to define the SFDUs. The object files that make up the library include: utility.obj utilmsg.obj lbltools.obj valtools.obj sfduftbl.obj creatlvo.obj mapltool.obj sfdutool.obj The actual filename of the WRAP library is WRAP.LIB on the DOS machines and WRAPLIB.A on the UNIX machines. Check the makefiles contained in the distribution for other details. 5.2 SFDU Library Constants The constants that are used throughout the SFDU source code are defined in the header file LVO.H. Some of the more important defines are listed here because they are used in the definition of the Data Structures. Since these constants are a part of the data structures, they should not be changed. There is, however, a table of User Definable Constants that can be modified in Section 5.2.8. Review the entire LVO.H file for all definitions. 5.2.1 LVO LABEL CONSTANTS These constants describe where certain elements are contained in the 20 byte CCSDS Label. #define LABEL_LENGTH 20 /* Label length: Num of bytes */ /* BYTE positions within label fields */ #define START_CAID 0 /* starting CAID byte position */ #define END_CAID 3 /* ending CAID byte position */ #define CAID_LENGTH 4 /* length of CAID field */ #define VERSION_BYTE 4 /* Version byte position */ #define CLASS_ID_BYTE 5 /* Class ID byte position */ #define SPARE_1_BYTE 6 /* Spare 1 byte position */ #define SPARE_2_BYTE 7 /* Spare 2 byte position */ #define START_DDID 8 /* starting DDID byte position */ #define END_DDID 11 /* ending DDID byte position */ #define DDID_LENGTH 4 /* length of DDID field */ #define START_DELIM_PARAM 12 /* starting Delimitation Parameter byte position */ #define END_DELIM_PARAM 19 /* ending Delimitation Parameter byte position */ #define DELIM_PARAM_LENGTH 8 /* length of Delimitation Parameter field */ 5.2.2 LVO DELIMITATION CONSTANTS These constants are used to describe the delimitation methods of the LVO. These constants are used directly in the formation of LABELs as well as tests for delimitation methods. #define UNKNOWN_DELIMITATION 0 #define ASCII_LENGTH 'A' #define BINARY_LENGTH 'B' /* Length */ #define MARKER 'S' /* Marker Pattern used */ #define NUM_EOFS 'E' /* Number of EOFs */ #define CONTIG_EOFS 'C' /* Number of contiguous EOFs */ #define SHARED_EOF 'F' /* One EOF */ 5.2.3 LVO TYPE CONSTANTS These constants associate meaningful names to the LVO IDs. These names are used solely for the purpose of adding readability to the source code. There are also constants for the various types of LVOs (structure, service, and data). #define LVO_COUNT 11 #define SFDU_DATA 'Z' #define INFORMATION_DATA_UNIT 'U' #define DESCRIPTION_DATA_UNIT 'F' #define DATA_ADMINISTRATION 'C' #define REPLACEMENT_DATA 'R' #define APPLICATION_DATA 'I' #define SUPPLEMENTARY_DATA 'S' #define DATA_DESCRIPTION 'D' #define DATA_ENTITY 'E' #define CATALOG_DATA 'K' #define VOLUME_DATA 'V' /* Valid Class Types */ #define UNKNOWN_CLASS 0 /* Class ID or TYPE unknown */ #define STRUCTURE_CLASS 1 /* Class Type Structure class */ #define SERVICE_CLASS 2 /* Class Type Service class */ #define DATA_CLASS 3 /* Class Type Data class */ 5.2.4 MAP LANGUAGE CONSTANTS These constants provide readability for the various Map Language Statements. /* Map Language Statement Ids */ #define ADID_STMT 1 #define DELIM_STMT 2 #define INCLUDE_FILE_STMT 3 #define REFERENCE_FILE_STMT 4 #define PRE_DELIM_STMT 5 #define PAD_STMT 6 /* PRE or POST Value data delimiters */ #define CR 13 #define LF 10 #define SEMICOLON 59 #define SPACE 32 5.2.5 LVO VALUE CONSTANTS The LVO VALUE constants are definitions for the type of value stored and how the value is stored. In some cases both the type and storage are the same. For example, a SFDU (Z) Class LVO has a value of LVO_TYPE and it is stored as an LVO TYPE (pointer to another LVO structure). #define UNKNOWN_VALUE 0 #define BUFFER_TYPE 1 /* value contained in LVO buffer */ #define PVL_TYPE 2 /* value contains PVL data */ #define REFERENCE_TYPE 3 /* value is stored in a file */ #define LVO_TYPE 4 /* value is an LVO */ #define ENGLISH_TEXT_TYPE 5 /* value is English text */ #define VALUE_BUFSIZ 524288 /* LVO Buffer size */ #define MARKER_LENGTH 20 /* Length of an LVO marker */ #define LEAD_MARKER_LENGTH 12 /* Length of CCSD$$MARKER */ The VALUE_BUFSIZ of 524288 (512K) applies to the SUN/UNIX platform. DOS platforms use a buffer size of 16384 (16K). 5.2.6 REPLACEMENT (R) CLASS CONSTANTS The REPLACEMENT CLASS CONSTANTS are used to describe the reference objects in the REPLACEMENT (R) Class LVO. File name length, number of directory levels, etc., are described here /* R CLASS REFERENCE TYPES/FILE TYPES */ #define UNKNOWN_KEYWORD_VALUE -1 #define CCSDS1 0 #define CCSDS2 1 #define DOS_FILE 2 #define UNIX_FILE 3 /* R CLASS REFERENCE FILE LENGTHS/MAX_DIRECTORIES */ #define CCSDS1_LENGTH 8 #define CCSDS1_EXT 3 #define CCSDS2_LENGTH 30 #define MAX_REF_DIRECTORIES 8 /* SFDU STACK SIZE */ #define STACK_SIZE 10 /* SFDU Stack Size Limit */ 5.2.7 FILE TABLE CONSTANTS The File Table constants are used to set the access modes and status of each file contained in the File Table structure. #define CLOSED 0 #define OPEN 1 #define SFDU_WRITE 1 #define SFDU_READ 2 #define SFDU_APPEND 3 #define PVL_READ 4 #define PVL_WRITE 5 5.2.8 USER DEFINABLE CONSTANTS There are certain CONSTANTS that can be changed to help memory and processing of the Tool Kit Libraries. These are the only constants that should/can be modified. Changes to other CONSTANTS will result in unpredictable behavior. CONSTANT DESCRIPTION DEFAULT VALUE_BUFSIZ Maximum size in bytes of an LVO value. The value can be placed in a buffer of this size. 512K (UNIX) 16K (DOS) STACK_SIZE Maximum number of entries allowed on a stack. 10 MAX_MESSAGE_LINE_LENGTH Maximum length of the message line used to print text, error messages, etc. 240 5.2.9 SFDU TYPE DEFINITIONS There are some type definitions contained in the LVO.H header file. The definitions are found throughout the code and should be easy to interpret. For example ULONG is a type definition for unsigned long integer. BYTE is a definition for unsigned char etc. 5.3 SFDU Data Structures Most of the data structures used by the SFDU library are defined using type definitions. These definitions consist of struct declarations that contain simpler declarations such as int and char. Some of the structs contain other struct definitions. For instance, the LVO structure contains a LABEL structure since an LVO consists of a LABEL and VALUE. Most functions operate on pointers to these defined structures. The primary structures that are used by the SFDU Library are: LABEL, LVO, SFDU, FILE REFERENCE, SFDU FILE HANDLE, and STACK. 5.3.1 LABEL structure The LABEL structure contains all the information for a single LVO label. It contains the label string as well as its parsed label fields. It is defined as follows : LABEL { char string[LABEL_LENGTH + 1] Complete label string including the terminating NULL character char caid[CAID_LENGTH + 1] Control Authority Identification string including the terminating NULL character char version Version number of the LVO Label '1', '2', or '3' char class_id LVO Class Identifier (Z (SFDU), K (CATALOG) etc.) char spare1 Spare Byte 1 : Used with version ID to determine what delimitation method to use char spare2 Spare Byte 2 : Not used char ddid[DDID_LENGTH + 1] Data Description Identification string including the terminating NULL character. char delim_parameter[DELIM_PARAM_LENGTH + 1] Delimitation parameter string including the terminating NULL character. int mode mode = REFERENCED_LABEL if label was obtained from a LABEL statement in a Replacement object rather than read from the SFDU itself. } 5.3.2 LVO structure The LVO structure contains a pointer to a LABEL structure containing the label of the LVO, a VALUE structure that defines the value of the LVO, pointers to the next and parent LVOs, and other fields required for processing the LVO. Note that there is no independent VALUE structure so functions that operate on LVO value fields must pass the entire LVO structure. LVO { SFDU_FILE_HANDLE *finfo ; The SFDU_FILE_HANDLE structure contains information about the file the LVO object is located in: filename, file pointer, and status. LABEL *label Pointer to the LABEL of the LVO VALUE_STRUCTURE contains the LVO VALUE { ULONG length length in bytes of the LVO value int storage Indicates how the value is stored. Values can be stored in a buffer, in a file (value too large for a buffer), or in another LVO as is the case with structure class LVOs int vtype Indicates the type of value stored char * pre_delimiter_data ; Data contained in this buffer is written prior to the actual data of the LVO char * post_delimiter_data ; Data contained in this buffer is written after the actual data of the LVO ULONG pre_delimiter_length ; Length of the pre_delimiter_data buffer ULONG post_delimiter_length ; Length of the post_delimiter_data buffer Statement RClass_stmt ; for use with Replacement CLass LVOs. This is the PVL Statement pointer to statements contained on the R Class union A union is used here since the value can be only one of the following items { LVO *child_lvo Value is one or more LVOs BYTE *buffer Value is contained in a buffer FILE_REFERENCE *reference Value is contained in a file pointed to by a FILE REFERENCE structure. } of_type Statement PVL_Tree Parameter-Value statement tree for Replacement (R) and Data Administration (C) Class objects. } value LVO *parent_lvo Pointer to the parent LVO LVO *next_lvo Pointer to the next LVO int parse_level ; level within the SFDU where the LVO occurs e.g. The first Z LVO is at level 1, any LVO contained within is at level 2 } How the value of an LVO is stored is contained in the storage variable. Since the value of any LVO can be one of three types, the of_type union declaration was used to give some readability to the source code. For instance, an LVO value pointer to a buffer would read: lvo->value.of_type.buffer A buffer will be created up to a maximum size of VALUE_BUFSIZ defined in the LVO header file (LVO.H). The other types of value storage are the child LVO or a File Reference. If the value stored is of type LVO, the value is actually a pointer to another LVO (the child of the current LVO): lvo->value.of_type.child_lvo A graphical example of the child LVO pointer is shown in Figure 5.3.2. The SFDU (Z) Class LVO has a pointer for its value while the K Class has data associated with it as depicted by the shading. The FILE REFERENCE value type is a pointer to a structure containing information on where data for the LVO is located in the SFDU file. The FILE REFERENCE structure is discussed in section 5.3.3. The PVL_Tree Statement pointer points to a tree of PVL statements. The Replacement and Data Administration Class LVOs contain PVL data which is parsed into this tree form. The pointers child_lvo, next_lvo, and parent_lvo are used for connecting LVOs into a tree structure. This linked structure enables functions to traverse the LVOs that make up an SFDU. Remember the child pointer is contained in the value union. This is because structure LVOs can only have LVOs as their value fields. If more than one LVO makes up the value field of an LVO, the first LVO is connected via the child pointer while the other LVOs are connected with next pointers to each other. The last LVO that is a child of another LVO will have its next pointer set to NULL. È FILE REFERENCE structure The value of a simple class LVO (LVO that doesn't contain more LVOs as its value) may be stored in a memory buffer. However, the size of the value may be too large to store in memory. For example if a LVO is 10MB, it may not be efficient to read the data into a buffer even if the space was available. To solve this problem, data must be kept in the SFDU file where it may be accessed when it is needed for processing. The File Reference structure stores such information needed to access data of an LVO. The FILE REFERENCE structure contains a pointer to a SFDU_FILE_HANDLE structure which contains information on the file itself (name, pointer, etc.). The REFERENCE structure also contains the offset and length of the value within the file. These items are used to read the value when needed. A graphical representation of the FILE REFERENCE structure is shown in Figure 5.3.3. Notice the offset points to the value of the LVO and not the label. FILE_REFERENCE { SFDU_FILE_HANDLE *finfo ; ULONG offset Offset to the start of the value in the file ULONG length Length of value in bytes } 5.3.4 SFDU structure The SFDU structure contains information used during the processing (parsing or creating) of SFDUs. The SFDU structure is nothing more than a SFDU (Z) Class LVO. However, the processing requires that certain information be maintained. Stacks and other fields within the SFDU structure allow this. The SFDU structure contains a pointer to the first LVO of the SFDU which is usually a Z Class LVO. The structure also contains a stack of open files which is used during the processing of the SFDU. When a Replacement Object instructs the SFDU that LVOs are contained in another file, the new file information (SFDU_FILE_HANDLE) is pushed onto the open_files stack on top of the current file. When the data in the new file is exhausted, the stack is popped and data is then read from the previous file. The same type of processing occurs with the Structure and the Replacement Class statement stacks which keep track of which structure class LVOs and R Class statements need to be completed. For example, when a new structure class LVO's label is parsed, the structure LVO is pushed onto the stack. After each parse of an LVO from the SFDU, the structure LVO on the top of the stack is checked to determine if its delimitation has been reached. The R Class statement and open_files stacks are used only when the SFDU contains Replacement Class Objects. The definition of the SFDU structure follows: SFDU { Stack_Type open_files ; /* Stack of opened files for the SFDU */ Stack_Type structure Stack of structure class LVOs to be completed while processing this SFDU Stack_Type RClass_stmts Stack of R class statements that need to be completed while processing this SFDU LVO *head_lvo First LVO of the SFDU (usually a Z class) char *curr_labelstr Current label string, for use with R class stack. This value is assigned to unlabeled reference objects. char base_filename[80] Base name of files created by the unwrap process. Numerical numbers and file extensions are added to create the total output name. int lvo_count[LVO_COUNT+1] Count of each type of LVO in the SFDU; The largest count is also stored in lvo_count[0] i.e. LARGEST = 0 char *filename original input file } 5.3.5 SFDU FILE HANDLE structure All files processed by the SFDU Library functions are organized into a SFDU FILE HANDLE structure. This structure contains the filename, pointer, mode (read, write), and status (open, closed). The SFDU library source code makes use of this structure at the LVO level. Each lvo contains this structure so access to the LVO is readily available. SFDU_FILE_HANDLE { char *filename FILE *fp File pointer BYTE filemode operation mode WRITE, APPEND, READ, etc. BYTE filestatus OPEN, CLOSED } Note this structure is not used by the PVL libraries. Currently there is no limitation on the number of files that can be opened by an SFDU. However, the operating system may limit the number of files that can be opened at once. 5.3.6 STACK structure In previous sections, references were made to stacks for structure classes, replacement class statements, and open files. All these stacks make use of the generic stack structure shown here: struct { void *stack[STACK_SIZE+1] Stack space NOTE : 0th item unused for stack processing Use 1..STACK_SIZE. Some functions actually do use the 0th element of the array, but not for managing the stack. int top Stack pointer } Stack_Type The Stack structure contains allocated space for data and a top pointer for the top of the stack. The stack actually contains pointers to the data. By using pointers, this generic stack structure can be used for different types of data. Initially, the stack entries are pointers to void. When data from the stack is referenced, it is cast to the data type of the stack. For instance, to read the top of the SFDU structure stack the top function would read: (LVO *) util_top(&sfdu->structure) Other stacks of different data types are read the same way. New stacks can be implemented by just declaring the Stack_Type for the variable. 5.3.7 SFDU DESCRIPTION structure The SFDU DESCRIPTION structure is used as a look up table for information library functions may need. When storing information about LVO in data structures, it is more efficient to include char IDs to represent information rather than the entire name. The structure consists of a character ID and a character name as shown: struct SFDU_DESCRIPTION { char id ; char *name ; } sfdu_description Using this structure, simple look up tables can be made. For example, the LVO Class IDs table is made with the following SFDU DESCRIPTION structure declaration: sfdu_description sfdu_class[] = { {'0', "NONE"}, {'Z', "SFDU"}, {'U', "IDU"}, {'F', "DDU"}, {'C', "DATA_ADMINISTRATION"}, {'R', "REFERENCE"}, {'I', "APPLICATION_DATA"}, {'S', "SUPPLEMENTARY_DATA"}, {'D', "DATA_DESCRIPTION"}, {'E', "DATA_ENTITY"}, {'K', "CATALOGUE_DATA"}, {'V', "VOLUME_DATA"}, {NULL, NULL} } ; NOTE: The NULL values signal the end of the look up table. Whenever the name of a K Class LVO needs to be written, the lbl_description_text function will return a pointer to the string containing the full name. Similar tables exist for DELIMITATION types and ADID names. Likewise, the function lbl_descriptor_id can be used to convert a string to its character identifier. These tables make the source code more maintainable since these values need only be modified here if a change to the name or char id is desired. 5.3.8 The SFDU tree There are several references in this document to the SFDU tree structure. The SFDU tree is the connection of all LVOs associated with an SFDU. The connections are made using either the child_LVO pointer in the VALUE portion of the LVO structure or the next_LVO pointer. The SFDU library provides the functionality for building SFDU trees by performing all the necessary connections. The library also performs the checks needed to ensure that only valid connections are made. A sample Z-K-I SFDU tree is shown here: Notice the value of the Z Class LVO points to the K Class LVO. This is due to the Z being a structure Class LVO, whose value contains other LVOs. The simple class LVO's (K and I) value fields contain regular data (no pointers to other LVOs). 5.4 SFDU Library Function Highlights This section is intended to give an overview of how the SFDU Library source code is organized and the functionality provided by each file. Descriptions about the content of each source file is given. More importantly brief descriptions are given on high level functions that would be of interest to integrators. The source code is contained in several files. All functions are prefixed with an abbreviation of the file name that the function is contained in. This was done to make it easy to locate functions while reading the source code and/or this document. A table of the prefixes and corresponding file names follow: FUNCTION PREFIX FILE NAME sfd sfdutool.c (SFDU Tools) mapl mapltool.c (MAP Language Tools) lbl lbltools.c (LABEL tools) bld bldsfdu.c (Building) val valtools.c (LVO Value Tools) ftbl sfduftbl.c (SFDU File Table) create creatlvo.c (LVO Creation) create creatdat.c (Data Object Creation) create creatmap.c (MAP Language Creation) compare lvocmpre.c (LVO comparison) ops sfduops.c (SFDU/LVO Operations) util utility.c (UTILITY functions) util utilmsg.c (message functions) 5.4.1 LABEL TOOLS (LBLTOOLS.C) The LABEL TOOL functions operate on the LABEL structure. Most of the functions that determine types (delimitation, class, etc.) rely on the lookup tables declared using the SFDU Description Structure in the lbltools.c source file. Unit Description This module contains functions for manipulating labels. Label structures are used to store label information. Processing of labels is performed on label structures that represent the labels. Label structures contain the label string as well as the different label fields of the label string namely : Control Authority Id (CAID) (Byte 0-3) Data Description Id (DDID) (Byte 8-11) Class Id (Byte 5) Label version (Byte 4) Spare byte 1 and Spare byte 2 (Byte 6 and 7) Delimitation Parameter (Byte 12-19). Unit Components /* main functions */ int lbl_parse_sfdu_label(LABEL *) ; int lbl_get_class_type(char) ; int lbl_get_delim_type(LABEL *) ; int lbl_get_value_type(LABEL *) ; char lbl_descriptor_id(char *, sfdu_description *) ; char * lbl_description_text(char, sfdu_description *) ; /* support functions */ int lbl_description_table_index(char) ; LOGICAL lbl_modify_description_table(char, sfdu_description *, char *) ; LOGICAL lbl_validate_caid(char *) ; LOGICAL lbl_validate_version(char) ; LOGICAL lbl_validate_class(char) ; LOGICAL lbl_validate_spare_byte_1(char, char) ; LOGICAL lbl_validate_delim_parameter(LABEL *) ; LOGICAL lbl_default_adid_exists(LABEL *) ; Globals Defined sfdu_description sfdu_class[] table of class ids with corresponding description identifier sfdu_description sfdu_delimitation[] table of spare 1 bytes with corresponding delimitation description identifier sfdu_description sfdu_adid[] table of class ids with corresponding default ADID char valid_class_string[] = "ZUFCRISDEKV" string of valid class ids char valid_spare_string[] = "0ABSECF" string of valid version 3 spare 1 fields char **caid_table table of valid Control Authority Ids char **alternate_caid_table table of alternate Control Authority Ids loaded at run time External References char msg_string[] used to store the error message Change History Version Date Change Description RAG 09/07/93 Changed SIMPLE_DATA to APPLICATION_DATA 5.4.1.1 lbl_parse_sfdu_label(label) This function will parse a twenty byte SFDU label. The function will place the parsed contents into a LABEL structure. This is useful when creating LABELs or verifying labels read from an SFDU. Note that any SFDU parsed by the Tool Kit Library has already had its labels parsed using this function. Functions that create labels can be found in the CREATE LVO TOOLS file. Abstract Extract label fields and store in the label structure Return/Inputs/Outputs RETURN int return status LABEL_OK if label is parsed successfully INPUT LABEL *label input label to parse Description This routine extracts the following label fields from the input label stored in the string field of the input label structure and stores them in their respective fields in the same structure. LABEL FIELD POSITION(S) LABEL STRUCTURE FIELD Control Authority Id 0-3 label->caid Version Number 4 label->version Class Identifier 5 label->class_id Spare Field 1 6 label->spare1 Spare Field 2 7 label->spare2 Data Description Id 8-11 label->ddid Delimitation Parameter 12-19 label->delim_parameter The return status LABEL_OK is returned if all fields were extracted and validated successfully. In any case where the parse fails, a FATAL error is reported. Notes/Assumptions Assumes label is defined. Error Handling FATAL error is reported if any invalid label field is found. Change History NLP 07-18-91 Changed input parameter (originally string) NLP 07-11-91 Original code 5.4.1.2 lbl_get_class_type(class_id) This function will return the class type of an LVO. The valid Class Types are: STRUCTURE_CLASS, SERVICE_CLASS, and DATA_CLASS. This function in conjunction with bld_get_next_lvo could be used to search for various LVO types and process their values. Abstract Return the integer corresponding to the class type of class id Return/Inputs/Outputs RETURN int integer corresponding to STRUCTURE_CLASS, SERVICE_CLASS, or DATA_CLASS INPUT char class_id input class identifier Description This function returns an integer which identifies the class type of class id. Each class_id may be classified either as a STRUCTURE class, a SERVICE class, or a DATA class. The following summarizes the class types and the member class ids that belong to each type: CLASS TYPE CLASS ID Structure Class Z U F Service Class C R Data Class I S D E K V Notes/Assumptions None Error Handling None Change History NLP 08-13-91 Original code 5.4.1.3 lbl_get_delim_type(label) Abstract Return the integer corresponding to the delimitation type of the LVO with LABEL inlabel Return/Inputs/Outputs RETURN int integer corresponding to the delimitation type of the LVO with LABEL label INPUT LABEL *label input label Description This function returns an integer which identifies the delim type of the LVO with the given label. The following table summarizes the rules for determining delimitation types. The integers returned which are defined in a header file are also listed : VERSION SPARE 1 FIELD DELIMITATION RETURN INTEGER 1 '0' LENGTH_ASCII (Length in ASCII) 2 '0' LENGTH_BINARY (Length in binary) 3 'A' LENGTH_ASCII 'B' LENGTH_BINARY 'S' MARKER (Use an end marker pattern) 'E' NUM_EOFS (Number of EOFs) 'C' CONTIG_EOFS (Number of contiguous EOFs) 'F' SHARED_EOF (One EOF) 0 UNKNOWN_DELIMITATION (Unable to determine) Notes/Assumptions Assumes label is defined. Error Handling None Change History NLP 08-21-91 Original code 5.4.1.4 lbl_get_value_type(inlabel) Abstract Return the number corresponding to the value type of the LVO specified by LABEL inlabel Return/Inputs/Outputs RETURN int the integer corresponding to the value type of inlabel INPUT LABEL *inlabel input LABEL Description The value type of the LABEL inlabel is determined. The recognized value types are defined in a header file with each type corresponding to an integer as follows : PVL_TYPE 2 LVO value contains PVL data LVO_TYPE 4 LVO value is an LVO ENGLISH_TEXT_TYPE 5 LVO value consists of English text UNKNOWN_VALUE 0 Notes/Assumptions Assumes LABEL inlabel is defined. Error Handling None Change History XXX MM/DD/YY Original Code 5.4.1.5 lbl_descriptor_id(description, descriptor_table) Abstract Return the corresponding id for description Return/Inputs/Outputs RETURN char the corresponding id for description INPUT char *description input description identifier INPUT sfdu_description *descriptor_table table of ids with corresponding description Description The id for description is determined by looking up the table descriptor_table. Each entry in the table is made up of an id and an identifier serving as a description of the id. This function uses the description as a search index into the table to find the corresponding id to return. Sample descriptor table : sfdu_description sfdu_class[] = { {'0', "NONE"}, {'Z', "SFDU"}, {'U', "IDU"}, {'F', "DDU"}, {'C', "DATA_ADMINISTRATION"}, {'R', "REFERENCE"}, {'I', "APPLICATION_DATA"}, {'S', "SUPPLEMENTARY_DATA"}, {'D', "DATA_DESCRIPTION"}, {'E', "DATA_ENTITY"}, {'K', "CATALOGUE_DATA"}, {'V', "VOLUME_DATA"}, {NULL, NULL} } Notes/Assumptions Assumes descriptor_table is defined. Error Handling None Change History XXX MM/DD/YY Original Code 5.4.1.6 lbl_description_text(id, descriptor_table) Abstract Return the corresponding description for id Return/Inputs/Outputs RETURN char * the corresponding description for id INPUT char id input id INPUT sfdu_description *descriptor_table table of ids with corresponding description Description The description for id is determined by looking up the table descriptor_table. Each entry in the table is made up of an id and an identifier serving as a description of the id. The id is used in this function as a search index into the table to find the corresponding description to return. Sample descriptor table : sfdu_description sfdu_class[] = { {'0', "NONE"}, {'Z', "SFDU"}, {'U', "IDU"}, {'F', "DDU"}, {'C', "DATA_ADMINISTRATION"}, {'R', "REFERENCE"}, {'I', "APPLICATION_DATA"}, {'S', "SUPPLEMENTARY_DATA"}, {'D', "DATA_DESCRIPTION"}, {'E', "DATA_ENTITY"}, {'K', "CATALOGUE_DATA"}, {'V', "VOLUME_DATA"}, {NULL, NULL} } Notes/Assumptions Assumes descriptor_table is defined. Error Handling None Change History XXX MM/DD/YY Original Code 5.4.2 VALUE TOOLS (VALTOOLS.C) Functions contained in the VALUE TOOLS file operate on the VALUE structure that is contained in the LVO structure. The operations are concerned mostly with validation although there are functions for length computation and value processing. Highlights: Unit Description This module contains functions which process Label-Value Object (LVO) value data. Among the operations performed are computation of value data length, validation of value data for specific LVO class types, and processing of Parameter-Value Language (PVL) data in LVO values. Unit Components /* main functions */ ULONG val_compute_length(LVO *) ; LOGICAL val_check_adid_spec(LVO *) ; LOGICAL val_validate_data_admin_stmts(Statement) ; LOGICAL val_validate_reference_stmts(Statement) ; /* support functions */ LOGICAL val_check_DDU_value(LVO *) ; LOGICAL val_check_IDU_value(LVO *) ; LOGICAL val_process_reference_stmts(Statement *, Statement *, char **, char **) ; void val_process_initial_reference_stmts(Statement *, char **, int *) ; int val_check_rclass_keyword_values(Statement, int) ; LOGICAL val_check_file_name_length(char *, int) ; Statement val_make_reference_stmts(Statement, Statement, char *, char **, int) ; Globals Defined None External References char msg_string[] used to store error message Change History Version Date Change Description 5.4.2.1 val_compute_length(parent_lvo) This function will compute the length of structure class LVOs. It recursively calls itself when the value of a structure class LVO contains another structure LVO. This function is very useful when trying to determine how large an SFDU is especially when preparing to write the SFDU to output medium and the size needs to be known in advance. Lengths of simple class LVOs are calculated by adding the length of the value plus 20 bytes for the label plus 20 bytes for those delimited by marker. Abstract Compute the total length of parent_lvo's value field which consists of children LVOs Return/Inputs/Outputs RETURN ULONG size in bytes of the children LVOs of LVO parent_lvo INPUT LVO *parent_lvo LVO whose length is to be computed. Description This function sums the value lengths of the children of parent_lvo plus their respective label lengths. The total number (in bytes) obtained is the value length of parent_lvo. Notes/Assumptions Function assumes that parent_lvo is a structure LVO with attached child LVOs. Error Handling None Change History NLP 08-21-91 Original Code. RAG 05-26-92 Computation of length of STRUCTURE LVOs includes only those LVOs contained in the same file RAG 08-01-93 Removal of SFDU_fileid; replaced with finfo pointer contained in the SFDU 5.4.2.2 val_check_adid_spec(lvo) Abstract Check whether LVO conforms to the CCSDS ADID specifications Return/Inputs/Outputs RETURN LOGICAL return validation value (TRUE/FALSE) INPUT LVO * lvo LVO whose child LVOs are to be validated Description The value of the LVO is checked if it has a CONTROL AUTHORITY ID (CAID) of CCSD_caid. If it does and contains a valid CCSDS DDID, the following are checked, otherwise FALSE is returned : If LVO lvo's DDID is 0001, its value field is composed of one or more LVOs, If LVO lvo's DDID is 0003, its value field is composed of Parameter-Value Language (PVL) statements; The allowable PVL statements are as follows : REFERENCETYPE = ... LABEL = ... REFERENCE = ... If LVO lvo's DDID is 0004, its value field is composed of PVL statements; The allowable PVL statements are as follows : ADIDNAME = adid DEDID = adid DDRID = adid SUPID = adid If LVO lvo's DDID is 0005, its value field is composed of LVOs conforming to the following rules : The first child LVO is a C class LVO. There may be 0 or more additional children LVOs of class D, E, K, S, or R If LVO lvo's DDID is 0009, its value field is composed of LVOs conforming to the following rules : There may be one or more children LVOs of class U, I, S, K, V, C, or R For details of the CCSDS specifications for LVOs, consult the CCSDS Draft Recommendation for SFDUs: Structure and Construction Rules (CCSDS Red Book, June 1991). Notes/Assumptions See CCSDS SFDU Red Book (Structure and Construction Rules), June 1991. for a detailed description of the CCSDS specification. Error Handling All LVOs not conforming the CCSD ADID specs cause WARNINGs. Change History NLP 10/15/91 Original code. 5.4.2.3 val_validate_data_admin_stmts(stmt) This function will validate the PVL statements contained in DATA ADMINISTRATION (C) Class LVOs. This function is useful for verifying C Class LVOs created from sources other than the Tool Kit. Any DATA ADMINISTRATION Class LVO created with the Tool Kit is automatically validated (See SERVICE_DATA Map Language aggregation statement). Abstract Validate Parameter-Value Language (PVL) statements used in a Data Administration LVO Return/Inputs/Outputs RETURN LOGICAL TRUE if statements are valid, FALSE otherwise INPUT Statement stmt root statement of PVL statement tree to validate Description This function checks if each statement in the statement tree is a valid Data Administration statement starting at stmt. The first statement must be ADIDNAME = adid Subsequent statements may be DEDID = adid DDRID = adid or SUPID = adid Note that the ADIDNAME statement is mandatory and may appear only once. This function returns TRUE if all statements are valid and FALSE otherwise. Notes/Assumptions See CCSDS SFDU Red Book (Structure and Construction Rules), June 1991 for a detailed description of the CCSDS specification. Error Handling WARNINGs are reported in all cases of statement errors. Change History XXX MM/DD/YY Original Code 5.4.2.4 val_validate_reference_stmts(stmt) This function will validate the PVL statements contained in REPLACEMENT (R) Class LVOs. This function is useful for verifying R Class LVOs created from sources other than the Tool Kit. Any REPLACEMENT Class LVO created with the Tool Kit is automatically validated (See REFERENCE_DATA_FILE Map Language Statement). Abstract Validate REFERENCE class statements according to CCSDS standards Return/Inputs/Outputs RETURN LOGICAL TRUE if statements are valid, FALSE otherwise INPUT Statement stmt root statement of REFERENCE statement tree to be validated Description This function validates the following REFERENCE Class statements : REFERENCETYPE = type type may be $DOS or $UNIX, LABEL = label label is a valid label string (see Notes), REFERENCE = filename the file with name filename exists. This function returns TRUE if all statements are valid and FALSE otherwise. Notes/Assumptions Note that it is not possible to have a LABEL statement where the label string value uses binary length delimitation. PVL statements only allow text characters. Assumes stmt is not NULL. Error Handling The REFERENCETYPE must match valid CCSDS type (UNIX, DOS etc.) The length of the label in the 'LABEL = label' statement must be equal to LABEL_LENGTH. A WARNING message is produced if the filename in the REFERENCE stmt does not exist. Change History XXX MM/DD/YY Original Code 5.4.2.5 val_check_DDU_value This function will check the validity of Data Description Units (U Class LVOs). These checks are in accordance with the specifications in the CCSDS recommendations. This function is called automatically when SFDUs are built with Map Language statements. This function can be used if an application builds the SFDU without the library functions. Abstract Validates the class id of the child/children of LVO lvo (a Data Description Unit LVO) according to CCSDS specification Return/Inputs/Outputs RETURN LOGICAL return validation value (TRUE/FALSE) INPUT LVO * lvo LVO whose child LVOs are to be validated. Description CCSDS's specification for Data Description Units (DDUs) allows only certain specific classes of LVOs. This function non- recursively checks if each child LVO of the DDU complies to the CCSDS specification. It returns TRUE if the DDU is valid, otherwise it returns FALSE. The first LVO value must be a class C LVO. Subsequent LVO values can be any number of the following classes : D - Data Description Record Object E - Data Entity Dictionary Object K - Catalogue Attribute Object S - Supplementary Data Object R - Replacement Service Object. Notes/Assumptions See CCSDS SFDU Red Book (Structure and Construction Rules), June 1991. for a detailed description of the CCSDS specification. Error Handling None Author and Institution Norbert L. Piega / JPL Ronald A. Green / JPL Change History XXX MM/DD/YY Original Code 5.4.2.6 val_check_IDU_value This function will check the validity of Information Data Units (F Class LVOs). These checks are in accordance with the specifications in the CCSDS recommendations. This function is called automatically when SFDUs are built with Map Language statements. This function can be used if an application builds the SFDU without the library functions. Abstract Validates the class id of the child/children of LVO lvo (an IDU LVO) according to CCSDS specification Return/Inputs/Outputs RETURN LOGICAL return validation value (TRUE/FALSE) INPUT LVO * lvo LVO whose child LVOs are to be validated Description The CCSDS specification for Information Data Units (IDUs) allows only certain classes of LVOs. This function checks if each child LVO of the IDU LVO complies with the CCSDS specification. It returns TRUE if the IDU is valid, otherwise it returns FALSE. The value field of a valid IDU LVO is composed of one or more LVOs with any of the following allowed class ids : U - Information Data Unit I - Application Data Object S - Supplementary Data Object K - Catalogue Attribute Object V - Volume Preparation Data Object C - Data Administration Service Object R - Replacement Service Object Notes/Assumptions This function is recursive because IDUs can contain more IDUs See CCSDS SFDU Red Book (Structure and Construction Rules), June 1991. for a detailed description of the CCSDS specification. Error Handling None Author and Institution Norbert L. Piega / JPL Ronald A. Green / JPL Change History NLP MM/DD/YY Original Code RAG 09/07/93 Changed I object to APPLICATION_DATA from SIMPLE_DATA 5.4.3 BUILD / PARSE SFDU (BLDSFDU.C) Functions contained in the BUILD/PARSE SFDU file are used primarily to read and parse LVO information contained in the SFDU input file(s). The functions in bldsfdu.c make calls to functions contained in other source files such as LABEL and VALUE tools to validate the information that is read. The name BUILD (bldsfdu.c) does not logically match the functionality provided by this source file. Early in the Tool Kit development the functions to read, parse and build the SFDU tree were all contained in this file. Now the SFDU Tree building functions are contained in their own file (SFDUTOOL) for the purpose of reducing library and application sizes. For example, the WRAP Library does not need parsing functions, therefore the applications produced for SFDU generation (wrapping) have smaller sizes. These functions do make use of the SFDU TOOL functions to build the SFDU tree structure (See Section 5.3.8) This tree structure is built as LVOs are parsed from the SFDU input file(s). Unit Description This module contains functions used to build label value objects (LVOs) and the SFDU trees which make up the logical representation of SFDUs. The trees are built during the parsing of SFDUs. Unit Components /* main functions */ int bld_parse_n_lvos(SFDU *, int, int *) ; LVO * bld_parse_next_lvo(SFDU *, int *) ; Statement bld_set_up_PVL_tree(LVO *, int *) ; /* support functions */ LABEL * bld_get_next_label(SFDU *, int *) ; int bld_read_sfdu_label(LABEL *, SFDU *) ; LVO * bld_complete_lvo_value(LVO *, SFDU *, int *) ; int bld_set_up_value(LVO *, SFDU *) ; int bld_set_up_length_value(LVO *, SFDU *, UCHAR) ; int bld_read_into_lvo_buffer(LVO *, SFDU *) ; int bld_set_up_file_reference(LVO *, SFDU *) ; void bld_pop_lvos_by_length(SFDU *) ; Globals Defined LOGICAL ResolveRClasses TRUE - resolve Replacement objects (default) FALSE - do not resolve Replacement objects LOGICAL JPLS_std TRUE - use JPL standard where necessary (default) FALSE - do not use JPL standard marker patterns LOGICAL CCSD_std TRUE - use CCSDS standard where necessary (default) FALSE - do not use CCSDS standard marker patterns char CCSD_MARKER_PATTERN[] = "CCSD$$MARKER" CCSD standard lead marker pattern char JPLS_MARKER_PATTERN[] = "CCSD3RE00000" ; JPL standard lead marker pattern External References char msg_string[] used to store error message Change History Version Date Change Description 07-26-93 Removal of global FileTable variable File Information (finfo) is now contained in the lvo itself Function highlights: 5.4.3.1 bld_parse_n_lvos(sfdu, n, status) Parses an SFDU to get N number or all LVOs contained in an SFDU. This function can be called a successive number of times using the same SFDU to read N number of LVOs at a time. Abstract Parse 'n' LVOs from SFDU sfdu Return/Inputs/Outputs RETURN int the actual number of LVOs parsed INPUT int n the number of LVOs to be parsed INPUT SFDU the SFDU where the LVOs will be parsed from MODIFY int *status status parameter passed on from lower level functions Description Reads n LVOs by using iterative calls to the parse next LVO function. Function will end if the EOF is reached and there are no other files on the SFDU file stack. Notes/Assumptions A value of n = 0 will cause all LVOs in the SFDU to be parsed. Error Handling Reports error on incorrect LVOs. Displays the LVOs label. Change History NLP 08-21-91 Original Code RAG 03-29-92 Add RClass LVO stack to properly handle R Class LVOs RAG 08/01/93 Replaced add_table_entry with open_sfdu_file RAG 09/07/93 Modified 'Parsed' and 'Parsing' msgs to add LVO Class ID 5.4.3.2 bld_parse_next_lvo(sfdu, status) Parses the next LVO object from the SFDU file(s). The function name may be misleading because if the next LVO is a structure class this function will return only the LABEL portion of the LVO and leave the LVOs in the value field for the next call. The bld_parse_next_lvo function relies on two lower level functions (bld_get_next_label and bld_complete_lvo_value) to read the entire LVO object. It is not recommended to use the lower level functions to read LVOs since some set up and initialization of the LVO is done at this higher level. Abstract Get the next lvo from the sfdu file Return/Inputs/Outputs RETURN LVO * newly created LVO INPUT SFDU *sfdu SFDU to obtain the next LVO from OUTPUT int status status for get next label & complete LVO value routines Description Reads the next LVO of the SFDU. The label is read first followed by the value. If an incorrect or no label read memory allocated for the LVO is freed. Validation of the value of the LVO is done for SERVICE data classes (CCSD003 & CCSD0004). Notes/Assumptions Only UNIX & DOS files are supported for resolving R Class objects. Error Handling Errors reported if the value fields cannot be validated. Change History NLP 08-21-91 Original Code RAG 06/17/92 Check return status of validate_ref stmts if in error quit here, rather than the routine RAG&MA 07/16/93 Changed parameter 'status' in call of function bld_set_up_PVL_tree to 'parse_status' (in order to avoid conflict with "global" status) RAG 08/01/93 Replaced add_table_entry with open_sfdu_file 5.4.3.3 bld_set_up_PVL_tree(lvo) Abstract Parse LVO lvo's value field to obtain a PVL tree Return/Inputs/Outputs RETURN Statement root of the PVL tree INPUT LVO *lvo LVO whose value contains PVL statements Description The PVL tree is created using either the parse file or parse buffer routines based on how the PVL statements are stored (FILE REFERENCE or buffer). Statements stored as reference are copied to a temporary file first and then parsed. Once the PVL tree is created, the temporary file is deleted. Notes/Assumptions The value field of LVO is actual PVL. This is determined by the adid of the label of lvo which should be either CCSD0003 or CCSD0004. Error Handling FATAL errors occur if lvo's delimitation type is unrecognized. The status variable contains TRUE or FALSE based on the result of the PVL parse Change History RAG 01/19/93Added return status for PVL parse 5.4.4 SFDU TOOLS (SFDUTOOL.C) The SFDU TOOLS file contains functions that operate on the SFDU tree structure (See Section 5.3.8). The tree structure is a collection of linked LVO data structures that represent the SFDU. Unit Description This module contains functions used to operate on Standard Formatted Data Units (SFDUs) and the SFDU trees which make up the logical representation of SFDUs. The trees are built during the parsing of SFDUs. Unit Components /* main functions */ SFDU * sfd_initialize_sfdu(char *) ; LVO * sfd_get_next_lvo(LVO *, LOGICAL) ; void sfd_display_lvo_summary_report(SFDU *) ; /* support functions */ void sfd_append_lvo(LVO *, SFDU *) ; External References char msg_string[] used to store error message Change History Version Date Change Description 5.4.4.1 sfd_initialize_sfdu(filename) Initialize an SFDU for processing. The function sets up an SFDU tree for attaching LVOs as they are parsed from the SFDU file. This function is also used in the creation of SFDUs and must be called before an SFDU is processed. Abstract Allocates a new SFDU structure and initializes its fields Return/Inputs/Outputs RETURNSFDU * pointer to the newly allocated SFDU INPUTchar *filename input file name Description This function allocates a new SFDU structure and initializes its fields. The pointer to the new structure is returned. Notes/Assumptions If a valid filename is passed to this function, its name is added to the open_files stack of the sfdu. Otherwise (if NULL is passed), the function assumes that an SFDU structure tree is to be created and its LVO structures to be generated internally. Error Handling None Change History NLP 08-22-91Original Code. 5.4.4.2 sfd_get_next_lvo(lvo) This function will return a pointer to the next LVO from a parsed SFDU contained in an SFDU tree. This function is useful for processing LVOs one at a time (e.g. verifying the value fields, writing the value to a file etc.) Abstract Get the next LVO that immediately follows LVO lvo, whether it be a child or a next LVO Return/Inputs/Outputs RETURNLVO * the next LVO INPUTLVO *lvo the current LVO Description This function returns a pointer to the next LVO or to the child LVO that is attached to LVO lvo Notes/Assumptions None Error Handling None Change History NLP MM/DD/YY Original Code 5.4.4.3 sfd_display_lvo_summary_report(sfdu) Abstract Print a report summarizing the LVOs contained in SFDU sfdu. Return/Inputs/Outputs RETURN none INPUT SFDU *sfdu Description This function prints a summary of LVOs found in a parsed SFDU. In particular the report contains the following items as listed: Object Type Authority Delimiter Delimiter Value Object Description Method Parameter Size ID ID (bytes) SFDU CCSD0001 ASCII_LENGTH 00000483 483 Z SFDU CCSD0001 BINARY_LENGTH -BINARY- 463 Z CATALOGUE_DATA RJPLL015 MARKER BBBBBBBB 325 K REFERENCE CCSD0003 ASCII_LENGTH 00000078 78 R APPLICATION_DATA NJPL0351 SHARED_EOF 00000001 2624 I Notes/Assumptions Assumes sfdu has been completely parsed or constructed. LVOs delimited by BINARY LENGTH show "-BINARY-" in the delimiter parameter field. Error Handling None Change History XXX MM/DD/YY Original Code MA 07/21/93 Modify to have output written by the function util_print_message RAG 08/29/93 New output format RAG 08/30/93 Change function name from lvo_totals_report to sfd_display_lvo_summary_report 5.4.5 MAP LANGUAGE TOOLS (MAPLTOOL.C) The MAP LANGUAGE TOOLS file contains functions for interpreting MAP LANGUAGE statements. There is only one high level function of interest here. The other functions in this file are in support of the mapl_create_sfdu_from_map function. Unit Description This module contains WRAP tools namely functions that are used to interpret Map Language specifications of SFDUs into actual SFDUs. All types of Map Language statements are handled in this module. Unit Components /* main functions */ SFDU * mapl_create_sfdu_from_map(SFDU *, Statement, Statement) ; /* support functions */ void mapl_fatal_wrap_error(char *, char *) ; /* map language statement processing functions */ LVO * mapl_aggr_stmt_to_lvo(SFDU *, Statement) ; void mapl_stmts_to_lvo(Statement *, SFDU *, LVO *, Stack_Type *) ; void mapl_stmt_to_adid(LVO *, Statement) ; void mapl_stmt_to_delimitation(LVO *, Statement) ; void mapl_stmt_to_include_data(SFDU*, LVO *, Statement) ; void mapl_stmt_to_reference_object(LVO *, Statement, LVO **) ; void mapl_stmts_to_service_data(LVO *, Statement) ; /* prefix and pad data support functions */ void mapl_process_pre_delim_stmt(LVO *, Statement) ; void mapl_prefix_lvo_data(LVO *lvo, char *, ULONG) ; void mapl_process_pad_stmt(LVO *, Statement) ; void mapl_pad_lvo_data(LVO *, char, ULONG) ; /* map language macro support functions */ /* Structure used for macro statement lists */ typedef struct MACRO_STMT_ITEM { Statement macro_item ; struct MACRO_STMT_ITEM *next_item ; } macro_stmt_item ; /* Structure used for the collection of macros */ typedef struct MACRO_DEF { char *name ; int nargs ; macro_stmt_item *list_head ; Statement parameter_list ; Statement start ; struct MACRO_DEF *next_macro ; } MACRO ; void mapl_process_macro(Statement) ; macro_stmt_item * mapl_add_macro_stmt_to_list(macro_stmt_item *, Statement) ; void mapl_make_macro_stmts_to_modify_list(MACRO *, Statement) ; void mapl_modify_macro_parameter_values(MACRO *, Statement) ; Globals Defined MACRO *macro_list list of macro objects External References sfdu_description sfdu_class[] table of class ids with corresponding description identifier sfdu_description sfdu_delimitation[] table of spare 1 bytes with corresponding delimitation description identifier sfdu_description sfdu_adid[] table of class ids with corresponding default ADID SFDU_FILE_HANDLE *scratch File Structure pointer to a temporary file used for the creation of Map Language Statements char msg_string[] used to store error string Change History Version Date Change Description The lower level functions in this file create LVO structures and their components such as label delimitation, ADID values, etc. The functions support all aspects of LVOs and SFDUs (LABELS, VALUES, etc.). However any new MAP LANGUAGE statements would have to have code added to this file to support it. Function highlight: 5.4.5.1 mapl_create_sfdu_from_map Creates a SFDU tree from map statements written in PVL. If the tree is successfully created, the create_write_lvo function can be used to write the SFDU to a file. Abstract Create the sfdu specified by the Map Language statements starting at stmt Return/Inputs/Outputs RETURN SFDU *sfdu INPUT Statement stmt INPUT Statement cmnd_line_stmts MODIFY SFDU *sfdu Description This is the main driver for interpreting map statements in the statement tree and generating the appropriate LVOs for the sfdu. The first statement stmt is processed as the root of the tree. The following type map statements are interpreted : BEGIN_OBJECT = lvo_class_description where lvo_class_description is a valid class description identifier, BEGIN_OBJECT = SERVICE_DATA, DELIMITATION = (MARKER, marker_string) where marker_string is a valid 8 byte marker string, DELIMITATION = (delim_type, NULL) or DELIMITATION = delim_type where delim_type is ASCII_LENGTH, BINARY_LENGTH, or SHARED_EOF, REFERENCE_DATA_FILE = reference_file_name, INCLUDE_DATA_FILE = include_file_name, macros. A statement stack is used to keep track of which map statement to process next. Notes/Assumptions Refer to the Map Language Specification document for a detailed description of the supported map statements. Error Handling None Change History XXX MM/DD/YY Original Code RAG 01/19/93 Changed parameter name from cmnd_line_stmts to external_stmts (statements outside the map file that need to be processed) RAG 08/30/93 Added parse_sfdu_label call to load LABEL 5.4.6 CREATE LVO TOOLS (CREATLVO.C) The CREATE LVO TOOLS file contains functions for creating and writing LVOs. There is also support for writing out entire SFDUs. Unit Description The CREATLVO unit provides functions for creating/modifying Label Value Objects (LVOs) and SFDUs. The functions create labels, values, LVOs and SFDUs. Functions for validating delimitation prior to creating SFDUs are also included. Unit Components /* main functions */ void create_wrapped_sfdu_file(SFDU *, char *) ; char * create_CCSDS_standard_label(char, int, char *, ULONG) ; char * create_version3_label(char *, char, char *, int, char *, ULONG) ; /* support functions */ void create_write_lvo(SFDU *, LVO *) ; char * create_modify_label_delimitation(char, char *, ULONG, char *) ; void create_lvo_EOF_delimitation_check(LVO *) ; void create_sfdu_delimitation_check(SFDU *) ; Globals Defined External References sfdu_description sfdu_class[] table of class ids with corresponding description identifier sfdu_description sfdu_adid[] table of class ids with corresponding default ADID LOGICAL JPLS_std if TRUE, use JPL standard marker for wrapping char msg_string[] used to store error string Change History Version Date Change Description RAG 08/01/93 Modified to support removal of global FileTable variable; File Information is contained in the SFDU 5.4.6.1 create_wrapped_sfdu_file(sfdu, output_file) Essentially, this is a WRAP function. The function assumes that the SFDU is stored in a SFDU tree structure. The resulting output would go to an SFDU file. Abstract Write SFDU sfdu to output SFDU file output_file Return/Inputs/Outputs RETURN void INPUT SFDU *sfdu INPUT char *output_file OUTPUT SFDU output file created Description This function creates the SFDU file output_file for sfdu. Using the create_write_lvo function, each LVO in sfdu is written to the output file in the sequence that it should appear in the SFDU. Notes/Assumptions Assumes sfdu is defined. Error Handling None Change History XXX MM/DD/YY Original Code RAG 08/01/93 Replaced add_table_entry with open_sfdu_file 5.4.6.2 create_CCSDS_standard_label( class, delimitation, delim_parameter, value_length) Creates a 20 byte CCSDS standard label. This function can only be used to create labels for the CCSDS defined LVO classes (Z, U, F, C, and R). Abstract Create a CCSDxxxxxxx type label for inclusion into an LVO Return/Inputs/Outputs RETURN char * INPUT char class INPUT char delimitation[] INPUT ULONG value_length Description Create a CCSD supported label. The ADID is always 'CCSD' while the DDID value is based on the LVO Class. The CCSDS supported classes are: LVO TYPE ADID Z Class SFDU_DATA 0001 F Class DESCRIPTION DATA UNIT 0005 U Class INFORMATION DATA UNIT 0009 R Class REPLACEMENT DATA 0003 C Class DATA ADMINISTRATION 0004 Notes/Assumptions The class id is a CCSDS standard class Error Handling An error is reported if class_id is a non CCSDS standard class Change History XXX MM/DD/YY Original Code 5.4.6.3 create_version3_label(caid, class, ddid, delimitation, delim_parameter, value_length) Creates a 20 byte SFDU label. Useful when creating your own Label Value Objects (LVOs) for inclusion into an SFDU. Abstract Create a version 3 label for inclusion into a Label Value Object (LVO) Return/Inputs/Outputs RETURN char * pointer to the newly created label INPUT char caid[] Control Authority ID INPUT char class class type for the label INPUT char ddid[] Data Description Identifier INPUT char delim_parameter[] delimitation parameter for the new label INPUT ULONG length of the value of the LVO Description Create a version 3 label based on the inputs of the CAID, class type, DDID, delimitation, delimitation parameter, and the length of the value of the LVO. Notes/Assumptions The CAID and DDID are assumed to be correct. Error Handling None Change History XXX MM/DD/YY Original Code 5.4.7 CREATE DATA OBJECTS (CREATDAT.C) The CREATE DATA OBJECTS file contains functions for creating data objects from SFDU tree structures. There are also support functions to describe the names of the data files to be written. The primary function, however, is the create_unwrapped_files which is the top level unwrap function. Unit Description The CREATDAT unit provides functions used when creating the unwrap data files of a SFDU. The functions set up the base file name and the file extensions to use, and write data extracted from SFDUs. Unit Components /* main functions */ void create_unwrapped_files(SFDU *, char *) ; void create_set_up_base_file_name(SFDU *) ; /* support functions */ char * create_adjust_filename(char *, int) ; Globals Defined sfdu_description file_extension[] table of class ids with corresponding default file extension used for "unwrapped" files External References sfdu_description sfdu_class[] table of class ids with corresponding description identifier char msg_string[] used to store error string Change History Version Date Change Description RAG 08/01/93 Removal of global FileTable variable 5.4.7.1 create_unwrapped_files(sfdu, base_filename) Essentially this is an UNWRAP function. The data from the LVOs of the SFDU will be written to individual data files. The functions assumes that the SFDU has been parsed and stored in a SFDU tree structure (See Section 5.3.8). Abstract Unwrap data from an SFDU file to separate data files, removing all traces of SFDU labels. Return/Inputs/Outputs RETURN void INPUT SFDU * sfdu INPUT base_filename The prefix to be given to each unwrapped file, usually based on the sfdu filename Description This function will produce data files from an SFDU. The generated files will have all SFDU specific information removed leaving a raw data file. The data will be written to files based on base_filename if base_filename is NULL the files will be prefixed with a portion of the original SFDU file name. The rest of the file name is based on the number of the type of LVO found (01, 02, etc). Finally the extension of the file is determined based on the LVO type. These extensions are user configurable. See function create_modify_file_extension_table Notes/Assumptions This function assumes that the SFDU has been completely parsed first. See bld_parse_n_lvos function. An external reference is made to the file_extension_table to determine what extension to give to the various unwrapped data types. Error Handling None Change History XXX MM/DD/YY Original Code RAG 05/28/93 Removed call to set_ up_ base_filename which was based on the SFDU name or an option passed to the unwrap application The call is now in the unwrap application 5.4.7.2 create_set_up_base_file_name(sfdu) Abstract Set up the base file name to be used for "unwrapped" files Return/Inputs/Outputs RETURN none MODIFY SFDU *sfdu input SFDU for which the output base file name is determined Description Determine how many digits are needed for an adjusted filename. The output files for data will use as much of the filename (minimum 4 chars) to form the output filename, the rest would be sequences of numbers 0001, 0002, etc depending on the largest number of any type of non structure LVO. Notes/Assumptions We really only want to write out non-structure values. Assumes that the input SFDU has already been parsed. Error Handling None Change History XXX MM/DD/YY Original Code MA 04/13/93 Replace while loop with (math library) function log10 This function can be used to modify the extensions of the data files generated when an SFDU is unwrapped (See the previous function). The actual look up table (type sfdu_description) file_extension is contained in file creatdat.c can be modified directly in the source code. The table can also be modified at run time by using the options.def file. 5.4.8 CREATE MAP LANGUAGE FILES (CREATMAP.C) The CREATE MAP file contains functions that can be used to create MAP LANGUAGE files. The functions operate on completed LVO structures to generate the Maps. These functions are useful after using the parse functions in bldsfdu.c and the tree building functions in sfdutool.c to build an SFDU tree. The tree can then be used to generate a Map of the SFDU. Unit Description The CREATMAP unit provides functions for creating/modifying Map Language statements representing Label Value Objects (LVOs) and SFDUs. Unit Components /* main functions */ void create_map_file(SFDU *, char *) ; void create_map_statements(SFDU *, LVO *, int, FILE *) ; /* support functions */ void create_adid(char *, LABEL *) ; void create_delimitation_map_stmt(char *, LABEL *) ; void create_print_map_statement(int, char *, FILE *) ; Globals Defined sfdu_description file_extension[] table of class ids with corresponding default file extension used for "unwrapped" files External References sfdu_description sfdu_class[] table of class ids with corresponding description identifier sfdu_description sfdu_delimitation[] table of spare 1 bytes with corresponding delimitation description identifier sfdu_description sfdu_adid[] table of class ids with corresponding default ADID char msg_string[] used to store error string Change History Version Date Change Description RAG 08/01/93 Removal of global FileTable variable LVOs now contain file information 5.4.8.1 create_map_file(sfdu, output_map_file) Abstract Generate a Map Language file Return/Inputs/Outputs RETURN void INPUT SFDU *sfdu SFDU containing the LVO that the MAP statements are to be derived from INPUT char *output_map_file Name of the Map Language file Description This function first opens a Map Language file, then writes the current date and time to it, followed by all the Map statements, and finally closes the file Notes/Assumptions None Error Handling None Change History MA 03/04/93 Original Code MA 03/22/93 Add the path and filename of the SFDU file to the Map Language file RAG 07/20/93 Remove use of FileTable replaced with fopen function... no use of sfduftbl.c 5.4.8.2 create_map_statements(sfdu, lvo, level, fp) This function will output a Map Language statements to a file that represent an LVO. The function is recursive to handle the structure LVOs such as the SFDU (Z) Class. Abstract Create and write map statement(s) for LVO lvo to the file pointed to by fp Return/Inputs/Outputs RETURN void INPUT SFDU *sfdu SFDU containing the LVO that the MAP statements are to be derived from INPUT LVO *lvo LVO to derive the Map Language statements from INPUT int level indentation level of where the Map Language statement is to be written INPUT FILE *fp address of the file pointer where created Map Language statement is to be written Description Creates the following MAP LANGUAGE statements: BEGIN_OBJECT = LVO type END_OBJECT = LVO type BEGIN_OBJECT = SERVICE_DATA END_OBJECT = SERVICE_DATA ADID = adidname DELIMITATION = (delimitation, parameter) INCLUDE_DATA_FILE = filename Map Language statements in SERVICE_DATA aggregations are duplicated exactly as they are specified in REFERENCE and DATA_ADMINISTRATION Class LVOs. Other statements created are based on their values in the LABEL structure of LVO lvo. Map Language statements are created for any child LVOs of structure type LVOs by recursively calling the create_map_statements function. The filenames in the INCLUDE_DATA_FILE statements make use of the LVO_TYPE array in the SFDU structure to determine what number to affix to the base filename (e.g. file0001.ref, file0002.ref would represent the 1st and 2nd reference class objects). Notes/Assumptions All the information in the LABEL structure is complete. All structure LVOs are completed (i.e. contain their children) Error Handling None Change History XXX MM/DD/YY Original Code 5.4.9 SFDU FILE TABLE TOOLS (SFDUFTBL.C) The FILE TABLE TOOLS file contains functions for manipulating the SFDU FILE HANDLE data structure. The SFDU Libraries previously made use of a File Table that contained entries for all files processed by the SFDU Library. Most of the functions contained in this file are in support of the other functions in the Library. If changes to the SFDU Library are necessary due to using a different operating system and/or hardware, the most important function which may need to be modified for user applications is the ftbl_read_sfdu_data function, since it is the lowest level function responsible for input of SFDU data. The only other function that reads SFDU data is the bld_set_up_value function. While looking for label markers to delimit an LVO value, it reads SFDU data one byte at a time. It also reads an extra character to force an EOF condition when the LVO delimitation calls for it. Unit Description Routines for managing the File Table Unit Components /* support functions */ LOGICAL ftbl_sfdu_file_seek(SFDU *, ULONG, int) ; LOGICAL ftbl_reached_sfdu_eof(SFDU *) ; int ftbl_open_sfdu_file(SFDU *, char *, int) ; int ftbl_read_sfdu_data(SFDU *, char *, ULONG, int *) ; void ftbl_close_file(SFDU_FILE_HANDLE *) ; void ftbl_open_scratch_file(void) ; void ftbl_delete_scratch_file(void) ; Globals Defined External References char msg_string[] used to store error message Change History Version Date Change Description NLP 7-25-91 Original code RAG 07/26/93 Removal of Global FileTable LVO/SFDU now contain file information RAG 08/01/93 Removed close_all_files function should be replaced with a close all sfdu files function. 5.4.9.1 ftbl_read_sfdu_data(sfdu, buffer, nbytes, status) The read_sfdu_data function reads data from the SFDU. The SFDU data is read as stream data in binary mode. The arguments of the function include the number of bytes to be read and the SFDU where they are to be read from. Information contained on the File Stack of the SFDU structure indicates where the data from the SFDU will come from next. If the EOF was reached while reading the current data stream, the EOF status and the number of read bytes are returned. If an EOF is returned, the calling function could then issue another request to read data which would come from the next file on the top of the File Stack. It is important that any function utilizing ftbl_read_sfdu_data verify the returned status before processing the data. The function was written with the assumption that SFDU would be the only type of data read. Furthermore, the data to be read would either start at a label or a value object. Since these are items that are expected, carriage return-linefeed combinations are ignored. Review the code for more details. Abstract Determine where to read data then read nbytes of data from SFDU file Return/Inputs/Outputs RETURN int number of bytes read INPUT ULONG nbytes number of bytes to be read MODIFY SFDU *sfdu SFDU that data is to be read from MODIFY char *buffer buffer where the data is to be read into MODIFY int *status process status Description This function uses the SFDU * to determine which file to read data from. The source is the file on the top of the file stack of the SFDU. If an EOF is read it is returned as a status to the calling function. The following are possible return values for status: 1) VALUE_OK if data was read successfully 2) INCOMPLETE_DATA if the size of data read did not equal the bytes requested 3) EOF_REACHED if the file read an EOF character Notes/Assumptions The calling function is responsible for verifying the status returned before processing the data. Error Handling Only file access errors are reported. It is up to the calling routine to determine if there are any errors with the data itself. Change History XXX MM/DD/YY Original Code RAG 02/31/92 Removal of all file stack and RClass checking 5.4.10 PROGRAM OUTPUT MESSAGES (UTILMSG.C) The UTIL MESSAGE file contains functions that are responsible for all the output messages written to the screen (stdout). Users developing applications that need to control the output need only modify or replace the util_print_message and util_print_error functions in this file. Unit Description UTILMSG.C contains the function which prints error messages and a function for printing any output string. Unit Components void util_print_message(char *) ; void util_print_error(int, char *, char *) ; void util_toggle_warnings(LOGICAL) ; void util_toggle_messages(LOGICAL) ; LOGICAL util_inquire_toggle(LOGICAL) ; void util_open_message_file(char *) ; void util_close_message_file(void) ; Globals Defined LOGICAL print_warnings Global flag whether to print warning messages or not char msg_string[MAX_MESSAGE_LINE_LENGTH] used to store error/message string External References Change History Version Date Change Description 5.4.10.1 util_print_message(output_string) This function is simply a fprintf. The string that is passed is a pointer to a global string. That global string is written over when a new message is output to the screen. If messages are to be kept, a copy of the string must be made. Abstract Print output string Return/Inputs/Outputs RETURN none INPUT char *output_string the string to be printed OUTPUT output_string printed Description This function is used to print a output string. This function is used to make it easier to modify the output command used by the SFDU library. For now, it is a simple printf. Notes/Assumptions Assumes message string is defined. Error Handling None Change History XXX MM/DD/YY Original Code MA 03/09/93 Add test of whether or not output messages are toggled on RAG 06/25/93 All messages now directed to stderr MA 07/19/93 All messages now directed to variable destination (that is set to stderr by default and that optionally can be set to a file) MA 09/13/93 Default of output_dest changed to stdout 5.4.10.2 util_print_error(error_type, function_name, error_string) This function prints error messages to the screen (stdout). The function will also exit the application program if the type of ERROR passed to it is FATAL. Modifying the FATAL behavior is not recommended since the function that generated the message is in an unrecoverable state. There is also a global flag that can suppress printing of WARNING messages. The flag can be set using the util_set_print_error function. The error message string argument is a pointer to a global string. That global string is written over when a new error message is generated. If a message is to be kept, a copy of the string must be made. Developers may want to add their own ERROR codes for their applications. Abstract Prints an error message to stderr (default) or, optionally, to a user specified file Return/Inputs/Outputs RETURN none INPUT int error_type INPUT char *function_name INPUT char *error_string OUTPUT error message WARNING or FATAL message to stdout Description This routine prints an error message to stderr (default) or, optionally, to a user specified file. The message consists of the type of error (WARNING or FATAL error), the name of the function reporting the error, and the error string passed by the function. If the error type is FATAL and the user has specified a file for message output, the error message is also printed to stderr. Notes/Assumptions All files in the file table are closed on FATAL errors. Error Handling Error types other than WARNING and FATAL are considered unrecognized. Change History XXX MM/DD/YY Original Code RAG 06/25/93 All messages now directed to stderr MA 07/19/93 All messages now directed to variable destination (that is set to stderr by default and that optionally can be set to a file) MA 09/13/93 Default of output_dest changed to stdout 5.4.10.3 util_toggle_warnings(on_off) Abstract Toggle printed warnings on or off Return/Inputs/Outputs RETURN none INPUT LOGICAL on_off Indicates whether the printed warning messages should be toggled on or off Description This function toggles printed warning messages on or off by assigning appropriate values to the global flag print_warnings. Note that print_warnings signals whether the util_print_error function should print WARNING messages or not. Notes/Assumptions None Error Handling None Change History NLP 09/21/92 Original Code MA 03/09/93 Code modified to match code for toggling messages 5.4.10.4 util_toggle_messages(on_off) Abstract Toggle printed messages on or off Return/Inputs/Outputs RETURN none INPUT LOGICAL on_off Indicates whether the printed (informational) messages should be toggled on or off Description This function toggles printed output messages on or off by assigning appropriate values to the global flag print_messages. Note that print_messages signals whether the util_print_message function should print (informational) messages or not. Notes/Assumptions None Error Handling None Change History MA 03/09/93 Original Code 5.4.10.5 util_inquire_toggle(type) Abstract Inquire whether the specified type of messages are toggled on or off Return/Inputs/Outputs RETURN LOGICAL TRUE if specified type is toggled ON, FALSE if specified type is toggled OFF, INQUIRE_ERROR if specified type is undefined INPUT LOGICAL type Specifies whether the inquiry is for warning messages (type == WARNING) or (informational) output messages (type == MESSAGE) Description This function returns the value of the print_warnings or the print_messages global flag, i.e., indicates whether the specified type of messages is toggled on or off. Notes/Assumptions None Error Handling Returns the value INQUIRE_ERROR (= 2) if the function is called with an undefined type value Change History MA 03/09/93 Original Code 5.4.10.6 util_open_message_file(msg_file) Abstract Open a file to direct error and (informational) output messages to Return/Inputs/Outputs RETURN none INPUT char *msg_file The name of the file to be opened Description This function opens a file that all error and (informational) output messages are directed to. Notes/Assumptions None Error Handling If the file open fails, a FATAL error message is written to stderr and the program terminates. Change History MA 07/19/93 Original Code 5.4.10.7 util_close_message_file() Abstract Close the file for error and (informational) output messages Return/Inputs/Outputs RETURN none INPUT none Description This function closes the file that all error and (informational) output messages are directed to. Notes/Assumptions None Error Handling None Change History MA 07/19/93 Original Code 5.4.11 UTILITY FUNCTIONS (UTILITY.C) The UTILITY file contains utility functions written in support of the other Library functions. Functions include push, pop, top, and empty functions for the stack structure and data conversion routines. There are also functions for getting directory file listings from the DOS and UNIX machines. These may need to be modified if the source code is ported to other operating systems or different compilers are used. Unit Description This module is a collection of functions that are used to support the other functions used in the creation and manipulation of SFDUs. Unit Components /* main functions */ void *util_do_malloc(unsigned int) ; ULONG util_file_reference_copy(FILE *, FILE *, ULONG, ULONG) ; /* support functions */ void util_push(Stack_Type *, void *) ; void util_pop(Stack_Type *) ; void * util_top(Stack_Type *) ; LOGICAL util_empty(Stack_Type *) ; ULONG util_charstr_to_long(UCHAR *) ; void util_long_to_charstr(ULONG, UCHAR *) ; void util_long_to_ascii(ULONG, char *, int) ; #ifdef DOS char ** util_get_TCDOS_file_list(char *, int *) ; #endif #ifdef SUN char * util_create_regular_expression(char *) ; char ** util_get_SUNUNIX_file_list(char *, int *, char *) ; #endif char ** util_expand_filespec(char *, int *) ; External References Change History Version Date Change Description RAG 08/30/93 Removed util_print_tree function see sfd_display_lvo_summary_report 5.4.11.1 util_do_malloc(size) Abstract Allocates size bytes of main memory (smart malloc) Return/Inputs/Outputs RETURN void * pointer to the newly allocated space INPUT unsigned int size size of the space requested for allocation Description This is the same as malloc except it reports a fatal error when malloc is unable to allocate the bytes requested. When successful, a pointer to the newly allocated space is returned. Notes/Assumptions None Error Handling If malloc is unable to allocate enough memory, a FATAL error is reported. Change History XXX MM/DD/YY Original Code 5.4.11.2 util_file_reference_copy(source, dest, offset, length) Abstract Copies a portion of the source file into the destination file Return/Inputs/Outputs RETURN ULONG Number of bytes written to outfile INPUT FILE *source source file pointer MODIFY FILE *dest destination file pointer INPUT ULONG offset offset within source (in number of bytes) where the data starts INPUT ULONG length number of bytes to copy Description util_file_reference_copy copies n bytes from the source file stream source to the destination file stream dest starting at offset bytes from the beginning of the source stream. Notes/Assumptions None Error Handling None Change History NLP 08-27-91 Original code. 5.4.12 SFDU OPERATION FUNCTIONS (SFDUOPS.C) The SFDUOPS file contains some functions that may be of interest to application developers. The functions provide capability to create, modify, and delete LVOs and SFDUs. The functions are contained in the SFDUOPS.LIB library. Unit Description SFDUOPS.C contains functions for creating and modifying LVOs and SFDUs. The functions create simple LVOs from buffer or file data, insert or delete LVOs from SFDUs, create structure LVOs, and replace LVO value fields. Unit Components /* main functions */ void ops_change_delim_to_length(LVO *) ; SFDU * ops_change_lvo_buffer_value(SFDU *, LVO *, char *, ULONG) ; SFDU * ops_change_lvo_file_value(SFDU *, LVO *, char *) ; char * ops_copy_lvo_value_to_buffer(LVO *) ; void ops_copy_lvo_value_to_file(LVO *, FILE *) ; LVO * ops_create_lvo_from_buffer_data(char, char *, char *, char, char *, char *, ULONG) ; LVO * ops_create_lvo_from_file_data(char, char *, char *, char, char *, char *) ; LVO * ops_create_structure_lvo(char, char *, char *, char, char *, LVO *) SFDU * ops_delete_lvo_from_sfdu(SFDU *, LVO *) ; SFDU * ops_get_sfdu_structure_from_file(char *, int *) ; SFDU * ops_insert_lvo_into_sfdu(SFDU *, LVO *, LVO *) ; LOGICAL ops_verify_lvo(LVO *) ; /* support functions */ void ops_adjust_labels(SFDU *, LVO *) ; void ops_adjust_parse_levels(SFDU *) ; void ops_free_lvo(LVO *) ; void ops_free_value(LVO *) ; Globals Defined External References char msg_string[] used to store the error message sfdu_description sfdu_class[] table of class ids with corresponding description identification Change History Version Date Change Description 1.2 09/01/93 MA Changed names of functions - now they are prefixed with ops_ 1.2 09/13/93 MA Reorganized order of functions - first come main functions, followed by support functions Some of the highlights of the SFDU OPERATION functions: 5.4.12.1 ops_change_delim_to_length(sfdu, lvo, new_file_value) Abstract Change delimitation type to ASCII length Return/Inputs/Outputs RETURN none INPUT LVO *lvo Description This function changes the delimitation type for an LVO to ASCII length. The lengths of succeeding parent LVOs are also adjusted by recursive execution of this function. Notes/Assumptions None Error Handling None Change History ??? ??/??/9? Original Code 5.4.12.2 ops_change_lvo_file_value(sfdu, lvo, new_file_value) Abstract Replace current lvo value with data in file new_file_value stored via file reference Return/Inputs/Outputs RETURN SFDU *sfdu SFDU with modified LVO INPUT SFDU *sfdu SFDU to modify INPUT LVO *lvo LVO containing value to modify INPUT char *new_file_value file name of file containing new LVO value Description This function frees the current value field of lvo whether it is a buffer or file reference. A file reference to the new file value is created and assigned lvo's value field. The label of lvo is updated and all parent LVOs affected are adjusted as necessary. Other LVO fields affected by the change are finfo, value.vtype, value.storage, value.length, all label sub-fields. Notes/Assumptions Assumes lvo is defined. Error Handling None Change History XXX MM/DD/YY Original Code MA 08/17/93 Change FileTable to pointer 5.4.12.3 ops_change_lvo_buffer_value(sfdu, lvo, new_buffer_value, new_buffer_length) Abstract Replace current lvo value with data in buffer new_buffer_value Return/Inputs/Outputs RETURN SFDU *sfdu SFDU with modified LVO INPUT SFDU *sfdu SFDU to modify INPUT LVO *lvo LVO containing value to modify INPUT char *new_buffer_value buffer containing new value data INPUT ULONG new_buffer_length length of new_buffer_value Description This function frees the current value field of lvo whether it is a buffer or file reference. The buffer new_buffer_value is assigned as lvo's new value field. The label of lvo is updated and all parent LVOs affected are adjusted as necessary. Other LVO fields affected by the change are value.vtype, value.storage, value.length, all label sub-fields. Notes/Assumptions Assumes lvo is defined. Error Handling None Change History XXX MM/DD/YY Original Code 5.4.12.4 ops_create_lvo_from_buffer_data(lvo_class, caid, ddid, delim_type, delim_parameter, buffer, buffer_length) This function will create an LVO data structure based on data contained in a buffer. The structure will have the appropriate values filled in. The arguments include the buffer pointer, buffer length, and LVO specific information such as ADID and delimitation method. Once the LVO is created it can be attached to an SFDU tree. Abstract Create a new LVO whose value is contained in a buffer Return/Inputs/Outputs RETURN LVO * new LVO created INPUT char lvo_class class id for new LVO INPUT char caid[] CAID for new LVO INPUT char ddid[] DDID for new LVO INPUT char delim_type type of delimitation for new LVO; also equal to spare 1 INPUT char delim_parameter[] delimitation parameter to be used by new LVO's label INPUT char *buffer buffer containing value data for new LVO INPUT ULONG buffer_length length of buffer Description This function allocates a new LVO whose value field is stored in a value buffer. The label fields are populated with the passed label data while the value field is assigned using the passed buffer and buffer length. Notes/Assumptions Assume passed buffer information (buffer, buffer length) are valid. Error Handling None Change History XXX MM/DD/YY Original Code 5.vþšË ops_create_lvo_from_file_data(lvo_class, caid, ddid, delim_type, delim_parameter, filename) This function will create an LVO data structure based on data contained in a file. The structure will have the appropriate values filled in. The arguments include the file name and LVO specific information such as ADID and delimitation method. Once the LVO is created it can be attached to an SFDU tree. Abstract Create a new LVO whose value is contained in a file Return/Inputs/Outputs RETURN LVO * new LVO created INPUT char lvo_class class id for new LVO INPUT char caid[] CAID for new LVO INPUT char ddid[] DDID for new LVO INPUT char delim_type type of delimitation for new LVO; also equal to spare 1 INPUT char delim_parameter[] delimitation parameter to be used by new LVO's label INPUT char *filename name of file containing value data of new LVO Description This function allocates a new LVO whose value field stored through a file reference. The label fields are populated with the passed label data. A file reference structure is created for the file containing value data and is assigned to the LVO's value field. Notes/Assumptions Assume passed file is valid. Error Handling None Change History XXX MM/DD/YY Original Code RAG&MA 08/27/93 Change FileTable to pointer; Open the referenced file inside this function 5.4.12.6 ops_create_structure_lvo(class_type, adid, delim_type, delim_parameter) This function will create a structure Class LVO (SFDU, DDU, or IDU). The created structure LVO can be attached to an SFDU tree. Abstract Create a STRUCTURE class LVO (Z, U, F) Return/Inputs/Outputs RETURN LVO * Newly created structured LVO INPUT class_type Class Type of the LVO to be created INPUT char adid ADID of the LVO to be created INPUT char delim_type delimitation method to be used to delimit the LVO INPUT char delim_parameter delimitation_parameter if necessary Description This function will create a structure class LVO based on the inputs. Z (SFDU) U (Data Description Unit) F (Information Data Unit) Really this function creates the necessary pieces of the label, the delimitation parameters (length) may be filled in later Notes/Assumptions Function will only create Version3 LVOs Error Handling ... Change History RAG 06/18/92 Original Code MA 08/24/93 Change FileTable index to finfo pointer 5.4.12.7 ops_delete_lvo_from_sfdu(sfdu, lvo_to_delete) This function will delete an LVO from an SFDU. Once deleted the SFDU will be modified to correct any LVOs and LABELS that may change because of the deletion. Abstract Delete LVO lvo from SFDU sfdu Return/Inputs/Outputs RETURN INPUT LVO *lvo LVO to be deleted MODIFY SFDU *sfdu SFDU containing LVO to be deleted Description This function deletes lvo_to_delete from sfdu. The deletion of lvo_to_delete involves searching for the pointers affected by the deletion to keep the LVO tree properly connected after deletion. After lvo_to_delete is deallocated, labels of all affected LVOs in the SFDU are updated. Notes/Assumptions None Error Handling WARNING on bad parent Change History NLP 03/04/92 Original Code 5.4.12.8 ops_insert_lvo_into_sfdu(sfdu, lvo_to_insert, lvo_to_move) This function will insert an LVO into an SFDU. Once inserted, the SFDU will be modified to correct any LVOs and LABELS that may change because of the insertion. This function is different from the sfd_append_lvo function since the point of insertion can be specified. The sfd_append_lvo can only append LVOs at the end of the SFDU tree. Abstract Insert a LVO lvo_to_insert in SFDU sfdu at the position of lvo_to_move Return/Inputs/Outputs RETURN SFDU *sfdu modified SFDU INPUT SFDU *sfdu SFDU to modify INPUT LVO *lvo_to_insert LVO to insert in the SFDU INPUT LVO *lvo_to_move LVO currently occupying position where other LVO will be inserted Description This function inserts LVO lvo_to_insert in the position where lvo_to_move is currently located in the SFDU sfdu. If lvo_to_move equals NULL, a WARNING is reported and insertion is not performed. Notes/Assumptions None Error Handling WARNING if lvo_to_move equals NULL. Change History XXX MM/DD/YY Original Code 5.4.12.9 ops_copy_lvo_value_to_buffer(lvo) This function will copy the value of an LVO to a buffer. Since the parse functions of the library produce FILE REFERENCES for large values, this function is useful for placing the data in a buffer for easier access. Abstract Return a buffer containing a copy of the contents of an LVO's value field. Return/Inputs/Outputs RETURN char * a pointer to a copy of the data INPUT LVO *lvo LVO containing the value to copy Description This function copies the value field of an LVO to a buffer for processing by a user program. The function will copy the value whether it is stored in a buffer or a FILE REFERENCE Notes/Assumptions LVO cannot be a structure class LVO. The returned buffer should be freed after use. Error Handling Function will return NULL if enough memory could not be allocated to store the copy of the value. Change History RAG 07/06/92 Original Code MA 08/17/93 Change FileTable to pointer MA 09/30/93 Add parameter to error message in case of LVO_TYPE; Add NULL terminator to (returned) buffer 5.4.12.10 ops_copy_lvo_value_to_file(lvo, fp) This function will copy the value of an LVO to a file. Since the parse functions of the library produce FILE REFERENCES or buffers for the values, this function is useful for placing the data in a file for easier access. This function could be part of an unwrap application. Abstract Copy the contents of an LVO's value field to an file. Return/Inputs/Outputs RETURN none INPUT LVO *lvo LVO containing the value to copy INPUT fp File Pointer where the data is to be copied to Description This function copies the value field of an LVO to an opened file specified by the file pointer. The function will copy the value whether it is stored in a buffer or a FILE REFERENCE Notes/Assumptions LVO cannot be a structure class LVO. The File specified by the File Pointer is opened and ready for writing Error Handling Function will return NULL if enough memory could not be allocated to store the copy of the value. Change History RAG 07/06/92 Original Code MA 08/17/93 Change FileTable to pointer MA 09/30/93 Add parameter to error message in case of LVO_TYPE 5.4.12.11 ops_get_sfdu_structure_from_file(filename, status) Abstract ops_get_sfdu_structure_from_file will parse either a SFDU formatted file or a Map Language File and return the corresponding SFDU structure tree. Return/Inputs/Outputs RETURN SFDU *sfdu Created sfdu structure INPUT char * filename File containing the SFDU or Map Language File MODIFY int * status Status of the operation Possible values are PARSE_FAIL or PARSE_SUCCESS Description This function first checks if the file can be parsed as an SFDU, if a Map Language parse is done. In either case, if the parse fails the constant PARSE_FAIL is returned in the status variable. If the parse is a success, PARSE_SUCCESS is returned and the created sfdu structure is returned. Notes/Assumptions None Error Handling None Change History RAG ??/??/93 Original Code 5.4.13 COMPARE LVOs (LVOCMPRE.C) Unit Description LVOCMPRE.C contains functions that can be used to verify two SFDUs (LVOs) are the same type. These checks contain a combination of CLASS, ADID, and DELIMITATION Unit Components /* main function */ compare_lvos /* support functions */ compare_lvo_class compare_lvo_delimitation compare_lvo_adid Globals Defined External References N/A Change History 1/12/93 Creation 5/24/93 RAG Change function names from same_... to compare... 5.4.13.1 compare_lvos(lvo1, lvo2, check_class, check_adid, check_delimitation) Abstract Check if the two input sfdus have the same structure. Return/Inputs/Outputs RETURN LOGICAL TRUE/FALSE indicating equality INPUT LVO* lvo1 first of the two SFDUs INPUT LVO* lvo2 second of the two SFDUs being compared INPUT int check_adid LOGICAL flag for checking the ADIDs of the two SFDUs INPUT int check_class LOGICAL flag for comparing the LVO class types of the two SFDUs INPUT int check_delimitation LOGICAL flag for checking the DELIMITATION of the two SFDUs Description Determines if two input SFDUs have the same structure.. e.g two Z-K-I SFDUs. Any combination of these three checks can be made with two SFDUs: LVO Class Type, ADID name, and Delimitation. Notes/Assumptions This function determines structural equality NOT equality of the contents of the SFDUs. The function does not consider case of Referenced LVOs (R Class). A ZKRI is different from a ZKI even though the R references the I. Error Handling None Change History RAG 01/12/93 Original Code 5.5 Error Handling Errors are handled in one of two ways by the SFDU Library. The functions may return a status code that indicates the result of the operation. The return codes are documented in the above Function Descriptions. These return codes can be used to direct processing of the user developed applications. The other type of error handling involves the reporting of problems with the processing of SFDUs. There are two types of SFDU processing errors produced by the SFDU Library: WARNING and FATAL. WARNINGs will not terminate the processing of SFDUs, however the FATAL errors always do. Each time an error is detected, an error message containing the name of the function that caused the error and descriptive text is sent to the util_print_error function. The WARNING messages can be suppressed by setting the print_warnings flag in the utilmsg.c file. These error messages can be processed by user applications for display in windows of GUI applications, redirected to files, etc. The util_print_error function is contained in the file utilmsg.c. This function currently writes the message to stdout, but it can be modified to handle the messages as appropriate. This was done to save integrators the trouble of searching for all areas of the code that handle errors. All error messages are written to a global character array, so once a message is overwritten it is gone. A new array would have to be allocated if a message is to be saved for later use. Similarly, the util_print_message in the utilmsg.c file can be modified to process the status messages that get written to standard out. These messages include processing and status messages. These messages are also written to a global character array. If the message is to be kept, space must be allocated and the message copied to it. Note that the application EXTRACT is an exception from the default of sending status and error messages to stdout. The messages are instead sent to stderr in this application. 5.6 SFDU Function Summary The following is a summary of functions that might be of interest to the application developers. These are not all the functions included in the Library but those that were highlighted in the previous section. FUNCTION NAME DESCRIPTION LABEL TOOLS lbltools.c lbl_parse_sfdu_label Parse an SFDU label and store the label fields in a label structure lbl_get_value_type Return the type of the data in an LVO's value field based on its label data lbl_get_class_type Return if an LVO is a STRUCTURE class, DATA class, or SERVICE class LVO based on its class id lbl_get_delim_type Return the type of delimitation used by an LVO (ASCII_LENGTH, BINARY_LENGTH, MARKER, SHARED_EOF, NUM_EOFS or CONTIG_EOFS lbl_descriptor_id Return the ID of an element in an SFDU descriptor table corresponding to the description text lbl_description_text Return the description text of an element in a SFDU descriptor table corresponding to a descriptor ID VALUE TOOLS valtools.c val_compute_length Compute and return the length of a STRUCTURE class LVO's value val_validate_reference_stmts Validate the PVL statements used in a Reference class LVO val_validate_data_admin_stmts Validate Parameter-Value Language (PVL) statements used in a Data Administration LVO val_check_adid_spec Check whether a LVO conforms to the CCSDS ADID specifications val_check_DDU_value Validate the value field of an Description Data Unit (DDU) val_check_IDU_value Validate the value field of an Information Data Unit (IDU) BUILD / PARSE TOOLS bldsfdu.c bld_parse_n_lvos Parse n LVOs from an SFDU file bld_parse_next_lvo Parse the next LVO from an SFDU bld_set_up_PVL_tree Parse the value field of an LVO to setup a PVL tree. SFDU TOOLS sfdutool.c sfd_initialize_sfdu Create an SFDU structure and initialize its fields sfd_get_next_lvo Return the next LVO in an SFDU file sfd_display_lvo_summary_report Display a formatted report on the LVOs parsed/created from an SFDU MAP LANGUAGE TOOLS mapltool.c mapl_create_sfdu_from_map Interpret a Map Language file to create an SFDU tree CREATE LVO TOOLS creatlvo.c create_CCSDS_standard_label Create a byte string containing a CCSDS standard label create_version3_label Create a byte string containing a version 3 SFDU label create_wrapped_sfdu_file Write the SFDU represented by an SFDU tree into an SFDU file CREATE MAP LANGUAGE FILES creatmap.c create_map_statements Create Map Language statements for LVOs in an SFDU create_map_file Create a Map Language file from an SFDU CREATE DATA OBJECTS creatdat.c create_set_up_base_file_name Set up the base filename to be used for "unwrapped" files create_unwrapped_files Create files containing value data extracted from an SFDU OUTPUT MESSAGES utilmsg.c util_print_error The SFDU Tool Kit's primary means of error reporting - reports FATAL errors and WARNINGs SFDU File Table Tools sfduftbl.c ftbl_read_sfdu_data Reads data from the appropriate file of the SFDU. UTILITY FUNCTIONS utility.c util_do_malloc Allocates memory for use by the Tool Kit. Reports error if not enough memory util_file_reference_copy Copys data contained within a file to another file. Useful for copying SFDU File Reference Data SFDU OPERATIONS sfduops.c ops_change_delim_to_lenght Changes LVO delimitations to ASCII length ops_change_lvo_buffer_value Changes LVO value field to data contained in a buffer ops_change_lvo_file_value Changes LVO value field to data contained in a file ops_create_lvo_from_buffer_dat a Create a LVO and use the data stored in the passed buffer argument as its value field ops_create_lvo_from_file_data Create a LVO and use the data from the passed file argument as its value field ops_copy_lvo_value_to_buffer Copy LVO value field to a buffer ops_copy_lvo_value_to_file Copy the value of an LVO to a file. ops_create_lvo_from_buffer_dat a Create an LVO from data contained in a buffer ops_create_lvo_from_file_data Create an LVO from data contained in a file ops_create_structure_lvo Create a Structure class LVO ops_delete_lvo_from_sfdu Delete a LVO from an SFDU tree ops_insert_lvo_into_sfdu Insert a LVO into an SFDU tree ops_get_sfdu_structure_from_fi le Get the SFDU structure tree from a Map or SFDU file ops_verify_lvo Verify the data stored in an LVO structure COMPARE LVOS lvocmpre.c compare_lvos Compare lvo1 with lvo2 for equality. Three checks can be done Class Type, ADID, and Delimitation 6 PVL Library The PVL Library is a collection of routines that can be used to create and manipulate PVL data. The library is organized into top level and low level functions. The top level functions serve as a layer above the low level functions. Although user programs may perform all operations using the top level routines, the low level routines are available for those who want to access them. 6.1 PVL Library Constants This section lists some of the constants used in the PVL Library. Below are the codes used to identify what type of value a stored PVL statement object has. For example, the statement SAMPLE = 94.7 has a value of type real. Therefore, the statement's value type would be TYPE_REAL. The value types used are based on the types defined in the PVL specification. TYPE_UNQUOTED 1 TYPE_CHAR 2 TYPE_INT 3 TYPE_NON_DECIMAL 4 TYPE_REAL 5 TYPE_DOUBLEQ_STRING 6 TYPE_SINGLEQ_STRING 7 TYPE_SET 10 TYPE_SEQUENCE 11 TYPE_TIME_DATE 12 NO_VALUE 0 Other constants used in the library are logical values, or return codes. TRUE 1 FALSE 0 ACCEPT 1 REJECT 0 ERROR -1 These constants are found in PVL.H along with preprocessor macros listed below. The macros are used when parsing PVL statements to determine the type of character inputs : ISINTCHAR(c), ISREALCHAR(c), ISQUOTABLE(c), ISLITERAL(c), ISRHS(c), ISUNITS(c), ISKEYWORD(c), ISWHITE(c), ISEOS(c). 6.2 PVL Data Structures There are only a few structures used in the PVL library. The primary structure is the leaf structure which stores statement data. The other structures are the Value_and_Type structure and the list structure for value lists. 6.2.1 The leaf Structure The leaf structure stores all statement specific data. It stores the keyword string, the value string or its components, and links to related leaves. Below is the declaration for the leaf structure. leaf { char *name keyword char *valuestr Value string. Note that for sets and sequences, the value string is divided into its elements which are represented by individual leaves. The original set or sequence value string is not stored in these cases. Some examples are shown later in this section. char *unitstr Unit string int is_aggr TRUE or FALSE indicates whether the statement is an aggregation or not int value_type may be TYPE_INT, TYPE_REAL, TYPE_UNQUOTED, etc. described in section 6.2 depending on the type of the statement's value int listlevel List level is used for list values. For example, in the statement x = (a, b) the leaves for a and b have list level 1; in the statement y = (a, (b), {c}, d) the leaves for a and d have list level 1 while the leaves for b and c have list level 2. int line_no Line number where statement is located in a file int stmt_no Statement number within the PVL data object union { long intval Value converted to integer double realval Value converted to real char *stringval Copy of value string (without quotes) char *timeval Time value string leaf *vlist Used for connecting list elements of list-valued statements } value leaf *sub Used for connecting sub-statements of aggregations leaf *next Used for connecting to the next statement in the PVL data object or the next list element in a list } Different types of PVL statements are represented using a single leaf or a set of leaves connected together. Simple statements with integer, real, non-decimal, string, date or time values are represented using a single leaf. Simple statements which have lists, namely sets or sequences, as values are represented by groups of linked leaf structures. Aggregation statements use single leaves with a connection to their sub-statements. Below are some sample PVL statements. Their corresponding internal representations using leaf structures are shown in the figures that follow. (1) ADID = CCSD0001 (2) DELIMITATION = (MARKER, ENDZHERE) (3) SET = { (6,4), (6,2), 8 } (4) BEGIN_OBJECT = G1 FIRST = A LAST = Z END_OBJECT Although all the functions in the PVL library operate on leaves, applications do not have to declare pointers to leaves. The following type definitions allow applications to declare statement objects or list element objects which hide the notion of leaves. The top level routines use these types; they create statements, search for statements, and insert statements not leaves. typedef leaf * Statement typedef leaf * List_element List elements represent leaves for values contained in sets or sequences. From the previous list type statement example SET = {(6,4), (6,2), 8} the list elements of SET are the sequence (6,4), the sequence (6,2), and 8. The list element (6,4) also consists of list elements which are 6 and 4 while the list element (6,2) consists of list elements 6 and 2. 6.2.2 The Value_and_Type Structure A structure called Value_and_Type is used in the PVL library for passing value data. The structure stores the value type as well as the actual statement value. Value_and_Type { int value_type may be TYPE_INT, TYPE_REAL, TYPE_UNQUOTED, etc. depending on the type of the statement's value union { long intval Value converted to integer double realval Value converted to real char *stringval Copy of value string (without quotes) char *timeval Time value string leaf *listval Used for connecting list elements of list-valued statements } val } 6.2.3 The list Structure The list structure is an intermediate structure used for building a linked list containing data in the value part of a "keyword = value" statement. This list structure is used exclusively by the low level routines. The linked list is called a value list and is built when the value is parsed and its type determined. Therefore, when building the leaves for statements, all relevant value information may be accessed through the value list. list { char *str char *units int value_type int listlevel int line_no int stmt_no list *lnext } Below are some sample statements and their corresponding value lists. (1) Sample = "This is a string" (2) SET = { 1, 2, 3, (4,5) } NOTE: Aggregations do not have values so they do not use value lists. Also note the term "list" here is different from the one used to refer to list values (sets and sequences) described earlier. "List" here refers to the value lists used by the low level function make_leaf to hold value data while lists in the earlier section refers to statement values that are sets or sequences. 6.3 PVL Library Function Highlights This section is intended to give an overview of how the PVL Library source code is organized and the functionality provided by each file. Descriptions about the content of each source file is given. More importantly brief descriptions are given on high level functions that would be of interest to integrators. Most of the functions mentioned here are contained in the source file toplevel.c. The top level routines allow applications to create and manipulate PVL trees. The tree is an internal representation of a PVL data object. Applications may utilize the functions listed below to manipulate PVL data. Most of the functions listed are contained in the TOPLEVEL.C source file. The routines are grouped according to functionality. 6.3.1 PVL Top Level Function Summary A table of the top level functions in the PVL library is shown here. All of these functions can be found in TOPLEVEL.C. FUNCTION NAME OPERATION Add a statement to a tree add_statement add a statement to a PVL tree add_substmt add a sub-statement to an aggregation Change statement data change_keyword change statement keyword change_value change statement value change_aggregation_tag change aggregation block name change_aggregation_keyword change aggregation block keyword (OBJECT, GROUP, etc.) change_one_units change units string of a statement change_all_matched_units change units string of all statements which currently have the given units string Count statements count_statements count all statements in a tree count_substmts count sub-statements in an aggregation count_aggregations count aggregations in a tree count_sub_aggrs count sub-aggregations in an aggregation Create statement objects create_statement create a statement object create_aggregation create an aggregation create_pvl_object Create PVL data object delete_statement Delete a statement from a tree is_aggregation Identify statement type Aggregation or simple keyword- value insert_statement Insert a statement in a tree Move statement(s) in a tree move_statement move a statement within a PVL tree move_number move the statement with the given number swap_statements swap positions of two statements renumber Renumber statements in a tree Return statement data get_stmt_value return the value of a statement get_keyword return the keyword of a statement get_aggregation_tag return the aggregation name of a statement get_stmt_value_type return the value type of a statement get_value_string return the value of a statement as a string Search routines search_name search for a statement by name search_number search for a statement by number predecessor return the previous statement successor return the next statement Search involving aggregations next_matched_aggr search for the next aggregation with the same name as the given aggregation search_nth_matched_aggr search nth aggregation of the given name search_nth_substmt search nth sub-statement of a given aggregation search_parent_aggregation search parent aggregation where a given sub-statement belongs The unit description for TOPLEVEL.C follows: Unit Description This module contains the main PVL routine library - user level operations on PVL tree data. The user may call all non-static functions defined in this module through his/her program. The definition of the type Statement is in module stmtops.h as well as the definition of type Value_and_Type. Low level structures and functions are utilized by the routines in this module, thus the inclusion of leafops.h. The operations on list-valued statements part of the PVL routine library is found in module listops.c. stmtops.h ( definition of leaf structure ) pvl.h ( PVL global data type definitions ) buffer.h ( buffering routines header ) Unit Components Globals Defined int stmtnumber Used for renumbering statements char error_string[MAX_ERROR_STRING_LENGTH] ; String used to store error message static int stmtcount Used for counting statements static int aggrcount Used for counting aggregations static Statement last_aggr_passed Used to keep track of the last aggregation statement encountered during recursion in search_parent_aggregation External References Change History Version Date Change Description Revision 1.1 91/4/01 norbert Add handling of DATE/TIME values in get_stmt_value Revision 1.5 91/05/17 1:00 pm norbert Added count_statements, count_substmts, count_aggregations, count_subaggrs Revision 1.4 91/05/08 14:15 norbert Record addition of swap_statements, removal of rec_search_name, and rec_search_number Revision 1.3 91/04/29 10:20 am norbert Added the following functions : search_nth_matched_aggr, search_nth_substmt, is_aggregation, next_matched_aggr Revision 1.2 91/04/18 10:00 am norbert Allowed both delimited and nondelimited unit string inputs in create_statement, change_one_units, rec_change_units, change_all_matched units Revision 1.1 91/03/22 10:30 am norbert Added search_number, move_number Revision 1.0 91/03/20 9:00 am norbert Report parser modules reorganization Initial revision 6.3.2 Parse Calls (PARSCALL.C) The main tree generating functions in the PVL library are parse_file, which creates a tree for PVL data stored in a file, and parse_buffer, which creates a tree for PVL data stored in a buffer. Unit Description The functions here are the main parsing calls. A function which calls the parser given file input is supplied as well as another given a user buffer input. The primary call to the parser is yyparse(). Unit Components parse_file parse_buffer Globals Defined None External References leaf * root root leaf of PVL tree char * filename name of PVL file to parse int stmtno statement number int lineno statement line number Change History Version Date Change Description Revision 1.0 91/03/20 9:00 am norbert Report parser modules reorganization 6.3.2.1 parse_file(infile, status, offset, length) parse_file parses PVL data from an input file and builds a PVL tree. The data that is read from the input file is processed through a pair of buffers which is managed by the PVL buffer routines. Once the PVL tree is built, it may be manipulated to change the represented PVL data. Synopsis leaf * parse_file(infile, status, offset, length) Abstract Parse a PVL file and create a PVL tree for parsed PVL data Return/Inputs/Outputs RETURN leaf * returns the head pointer to the PVL tree created INPUT char *infile name of input PVL file MODIFY int *status returns the status of the parse (PARSE_FAIL/PARSE_SUCCESS) this is actually the code returned from yyparse() INPUT ULONG offset offset from the beginning of the file where the PVL data begins INPUT ULONG length length of the PVL data from the offset position Description This function parses PVL data contained in a file. Data are put in buffers as they are read from the input file. The buffers are parsed and reloaded as necessary. Initially, the statement number, the line number and the head tree pointer are initialized. Then, the YACC generated function yyparse is called to perform syntax analysis. The code generated by YACC also creates the PVL tree during parsing. Note that the output tree's head pointer is a global variable. Leaves are added to the tree using this variable. When parsing ends, the tree completed is returned. The #define constants START and ALL can be passed in the offset and length parameters respectively to force parsing for the entire file. Notes/Assumptions The parsing will stop if a PVL 'END' statement is encountered,regardless if there are more PVL statements after the 'END' statement. The parsing code were generated by specifying the PVL language through a set of rules which are translated by YACC into C code. Along with the rules are corresponding actions specified in C. Most of the actions specified in the PVL parser are calls to the PVL library for creating leaves and building trees. Error Handling Syntax errors detected are reported by yyparse Two #define constants indicate the status of the parse: PARSE_FAIL and PARSE_SUCCESS Change History XXX MM/DD/YY Original Code RAG 01/19/93 Added status parameter RAG 02/22/93 Added offset and length parameters 6.3.2.2 parse_buffer(buf, n_bytes, status) parse_buffer is similar to parse_file except this function processes data from an input buffer with a specified buffer length. The same initialization process is involved between parse_file and parse_buffer and the same data type is returned - a PVL tree. Synopsis leaf * parse_buffer(buf, n_bytes, status) char * buf; unsigned long n_bytes; int *status Abstract Parse a PVL buffer and create a PVL tree for parsed PVL data Return/Inputs/Outputs RETURN leaf * returns the head pointer to the PVL tree created INPUT char *buf address of first byte in the input buffer INPUT unsigned long n_bytes length of the input buffer MODIFY int *status returns the status of the parse (PARSE_FAIL/PARSE_SUCCESS) this is actually the code returned from yyparse() Description This function handles the initiation of the parsing process in the case where the input supplied is stored in a buffer. The buffer must be defined and its length must be specified. Once the length specified is reached, parsing is halted. Initially, the statement number, the line number and the head tree pointer are initialized. Then, the YACC generated function yyparse is called to perform syntax analysis. The code generated by YACC also creates the PVL tree during parsing. Note that the output tree's head pointer is a global variable. Leaves are added to the tree using this variable. When parsing ends, the tree completed is returned. Notes/Assumptions The parsing will stop if a PVL 'END' statement is encountered, regardless if there are more PVL statements after the 'END' statement. The parsing code were generated by specifying the PVL language through a set of rules which are translated by YACC into C code. Along with the rules are corresponding actions specified in C. Most of the actions specified in the PVL parser are calls to the PVL library for creating leaves and building trees. Error Handling Syntax errors detected are reported by yyparse Two #define constants indicate the status of the parse: PARSE_FAIL and PARSE_SUCCESS Change History RAG 01/19/93 Added status parameter 6.3.3 Statement Operations (TOPLEVEL.C) Once a PVL tree is created, the statements of the tree can be operated on using several functions. The following are functions that can be used to create/manipulate the statements of a PVL Tree. 6.3.3.1 stmt_to_string(stmt) The stmt_to_string functions converts the internally stored representation of a Statement structure to a printable string. Abstract Return the statement string represented by stmt Return/Inputs/Outputs RETURN char * the statement string constructed INPUT Statement stmt input PVL statement Description The statement string is not stored in structure Statement. This function reconstructs and returns the PVL statement string. Note that this function does not handle all types of statements, namely those containing multiple level list values. Only the following types are handled : TYPE OF STATEMENT STATEMENT STRING 1) simple statements name> = valuestr> 2) aggregations BEGIN_OBJECT = name> 3) lists (1 level only) name> = (, ) *the statement tree is traversed to get element1 and element2 Notes/Assumptions Assumes statement inputs are of the types listed above. Assumes stmt is defined. Length of stmt_string < MAX_STMT_STRING. Error Handling None Change History NLP 12/20/91 Original Code NLP 10/01/92 Originally mapl_stmts_to_string. Added sets, units. 6.3.3.2 get_stmt_value(stmt) Returns the value of a statement object. The value is returned along with the value type through a Value_and_Type structure (see section on Data Structures for a description of this structure). Synopsis Value_and_Type * get_stmt_value(stmt) Statement stmt; Abstract Return the value and value type of a statement Return/Inputs/Outputs RETURN Value_and_Type * returns the value of stmt together with its type through the structure Value_and_Type. Note that the value may be a data type or a pointer to a statement (for lists). INPUT stmt is the statement whose value is requested Description This function returns the value field and corresponding data type of the statement stmt. The data structure used for returning these data is defined as type Value_and_Type, with a value field and a type field. In case of failure to find the value requested, NULL is returned. Notes/Assumptions Value types are designated by unique integer values defined in module pvl.h. Error Handling None Change History XXX MM/DD/YY Original Code 6.3.3.3 create_statement(keyword, value_string, unit_string) Creates a statement object given a keyword string and a value string. The created statement may be added to a pre-existing PVL tree. Synopsis Statement create_statement(keyword, value_string, unit_string) char * keyword; char * value_string; char * unit_string; Abstract Create a new statement object Return/Inputs/Outputs RETURN Statement the newly created statement INPUT keyword keyword string of statement to create INPUT value_string value string of statement to create Description create_statement creates a new statement object storing the passed PVL data. Creation is executed by reconstructing a PVL statement into a buffer. The buffer is passed to the parser which creates the appropriate statement object for the statement. The parser constructs the low level leaf structure and the necessary value conversion and automatic generation of member objects for list types. The statement object is returned if this process succeeds, otherwise NULL is returned. Notes/Assumptions Uses parse_buffer(buffer, buffer_length, status); Error Handling Invalid input strings cause error messages. Change History XXXMM/DD/YYOriginal Code RAGMM/DD/YYAdded status code for parse_buffer call 6.3.3.4 create_aggregation(aggr_key, aggr_name, substmts) Creates an aggregation statement object given an aggregation keyword type (GROUP or OBJECT) and an aggregation name. Synopsis Statement create_aggregation(aggr_key, aggr_name, substmts) char * aggr_key; char * aggr_name; Statement substmts; Abstract Create an aggregation statement object Return/Inputs/Outputs RETURN Statement the newly created statement INPUT char * aggr_key "OBJECT" to create aggregations with the "BEGIN_OBJECT" keyword "GROUP" to create aggregations with the "BEGIN_GROUP" keyword INPUT char * aggr_name the aggregation block name to be used by the new statement INPUT Statement substmts statements that are connected as sub-statements of the new aggregation statement Description create_aggregation creates an aggregation statement using the passed aggregation statement data. This function is the high level version of make_aggregation_branch. The difference of this function from add_aggregation_branch is that this validates inputs before proceeding with the creation. NULL is returned in case of failure to create an aggregation statement object. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code 6.3.3.5 create_pvl_object(head_stmt, outfile) Synopsis void create_pvl_object(head_stmt, outfile) Statement head_stmt; char * outfile; Abstract Create a PVL data object out of a statement tree Return/Inputs/Outputs RETURN void INPUT Statement head_stmt head_stmt is the start statement of the statement tree which will be written as PVL data object INPUT char * outfile outfile is the name of the output file where the created data object is written Description create_pvl_object constructs a PVL data object out of the statement tree starting at head_stmt using recursive functions which perform the actual data object construction. In case of a NULL head statement, no data object can be generated. The data object that is generated is written to an output file with the filename outfile. Notes/Assumptions Uses print_stmt Error Handling None Change History XXXMM/DD/YYOriginal Code RAG 06/08/93 Added nicer output formatting (indent to 3) 6.3.3.6 add_statement(head_stmt, new_stmt) Adds a statement to a PVL tree. The added statement is added as the last statement in the tree. Synopsis Statement add_statement(head_stmt, new_stmt) Statement head_stmt, new_stmt; Abstract Add a statement to the current collection of statements in the statement tree Return/Inputs/Outputs RETURN Statement returns the start statement of the modified statement tree INPUT Statement head_stmt head_stmt is the start statement of the statement tree to be modified INPUT Statement new_stmt new_stmt is the new statement to be added to the statement tree Description add_statement adds a statement object as the last statement in a statement tree. In case of an error, no addition is performed. Notes/Assumptions add_statement is similar to attach_leaf_to_end except add_statement also contains input validation. Error Handling None Change History XXX MM/DD/YY Original Code 6.3.3.7 add_sub_stmt(aggr_stmt, substmt) Adds a sub-statement to an aggregation. The sub-statement is added as the last sub-statement of the aggregation. Synopsis Statement add_sub_stmt(aggr_stmt, substmt) Statement aggr_stmt, substmt; Abstract Add a sub-statement to the current collection of sub-statements of an aggregation Return/Inputs/Outputs RETURN Statement returns the passed aggregation statement with the new sub-statement attached INPUT Statement substmt substmt is the sub-statement to be added to the aggregation statement substmt Description add_substmt adds a statement to the collection of sub- statements of the aggregation statement aggr_stmt. In case of error, the addition is not performed. Notes/Assumptions Uses attach_leaf_to_end Error Handling None Change History XXX MM/DD/YY Original Code 6.3.3.8 delete_statement(head_stmt, stmt_to_delete) Deletes a statement from a tree. The statement to delete may be an aggregation or a simple statement. Synopsis Statement delete_statement(head_stmt, stmt_to_delete) Statement head_stmt, stmt_to_delete; Abstract Delete a statement from a statement tree Return/Inputs/Outputs RETURN Statement returns the passed start statement with the stmt_to_delete deleted INPUT Statement head_stmt head_stmt is the start statement of the statement tree to be modified INPUT Statement stmt_to_delete stmt_to_delete is the statement to be removed from the statement tree Description This function removes a statement from a statement tree and deallocates the removed statement. In case of an error, deletion is not performed. Notes/Assumptions Uses kill_leaf Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.3.9 insert_statement(head_stmt, new_stmt, at_stmt) Synopsis Statement insert_statement(head_stmt, new_stmt, at_stmt) Statement head_stmt, new_stmt, at_stmt; Abstract Insert a statement in a statement tree Return/Inputs/Outputs RETURN Statement returns the passed start statement with the new inserted statement INPUT Statement head_stmt head_stmt is the start statement of the statement tree to be modified INPUT Statement new_stmt new_stmt is the new statement to be inserted INPUT Statement at_stmt at_stmt is the statement in front of which the new statement will be inserted Description insert_statement inserts a statement new_stmt to a statement tree in front of the statement at_stmt. In case of an error, no insertion is performed. Notes/Assumptions insert_statement is similar to insert_leaf except insert_statement also includes input validation Error Handling None Change History XXX MM/DD/YY Original Code 6.3.3.10 move_statement(head, from, to) Synopsis Statement move_statement(head, from, to) Statement head, from, to; Abstract Move a statement to a different location in a statement tree Return/Inputs/Outputs RETURN Statement returns the start statement of the modified statement tree INPUT head_stmt is the start statement of the statement tree to be modified INPUT Statement from from is the statement to be moved INPUT Statement to to is the statement location where 'from' is to be moved Description move_statement removes a statement object (from) from its current location in the statement tree and inserts it in front of another passed statement (to). Note that statement numbers are adjusted when this operation is performed. The new tree start pointer is returned. Moving is not performed in case of an error. Notes/Assumptions Uses detach_leaf, insert_leaf Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.4 Get Statement Data (TOPLEVEL.C) The following set of functions can be used to get data from the PVL Statement structure, including both the keyword and value portion of the statements. Values that are lists are treated a differently. Check the LIST OPERATIONS section for more details. 6.3.4.1 get_keyword(stmt) Returns the keyword of a non-aggregation statement. Synopsis char * get_keyword(stmt) Statement stmt; Abstract Return the keyword of a statement Return/Inputs/Outputs RETURN char * returns the keyword of stmt INPUT Statement stmt stmt is the statement whose keyword is being requested Description get_keyword returns the keyword string of a statement. If the statement is an aggregation, either "BEGIN_OBJECT" or "BEGIN_GROUP" is returned. NULL is returned when an error is encountered. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code 6.3.4.2 get_aggregation_tag(aggr_stmt) Returns the aggregation name of an aggregation statement. Note that the aggregation name is the string on the right hand side of an aggregation statement string (i.e. G1 in OBJECT = G1). Synopsis char * get_aggregation_tag(aggr_stmt) Statement aggr_stmt; Abstract Return the block name of an aggregation statement Return/Inputs/Outputs RETURN char * returns the aggregation block name of aggr_stmt INPUT aggr_stmt is the statement whose block name is being requested Description get_aggregation_tag returns the block name of an aggregation statement. It returns NULL in case of an error. Notes/Assumptions This may not be used for non-aggregation statements, otherwise an error is reported. Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.4.3 get_value_string(stmt) Synopsis char * get_value_string(stmt) Statement stmt; Abstract Return the value string of a statement Return/Inputs/Outputs RETURN char * returns the value string of stmt INPUT stmt is the statement whose value string is requested Description This function returns the value string of the given statement. It returns NULL in case of error. Notes/Assumptions This may not be used for aggregation statements since they don't have values, otherwise an error is reported. Error Handling None Change History XXX MM/DD/YY Original Code 6.3.4.4 get_stmt_value_type(stmt) Synopsis int get_stmt_value_type(stmt) Statement stmt; Abstract Return the number corresponding to the type of the value of a statement. Return/Inputs/Outputs RETURN INPUT stmt is the statement whose value's type is being requested MODIFY Description get_stmt_value_type returns the number corresponding to the type of the statement stmt's value. Type may either be any of the valid data types or any of the list types set and sequence (their representative numbers are defined in a header file pvl.h ). In case of an error -1 is returned. Notes/Assumptions This may not be used for aggregation statements since they don't have values, otherwise an error is reported. Error Handling None Change History XXX MM/DD/YY Original Code 6.3.4.5 is_aggregation(stmt) Returns a flag indicating whether a statement is an aggregation statement or not. Synopsis int is_aggregation(stmt) Statement stmt; Abstract Return a flag to indicate if a statement is an aggregation or not Return/Inputs/Outputs RETURN int returns 1 if stmt is an aggregation returns 0 is stmt is not an aggregation returns -1 if an error is found INPUT stmt is the statement to be processed Description is_aggregation returns 1 if the given statement is an aggregation, and 0 otherwise. In case of an error, -1 is returned. Notes/Assumptions None Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.5 Change Statement Data (TOPLEVEL.C) The following functions provide capability to modify data contained in the PVL Statement structure. Modifications can be made to keywords, values and their units, and aggregations. Elements contained in the list type values are different and can be modified using the List Operation functions. 6.3.5.1 change_keyword(head_stmt, oldkeyword, newkeyword) Changes the keyword of a statement object in a PVL tree. Synopsis Statement change_keyword(head_stmt, oldkeyword, newkeyword) Statement head_stmt; char * oldkeyword, * newkeyword; Abstract Change the keywords of all statements with keyword olddkeyword in the statement tree starting at head to newkeyword Return/Inputs/Outputs RETURN Statement returns the start statement of the statement tree with the keyword changes in all affected statements INPUT Statement head starting statement in the statement tree where the change is performed INPUT char * oldkeyword the keyword to be replaced INPUT char * newkeywword the keyword to substitute for oldkeyword Description change_keyword initiates the keyword change process by validating inputs and starting a call to the recursive keyword change function rec_change_keyword. Checks made are if head is NULL, if passed keywords are valid, if the statement affected is an aggregation or not, and if a statement with the given keyword exists. The keyword change process changes the keyword (in name field) of all statements with the keyword oldkeyword to the new keyword newkeyword. No change is performed in case of an error. Notes/Assumptions This function may not be used for aggregation statements. See change_aggregation_keyword for changing keywords of aggregations. Uses recursive function rec_change_keyword Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.5.2 change_value(head_stmt, stmt_to_change_valuestr) Changes the value of a statement object in a PVL tree. Synopsis Statement change_value(head_stmt, stmt_to_change, valuestr) Statement head_stmt, stmt_to_change; char * valuestr; Abstract Change the value field of a statement Return/Inputs/Outputs RETURN Statement returns the changed statement INPUT Statement head_stmt head_stmt is the start statement of the tree containing the statement to change INPUT Statement stmt_to_change stmt_to_change is the statement whose value will be changed INPUT char * valuestr valuestr is the value string that will replace the old value string MODIFY stmt_to_change->gdt, stmt_to_change->value changes in gdt and value fields must also be made Description change_value changes the value string of the stmt_to_change to the new value string valuestr. Necessary changes in fields gdt (value type) and value are also performed. The changes are executed by reconstructing a new statement object with the new value string and inserting it in place of the existing object which currently holds the old value. Validation of the value string is performed prior to any changes. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code 6.3.5.3 change_aggregation_keyword(aggr_stmt) Synopsis Statement change_aggregation_keyword(aggr_stmt) Statement aggr_stmt; Abstract Change the aggregation keyword of an aggregation statement Return/Inputs/Outputs RETURN Statement returns the changed statement INPUT aggr_stmt is the aggregation statement whose keyword will be changed Description change_aggregation_keyword automatically changes the aggregation keyword of the passed aggregation statement from 'begin_object' to 'begin_group' or vice versa by changing the valuestr field from "OBJECT" to "GROUP" or vice versa. There is no need to specify the old keyword and the new keyword. The changed statement is returned. No change is performed in case of an error. Notes/Assumptions This function may not be used with non-aggregation statements (see change_keyword). Error Handling None Change History XXX MM/DD/YY Original Code 6.3.5.4 change_aggregation_tag(head, oldname, newname) Synopsis Statement change_aggregation_tag(head, oldname, newname) Statement head; char * oldname, * newname; Abstract Change the aggregation name of all aggregation statements in statement tree starting at head Return/Inputs/Outputs RETURN Statement returns the changed aggregation statement INPUT Statement head_stmt head_stmt is the start statement of the tree to change INPUT char * oldname oldname is the aggregation name to be changed INPUT char * newname newname is the the name that will replace oldname Description change_aggregation_tag replaces the group/object name of all statements with group/object name 'oldname' to 'newname'. This name is stored in the 'name' field of an aggregation statement. In case of error/failure to continue, no change is performed. Validation of aggregation names is performed prior to any change. Notes/Assumptions None Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.5.5 change_one_units(stmt_to_change, new_units) Synopsis Statement change_one_units(stmt_to_change, new_units) Statement stmt_to_change; char * new_units; Abstract Change the units field of a statement Return/Inputs/Outputs RETURN Statement returns the changed statement INPUT stmt_to_change is statement object to be modified INPUT new_units is the new unit string that will replace the given statements current unit string Description change_one_units changes the units string of a statement object from its current unit string value to the unit string new_units. new_units is validated first before it can replace the current unit string. No change is performed in case of errors such as a NULL input statement or an invalid unit string. Note that delimiters are removed from the new unit string if they are found. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code 6.3.5.6 change_all_matched_units(head_stmt, oldunits, newunits) Synopsis Statement change_all_matched_units(head_stmt, oldunits, newunits) Statement head_stmt; char * oldunits, * newunits; Abstract Initiate the unit string change process (all statements with the unit string oldunits are changed) Return/Inputs/Outputs RETURN Statement returns the start statement of the modified statement tree INPUT head_stmt is the head statement of the statement tree to be modified INPUT old_units is the unit string to be replaced INPUT new_units is the unit string that will replace old_units Description change_all_matched units initiates the unit string replacement of all affected statements. It calls rec_change_units as well as the pre-validation of the replacement unit string. The unit string of all statements found with the unit string oldunits are changed to newunits. No change is made in case of an error. Notes/Assumptions The delimiters '<' and '>' may or may not be included in the unit string inputs Uses rec_change_units Error Handling None Change History XXXMM/DD/YYOriginal Code _^ Count Statements (TOPLEVEL.C) The functions listed here provide capability to count the number of statements in a particular aggregation or the number of aggregations themselves. 6.3.6.1 count_statements(stmt) Synopsis int count_statements(stmt) Statement stmt; Abstract Return the number of statements in a statement tree Return/Inputs/Outputs RETURN int number of statements in statement tree starting at stmt INPUT stmt first statement in the tree/sub-tree to perform count on MODIFY extern int stmtcount stmtcount is a global variable which stores the statement count. It is initialized in this function to zero. Description This function counts the number of statements in a statement tree and returns the total. In case of errors, it returns -1. Notes/Assumptions None Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.6.2 count_substmts(aggr_stmt) Synopsis int count_substmts(aggr_stmt) Statement aggr_stmt; Abstract Return the number of sub-statements in an aggregation Return/Inputs/Outputs RETURN int the sub-statement count INPUT Statement aggr_stmt the aggregation statement containing the sub-statements to count Description This function performs count_statements on an aggregation to determine the number of sub-statements in the aggregation. It returns the total count. In case of error, it returns -1. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code 6.3.6.3 count_aggregations(stmt) Synopsis int count_aggregations(stmt) Statement stmt; Abstract Return the number of aggregation statements in a statement tree Return/Inputs/Outputs RETURN int number of aggregation statements in a statement tree INPUT Statement stmt head statement of statement tree to perform count on MODIFY static int aggrcount global variable used to store count Description This function counts the number of aggregation statements in a statement tree. It returns the total count. In case of error, it returns -1. Notes/Assumptions None Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.6.4 count_sub_aggrs(aggr_stmt) Synopsis int count_sub_aggrs(aggr_stmt) Statement aggr_stmt; Abstract Return the number of sub-aggregations in an aggregation statement Return/Inputs/Outputs RETURN int number of sub-aggregations under an aggregation statement INPUT aggr_stmt the aggregation statement whose sub-aggregation count is requested Description This function performs count_aggregations on an aggregation statement to count how many sub-aggregations it contains. Sub-aggregations are simply sub-statements which are aggregations. The total count is returned. In case of error, -1 is returned. Notes/Assumptions None Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.7 Search Statements (TOPLEVEL.C) Searching capability are provided by the functions listed below. Searches can be done on both keyword names and aggregation names. Capability for nth number searches is also provided, as well as simple successor and predecessor functions. 6.3.7.1 search_name(head, tomatch) Synopsis Statement search_name ( head, tomatch ) Statement head; char * tomatch; Abstract Search for a statement in a statement tree by name Return/Inputs/Outputs RETURN Statement returns the first statement with the matched keyword returns NULL if no match INPUT Statement head head statement to begin search at INPUT char *tomatch the keyword of the statement to search for Description This function recursively searches for the first statement with a name field which matches the passed string tomatch. It can be used to find a statement with a known keyword or an aggregation statement with a known aggregation name since both are stored in the 'name' field. The search is done through a depth-first traversal of the statement tree (look at sub then vlist then next) beginning at the head statement. The matched statement is returned. NULL is returned if no match was found. Notes/Assumptions This function may be used to search for an aggregation or for a simple statement since both store their names in the name field. Aggregations store their block name while non- aggregations store their keyword in the name field. Error Handling NULL input statements cause an error message. Change History XXXMM/DD/YYOriginal Code 6.3.7.2 next_matched_aggr(current_aggr) Synopsis Statement next_matched_aggr(current_aggr) Statement current_aggr; Abstract Find the next aggregation with the same name as current_aggr Return/Inputs/Outputs RETURN Statement returns the next aggregation found with the same name as current_aggr INPUT Statement current_aggr current_aggr is the aggregation whose name will be used to in the search Description next_matched_aggr returns the next aggregation statement with the same name as the current_aggr. Sub-statements of the current_aggr and succeeding statements in the same level as the current_aggr are included in the search. NULL is returned in case of an error or search failure. Notes/Assumptions See also search_nth_matched_aggr Error Handling None Change History XXX MM/DD/YY Original Code 6.3.7.3 search_nth_matched_aggr(head_stmt, nth, aggr_name) Synopsis Statement search_nth_matched_aggr(head_stmt, nth, aggr_name) Statement head_stmt; int nth; char * aggr_name; Abstract Find the nth aggregation with by name Return/Inputs/Outputs RETURN Statement returns nth matched aggregation, NULL if not found INPUT Statement head_stmt head_stmt is the starting point for the search INPUT int nth nth is the number position of the statement to search for INPUT char *aggr_name aggr_name is the common aggregation name Description search_nth_matched_aggr looks for the nth aggregation statement whose name matches aggr_name. Note that only statements in the same level as the head_stmt (starting statement) are included in the search. NULL is returned in case of an error or search failure. Notes/Assumptions See also next_matched_aggr Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.7.4 search_nth_substmt(aggr_stmt, nth) Synopsis Statement search_nth_substmt(aggr_stmt, nth) Statement aggr_stmt; int nth; Abstract Return the nth sub-statement of aggr_stmt Return/Inputs/Outputs RETURN Statement returns the nth sub-statement of aggr_stmt INPUT Statement aggr_stmt aggr_stmt is the aggregation whose nth sub-statement is requested INPUT int nth nth is the number position of the sub-statement requested i.e. if nth is 1, find first sub-statement, etc. Description This function returns the nth sub-statement of the aggregation statement current_aggr. NULL is returned in case of an error or search failure. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code 6.3.7.5 search_parent_aggregation(head_stmt, substmt) Synopsis Statement search_parent_aggregation(head_stmt, substmt) Statement head_stmt, substmt; Abstract Return the first smallest aggregation to which substmt belongs as a sub-statement Return/Inputs/Outputs RETURN Statement returns the parent statement of substmt INPUT Statement head_stmt head_stmt is the head_stmt of the tree where the search is performed INPUT Statement substmt substmt is the sub-statement whose parent aggregation is requested MODIFY extern Statement last_aggr_passed last_aggr_passed is a global variable which is used to keep track of the last aggregation passed while doing the search Description search_parent_aggregation returns the aggregation which immediately encloses the sub-statement substmt. NULL is returned in case of an error or search failure. Notes/Assumptions Note that the search is depth first so that even if the same sub-statement is located in more than one place, the first one matched is the one returned. This avoids confusion when a deeper nested aggregation contains the same sub-statement in a separate less deeply nested aggregation. Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.7.6 predecessor(head_stmt, stmt) Synopsis Statement predecessor(head_stmt, stmt) Statement head_stmt, stmt; Abstract Initiate the predecessor search operation Return/Inputs/Outputs RETURN Statement returns the preceding statement of stmt INPUT Statement head_stmt head_stmt is the start statement of the statement tree to be searched INPUT Statement stmt stmt is the statement whose predecessor is requested Description predecessor initiates the search of the statement previous to the statement 'stmt' by validating inputs and calling the recursive function search_previous. search_previous returns the statement immediately prior to the given statement in the enclosing PVL space after a recursive search process. It returns NULL if there is no previous statement or if an error was encountered. Notes/Assumptions See also search_previous Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.7.7 successor(head_stmt, stmt) Synopsis Statement successor(head_stmt, stmt) Statement head_stmt, stmt; Abstract Return the "next" statement of stmt Return/Inputs/Outputs RETURN Statement returns the succeeding statement of stmt INPUT Statement head_stmt head_stmt is the start statement of the statement tree to be searched INPUT Statement stmt stmt is the statement whose "next" statement is requested Description successor searches for the statement which follows the statement stmt in the statement tree starting at head_stmt. NULL is returned if the successor can't be found or if an error occurs. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code 6.3.8 List Operations (LISTOPS.C) The List Operations, which are part of the top level library, are used for statements containing list values (sets or sequences). The following is the unit header followed by a summary table of the available functions. Unit Description This module includes routines for accessing and manipulating list valued statement objects and list elements within a given statement tree. It uses low level routines as well as some routines defined in module toplevel.c. Note: The terms list type statements, list-valued statement and lists are used interchangeably. Unit Components Globals Defined None External References char error_string[]; String used to store error message Change History Version Date Change Description Revision 1.1 91/4/01 norbert Add handling of DATE/TIME values in get_list_element_value Revision 1.0 91/4/3 2:45:00 norbert Initial revision FUNCTION NAME DESCRIPTION Manipulating Lists add_list_element Add a list element to a list append_list_element Append a list element to another list element in a list change_list_element Change a list element create_list_element Create a list element delete_list_element Delete a list element from a list insert_list_element Insert a list element into a list count_list_elements Count list elements in a list get_list_element_type Return list element data get_list_element_value get_nth_list_element_value point_nth_list_element Search the nth list element of a list 6.3.8.1 add_list_element(list_stmt, element) Synopsis Statement add_list_element(list_stmt, element) Statement list_stmt; List_element element; Abstract Add a list element to a list Return/Inputs/Outputs RETURN Statement returns the list statement with the new element added INPUT Statement list_stmt list_stmt is the list-valued statement to which an element is to be added INPUT List_element element element is the list element to be added to the list Description add_list_element adds a list element object to the list statement list_stmt. In the case of an error, the addition is not performed. Notes/Assumptions None Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.8.2 append_list_element(new_element, to_element) Synopsis List_element append_list_element(new_element, to_element) List_element new_element, to_element; Abstract Append a list element to a another list element Return/Inputs/Outputs RETURN List_element returns the elements appended together INPUT List_element new_element new_element is the list element to be appended INPUT List_element to_element to_element is the list element to which new_element is to be appended Description append_list_element appends a list element to another list element in a list. In the case of an error, appending is not performed. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code 6.3.8.3 change_list_element(list_stmt, element, new_value) Synopsis Statement change_list_element(list_stmt, element, new_value) Statement list_stmt; List_element element; char * new_value; Abstract Change a list element value Return/Inputs/Outputs RETURN Statement returns the modified list statement INPUT Statement list_stmt list_stmt is the list to which the element to be changed belongs INPUT List_element element element is the list element whose value is to be changed INPUT char * new_value new_value is the new element value replacement Description change_list_element changes the value of the list element element from its current value to the new value new_value. It returns the modified list statement if it succeeds, otherwise it returns NULL. change_list_element performs change_value on the list element object list_stmt. In the case of an error, the change is not performed. Notes/Assumptions None Error Handling None Change History XXXMM/DD/YYOriginal Code RAG 06/07/93 Modified to return the list element rather than the statement its contained within 6.3.8.4 create_list_element(list_stmt, new_element_str, new_element_units) Synopsis List_element create_list_element(list_stmt, new_element_str, new_element_units) Statement list_stmt; char * new_element_str; char * new_element_units; Abstract Create a list element object for a list statement Return/Inputs/Outputs RETURN List_element returns the created list element INPUT Statement list_stmt list_stmt is the statement for which an element is to be created INPUT char * new_element_str new_element_str is the value string of the new element to be created INPUT char * new_element_units new_element_units is the unit string of the new element to be created Description create_list_element allocates creates a list element intended to be added to the list statement list_stmt's elements. The list element created may be any type including lists. The element must be inputted as a character string in statement form. If it has a unit string it must be entered separately, otherwise new_element_units must be NULL. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code RAG 01/19/93 Added status to parse_buffer call 6.3.8.5 delete_list_element(list_stmt, element) Synopsis Statement delete_list_element(list_stmt, element) Statement list_stmt ; List_element element; Abstract Delete a list element from a list statement Return/Inputs/Outputs RETURN Statement returns the modified list statement INPUT Statement list_stmt list_stmt is the list statement to which the element to be deleted belongs INPUT List_element element element is the list element to be deleted Description delete_list_element deletes the list element element from a list. The list is the list statement list_stmt. In the case of an error, deletion is not performed. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code 6.3.8.6 insert_list_element(list_stmt, new_element, at_element) Synopsis Statement insert_list_element(list_stmt, new_element, at_element) Statement list_stmt; List_element new_element, at_element; Abstract Insert a list element into a list in front of another element Return/Inputs/Outputs RETURN Statement returns the list statement with the new inserted element INPUT Statement list_stmt list_stmt is the list-valued statement to which an element is to be inserted INPUT List_element new_element new_element is the list element to be inserted INPUT List_element at_element at_element is the list element in front of which new_element will be inserted Description add_list_element inserts the list element new_element in front of another list element at_element in the list list_stmt. In the case of an error, the insertion is not performed. Notes/Assumptions None Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.8.7 count_list_elements(list_stmt) Synopsis int count_list_elements(list_stmt) Statement list_stmt; Abstract Return the number of elements in a list Return/Inputs/Outputs RETURN int returns the count of elements in the list list_stmt INPUT Statement list_stmt list_stmt is the list-valued statement whose element count is requested Description count_list_elements returns the number of elements in the list statement list_stmt. In the case of an error, -1 is returned. Notes/Assumptions None Error Handling None Change History XXX MM/DD/YY Original Code 6.3.8.8 get_list_element_type(element) Synopsis int get_list_element_type(element) List_element element; Abstract Return the type of a list element Return/Inputs/Outputs RETURN int returns the integer corresponding to the list element's value type INPUT List_element element element is the list element whose type is requested Description get_list_element_type returns value the type of the list element element. Actually, it simply calls the function get_stmt_value_type. The types are identified through preprocessor define statements in header file pvl.h. Each valid data type corresponds to an integer identification. Notes/Assumptions See also get_stmt_value_type Error Handling None Change History XXX MM/DD/YY Original Code 6.3.8.9 get_list_element_value(element) Synopsis Value_and_Type * get_list_element_value(element) List_element element; Abstract Return the value of a list element along with its value type Return/Inputs/Outputs RETURN Value_and_Type * returns a pointer to a structure containing the value and value type of the list element element INPUT List_element element element is the list element whose value is requested Description get_list_element_value returns the value of the list element element together with its value type through a Value_and_Type structure. In the case of an error, NULL is returned. Notes/Assumptions See also get_list_element_value Note that the default field in the union is stringval where the value string is stored when no other value_type can be matched. Error Handling None Change History XXXMM/DD/YYOriginal Code 6.3.8.10 get_nth_list_element_value(nth, list_stmt) Synopsis Value_and_Type * get_nth_list_element_value(nth, list_stmt) int nth; Statement list_stmt; Abstract Return the value of the nth list element of a list along with its type Return/Inputs/Outputs RETURN Value_and_Type * returns the value and value type of list_stmt's nth element through a Value_and_Type structure INPUT int nth nth is the position of an element in the list INPUT Statement list_stmt list_stmt is the list which owns the list element to be processed Description get_nth_list_element_value returns the value of the nth list element of the list statement list_stmt along with its value type through a Value_and_Type structure. This function uses get_list_element_value on the nth element of the list-valued statement. In the case of an error, a value of 0 and value type of -1 is returned. Notes/Assumptions See also get_list_element_value Error Handling None Change History XXX MM/DD/YY Original Code 6.3.8.11 point_nth_list_element(nth, stmt) Synopsis List_element point_nth_list_element(nth, stmt) int nth; Statement stmt; Abstract Return the nth list element of a list valued statement Return/Inputs/Outputs RETURN List_element returns the nth list element of the list statement stmt INPUT int nth nth is the position of the element requested INPUT Statement stmt stmt is the statement whose list value's nth element is requested Description point_nth_list_element searches for the nth list element of the list-valued statement stmt. It returns the nth list element if it is found, otherwise it returns NULL. Notes/Assumptions See also print_stmt Error Handling None Change History XXX MM/DD/YY Original Code 6.4 Low level routines The low level PVL routines operate on the same basic structure and tree arrangement as the top level routines. However, low level routines refer to the basic structure as leaves. Low level routines perform simple tasks such as creating leaves, inserting leaves, or pruning trees. Low level routines may also require the use of other intermediate structures which the user does not need to worry about at the top level. Most of the top level functions involve the use of one or more low level functions. The low level functions are listed here for reference only. Most applications will not need to make use of these functions. The source code and function headers, however, are available in the respective files 6.4.1 Low Level Parser Support Functions (LEAFOPS1.C) Among the low level routines are the leaf creation and attachment routines. These are the routines which the PVL parser calls to build the PVL tree while parsing the input data. Other related routines are also found in this group. Also included in this group are value list routines. Value list routines are routines used by the PVL parser to set up a linked list of the list structure described in section ?. The function make_leaf uses the linked list to access the value data and value type of a PVL statement when creating a leaf for the statement. For details, refer to the functional description of make_leaf. 6.4.1.1 make_leaf Create leaf structure(s) to represent a statement 6.4.1.2 attach_leaf_to_end Add a leaf to the end of a tree or sub-tree 6.4.1.3 make_aggregation_branch Create an aggregation branch 6.4.1.4 dump_report Print a report of parsed PVL statements 6.4.1.5 new_list Allocate a value list record 6.4.1.6 attr_list Attach value list record to value list 6.4.2 Additional Low Level Routines (LEAFOPS2.C) A few additional functions designed to support the statement operations in the top level are included in the low level library. These functions are listed below. 6.4.2.1 kill_leaf Deletes a leaf from a tree 6.4.2.2 kill_tree Deletes a tree or sub-tree 6.4.2.3 append_leaf Appends a leaf to another leaf 6.4.2.4 detach_leaf Detaches a leaf from a tree 6.4.2.5 insert_leaf Inserts a leaf into a tree 6.4.2.6 tree_copy Makes a copy of a tree 6.4.2.7 previous_pointer Returns the leaf that links a given leaf to a tree 6.5 PVL Error Handling The errors reported by the PVL Library are either syntax errors encountered while parsing or errors due to invalid calls to the top level library. Syntax errors occur when the input PVL data being parsed does not conform to the PVL specification. Invalid top level function calls may be due to illegal function arguments or improper use of the function. In case of parsing errors, the last valid statement found is printed as well as the last token successfully obtained. For top level function call errors, a description of the error is printed. Processing is halted by the PVL Library in all cases of errors.