UPD/UPR/UPP Module list

 

Terms

The upd low level design uses several terms in names of arguments, and for other purposes in the design, whose representation and meaning are defined here:
node
a string containing the DNS name of the host

 
filename
dir
db
product_root
a string containing a POSIX file path name.  In the case of product_root it is specifically a directory that is the root of the filetree for a given product's files.  in the case of db, it is a directory containing a ups database.
instance_spec
a Perl hash containing values for (at least)
dependency list
spec_list
a Perl array of references to instance_spec's.   When used as a depency list, the order is signifigant, it is a topologically sorted dependency list. (e.g. dependants come first)
add_args
A perl hash of an incomplete instance_spec (actually, it's more than just a spec. it includes other args as well)., used as an override on an instance_spec when declaring products.
flags
a Perl hash where $flags{opt_i} is the value of the -i flag on the command line. This hash table has main scope and can be accessed like: $main::flags{opt_i}.
status_code
a boolean value indicating whether a routine succeeded or failed.  If the routine checks something, it has a reference parameter where the thing being checked is returned, the status_code indicates whether it was successful at checking, not wether the thing being  checked for exists.
fd
File descriptor -- actually a Perl filehandle
prop_info
Special information needed to fetch proprietary products. -- currently a group name and password for SITE GROUP on the wu-ftp server.

Modules and Subroutines

The initial design is to break the code up into the following modules, with subroutines defined as below:

The updxfr module

This module contains routines to encapsulate the remote file transfer mechanism, currently ftp.
status_code = updxfr_ls( node, dir, fd )
lists the contents of the directory dir on the host node, printing the results on file descriptor fd.
status_code = updxfr_file( node, dir, dist_filename, local_filename )
transfers a file dist_filename from the distribution host  node to the local host., where it is called local_filename   Local filenames are relative to the current working directory, remote filenames are local to dir.
status_code = updxfr_dir( node, dir, dist_filename, local_filename )
transfers a directory dist_filename from the distribution host  node to the local host., where it is called local_filename   Local filenames are relative to the current working directory, remote filenames are local to dir.

The updups module

This module contains routines to encapsulate ups on the local and the distribution (remote) host. Functions has as first argument the node name and port number (node:port). Local ups is used if passed node:port is localxxx or null.
Note: Some ups commands are only valid on local node.
status_code = updups_find( host:port, &instance_spec, component_1, component_2, ... )
Does a ups list to obtain the value for associated with the components in the product mentioned in instance_spec. The found values is returned in the passed instance_spec.
status_code = updups_depend( host:port, &instance_spec, &dependency_list )
Do a ups depend to determine what the dependencies on the product in the instance_spec are, which it returns in depenency_list. main::flags is examined for optional-dependency arguments.
status_code = updups_delcare( host:port, &instance_spec, add_args, db )
Do a ups declare in the local environment on database db, of instance_spec overridden with add_args.
status_code = updups_get( host:port, &instance_spec, &filename_list )
Does a remote ups get to obtain the location of files external to the product root.
status_code = updups_exist( host:port, &instance_spec, &exists )
Do a ups exist to determine if a given product instance exists.  Note that if the product exists but disagrees in terms of chains to the instance, this still returns true.

The updcgi module

This module contains the cgi scripts needed for the webserver node.

The updusr module

This module contains routines that are the user callouts to provide configuration flexibility.
status_code = updusr_getdb( &my_instance_spec, &top_instance_spec,  dist_node, dist_db )
Gets and stores (into my_instance_spec) the database into which the product should be declared.
status_code = updusr_get_unwind_proddir( &my_instance_spec, &top_instance_spec,  dist_node, dist_db )
Gets and stores (into my_instance_spec) the directory into which  the product files should be put.
status_code = updusr_get_declare_proddir( &my_instance_spec, unwind_dir )
On most platforms, simply returns unwind_dir (in my_instance_spec), but can modify it appropriately for systems where the place you unwind it is spelled differently than the place you declare it to be.
status_code = updusr_release_volume( dir )
On most platforms does nothing, but on AFS systems, runs an appropriate script to release a read/write volume to its read-only clones.
status_code = updusr_gettablefile( &my_instance_spec )
Gets and stores (into my_instance_spec) the location of the instance's table file.
status_code = updusr_getupsdir( &my_instance_spec )
Gets and stores (into my_instance_spec) the location of the instance's ups subdirectory.

The updchk module

This module contains routines that are used to check consistency and prerequisites.
 
status_code = updchk_prerequisite( distribution_node )
Checks that neccesary environment variables are present, and that distribution_node is valid.
status_code = updchk_depend( &local_depend_list, &dist_depend_list, fd )
Checks the dependency lists against each other, and prints any ups commands neccesary to make the local_depend_list
look like the dist_depend_list as far as chains.
status_code = updchk_manifest( prod_dir )
Looks for a $prod_dir/.manifest file, and if it finds one, checks it against the files actually there.
status_code = updchk_size( &instance_list )
Scans instance_list, determines what needs to be downloaded, how much space it would take in which filesystems, and whether it all fits.  (may not be completely implemented untill a later release).
status_code = updchk_instance_spec( &instance_spec, routine )
Checks the instance spec to make sure all of the necessary fields are filled in for the specified routine

The updui module

This module contains routines that interact with the user.   In the future, there will probably be a menu interface to upd here.
status_code = updui_prompt_proprietary( &instance_spec, &prop_info, &filename )
Prompts the user for a filename and special proprietary product fetch information  prop_info needed for instance_spec.

The updalg module

This module contains routines which algorithmically determine something important.
status_code = updalg_find_realproddir( &instance_spec, overlay, dependency_list, &path )
This routine finds where  to put instance spec.  if positive, overlay is an index into dependency_list indicating which product realproddir is an overlay on.
status_code = updalg_save(  realname )
This routine will eventuall save the file realname under a backup filename (something like $realname . ".bak") and take whatever clever steps are appropriate to keep the "right" backup file.  In the initial release, it does nothing.

The upderr module

This module contains error reporting code.
upderr_syslog( priority, format, ... )
Log messages to syslog().  Used to report errors of consequence to system managers, and system changes.
upderr_log( verbosity, format, ... )
Log messages to the user.  Verbosity is the level of verbosity that needs to be set to see the message.  Messages with verbosity of zero are always printed.
upderr_get( &string )
Collect messages reported so far with upderr_log().  Usually called by someone about to print the resulting string.
upderr_clear()
Will clear error stack
upderr_setverbose( verbosity )
Set the current verbosity level.

The updcmd module

This module contains the high level code to implement the various upd commands.
status_code = updcmd_install( &instance_spec, dist_node, dist_db, add_flags )
status_code = updcmd_update( &instance_spec, dist_node, dist_db )
status_code = updcmd_fetch( &instance_spec, dist_node, dist_db, filename )