NAME

IMS::ReleaseMgr::Utils - A collection of utility routines for rlsmgr scripts

SYNOPSIS

    use IMS::ReleaseMgr::Utils ':all';

    write_log_line($filename, $text);

DESCRIPTION

Several functional blocks of the different release manager scripts were identified as essentially identical. To this end, they have been gathered under the heading of "utilities" and kept here.

SUBROUTINES

The following routines are made available for explicit import. None are imported by default, so users of this package need to be specific in terms of what gets pulled in. There are three tag sets, one for signal-handling routines, one for database access and the third for accessing configuration via physical files. The tag ":all" can be used to import all routines.

write_log_line($file, $line)

Writes the specified $line (more than one may be passed in a single call) to the file specified in $file. Performs locking and unlocking, as well as proper buffer-seeking so as to allow different processes to utilize the same log file without danger of collision.

The following two routines may be brought in with the tag ":signals":

SIG_inc_trace

When assigned as a signal-handler, this routine can be used to automate the increment of trace levels. It expects a scalar $trace to exist in the MAIN:: namespace. That scalar is then incremented. The application is still responsible for associating the value of $trace with error logging and/or tracing.

SIG_dec_trace

This is a complement to the above routine. When triggered, it decrements the global scalar $trace.

The following routines may be brought in with the tag ":DBI":

DBI_mirror_specification(-mirror => $mirror)

Contacts the Oracle DBMS that stores the mirror-pool data and fetches the full specification for the requested mirror name $mirror. The return value is a hash reference, or the special value undef if there was an error.

DBI_mirror_host_list(-mirror => $mirror)

Similar to the previous routine, this call contacts the Oracle DBMS and retrieves the list of all host names that make up the pool for the specified pool $mirror. In the case of systems where there is only one host, the list is generally a single-item list containing the name of the one host. The return value is a list reference, or undef in case of error. Any of the hosts in the list that use a port other than the default HTTP port of 80, then that is appended to the hostname with a separating colon (":").

DBI_all_mirrors

Fetches all mirror specifications from the database and returns them in a hash reference whose keys are the mirror group names, and whose values are themselves hash references to the specification for the corresponding group. Returns undef on error.

DBI_all_hostlists

As above, fetches all the hostlists for all mirror groups, returning them in a hash table keyed by mirror name. Each table value is a list reference similar to what is returned by DBI_mirror_host_list

DBI_match_mirror_to_host(-mirror => $mirror, -host => $host)

In most cases, a physical hostname is not the same as the name the webserver considers itself to be. This routine matches the physical hostname $host to the correct virtual hostname in the pool for the mirror group $mirror. As an example (as of 10 July, 1999), for the mirror group www.buy.hp.com and physical host hpcc950.external.hp.com, the return value would be www2.buy.hp.com.

DBI_error

Returns the error string from the DBI interface that occurred with the most recent operation. Each of the other routines in this group sets and clears this value, so a null string is returned if the most recent operation was in fact successful.

The following routines may be brought in with the tag ":file". Each is a file-based counterpart to one of the DBI routines above, except for the fact that file-based configuration does not have access to the full database of mirror information, as is available via DBI. Thus, there are no equivalents to the "all mirrors" or "all hostlists" calls:

file_mirror_specification(-file => $file)

Read the specification data from the requested file. The value of $file should be an absolute path for safety sake, though this is not a strict requirement. Other lines may be in the file; only those lines that look to be of the form, "NAME=VALUE" are actually parsed. This allows for configuration files to include Bourne shell code and double as launch files. See examples in the /opt/ims/ahp-bin directories of hosts hpcc925.external.hp.com or hpcc950.external.hp.com for how this is currently used in production. Returns a hash reference just like the DBI counterpart. The return value is undef on error.

file_mirror_host_list(-file => $file)

Read the list of hosts that comprise a mirror pool. Returned as a list reference as the DBI counterpart does. Unlike the specification file, only comments, blank lines and data lines may be in this file. A data line has either a single hostname (such as www2.buy.hp.com) or a hostname with the physical host name of the machine in question as a second item on the line, separated by whitespace: "www2.buy.hp.com <some space> hpcc950.external.hp.com". The second value is used by the next API hook. This routine only returns the aliases. The return value is undef on error.

file_match_mirror_to_host(-file => $file, -host => $physical_host)

Using the file specified, try to determine which of a set of aliases that comprise a mirror pool match to the current physical host. This is for cases when it is necessary to find place within the mirror list of the running host. If $file has no physical host data, or insufficient, then a null return is the result. Otherwise, the relevant alias is returned.

file_error([ $text ])

All of the file_* routines set their error text via this routine, and programs using the API can retrieve it using this call. All routines clear this at the start, so that a stale message is not carried over. Any parameter present is taken to be a new value for the error message. General external use should not need to set any errors.

The remaining routines represent a miscellany of assorted functionality used by both client and server ends of the release process:

fork_as_daemon($dont_die)

Causes the running process to background itself, using a strict model as defined in the W. Richard Stevens book, "Advanced UNIX Programming". In brief: the process forks (parent exits), sets its own process group, detaches from the TTY, sets the TTY-related signals to be ignored, and forks again. It is the grandchild that eventually returns from this call.

If there is an error, the default course of action is to die, reporting the error in the process. If the routine is passed a single non-null parameter, the routine will instead return the error message as a string, and not die. The normal return code (for a successful detachment) is a null string.

send_mail($to, $subject, $body)

Sends an e-mail message to all addresses in $to (a comma-separated list). The parameter $subject is used for the message subject header. The text is presumed to be in $body. The $body parameter may be a scalar or a list reference (to allow more than one line of text). No extra formatting is done to $body before sending.

eval_make_target($target, [ $dir_root, $host, @extra_args ])

This routine is used to execute the UNIX make command. The caller is assumed to be in the directory that contains the Makefile. The value of $target is given to make as a command-line parameter. If $dir_root is passed and is non-null, it is used as a base directory for passing the following variables as command-line arguments to make:

    TARGETHOST=$host
    WWWDOC=$dir_root/htdocs
    WWWBIN=$dir_root/bin
    WWWCGI=$dir_root/cgi-bin
    WWWFCGI=$dir_root/fcgi-bin
    WWWJAVA=$dir_root/applets
    WWWLOCAL=$dir_root/local

Anything passed in @extra_args is added to the end of the make command-line. If the developer wishes to pass something in @extra_args without using $dir_root, then the second parameter must be either a null string ("") or an explicit undef:

    eval_make_target($target, undef, undef, @extra_args);

variable_substitution($hashref)

This was intended to be an internal support routine, but after popping up in several other places, it is now exported. It takes the hash reference passed in and scans it for nested references in the values part, to keys of the hash itself. That is, if there is a key called SERVER_ROOT, all values that contain the sequence "$SERVER_ROOT" will have that substituted with the value of $hashref-{SERVER_ROOT}>.

AUTHOR

Randy J. Ray <randyr@nafohq.hp.com>

SEE ALSO

IMS::ReleaseMgr, perl(1).