Summary-Level History File Example

Control Statements and Tables › CA JARS Control Statements › SORT Statement › Summary-Level History File Example

Summary-Level History File Example

The following example illustrates how to create a summary-level history file:

                    Points to Run Date in
                    Basic Accounting Table
                                │
                                │
    Points to User Information  │ ┌────── Points to Start Time in
    in Basic Accounting Table   │ │       Basic Accounting Table
                │               │ │
                │        ┌──────┘ │
                │        │        │    Sort only           History
                │        │        │    Job records┐┌────── File Name
                │        │        │               ││
                ▼        ▼        ▼               ││
              ┌────┐   ┌───┐    ┌───┐             ▼▼
  position   1         2        2          4  5   5     6  6      7         8
    1........0.........0........9..........0  0...4.....0..3......0.........0
    ASORT    07708AE104306A2103702A21             JHISTORY 2
             -------- -------- ------
                -         -        -                       -
                │         │        │                       │
              First     Second    Third        History Level Flag
              Sort      Sort      Sort
              Level     Level     Level

In this example, you may request that history records be generated for each change in the second sort control field as indicated by the history-level flag: 2. Each time this sort control field (run date) changes, a record is written to the history file defined by the file name HISTORY. In the job setup for this run, supply a DD statement with the DDNAME HISTORY defining the history file created for Report A.

Report A is sorted on three levels. The most general level is user information (beginning at position 77 in the Basic Accounting Table), sorted in ascending order on the first eight positions. Eject to new page after printing summary lines, and include descriptive headers.

The second sort level is run date (beginning position 43), a six-character field sorted in ascending order. Double space before printing summary lines and include descriptive header.

The third sort level is start time (beginning position 37 in the Basic Accounting Table). It is two-characters long (the hours portion), sorted in ascending order. Double space before printing summary lines. Include descriptive header. Note that reports designed to use the history file as input do not provide information to any level of detail greater than that specified at the time the history file was created. The following examples explain this statement:

Summary-Level History Flag Example #1
Sort Definitions:   Level 1:  account number
                    Level 2:  run date
History File Name:            'HIST001blank'
History Level Flag:           '1'

A history file (DDNAME HIST001) is generated during the formatting of this report. Each time the first level sort control field changes (each new account number), a record is output to HIST001, summarizing information for the previous account. Assuming there are 50 different account numbers to be reported on, there will be 50 records generated and written to HIST001. Only those data elements which can be logically added up for totals will contain values. The data element corresponding to the sort control field will also have a value. In this case, each history record contains an account number in the appropriate field since it was used as the sort control field definition.

Summary Level History Flag Example #2
Same parameters as in Example #1 with the following exception:
History Level Flag:  '2'

This example shows the importance of choosing sort definitions and a corresponding history-level flag wisely when creating a history file. In the previous example, each record generated contained an account number because the history-level flag caused history records to be generated at the first level. However, in that example, since run date is not logically additive and is a subordinate sort definition to that specified by the history flag, no output records contain a run date. Obviously, this could be a problem in subsequent reporting if it becomes necessary to identify or report on run date.

In the new example, the history flag is set so that a record is generated and written to HIST001 each time the second level sort control field changes (each new run date). Since run date is subordinate to account number, each record generated also contains the appropriate account number. More records are written to HIST001 (each run date within each account as opposed to each account), but the future flexibility is worth it. If HIST001 is input to CA JARS you can sort on account number and/or run date (or any other field that contains valid data) and still maintain integrity in the data by run date.

The CSV (comma separated value) member name field, when entered, will cause CA JARS to invoke the JSICSVJ exit in order to create an output CSV member in a PDS data set with this name. A CSV member name must start with a character and have no embedded blanks. Specifying this field requires the presence of the CAIJSCSV and CAIJSIDX DD statements during execution.

If you generate a CSV file, you can also generate an XML profile that describes the CSV file. This XML profile can be used by the iCan Service Management Suite to process the output CSV file from CA JARS. To generate the profile, place a "2" in column 73 of the SORT statement.

With the use of XML Profiles for the CSV files, CA JARS can be integrated with the iCan Service Management Suite. By automating the collection and aggregation of data from multiple data sources, the iCan Service Management Suite provides enterprises with a new level of visibility into IT resource utilization and service levels. The combination of CA JARS and the iCan Service Management Suite provides enterprises with:

Service level management reports concerning IT resource ulilization and services from a management or client perspective.
Usage based billing that accounts for IT resource ulilization and services throughout the enterprise.
Cost allocation and chargeback that allocates the cost of IT services based on actual usage through usage based billing.
Budgeting that forecasts future IT budget requirements, based on historical IT resource usage.
Fully customizable Web based reports that are complete with access control settings and rapid distribution methods through portal dashboards.

For more information, see the iCan Service Management Suite Administrator Guide.

Notes:

A single run of CA JARS can produce 15 history files of either kind, one per report. Since a detail (job or job/step) history file contains all job accounting data, not only the output on the report, there is no need to produce more than one file of either type per run. Summary level historical information varies depending on the sort fields selected, and is different for each report.
Data elements in the history record relative to computer billing are not filled with valid data unless rate parameters are present during creation of the history file using raw data. Rate parameters are input using the RATE, TSORATE, FORMRATE, SNARATE, APPCRATE, RJERATE, and PRIORITY statements. When history file input is used, the rate parameters do not apply or override existing computer billing-related data elements. These fields can be changed only by recreating the history file using raw data with new rate parameters present. The exception to this rule is that a history file created at the job step level is subject to rate calculations in the same manner as raw data input to CA JARS.
While history files of either type can be used as input to the CA JARS Report Writer, a job step (level 7) history file is often the most useful. For applications related to the Combined Billing Facility using CA JARS Wizard and files of records defined by the CA JARS Wizard JR70CBF glossary, a job step history file is mandatory.
When processing history data, no duplicate record checking occurs. Duplicate record checking only occurs on SMF data.

Position	Field Length	Field Name	Notes
1	1	Set Code	Must be supplied
2-9	8	Statement Type	SORT
10-17 18-25 26-33 34-41 42-49	8 8 8 8 8	1st Sort Level 2nd Sort Level 3rd Sort Level 4th Sort Level 5th Sort Level	pppllosd must be blank or numeric where: ppp: position of sort field from Basic Accounting Table ll: length of sort field (max 32) o: order of sort field, where the default A is ascending and D is descending s: summary line print option (see table below) d: description header flag, where blank prints at sort break and 1 prints description headers for this level (prints at beginning and end of sort break)
50 51 52 53	1 1 1 1	Job Flag Step Flag Forms Flag RJE Flag	Relates to elements available for display/printing (refer to Output Data Elements Table), where blank suppresses printing (if 50-53 are blank, defaults to contents of position 54 and prints summary report) and 1 prints detail records.
54	1	Required Records Indicator	Specifies types of records to include in sorting operation: A: Batch, TSO, RJE records J: batch, TSO job records default S: step records R: RJE records F: forms records
55-62	8	History File DDNAME	blanks : No history file xxxxxxxx: History file DDNAME
63	1	History-Level Flag	1-5: summary-level history file 6: job-level history file 7: job-step level history file
64	1	Print DDNAME Suffix	If non-blank, append to DDNAME of CAIJS(x) and use that DDNAME for the report output

If the value of position 73 is not equal to 3, these are the definitions for columns 65-72:

Position	Field Length	Field Name	Notes
65-72	8	CSV Member Name

If the value of position 73 is equal to 3, these are the definitions for columns 65-72:

Position	Field Length	Field Name	Notes
65-66	2	DDNAME Suffix for XML Output	Two non-blank alphanumeric characters. (Required if position 73 is set to 3.)
67-68	2	DDNAME Suffix for XML Schema for Output	Optional field, which can contain two alphanumeric characters. The default value used is the value set in positions 65-66.
69-70	2	Optional XML Code Page	Two numeric characters. As of now, the only supported code pages are: 00 - EBCDIC (Default) 01 - UTF-8
71-72	2	Ignored
73	1	XML Indicator	1. Indicates that no XML profile or XML data should be generated when the CSV report is produced. This is the default. 2. Indicates that an XML profile for the iCan Service Management Suite should be produced in the CSV library with member name PRFxxxxx, where xxxxx matches the five characters of the member name in columns 68-72. If the profile is not needed, this field should be left blank. 3. Produces an XML report in addition to the regular report.
74-80	7	Reserved	Not used

Summary Line Print Option Table

blank or N - No summary print for this level

1, 2, or 3 - Single, double, or triple space before printing summary

E* - Eject to new page after printing summary

P* - Eject to new page and reset page number after printing summary

* If either E or P is specified for the first level summary line, grand totals print on a page by themselves.