## Countdown to 2000
Start scenario Program source Input seed file Year 2000 Analysis Formatted report Analysis format Seed format Cross compilation Overview |  |
Guide to Year 2000 Analysis output format
The output is made up of two sections. The <HEADER> contains information about the ADT file and the seed file as well as the flags that have been set. The <PROGRAM> section contains specific information about the program that is being analyzed. As a result, it contains information about the source files involved and information about specific aspects of the program.
<HEADER>,</HEADER>
The header describes information about the analysis. It contains the name of the ADATA file, when the analysis occurred, the name of the seed file used, and the date of the last modification for the seed file. In addition, a list of output options specified in the seed file are listed.
<PROGRAM>,</PROGRAM>
The program section contains the following information: - information about parameters for calls and entries, - information about the files used for data IO, - information about CICS data access, - information about variables Through these various sections, there should be enough data to enable the user to make informed decisions about definite dates and possible dates and how pervasive they are through the module. Each program starts with a <PROGRAM> followed by the name of the program. The tag signifies the beginning of data pertaining to a specific program unit. The end of the data is signified with the </PROGRAM>. The following tags will mark the beginning of a specific piece of information between the start and end program tags. They are as follows and will be discussed individually: <CALL> <CICS-FILE-NAME> <CICS-FILE-VARIABLE> <DDNAME> <DDSTREAM> (PL/I only) <DDVARIABLE> (PL/I only) <ENTRY> <EXTERNAL-NAME> <INCLUDE> <NAME> <PROGRAM-INFO> <RESULT>
<CALL>,</CALL>
The <CALL> tag marks the beginning of a section describing an argument of a call. The <CALL> is followed by the name of the call and then the <ARGUMENT> tag and the argument number. The argument number corresponds to the argument in that position in the argument list. If the argument that is being described is the return value, the argument number will be replaced with the string "RETURN". The tag is then followed by the results. For more information on results, please see the section on <RESULT>. The section is then ended by the </CALL> tag. There is also an <ENTRY> tag that is very similar. The difference between the two tags is that <ENTRY> describes the formal parameters and <CALL> describes entering the actual parameters. There may be multiple occurrences of <CALL> tags and also multiple occurrences of <CALL> tags with the same call name. However, there will only be a single occurrence that applies to a specific call and argument. From the given information, a seed can be created and added to the seed file. This addition will allow you to propagate the information into future iterations.
<CICS-FILE-NAME>,</CICS-FILE-NAME>
The <CICS-FILE-NAME> describes a CICS file that is identified by a literal in the program. The literal follows the tag and is then followed by the results. Please see the section on <RESULT> for more details. There may be multiple <CICS-FILE-NAME> tags in the report file. However, they will all have different literals identifying them.
<CICS-FILE-VARIABLE>,</CICS-FILE-VARIABLE>
The <CICS-FILE-VARIABLE> describes a CICS file that is identified by a string stored in a variable in the program. The name of the variable follows the <CICS-FILE-VARIABLE> tag and is then followed by the results. Please see the section on <RESULT> for more details. NOTE: The information provided varies between the languages. In COBOL, there will be results following the name of the variable. However, in PL/I, there will be no results just the ending tag. The cause of this is due to the nature of PL/I. In PL/I, the ability to have variables of the same name in different scopes makes presenting useful data about year-related information difficult. This functionality for PL/I may be added in the future. There may be multiple <CICS-FILE-VARIABLE> tags in the report file. However, they will all have different variables identifying them.
<DDNAME>,</DDNAME>
A <DDNAME> tag specifies a file that is being read and or written by a program in the form of records. The tag is followed by an identifier that holds the name of the file that has been either set by a variable in JCL or as an environment setting. However in COBOL, the given identifier may be the actual name of the file if a literal is used inside of the environment section of the program rather than an identifier. After the identifier, the results pertaining to the ddname follows. Please see the section about <RESULT> for more information. After the results end, a </DDNAME> ends this section of data. There may be multiple <DDNAME> sections inside of the XRL file. From the data given in the XRL, an appropriate seed may be created and added to the seed file to further propagate the data.
<DDSTREAM>,</DDSTREAM> (PL/I only)
A <DDSTREAM> is very similar to a <DDNAME> except that it pertains to data being input and output as a stream rather than as records. As a result, the identifier following the starting tag holds the name of the file that has been either set by a variable in JCL or as an environment setting. The identifier is followed by a </DDSTREAM> to end the section of data. You may have noticed that there is no mention of results inside of the section. The reason for the lack of results is that stream input and output do not work on regular lengths. As a result, there is little information we can provide about the kind inside of the file. Thus, we simply mention that a DDSTREAM has been used inside of the program. There may be multiple <DDSTREAM> sections inside of the XRL.
<DDVARIABLE>,</DDVARIABLE> (PL/I only)
A <DDVARIABLE> is very similar to a <DDNAME> except that it points to an instance of a DDNAME or DDSTREAM. The identifier that follows the DDNAME is the name of the variable that contains the pointer to the open file. The identifier is followed by a </DDSTREAM> to end the section of data. You may have noticed that there is no mention of results inside of the section. The reason for the lack of results is that the particular file being used for I/O is unknown and no analysis can be made. However, we do mention the occurrence of a DDVARIABLE in the report to help the programmer understand the content of the program. There may be multiple <DDSTREAM> sections inside of the XRL.
<ENTRY>,<ENTRY>
The <ENTRY> tag marks the beginning of a section describing an argument of a call. The <ENTRY> is followed by the name of the call and then the <ARGUMENT> tag and the argument number. The argument number corresponds to the argument in that position in the argument list. The tag is then followed by the results. For more information on results, please see the section on <RESULT>. The section is then ended by the </CALL> tag. There is also a <CALL> tag that is very similar. The difference between the two tags is that <ENTRY> describes the formal parameters and <CALL> describes entering the actual parameters. There may be multiple occurrences of <CALL> tags and also multiple occurrences of <CALL> tags with the same call name. However, there will only be a single occurrence that applies to a specific call and argument. From the given information, a seed can be created and added to the seed file. This addition will allow you to propagate the information into future iterations.
<EXTERNAL-NAME>,</EXTERNAL-NAME>
The <EXTERNAL-NAME> tag is exactly the same as the <NAME> tag except it is external to the program. This tag was added for future enhancements to the tool.
<INCLUDE>,</INCLUDE>
The <INCLUDE> tag is a tag that was designed to aid in Cross Compilation. The purpose of the tag is to state information about a variable declared in a copy book or include file. The reported variable is identified by the defining position in the form of the file and the four number position in the form of startingLine.startingColumn.endingLine.endingColumn. The tag is followed by the results of the analysis. This tag is only reported for elementary items (items that have no children). In cross compilation analysis, the tag is used to see if common copybooks are used between files. In the event that the copy book is used by other programs, the data is added to the seed. There may be multiple instance of the <include> tag in the report. However, each location will be unique.
<NAME>,</NAME>
The <NAME> report tag marks the beginning of a section defining a variable contained within the program. The tag is followed by a the name of the variable. The tags following the variable are determined by whether the variable is a scalar, an array, or a structure. If the variable is a structure, the <NAME> is followed by <NAME> reports for all of the members of the structure. All results for the variable are defined in the report for each member of the structure. If the variable is an array, the <NAME> is followed by the <DIMENSIONS> tag. The dimension tag gives the maximal size for each dimension of the array. If the variable is an array of scalars, a list of results follows. However, if the variable is an array of structures, a list of each member of the structure is listed. If the variable is a scalar, the <NAME> tag is followed by the <SIZE> tag that describes the size of the scalar. Following the previous information is always a list of positions that describe the definition and usage positions of the variable in the source. The output of the list always has the format of a <FILE> report tag, the source file where the variable is defined, the <DEF-POS> and the position of the definition. A list of usage positions follow and they are always between <POS> report tags. However, <FILE> tags may occur within the list if the usage positions are contained within a different source file (an include or copybook). A definition position is made a sequence of four numbers separated by periods showing the starting row, starting column, ending row, and ending column respectively. A usage position is a definition position, but also may contain a string that describes how it is used. The string may have any of the following: e the variable is used in an external manner at this location r the variable is referenced at this position m the variable is modified at this position In the case that there is no string describing the usage, the lack of the string means that there is no data flow associated with the usage of the variable in the program. This behavior will occur in instances when the variable is being used to describe another variable as in a redefine or base. There may be multiple instances of <NAME> in the report. This information can be used to help modify your seed file as well as create new entries within your seed file. Note: PL/I does not report <NAME> for pointers.
<PROGRAM-INFO>,</PROGRAM-INFO>
The <PROGRAM-INFO> report tag is the beginning of a section that lists the files that are used within the program. The first file listed is always the primary file. The following files that are listed are the copybooks and include files used to compile the program.
<RESULT>,</RESULT>
The <RESULT> tags contain the results of the analysis for the item that contains the <RESULT> tag. <RESULT> <KIND> * <INDEX> index <LENGTH> length <ANNOTATION> text </ANNOTATION> ** <YEAR-REASON> text </YEAR-REASON> *** <NON-YEAR-REASON> text </NON-YEAR-REASON> *** </KIND> </RESULT> * There will be one or more instances of everything from <KIND> - </KIND>. ** There may 0 or more instances of <ANNOTATION> - </ANNOTATION> *** There may be either one or none of the tag. The <KIND> can be any of the following: <USED-AS-YEAR> specifies that the result may be year-related. This observation may come from seeding or as a result of an inference. <ALWAYS-YEAR> describes a result that the user has described to us that it is always a year. This result can only be set through a seed. The result cannot be propagated from an inference or be modified by an inference. <USED-AS-NON-YEAR> specifies that the result may be non-year related. This observation may come from either seeding or as a result of an inference. <ALWAYS-NON-YEAR> describes a result that can never be year related. This result can only be set through a seed. The result cannot be propagated from an inference or be modified by an inference. <USED-AS-YEAR-AND-NON-YEAR> specifies that the result is used in both manners. This can either be a result of seeding or conflicting inferences. This result or observation may arise from a seed and/or an inference. The conflict can occur when a result is used in both ways in different places. The length tag describes the number of bytes that describe the result. However, it is not always possible to report the length. There are some instances that we only know that the result applies from the index to an unknown length. As a result,the report will specify the length as UNKNOWN. The annotation tag contains strings that have been propagated from seeds. All annotations are listed that have either directly or indirectly affected the segment described by the index and length for the variable. This information may be useful to help debug the effects of certain seeds as well as pass useful information from seeds to the report. The <YEAR-REASON> and <NON-YEAR-REASON> describe why the variable (or part of the variable) has the kind described. The <YEAR-REASON> states a reason why the variable (or part of the variable) is year related. The <NON-YEAR-REASON> states a reason why the variable (or part of the variable) is not year related. There may be both a <YEAR-REASON> and <NON-YEAR-REASON> and in that case, the kind will be <USED-AS-YEAR-AND-NON-YEAR>. The reason given may be related to the input seed file or an inference made from the analysis. NOTE: If there is no <RESULT> tag, the tag that the <RESULT> would have applied to was output for informational reasons only. There is either no useful information or this type was not analyzed.
#### Comments to: shieldhe@us.ibm.com