Design Document for unix support module

unix support module

AUTHOR: D. Lloyd

Functional Summary:

Support routines and module modifications to allow executables to be called from tae or unix.

Comments:

None

BACKGROUND:

In current production MKLEVEL1B needs to be called from stacking routines in c-code. The method utilized presently is 'ugly' to say the least, confusing and difficult to follow. To invoke MKLEVEL1B the c-code issues a system call to run a shell script which sets up a temporary pdf that calls the MK1B pdf eventually running the MKLEVEL1B executable. It was decided that a more straightforward approach was needed. This decision was to allow the MKLEVEL1B executable callable from tae or unix. This would allow the stacker code to simply make a system call to the MKLEVEL1B executable.

REQUIREMENTS:

    1. Executable must be callable from unix as well as tae
    2. Parameter specification on unix command line must have the same
       look and feel as tae parameters
    3. Modules will only have one local function getargv(), similar to the
       getpar() function we now utilize, that will call supports to parse the 
       command line and assign values to variables
    4. Support routines check for validity or parameter names
    5. Support routines check for valid argument sequence
    6. Support routines check for valid argument type
    7. Support routines check for valid argument array count
    8. Local getargv() checks for required parameters
    9. Local getargv() assigns default values for unspecified parameters
    10. Incomplete parameters names will be expanded to their full names
	if they are unique.


An example of a typical command line follows:

    mklevel1b -line [working_dir]inputfile com='Please mount 3490 tape'
    chans='1 2 3' 

The example specifies the subcommand LINE, a positional value for the
input file, a tape mount comment and channel specifications.  The
parameter name 'com' will be fully expanded to 'comment'.

Scope/Limitations:

    1. The following parameter cases will be the only ones supported:

	a) a positional value -- as long as name parameters haven't been
	    previously specified.
	b) a single string:  "infile=[test]in.l1b"
	c) two strings split after the equal sign: "infile=" "[test]in.l1b"
	d) two strings split before the equal sign: "infile" "=[test]in.l1b"
	e) three strings split at the equal sign: "infile" "=" "[test]in.l1b"

	This means that array elements must be delimited properly:

	    inchans = "1" "2" "3"

	will not be parsed correctly where:

	    inchans = "1 2 3"

	will.  This also means that the current design won't allow arrays
	of strings:

	    comment="mount tape 12345" "mount tape 54321"

    2. A subcommand specification must be placed immediately after the
	executable name, preceded by ' -' (space and a dash) such as:

	    mklevel1b -line

Overall Design

If the module is called by tae, do normal tae initialization and getpar() otherwise call getargv(). Getargv() will initialize a parameter structure, specific to the module. The unix command line, stored in argv[], is parsed and the parameter specifications are returned in a list. Variables are given values by extracting the right hand side of the proper specification. The variables are returned to the caller. Flow is then the same as for any other executable. Note: Other than the caller check and call to getargv(), the module will have to be linked with the notae.a library.

Flow diagram:

  • Figure 1 Unix support module Flow Diagram

    Module design ( getargv ):

    This function is described here as general information to the programmer. Its intent is to round out the description of this module. Getargv is akin to the getpar function is most LAS modules and provides the same functionality in a non-TAE environment. For an example of getargv see the MKLEVEL1B module. As with getpar, the purpose of getargv is to retrieve input parameters. However getargv gets the parameters from the unix command line through the variables: argv[] and argc.

    PARAMETERS:

    argc
    IN: argument count

    argv
    IN: argument list

    xxx
    OUT: application unique variables as necessary

    ALGORITHM:

    initialize the PARAMETER structure
    parse argv expanding and checking for name validity c_parsepar()
    extract and assign variable values from parsed list:
        c_getsval()         get string value
        c_getival()         get integral value(s)
        c_getival()         get integral value(s)
        c_getfval()         get floating point value(s)
    
    if values aren't specified but have defaults, assign defaults
    if required values don't have values return FAIL
    

    RETURN VALUE(S):

    E_SUCC success

    E_FAIL failure


    Module design ( c_parseargv ):

    Parse the argv[] variable by searching for valid parameter and subcommand names. If incomplete names are found they will be expanded. Return a list containing the subcommand and all input parameters coupled with their respective values.

    PARAMETERS:

    argc
    IN: argument count

    argv
    IN: argument list

    parmlist
    IN: list of valid parameter names

    scmdlist
    IN: list of valid subcommands or NULL

    list
    OUT: list of expanded parameters and values

    ALGORITHM:

    check for parameters: argc > 1 if not print usage and error out
        return FAIL
    
    if subcommands are defined check for subcommand in argv[1]: check_name()
    
    initialize array indices
    while there are arguments unparsed in argv
        determine which of five cases the argument falls into
        check the cases validity
        if invalid return FAIL
    
        switch on argument case
    	build complete parameter specification
    	update array indices
    
        extract the parameter name
        check that parameter name is valid: check_name()
        if invalid return FAIL
        expand the parameter name and put in output list
        copy parameter value to output list
    
    for each parameter specification
        check for proper type
        check for proper count
    
    return SUCC
    

    RETURN VALUE(S):

    E_SUCC success

    E_FAIL failure


    Module design ( check_name ):

    Search a list of valid names for a match to the input name. If a partial unique match is made, the name is expanded.

    PARAMETERS:

    str
    IN: string in question

    list
    IN: list of valid comparison strings

    numlist
    IN: number of strings in valid list

    name
    OUT: expanded matching name

    ALGORITHM:

    get str length and convert to lower case
    initialize count and index
    for each name in list
        if str matches a substring of list[i] save index and increment count
    
    if count does not equal 1 error (one and only one match allowed)
        return FAIL
    
    copy matching list string to name
    
    return SUCC
    

    RETURN VALUE(S):

    E_SUCC success

    E_FAIL failure


    Module design ( c_getsval ):

    Retrieve the string value(s) for a specified parameter from a parameter specification. Convert to lower case. If more than one value, return an array of strings.

    PARAMETERS:

    name
    IN: string value of parameter to look for

    list
    IN: list of strings to search

    value
    OUT: string value (RHS) of parameter

    ALGORITHM:

    search list for name
    if name is found
        locate RHS
        copy RHS to value
        return SUCCESS
    
    return FAIL
    

    RETURN VALUE(S):

    E_SUCC success E_FAIL failure

    Module design ( c_getival ):

    Retrieve integer value(s) for a specified parameter from a parameter specification. If more than one value, return an array of integers.

    PARAMETERS:

    valuestring
    IN: string of space delimited values

    max
    IN: maximum allowable count for parameter

    numspec
    OUT: number of values actually specified

    output
    OUT: array of values specified

    ALGORITHM:

    init numspec to zero
    while not done
        extract characters up to next delimiter
        convert characters to long
        numspec++
        if numspec > max return FAIL
        if no more characters to convert we are done
    return SUCCESS
    

    RETURN VALUE(S):

    E_SUCC success

    E_FAIL failure


    Module design ( c_getfval ):

    Retrieve floating point value(s) for a specified parameter from a parameter specification. If more than one value, return an array of floats.

    PARAMETERS:

    valuestring
    IN: string of space delimited values

    max
    IN: maximum allowable count for parameter

    numspec
    OUT: number of values actually specified

    output
    OUT: array of values specified

    ALGORITHM:

    init numspec to zero
    while not done
        extract characters up to next delimiter
        convert characters to long
        numspec++
        if numspec > max return FAIL
        if no more characters to convert we are done
    return SUCCESS
    

    RETURN VALUE(S):

    E_SUCC success

    E_FAIL failure