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.
|
  
|
|