-- ++ -- -- COMPONENT: TR1_ADA_FUNCTION -- -- COMPONENT DESCRIPTION: -- -- This is the TR1 Ada module, used as sample data for the PDF report tool. -- -- The COMPONENT DESCRIPTION tag should contain the general, high-level -- information about the component. This includes the purpose of the component -- (CSC), and the relationships between any sub-level components of this -- component. It might also state the project unique identifier for the -- component, although that would more likely be found as part of the component -- name. -- -- INPUT/OUTPUT DATA: -- -- This tag should identify and state the purpose of each input and output to -- the CSC. It should also show the decomposition of each input and output -- into data elements, if appropriate. Each element must be described in a -- data dictionary. -- -- This section is a likely candidate for automation. Unfortunately, it is -- impossible to automate this section in the general case. Input and output -- data could be global data (in the Pascal global or Fortran common block -- sense), or they could be explicit parameters to procedures and functions, or -- they could be some combination or subset of both. -- -- However, within any given project, it may be possible to automate this, by -- exploiting knowledge of the methodology being used for the project. You -- could, for example, rely on naming conventions for this. You could also -- adopt a convention that this convention refers only to global data, and -- therefore only look at data that is global using the SCA DOMAIN attribute. -- In more complicated situations, you could determine those subprograms that -- are referenced from outside this component, and use their parameters as the -- input and output. -- -- A simpler approach, still using tags, is to change this to a structured tag -- (similar to the FORMAL PARAMETERS tag in conventional block comments). -- -- ALGORITHMS: -- -- The algorithm used is a straightforward sequence of computations. -- -- We make extensive use of variant records for this. -- -- This tag should describe the algorithms that are used in the component, -- in terms of the manipulation and generation of data. -- -- ERROR HANDLING: -- -- No errors are handled, but we do pass back tr1_exc_1. -- -- This tag describes the error detection and recover features of the -- component. This includes the handling of erroneous input data, among other -- conditions. -- -- LOGIC FLOW: -- -- This tag describes the logic flow of the component in terms of the above -- items. -- -- REQUIREMENTS ALLOCATION: -- -- This component partially meets the requirement of testing of a top level -- component that is a function. -- -- In general, this tag will specify the requirements of the CSCI that are -- satisfied (partially or totally) by this component. -- -- This tag happens to be defined as a text tag. You could get creative with -- SCA and keyword queries by adding a keyword tag, such as "REQUIREMENTS -- ALLOCATION BY KEYWORD", to provide some degree of traceability, at least -- within low-level designs and implementation code. For example, if you had -- -- REQUIREMENTS ALLOCATION BY KEYWORD: Requirement number 1 -- -- where Requirement_number_1 referred to a specific requirement, then the SCA -- query FIND SYMBOL=KEYWORD AND "Requirement number 1" would find all -- components that were related to that requirement. It is important that you -- understand the different types of tags, especially keyword tags, for this -- work. In particular, keywords cannot contain commas, and can cross at most -- one line boundary. ---- --++ -- UNIT OF: TR1_ADA_FUNCTION: -- -- UNIT DESCRIPTION: -- -- This is the unit section of this file. If you wish to include unit -- information in the same file as the component information given above, then -- the UNIT OF tag is required, for the sake of consistency. It also -- simplifies SCA queries tremendously. If yo don't wish to include unit -- information in the same file, then the code in this file should be dummy -- code; for example, a routine that simply returns (and perhaps is never -- called), or an Ada package specification that contains no declarations. -- At least one compilation unit is required, however, since SCA puts all -- information into a compilation unit. -- -- INPUT/OUTPUT DATA ELEMENTS: -- -- This tag describes the purpose of each input and output data element of the -- unit. The design of each data element needs to be in a data dictionary, as -- required by the 2167A specs. See the entry under INPUT/OUTPUT DATA, above, -- for more information. -- -- LOCAL DATA ELEMENTS: -- -- This section has the name and purpose of each data element that is declared -- in this unit and that isn't used by any other unit. As with INPUT/OUTPUT -- DATA, etc., this section can only be automated by using knowledge of the -- methodology or conventions of the project. -- -- INTERRUPTS AND SIGNALS: -- -- tr1_exc_1: -- Exceptions in this unit are converted to tr1_exc_1. -- -- This tag describes the interrupts and signals handled by the unit. For eac -- signal, it should include the source, purpose, priority, expected response -- and response time, and frequency of occurrence. -- -- UNIT ALGORITHMS: -- -- Since this is the same as a csc, the algorithm is the same. -- -- The UNIT ALGORITHMS section describes in detail the algorithms to be -- incorporated into the execution of the unit, in terms of manipulation of -- input and local data and the generation of output. -- -- Again, with proper knowledge of the methodology, this section could be -- automated by using the program code. See especially the way algorithms are -- presented in the INTERNALS report. -- -- UNIT ERROR HANDLING: -- -- The error detection and recovery features of the unit are described here. -- -- UNIT DATA CONVERSION: -- -- Any data conversion operations performed by the unit are described here. -- -- USE OF OTHER ELEMENTS: -- -- This tag describes the use of other elements by the unit, including but not -- limited to other units, shared data in global memory, and input and output -- buffers, including message buffers. -- -- UNIT LOGIC FLOW: -- -- This tag contains a description of the logic flow of the unit, in terms of -- the previous tags. The 2167A specification goes into more detail about what -- is specifically desired for this section -- -- DATA STRUCTURES: -- -- This tag describes local data structures implemented by the unit, and shared -- data structures used by the unit. Shared data structures should only be -- described once, and referenced from other places. -- -- LOCAL DATA FILES: -- -- This tag describes any data files or database that are part of the local -- data of the unit. -- -- LIMITATIONS -- -- This tag describes any limitations or unusual features that restrict the -- performance of the unit. -- -- REQUIREMENTS ALLOCATED TO THIS UNIT: -- -- Any requirements allocated to the component which belong to this unit are -- identified here. -- -- -- function tr1_ada_function ( p1 : in integer; -- The first parameter to tr1_ada_function p2 : in integer -- The second parameter to tr1_ada_function ) -- more comment on the function return integer is -- ++ -- FUNCTIONAL DESCRIPTION: -- -- This is the tr1_ada_function, used for testing out PDF reports. This -- function takes two parameters. -- -- FORMAL PARAMETERS: -- -- p1: -- The first parameter, an integer. -- -- p2: -- The second parameter, also an integer. -- -- RETURN VALUE: -- -- An integer value result. -- -- -- tr1_const_1 : constant := 17; -- constant decl subtype tr1_subtype_1 is INTEGER range 1 .. 23; -- SUBTYPE type tr1_type_1 (tag_id_1 : tr1_subtype_1 := 1) is -- comment on type record field_1 : INTEGER; -- comment field 1 field_2 : STRING (1 .. 27); field_3 : FLOAT; -- comment f3 case tag_id_1 is -- comment on discriminant when 1 => v_field_1 : INTEGER; when 2 => v_field_2 : FLOAT; -- comment on last field when others => v_field_3 : STRING (1..4); end case; end record; type tr1_type_2 is record field_1 : FLOAT; field_2 : tr1_type_1; -- comment on field_2 type tr1_type_1 end record; tr1_var_1 : INTEGER; -- simple variable tr1_var_2 : INTEGER := 35; -- initialized variable tr1_var_3 : tr1_type_1; -- user defined type tr1_var_4 : tr1_type_2; -- second user defined type tr1_con_1 : constant := 59; -- constant tr1_con_2 : constant STRING := "initial String value"; -- constant string tr1_exc_1 : exception; procedure tr1_ada_proc_1 (p1 : in INTEGER; p2 : in out INTEGER) is -- ++ -- -- FUNCTIONAL DESCRIPTION: -- -- This is a procedure nested inside an Ada function. It's job is to -- test the effect of nested procedures on reports. -- -- FORMAL PARAMETERS: -- -- p1: -- parameter 1 to nested procedure -- -- p2 : -- parameter 2 to nested procedure -- -- DESIGN: -- -- pretty trivial design -- [TBS]... -- -- -- tr1_var_1 : tr1_type_1; -- nested overloaded identifier begin tr1_var_1 := tr1_var_3; tr1_var_1.field_1 := p1 * 17; p2 := p1 * tr1_var_1.field_1 + tr1_var_1.v_field_1; end tr1_ada_proc_1; begin tr1_var_1:= p1 * tr1_var_2 * tr1_con_1; tr1_var_3.field_1 := tr1_con_1; tr1_var_3.v_field_1 := tr1_con_1 * 17; tr1_var_4.field_1 := 19.3; tr1_var_4.field_2 := tr1_var_3; tr1_var_4.field_2.field_1 := tr1_var_3.tag_id_1; tr1_var_1 := tr1_var_4.field_2.field_1 + tr1_var_4.field_2.v_field_1 + p2; tr1_var_1 := p2 + tr1_var_1 * tr1_var_3.field_1; return p2 * p1; exception when others => raise tr1_exc_1; -- convert all exceptions to tr1_exc_1 end tr1_ada_function;