#! /bin/sh
#
# lpsshfuncs -- Common shell functions for LPS support scripts
#
# @(#)lpsshfuncs	1.12	LPS_UNX_COM	02/19/95
#
# Copyright 1994   Digital Equipment Corporation, Maynard, MA
#
# DESCRIPTION:
#
# This file contains common Bourne shell functions used by many
# of the PrintServer support scripts.
#
# This script expects that the common kit variables have already
# been defined and exported.
#
# FUNCTION LIST:
#    checknumrange
#    choose
#    clearobjvars
#    expkitvars
#    expobjvars
#    getlevel
#    getobject
#    getpath
#    mkoldobjvars

# ---------------------------------------------------------------------------

# checknumrange()
#
# Function to validate a positive integer (usually input from the user),
# handling range checking and a default response value.
#
# Parameters:
#    $1 - Lower range value
#    $2 - Upper range value
#    $3 - Default value
#    $4 - Numeric string
#
# Returns the resolved numeric value in $RESPONSE.
#
# If the numeric string is valid, 0 is returned; otherwise 1 is returned
# to indicate an invalid string.
#
checknumrange ()
{
    lower=$1
    upper=$2
    def=$3
    val="$4"

    RESPONSE=""

    if [ "`echo $val | cut -c1`" = "-" ]
    then
	return 1
    elif [ -z "$val" ]
    then
	RESPONSE="$def"
	return 0
    elif [ "`echo $val | $TR -d '0123456789'`" ]
    then
	return 1
    elif [ $val -lt $lower -o $val -gt $upper ]
    then
	return 1
    else
	RESPONSE="$val"
	return 0
    fi
}

#----------------------------------------------------------------------

# choose()
# 
# A shell function to request the selection of an element from a list,
# with default response capability.  The parameter list is variable, based
# on the number of list elements:
#
#    $1 - Default element string if the user enters a null response.
#    $2 - The question (prompt) string.
#    $3 - The first list element string.
#    $4 - The second list element string.
#    ...
#    $n - The last list element string.
#
# This function is cheap, as it doesn't handle more than 9 list elements.
#
# The resulting response is stored in the utility shell variable $RESPONSE.
# The return value is 0 if a non-default element was entered, or 1 if the
# default response was selected by the user.

choose ()
{
    # First save and shift away the default response and question strings,
    # resulting in the parameter set consisting only of the element list.

    default=$1
    shift
    question=$1
    shift
    count=$#
    list=$@

    # Display the question and the corresponding list of element options,
    # then solicit a response from the user.
    #
    # While the element list is being displayed, each element is compared
    # to the default response in order to capture the element list index of
    # the default response.

    defindex=-987	# Bizarre, unlikely default value
    defresp=" []"
    i=1

    echo
    echo "$question?"
    echo "    Possible responses are:"

    for elem in $list
    do
	if [ "$default" = "$elem" ]
	then
	    defindex=$i
	    defresp=" [$i]"
	fi
	echo "	$i) $elem"
	i=`expr $i + 1`
    done

    while true
    do
	$ECHON "Enter a number from the above list${defresp}: "
	read resp

	if checknumrange 1 $count "$defindex" "$resp"
	then
	    if [ "$RESPONSE" = "$defindex" ]
	    then
		RESPONSE="$default"
		return 1
	    else
		RESPONSE=`echo $list | cut "-d " -f$resp`
		return 0
	    fi
	fi
    done
}

#----------------------------------------------------------------------

# clearobjvars()

# Shell function to clear all variables associated with a particular
# object type (class).
#
# Parameters:
#    $1 - The object type (class) identifier (eg, "ENV", "PC")
#    $2 - Flag parameter indicating the "OLD" object variables
#	  should also be cleared (eg: OLDPC_xxx); this parameter
#	  can be any non-null value to effect the clearing of
#	  the old variables.
#
# Return value is always 0, implying success.

clearobjvars ()
{
    cprefix=$1
    flag="$2"

    for var in `set | sed -n -e "s/^\(${cprefix}_.*\)=.*/\1/p"`
    do
	eval $var=""

	if [ "$flag" ]
	then
	    eval OLD$var=""
	fi
    done

    return 0
}

#----------------------------------------------------------------------

# expkitvars()

# Shell function to export all common kit variables.  With the exception of
# incredibly simple, independent scripts that do not invoke any subscripts,
# all scripts will typically invoke this script very near the beginning of
# execution.
#
# The variables exported here essentially define the set of all variables
# that are expected to be available to any kit script.
#
# See the "setkitvars" script for details about how this function works
# with global shell variables.
#
# This function expects the current working directory is either LPSROOT
# or LPSKIT.
#
# Parameters:
#    -none-
#
# Return value is always 0, implying success.

expkitvars ()
{
    . scripts/expkitvars

    return 0
}

#----------------------------------------------------------------------

# expobjvars()
#
# Parameters:
#    $1 - The object type (class) identifier (eg, "ENV", "PC")
#
# Return value is always 0, implying success.

expobjvars ()
{
    cprefix=$1

    for var in `set | sed -n -e "s/^\(${cprefix}_.*\)=.*/\1/p"`
    do
	export $var
    done

    return 0
}

#----------------------------------------------------------------------

# getlevel()
#
# This function is used to obtain a logging or debug level from the
# user.  The resulting value is returned in $RESPONSE.
#
# Parameters:
#    $1 - The default level value
#    $2 - Brief description of the level
#
# Return value is always 0, implying success.

getlevel ()
{
    deflvl=$1
    desc="$2"

    echo
    question="$desc level (0-9, [${deflvl}])? "
    while true
    do
	$ECHON "$question"
	read RESPONSE
	if checknumrange 0 9 $deflvl "$RESPONSE"
	then
	    return 0
	else
	    question="Please enter a number between 0 and 9 [${deflvl}]: "
	fi
    done
}

#----------------------------------------------------------------------

# getobject()
#
# This function is used to get all attributes of an existing object in
# the LPS Object Database and import their values into regularly named
# global variables based on the class name.
#
# Parameters:
#    $1 - Inherit values from the Environment object ("true" or "false")
#    $2 - Class identifier, one of {ENV, PS, PC, MC}.
#    $3 - The name of the object (for any class *other than* ENV)
#
# Return value is 0 if successful; otherwise, badodb is called to
# signal the end of the script, or 1 is returned if the parameters
# are incorrect.

getobject ()
{
    if $1
    then
	inherit=""
    else
	inherit="-I"
    fi

    case "$2" in
	ENV ) class="-e" ; name="" ;;
	MC  ) class="-m" ;;
	PC  ) class="-p" ;;
	PS  ) class="-s" ;;
	  * ) echo "getobject: Invalid class identifier: $2"
	      return 1 ;;
    esac

    name="$3"

    varfile=$TMPDIR/lpsodb.$$
    odberrs=$TMPDIR/odberrs.$$

    if $LPSODBLIST -f $LPSODB $inherit -B $class $name > $varfile 2> $odberrs
    then
	:
    else
	badodb $odberrs
	return   # Use badodb's return value
    fi

    . $varfile   # Import the global variables created by $LPSODBLIST

    rm -f $varfile $odberrs

    return 0
}

#----------------------------------------------------------------------

# getpath()
#
# A shell function to request and return a path specification, with crude
# and restrictive path spec validation.  The function will not return until
# an absolute path spec is entered by the user.
#
# Parameters:
#    $1 - The access type, one of the single letters used for determining
#	  path access with /bin/test (eg, "d", "r", etc).  The character
#	  "z" can be specified if path verification should not be done; if
#	  the "z" parameter is specified, then whatever the user enters is
#	  stored in $RESPONSE and the return value will be 0.  Alteratively,
#	  the character "Z" can be used to both imply "z" *and* have the
#	  the resulting RESPONSE value be set to null (see below).
#    $2 - Default path string if the user enters a null response.
#    $3 - The response prompt (question), with no trailing punctuation.
#
# If the user selects the default path, then no path spec validation is
# performed.
#
# The resulting response is stored in the utility shell variable $RESPONSE,
# whether it's a string entered from the user or the default response.
#
# The return value is 0 if a path was actually entered, or 1 if the
# default response was selected by the user.  If the access type is "Z",
# then the return value will be 2 (and $RESPONSE set to null) if the
# user signals an EOF (via CTRL/D or equivalent).

getpath ()
{
    acctype="$1"
    defpath="$2"
    prompt="$3"

    if [ "$acctype" = "Z" ]
    then
	catcheof=true
	acctype="z"
    else
	catcheof=false
    fi

    while true
    do
	echo
	$ECHON "$prompt [$defpath]? "

	if read resp
	then
	    eofseen=false
	else
	    eofseen=true
	fi

	if [ -z "$resp" ]	# Default selected?  Set and return.
	then
	    if $eofseen && $catcheof
	    then
		RESPONSE=""
		return 2
	    else
		RESPONSE=$defpath
		return 1
	    fi
	fi

	# Perform a basic, crude path string validation, where the
	# string must represent an absolute pathname consisting of
	# characters from a "reasonable" character set.

	if [ "$OSTYPE" = "OSF1" -o "$OSTYPE" = "BSD" ]
	then
	    leftovers=`echo $resp | $TR -d 'A-Za-z0-9\-_./'`
	else
	    leftovers=`echo $resp | $TR -d '[A-Z][a-z][0-9]-_./'`
	fi

	if [ "$leftovers" ]
	then
	    echo
	    echo "Sorry, but \"$resp\" is not a valid path.  Please use"
	    echo 'only characters from the set:  A-Z a-z 0-9 - _ . /'
	    echo "Please try again."
	    continue
	elif [ "`echo $resp | cut -c1`" != "/" ]
	then
	    echo
	    echo "Sorry, but you must enter an absolute path."
	    echo "Please try again."
	    continue
	fi

	# Perform a check for the path, if requested; otherwise return.

	if [ "$acctype" = "z" ]
	then
	    RESPONSE=$resp
	    return 0
	elif pathcheck $acctype "$resp"
	then
	    RESPONSE=$resp
	    return 0
	fi
    done
}

#----------------------------------------------------------------------

# mkoldobjvars()

# Shell function to clear all variables associated with a particular
# object type (class).
#
# Parameters:
#    $1 - The object type (class) identifier (eg, "ENV", "PC")
#
# Return value is always 0, implying success.

mkoldobjvars ()
{
    cprefix=$1

    for var in `set | sed -n -e "s/^\(${cprefix}_.*\)=.*/\1/p"`
    do
	eval OLD$var="\$$var"
    done

    return 0
}

#----------------------------------------------------------------------

#
# Local Variables:
# page-delimiter:"^#---"
# fill-column:75
# End:
