Utility CTOFANCI
This chapter includes the following topics:
Overview
Using utility CTOFANCI, you can:
-
Generate reports that you can use to develop a conversion work plan.
-
Create output libraries and copy or convert input members to members in the appropriate output libraries.
-
Translate specific automation keywords and parameters in input rules to Control-O rules with similar functionality.
Additional parameters of this utility enable you to:
-
Specify naming conventions and space management for libraries and members created by the utility.
-
Indicate whether to copy comment lines in input members to the output members.
-
Divide large amounts of input into multiple smaller runs of the utility and/or consolidate results from multiple runs of the utility.
-
Run the utility in simulation mode to gather information needed for a conversion work plan.
Logic
Input
Input to utility CTOFANCI consists of the libraries (PDSs) at your site that contain your currently implemented console automation definitions.
Input datasets and, optionally, members are specified to utility CTOFANCI using INCLUDE statements (see INCLUDE Statements).
Input datasets are handled one at a time. All selected members in each input dataset are processed before the utility proceeds to the next dataset.
Output
The content of each input member is analyzed to determine the language or automation product with which it is associated (for example, CA-AUTOMATE, CA-OPS, REXX program, or documentation member).
-
Input members containing console automation definitions are used to create Control-O rules with similar functionality. Each rule is added to a specified output Rule table (PDS member). Depending on utility parameters, more than one Rule table may be created. Additionally, more than one rule with the same ON statement (that is, selection criteria) may be created.
-
For information on conversion of specific keywords and parameters in the input scripts, see Conversion Details.
-
Input members containing other information (for example, CLISTs, TSO REXX or documentation members) are copied to locations specified using parameters of the utility. Each of these members is copied to a separate member in an output library. A comment is added to the beginning of each member containing the input member name and the date and time the member was processed by utility CTOFANCI. For example:
Copy/* <--- SITE1.REXX(REXX1) 00/10/13 09:02 */
-
The name of each output dataset and member is determined by the name pattern specified for parameters OUTDSN and OUTMEMNAME (described in Output Parameters).
Certain members in input libraries are neither translated nor copied into output libraries. Examples of such members are PDSMAN control members (for example $$$SPACE) and Control-O rules (if any) in the input libraries.
Output Datasets
Output dataset names are determined according to a pattern specified using parameter OUTDSN (described in Table 13 in Report Allocation Parameters).
-
If the output dataset does not exist, the utility creates a new PDS with the specified name and allocation parameters.
-
If the resolved dataset name matches the name of an existing dataset, processing depends on the value specified for utility parameter RESET.
-
By default, the existing dataset is used.
-
If RESET=OUTLIB is specified, a new dataset is created with the same name appended by a unique suffix. (The suffix appended to the new dataset name is the same as the <RUNID> keyword described in Table13 in Report Allocation Parameters.)
-
Output Member Names
Each output member created by utility CTOFANCI is assigned a name generated by resolving a member name pattern specified using parameter OUTMEMNAME (described in Table 13 in Report Allocation Parameters).
-
If the intended name of an output member matches the name of a member already in the designated output library, the new member is handled in the following way:
-
If a rule is directed to an existing output member, and that member is a Rule table, the rule is added to the Rule table.
-
If the new output member is not a rule member (for example, it is a TSO REXX or a Documentation member), the output is placed in a new member with a name of:
-
@DUPnnnn
where:
@DUP is a duplicate member prefix specified using parameter DUPPREF (Default:@DUP).
nnnn is a sequential number from 0001 to 9999.
-
-
If a rule is directed to an existing output member, but that member is not a Rule table, utility CTOFANCI searches among the existing @DUPnnnn members for a Rule table whose intended name matches the desired location for the rule. If such a table is found, the rule is added to the table. If no such table is found, a new @DUPnnnn member is created (using the preceding name format).
Reports
In addition to the rule libraries created by utility CTOFANCI, a variety of reports are produced by each run of the utility. These reports provide information about datasets and members selected by the utility, and how they were processed by the utility.
Reports generated by a run of the CTOFANCI utility (in normal or simulation mode) can be sorted to organize information that helps you develop a work plan for conversion of your site’s console automation definitions to Control-O.
For more information about reports produced by utility CTOFANCI, see Reports.
Monitoring Utility Execution
You should monitor the execution of utility CTOFANCI (by browsing the utility output) so that you can handle infinite loops promptly if they occur.
For information about how to handle infinite loops in a run of utility CTOFANCI, see Troubleshooting.
Restarting the Utility
If a previous run of utility CTOFANCI ended early (due to errors or because a specified maximum number of input members were processed), you can avoid unnecessary repetition of processing already performed by indicating that the utility begin processing with a specific dataset or member. For example, you can indicate that processing continue with the last dataset processed by the utility, or with the dataset or member that should have been processed next. For more information, see Execution and Restart Parameters.
For performance reasons, utility CTOFANCI often accumulates several rules–which are destined for the same Rule table–in memory before writing them to disk. If utility CTOFANCI ends due to an error, rules still in memory may appear in the utility’s reports, but may not have been completely processed. If CTOFANCI ends abnormally, it is recommended that you check the last rules processed by the utility to determine if incompletely processed rules listed in the utility reports are missing from the Rule tables. Ensure that the restart of the utility reprocesses any rules that were not completely processed in the previous run of the utility.
Activating Utility CTOFANCI
For more information about how to invoke utility CTOFANCI, see Conversion Steps .
The following control statements show all parameters that can be specified for utility CTOFANCI. This section describes each parameter is described in detail.
Figure 1 Control Statements for Utility CTOFANCi
TYPERUN OUTDSN=outdsn,OUTMEMNAME=memname,MODE={NORMAL|SIMULATION},
[OUTVOL=volser,][OUTUNIT=unitname,]
[OUTTRKS1=tracks,][OUTTRKS2=tracks,]
[OUTDIR=dirblocks,][RLSE=Y|N,]
[SYSOUT=sysout-class,][RPTSRCDSN=dsn|DUMMY,]
[RPTRULESDSN=dsn,][RPTRULESMOD=Y|N,]
[RPTSRCMOD=Y|N,][RESET=OUTLIB|NONE,]
[OUTBLKSZ=block-size,][OUTCOMMENTS=Y|N,]
[RESTARTDS=dsname|dsnid,] [SWEEK=SUN|MON,]
[DAYTIME=+HHMM|-HHMM,]
[RESTARTMEM=memname,][RULEPROGRESS=nn,]
[LINESEQ=NONE|STD|AUTO|col1-col2,][SIMLINELIM=nnn,]
[RULEWARNLIM=nn,][STOPAFTER=nnn,]
[DUPPREF=prefix,][RULEMODE=T|P,][RULEOWNER=ownerid]
INCLUDE DSN=dsname,MEMBER=memname
INCLUDE ...
The following rules apply to the syntax for control statements specified for utility CTOFANCI:
- Multiple INCLUDE statements can be specified for the utility.
- Each control statement (that is, a TYPERUN or INCLUDE statement) can span multiple lines.
- Specification for each parameter in a control statement must be contained in a single line.
- If not all parameters of a statement fit on a given line, a comma must appear after the last parameter on the line and subsequent parameters must be specified on subsequent lines. Positions between the comma and the end of the line must contain only blank spaces.
- To enter a comment line, specify an asterisk (*) in column 1 of the line.
Parameters
The parameters of utility CTOFANCI described in this section are specified using the TYPERUN statement. Only one TYPERUN statement can be specified for each run of this utility.
The TYPERUN statement can be used to specify:
-
Output Parameters
-
Report Allocation Parameters
-
Execution and Restart Parameters
-
Translation Parameters
Output Parameters
The following parameters indicate the naming conventions and locations for datasets and members created by utility CTOFANCI.
Table 12 Naming Convention and Location Parameters Created by Utility CTOFANCI
Parameter |
Description |
---|---|
OUTDSN |
Specifies values that determine the name of the output library for each rule created by the utility. Mandatory. The value specified for this parameter can be a maximum of 72 characters. The value can include any combination of constants (that is, A-Z, 0-9, $, @, or ‘.’) and/or one or more of the following keywords, including the angle brackets (<>):
|
OUTDSN (continued) |
|
OUTDSN (continued) |
Examples:
|
OUTMEMNAME |
Specifies values that determine the name of the member to which each output member or rule must be written. Mandatory. The value specified for this parameter can be a maximum of 72 characters. The value may include any combination of constants (alphanumeric characters) and keywords. Keywords valid for this parameter are the same as those valid for parameter OUTDSN (described elsewhere in this table). The string that results from resolution of the specified keywords must be a valid member name. If the intended name of an output member matches the name of a member already existing in the output library, utility CTOFANCI either appends the output to the existing member, or creates a new member. For more information, see Output Member Names. |
OUTVOL |
Volser to which new output libraries must be allocated. Optional. A maximum of six characters can be specified. If no value is specified for this parameter, allocation is performed without a volume specification (meaning, the location of output libraries is determined by the default settings of your site’s disk management software). |
OUTUNIT |
Unit name to which new output libraries must be allocated. Optional. A maximum of eight characters can be specified. If no value is specified for this parameter, allocation is performed without a unit specification. |
OUTTRKS1 |
Specifies the number of primary allocation tracks to be used for allocating new output libraries. Optional. A value from 1 to 9999 can be specified. Default: 10. |
OUTTRKS2 |
Specifies the number of secondary allocation tracks to be used for allocating new output libraries. A value from 1 to 9999 can be specified. Default: 20 |
OUTDIR |
Specifies the number of directory-blocks to be used for new output libraries. A value from 1 to 9999 can be specified. Default: 100 |
RLSE |
Indicates whether unused space in output libraries must be freed after the current run of utility CTOFANCI. Valid values are:
|
RESET |
Indicates what must be done if a library (PDS) already existed with the name of a specified output library prior to this run of utility CTOFANCI. Optional. The existing library was probably created by a previous run of the utility. This parameter determines how to arrange the results of different runs of utility CTOFANCI. Valid values:
|
OUTBLKSZ |
Block size to be used when creating new output libraries. Optional. A value from 80 to 32760 can be specified. Default: 6000 |
DUPPREF |
Four-character prefix to be used to name each new output member whose intended name matches an existing member’s name in the output dataset. Default: @DUP. Utility CTOFANCI appends a numeric suffix (from 0001 to 9999) to this prefix to create a new member name that does not conflict with existing members. The intended output name is included in the DESCRIPTION field of the output rule. |
Report Allocation Parameters
The following parameters indicate the location to which reports produced by utility CTOFANCI are written. For more information about these reports, see CTOFANCI Reports.
Table 13 Report Allocation Parameters
Parameter |
Description |
---|---|
SYSOUT |
A one-letter SYSOUT class for reports that are sent directly to a print file and not to a permanent dataset. Optional. Default: X |
RPTSRCDSN |
Location to which the rule source report (RPTSRC) must be written. Optional. Valid values are:
If no value is specified for parameter RPTSRCDSN, the report is written to a print file. |
RPTRULESDSN |
Dataset name of a cataloged sequential file to which the rule report (RPTRULES) must be written. If no dataset name is specified, the report is written to a print file. |
RPTRULESMOD |
Indicates whether to replace the data in the existing dataset specified in RPTRULESDSN, or to append the new information to the existing data. This parameter indicates how the RPTRULES report must be written if the specified output dataset contains data from a previous run of utility CTOFANCI. Valid values are:
Report RPTRULES is always allocated with an attribute of DISP=SHR (even if RPTRULESMOD=Y was specified). Therefore, you can browse this report while the utility is still running, regardless of the value specified for parameter RPTRULESMOD. This parameter can be used together with the Execution and Restart parameters (described elsewhere in this table) to manage accumulation of the results of multiple runs of utility CTOFANCI |
RPTSRCMOD |
|
Indicates whether to replace the data in the existing dataset specified in RPTSRCDSN, or to append the new information to the existing data. This parameter indicates how the RPTSRC report must be written if the specified output dataset contains data from a previous run of utility CTOFANCI. Valid values are:
This parameter can be used together with the Execution and Restart parameters (described elsewhere in this table) to manage accumulation of the results of multiple runs of utility CTOFANCI. |
Execution and Restart Parameters
The following parameters can be used to influence basic utility operations, and to indicate how utility CTOFANCI must be run if the previous run of the utility ended due to an error, or because the specified maximum number of input members was processed.
Table 14 Execution and Restart Parameters
Parameter |
Description |
---|---|
MODE |
Specifies whether output rules must be created by this run of Utility CTOFANCI. Valid values are:
|
RESTARTDS |
Dataset at which to start processing. If a previous run of utility CTOFANCI ended due to errors or because the specified maximum number of input members was processed, you can use this parameter to indicate that processing must start at a specific dataset and in this way avoid repetition of processing already performed in the previous run of the utility. If no value is specified for parameter RPTSRCDSN, the report is written to a print file. Valid values are:
The dataset ID assigned to a specific input dataset may change in subsequent runs of the utility if:
Therefore, a dataset ID must be used to indicate restart criteria only if no changes have been made to the selection statements or to your environment since the last run of CTOFANCI. When a value is specified for parameter RESTARTDS, utility CTOFANCI selects all input datasets according to the specified INCLUDE statements, and then skips all selected datasets until the specified one is encountered. You can also use this parameter to skip processing of an input dataset that causes utility CTOFANCI to fail or enter a loop. |
RESTARTMEM |
|
Member at which processing must start.
If no value has been specified for parameter RESTARTDS, the utility searches for the specified member in the first dataset selected using the INCLUDE statements. If the specified member is not found in the dataset, the CTOFANCI utility does not process any member in the dataset; instead, it starts processing with the first member of the next dataset. For additional information about restarting the utility in the see the description of the RESTARTDS parameter in this table. You can also use this parameter to skip processing of an input member that causes utility CTOFANCI to fail or enter a loop. |
|
RULEPROGRESS |
|
Number of input rules or members processed between progress messages. Utility CTOFANCI issues a progress message (CTOF28I) each time it finishes processing the specified number of rules and members. Default: 10. For more information about progress message CTOF28I, see Messages. |
|
SIMLINELIM |
Specifies how many lines to process in each input member while in simulation mode. In simulation mode, the utility does not translate automation statements in input members. Therefore, this parameter can reduce resource consumption and improve the performance of the utility in simulation mode. A value from 10 to 999 can be specified. This parameter is ignored if MODE=NORMAL is specified. If an input member contains more than the specified number of lines, the number of lines listed in the utility reports is specified as TURN (that is, truncated). If this parameter is not specified, all lines of each input member are processed. If a truncated member contains multiple rules, some rules may not appear in the reports produced by the simulation run of the utility. |
RULEWARNLIM |
|
Specifies a limit for the number of warnings to be displayed per input rule or member. Optional. A value from 1 to 99 can be specified. Utility CTOFANCI reports problems with input rules or members using warning messages. Certain recurring problems may result in multiple warning messages with similar content. Parameter RULEWARNLIM can be used to reduce the number of warning messages to a manageable number. If messages for a specific rule or member are suppressed as a result of the specified limit, a message is issued indicating the member name and the number of suppressed messages. |
|
STOPAFTER |
Specifies a maximum number of input members to be processed in this run of utility CTOFANCI. If the specified number of input members is processed, the utility shuts down. This parameter can be used together with Restart parameters (described elsewhere in this table) to manage accumulation of the results of multiple runs of utility CTOFANCI. If no value is specified for this parameter, all selected input members are processed during this run of utility CTOFANCI. |
Translation Parameters
The following parameters specify how to convert certain content in the input members, and how to determine values for certain parameters in output rules.
Table 15 Translation Parameters
Parameter |
Description |
---|---|
OUTCOMMENTS |
Indicates whether to copy comment lines from the input member to output rules. Optional.
|
LINESEQ |
Specifies the existence and position of line sequence numbers in input scripts:
|
RULEMODE |
Indicates the operation mode to be specified in Control-O rules created by the utility. Valid values are:
|
DAYTIME |
The start time of the work day at your site. The format is: DAYTIME=+hhmm or DAYTIME=-hhmm where:
The syntax for this parameter is identical to the syntax for Control-O and Control-M installation parameter DAYTIME. For more information, see the INCONTROL for z/OS Installation Guide. The DAYTIME value must be the same as that assigned to Control-O installation parameter DAYTIME. |
SWEEK |
|
Day on which the work week starts. Valid values:
|
Sample TYPERUN Statements
The following TYPERUN statements contain sample subsets of parameters that can be specified to utility CTOPFANCI:
TYPERUN OUTDSN=CTO.<INDSN>,OUTMEM=<INMEM>,OUTUNIT=3390,OUTVOL=MYVOL1,...
One output dataset is created for each input dataset. The name of the output dataset is the same as the name of the corresponding input dataset, with a prefix of CTO.
Each input member is processed. The resulting member or rule is placed in an output member with the same name in the corresponding dataset.
TYPERUN OUTDSN=CTO.NEW.RULES.<ETYPE>,OUTMEM=MAIN,...
All rules with the same type of selection criteria (for example, rules triggered by detection of a message) are grouped together in a separate output PDS (library). Each such PDS contains a single member (a Control-O Rule table) called MAIN.
TYPERUN OUTDSN=MY.SITE.RULES,OUTMEM=<INMEM>...
All output rules are placed in one output library. Output member names are the same as the names of the corresponding input members.
INCLUDE Statements
INCLUDE statements specify selection criteria for members to be processed by the utility. Multiple INCLUDE statements can be specified.
The format of an INCLUDE statement is as follows:
INCLUDE DSN=dsname,MEMBER=memname
where:
-
dsname is the dataset name (or mask) of the datasets to be processed by the utility.
-
memname is the member name (or mask) of the members to be processed by the utility.
Each specified value must be either a full name (dataset name or member name) or a valid mask (that is, a name prefix followed by an asterisk). An asterisk can appear in a dataset name mask only after a period (that is, you must specify complete qualifiers).
Any number of INCLUDE statements can be specified. Multiple INCLUDE statements can overlap (that is, a given dataset can match the selection criteria in more than one INCLUDE statement). INCLUDE statements that specify similar criteria can be used to select multiple sets of members from the same dataset. Each member selected using INCLUDE criteria is processed only once, regardless of the number of INCLUDE statements that match the member.
Sample INCLUDE Statements
INCLUDE DSN=SITE1.MVS1.OPS.RULES.*,MEMBER=*
INCLUDE DSN=SITE2.MESSAGES.*
INCLUDE DSN=SITE3.MVS2.AUTOMATE.*,MEMBER=MSG*
EXCLUDE statements (specifying members not to be processed) are not yet supported by utility CTOFANCI.
JCL Required to Execute CTOFANCI
The following is a sample of the JCL statements that activate utility CTOFANCI. For more information about activation of this utility, see Conversion Steps .
Figure 2 JCL Required to Execute CTOFANCI
//CTOFANCI JOB ,NAME,MSGCLASS=X,CLASS=A,NOTIFY=NAME//CTOFANCI EXEC PGM=IKJEFT01,DYNAMNBR=999,REGION=4M
//SYSEXEC DD DISP=SHR,DSN=CTOF.REXX
// DD DISP=SHR,DSN=SYS2.EXEC
//SYSPROC DD DISP=SHR,DSN=CTOF.REXX
// DD DISP=SHR,DSN=SYS2.CLIST
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSTSIN DD *
PROF NOPREFIX
CTOFANCI CTOF.REXX(SYSINPRM)