Analyzing and Converting Your Files

This section contains directions for converting 9.x scripts, source code, and other files with the prepare and analyzer tools. Unless otherwise stated, procedures and examples assume you are running on a 9.x system.




	CAUTION: Do not try to convert system files or move them from a 9.x to a 10.x system. You are unlikely to succeed in converting these files for yourself "by hand;" the upgrade process will do this conversion for you during the upgrade. In this context, "system" files are HP-UX files in the following 9.x directories and 10.x directories: `/usr/bin`, `/usr/sbin`, `/usr/lib`, `/etc`, `/sbin`, `/bin`, `/lib`, `/dev`, `/system`. `prepare` will bypass these directories.

Analyzing Files

prepare and analyzer examine files for potential problems, and, optionally, create a parallel set of files in which pathnames have been converted to their 10.x equivalents. This section deals with the process up to that point; the following section, “Converting Files ”, explains how to complete the conversion.

Strategies for Running prepare and analyzer

Together prepare and analyzer are capable of searching your 9.x system for all files that may need to be modified to run on 10.x, scoping the work, logging potential problems file by file and line by line, and creating new files in which the pathnames have been converted and other problems are flagged. How many of these capabilities you will want to use depends on how your system is set up, and perhaps on the major purposes of the system.

Read through each of the "cookbooks" below and decide which one best suits you; the "cases" are intended to help you decide but they are not binding: any of the "cookbooks" (and particularly the first two) will work for any "case".




	NOTE: `prepare` and `analyzer` will identify problems related to HP-UX pathnames and HP-UX "core" commands and libraries. They will not catch problems specific to applications and utilities, whether these are provided by a third party or by HP itself.

Case 1

If the system has many scripts, makefiles and application source files scattered throughout the directory tree (or if you think it may have), and you want to convert most of them to run on the 10.01 system, then you should run prepare using the two-stage recipe recommended in the manpage and outlined later in this chapter under “Two-Stage Cookbook for Running Prepare ”.

You can see a short version of this recipe if you simply invoke prepare without options:

/upgrade/bin/prepare

An example of a system that fits this description would be a multi-user development machine.

NOTE:

/upgrade/bin/prepare -h

runs a demo of prepare.

Case 2

If you know that most of the files you need to analyze are concentrated in a few directories on the 9.x system, and you know exactly which directories they are, then you may want to use or adapt one of the examples in the “One-Stage Cookbook for Running Prepare ” below.

If you are the owner/administrator of a single workstation, your system may fit this profile.

Case 3

If you are really only interested in a few files, and especially if they are large, you may be better off running analyzer directly on each file, without the prepare front end. See “Cookbook for Running Analyzer (without prepare) ” later in this section.

Two-Stage Cookbook for Running Prepare

This cookbook is for systems best described under “Case 1 ” above — that is, there are many scripts, makefiles and application source files scattered throughout the directory tree (or you think there may be.)

This procedure works particularly well for this case because the first stage weeds out files that do not need to be modified for 10.01, so that in the second stage you are running prepare on lists of files that prepare has identified as likely to need at least one change. This cuts down overall processing time considerably.

This procedure assumes a 9.x system. It uses the two-stage approach ("Identification" and "Conversion and Analysis") described in the prepare manpage. It is the most "automated" way to get started with prepare, and has the advantage of weeding out files that do not need changes.

Before You Start

You may want to add /upgrade/bin to your path so you don't have to type in the full pathname for prepare each time.

Procedure

Run prepare once without options to create the .preparerc file that prepare requires.
Answer y when asked if you want to create the file.
Review the .preparerc file.
This file is copiously self-documented. Check the defaults for file types and directories to be included and excluded, to make sure you get the results you want.
Run prepare on a directory specified by Directory_Name:
prepare -bvr Directory_Name
where:
-b
tells prepare to do only a quick check of files to see if they need further analysis and conversion.
-v
tells prepare to report progress to stdout.
-r
tells prepare to examine Directory_Name and the directories under it, recursively.
This creates four lists of files containing the names of all of the files prepare has examined. The file names are sorted into in these categories:
1.SHELL.g
shell scripts and makefiles
1.SRC.g
source files
1.TEXT.g
text files
1.ELSE.g
unrecognized files
Each of the files on these lists will have been subjected to a quick check for potential 10.x changes. Files that look as if they will need at least one change are listed in the following files:
1.SHELL
shell scripts and makefiles
1.SRC
source files
1.TEXT
text files
1.ELSE
unrecognized files
Edit each of these lists (1.SHELL, 1.SRC, 1.TEXT and 1.ELSE), removing files you don't want prepare and analyzer to look at, such as backup copies.

Run prepare on each of the lists of files.




	NOTE: `prepare` will duplicate not only your files, but also the original directory tree, under the output directory you specify. If you do not have enough disk space to create copies of the files, omit `-m NEWDIR` from the commands shown below.

Use these commands to analyze the files on each list, creating new files under NEWDIR:

prepare -V -l+2 -L $ -S $  -f 1.SHELL  -m NEWDIR
prepare -V -l+2 -L $ -S $  -f 1.SRC    -m NEWDIR
prepare -V -l+2 -L $ -S $  -f 1.TEXT   -m NEWDIR
prepare -V -l+2 -L $ -S $  -f 1.ELSE   -m NEWDIR

where:

-V

tells prepare to report progress (at the file level) to stdout.

-l+2 -L $

creates a logfile 1.SHELL.log

-S $

creates a summary file 1.SHELL.sum

-f

specifies the name of the file which contains the list of files to be examined.

-m

creates a new version of each original file under NEWDIR.

The new version has 10.x HP-UX pathnames in place of 9.x pathnames, and contains comments on other potential problems, such changed options to commands or system calls.

-m creates NEWDIR if it does not exist; if it does exist, old files are not overwritten by new ones. (Use -M instead of -m if you want old files to be overwritten.)

Examine the new files (those under NEWDIR in this example) and do the remaining work of converting them. You can use fscanner for this task. See the fscanner(update_aid) manpage for more information.

See “Converting Files ”, later in this chapter.

One-Stage Cookbook for Running Prepare

This cookbook should suit systems best described under “Case 2 ” above — that is, the files you want to convert for 10.x are concentrated in a few directories on the 9.x system, and you know exactly which directories these are.

This procedure assumes a 9.x system. It uses only the second, "Analysis and Conversion", stage described in the prepare manpage.

Before You Start

You may want to add /upgrade/bin to your path so you don't have to type in the full pathname for prepare each time.

Note that prepare will duplicate not only your files, but also the original directory tree, under the output directory you specify.

For example, if the original files are /patrick/bin, and you specify /patrick/10.0files as the output directory, the modified copies will be saved in /patrick/10.0files/patrick/bin

If you prefer, you can make prepare create a subdirectory hp_REL10_hp under each directory that contains files to be analyzed; analyzer then writes out the new files to those directories. To do this, use a period (.) instead of a directory name, for example:

/upgrade/bin/prepare -pas -m . -S mysum -f mylist

This is useful if the original files are only in one or two directories. For example, if all of the originals were in /patrick/bin and you specify "." for the output directory, the copies would be saved /patrick/bin/hp_REL10_hp

Procedure

Create a list of files.

Use find(1) to create a list of files that is to be examined and converted. For example, to create a list of all the files in the directory /patrick/bin and save it in a file called mylist in the current working directory:

find /patrick/bin -fsonly hfs -type f -print >mylist




	NOTE: The `-fsonly hfs` option is important: by default, `prepare` will not cross NFS mount points, meaning that you must run it on the NFS server. You can change this behavior if you have to; see "ADVANCED OPTIONS" in the `.preparerc` file (created in step 4) for directions.

Edit the list, removing files you don't want prepare and analyzer to look at, such as backup copies.
It's a good idea to remove compressed files and other binaries from the list as well, as analyzer will report these as errors.
NOTE: Remove blank lines, including trailing blank lines, from the list. analyzer reports the following error for each blank line it encounters:
analyzer ERROR: input file not specified
Scan the prepare manpage.
This cookbook does not exercise all of the options; there may be others that suit you better. (For example, you can specify options for a particular file on the list; these override the command-line options for that particular file.)
Run prepare once without options to create the .preparerc file that prepare requires:
/upgrade/bin/prepare
Answer y when asked if you want to create the default file.
Review the .preparerc file.
This file is copiously self-documented. Check the defaults for file types and directories to be included and excluded to make sure you get the results you want.
Run prepare; for example:
/upgrade/bin/prepare -pas -m /patrick/10.0files -S mysum -f mylist
where:
-pas
tells prepare and analyzer to examine:
absolute pathnames (-p)
system calls and routines in ASCII source code (-a)
commands and options in shell scripts (-s)
-m
tells the tools to write out copies of the original files, converting pathnames to their 10.0 equivalents and adding comments on other problems such as changed options to a command.
/patrick/10.0files specifies the directory to which analyzer will write out the copies of the files.
-S mysum
specifies the summary file that analyzer will write out.
-f mylist
is the input list of files to be examined (see step 1).
Examine the new files (those in /patrick/10.0files in this example) and do the remaining work of converting them.
See “Converting Files ” later in this chapter.




	NOTE: `prepare` will create the specified output directory (`/patrick/10.0files` in the above example) if it does not exist. If the output directory does exist, prepare will not overwrite files that are already there, unless you specify `-M` instead of `-m`. If you specify `-M`, existing files will be overwritten by new ones whenever the names match. `prepare` duplicates the original directory tree under the output directory you specify.

Examples

Examining scripts, not source code; write out detailed comments in log.
/upgrade/bin/prepare -ps -m /patrick/10.0files -l4 -L mylog -f mylist
- Examine files listed in the file mylist in the current working directory (-f mylist).
- Check commands and pathnames but don't check for system calls or library calls (-ps).
- Write output files to subdirectories under /patrick/10.0files (-m /patrick/10.0files).
- Write out detailed log to file mylog in the current working directory, including the text paragraphs that comment on specific problems found in the files (-l4 -L mylog).
Examining mix of files that includes source code as well as scripts, makefiles, and possibly text files.
/upgrade/bin/prepare -V -pas -m . -S mysum -f mylist
- Run in verbose mode (-V), reporting actions on stdout.
- Do all available checks: pathnames, library calls, commands (-pas).
- Write output files to subdirectories named hp_REL10_hp under directories that contain the original files.
- Write summary to file mysum in the current working directory.
Rechecking files on which you have already run prepare once.
/upgrade/bin/prepare -V -pas -M . -S mysum -f mylist
- Same as previous example, but overwrite hp_REL10_hp directories created by previous run of prepare (using the same list of files in mylist).

Useful prepare Options: Quick Reference

prepare -g
      "get": Generates lists classifying files according
       to types (output in  *.g files).
prepare -q
      "quick": Runs a quick analysis on the files in the *.g
      list and outputs another list (n.Shell, n.SRC etc.) of
      files that may require at least one modification for
      10.01.
prepare -b
      "build": Same as prepare -g -q
prepare -m
      "modify": create modified files in a save directory
       ("-m ." is special and results in a directory
       hp_REL10_hp).  Note that the full pathname is
       duplicated beneath the save directory.
prepare ... -l loglevel -L logfile
      "loglevel": 1...4 (precede number with + to get
       additional statistics of number of changes).  -l is
       ignored unless the logfile is specified with -L.
       Level 2 is usually about right; use 4 if you want the
       text that explains the changes to be printed in the
       logfile.
prepare ... -v|-V
      "verbose": -V recommended

Cookbook for Running Analyzer (without prepare)

This cookbook is for those who fit “Case 3 ” above — that is, if you want to examine only one or a few large files, and don't need the prepare front end.

To run analyzer directly on a single file (for example a large piece of code), use a command such as:
/upgrade/bin/analyzer -pas -l2 -L analyzer.pdlog -m myfile.10.0 myfile
To run analyzer on a list of files, you might write a script such as:
while read filename do /upgrade/bin/analyzer -ps -l2 -L analyzer.pdlog -m$filename.10.0 $filename mv $filename.10.0 $2 done < $1
where:
$1
is the filename of the input list of files.
$2
is a directory where the 10.01 versions of the files will be saved.

Converting Files

By this point you should have a set of partially converted files, in which the 9.x pathnames have been converted to their 10.x equivalents, and other potential problems have been flagged with comments.




	NOTE: By no means will all potential problems actually turn out to be things you need to fix, but you need to check all of them. In particular, look out for: Use of `mknod(1M)` or `mknod(2)` to create device files, and device file references in general. The names and the major or minor numbers will probably not be valid for 10.x. HP-UX (''DUX'') cluster options. Kernel generation using `regen` or `uxgen` (for the Series 800). These commands are not supported in 10.0; see the section "Kernel Convergence" in the Release Notes for HP-UX 10.10. `-F` in file system commands; the meaning has changed in 10.x. Conversely, `prepare` and `analyzer` will not catch problems that are specific to applications and utilities that are not part of the core operating system.

A quick way to find comments added by analyzer is to print out the summary file created with the -S option to prepare (see “One-Stage Cookbook for Running Prepare ”). A number greater than zero in the #WARN column means there's at least one line in the file in question that needs your attention. You can find analyzer's comment by searching for #analyzer in the output file. (Another method is to run fscanner using the analyzer keyword. Refer to the fscanner(update_aid) manpage for details.)

The comment lines point to text that describes the issue more fully. Look up this text either in the log file (if you chose log option -l4) or in the appropriate database (/upgrade/lib/CMDS_DB or /upgrade/lib/LIBS_DB).

Comments tagged with a code beginning with the letter C (e.g. C_120) refer to messages in the CMDS_DB; comments whose code begins with the letter L refer to messages in the LIBS_DB.

These "databases" are in fact ordinary ASCII text files; use the number (e.g. C_120) to search for the message via more or your favorite text editor. (Make sure you are in read-only mode!)

Check the comments in all of the files, make the changes that turn out to be necessary, then upgrade your system. Once you are up on 10.01, you should still do the testing and certification you would normally do on a new release before you run these programs and scripts or make them available to users.

Example

The following is an excerpt from a script that warns the user if he or she is logging in to a member of an HP-UX ("DUX") cluster:

#!/bin/ksh
 
.
.
.
if [ -r /etc/clusterconf ]
then
  if [ "`getcontext | grep remoteroot`" != "" ]
  then
    echo client of `cnodes -alC | grep ROOT | cut -d" " -f1`
  else
    echo cluster server
  fi
fi
 
.
.
.

After running prepare, you'd find that the summary file reports several warnings (#WARN) for this file. Examining the copy of the file that analyzer has created, you'd find this section commented as follows:

if [ -r OBSOLETE</etc/clusterconf>OBSOLETE ]
#analyzer, Line 58: Above pathname requires manual evaluation.
then
  if [ "`getcontext | grep remoteroot`" != "" ]
#analyzer, Line 60: Command "getcontext", OBSOLETE, see CMDS_DB entry C_089
#analyzer, Line 60: Command "grep", WARNING, see CMDS_DB entry C_092
  then
    echo client of `cnodes -alC | grep ROOT | cut -d" " -f1`
#analyzer, Line 62: Command "cnodes", OBSOLETE, see CMDS_DB entry C_045
#analyzer, Line 62: Command "grep", WARNING, see CMDS_DB entry C_092
  else
     echo Cluster server
  fi
fi




	NOTE: This is a fairly severe example, generated to show as much `analyzer` output as possible; you should not find many passages of real code as densely commented as this.

The reference to /etc/clusterconf (line 58) is the first problem. The file won't exist on a 10.x system, hence the OBSOLETE flag (and since there is no replacement for /etc/clusterconf, analyzer can't supply a 10.0 pathname.)

The next line invokes getcontext, which on 9.x is an HP-proprietary command. Searching for C_089 in /upgrade/lib/CMDS_DB, you'd find:

getcontext#obsolete#NA#C_089#
  The utility getcontext(1) is no longer supported. This
  option supports HP-UX clusters, whose underlying technology
  has changed as of 10.x. If your version of 10.x includes
  NFS Diskless, see "NFS Diskless" in the Release Notes for
  more information on HP's much enhanced implementation of the
  industry-standard diskless technology. #

This indicates the underlying problem: HP-UX ("DUX") clusters are not supported as of 10.0 (see “Converting HP-UX ("DUX") Clusters” of this manual), and so none of the supporting commands, such as getcontext and cnodes, will be there (though there is an entirely separate SVID3 system call getcontext).

The remaining messages in this example refer to grep, but the changes in question (concerning regular expressions) turn out not to affect this particular piece of code.

To run the script on 10.01, you would have to remove these lines or comment them out, and (once you are running NFS Diskless) find some other way of warning users that they're getting HP-UX from a remote server.

Analyzing and Converting Your Files

Technical documentation

» Table of Contents

Analyzing Files

Strategies for Running prepare and analyzer

Case 1

Case 2

Case 3

Two-Stage Cookbook for Running Prepare

Before You Start

Procedure

One-Stage Cookbook for Running Prepare

Before You Start

Procedure

Examples

Useful prepare Options: Quick Reference

Cookbook for Running Analyzer (without prepare)

Converting Files

Example