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)
- Standard ups key words:
- product
- version
- flavor
- qualifiers
- chain - in some cases, this is the particular chain that got us this dependency (see
foundby).
- database
- prod_dir
- upsdir
- table_file
- table_dir
- archive_name
- product_root
- table_file
- ups_dir
- ups 'user key words':
- _upd_overlay - a 'user defined' key word for group of products
- upd internal key words:
- foundby - can be chain or version, indicating how we got this dependency.
- unwind_dir - directory to unwind product.
-
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 )