GitArgGetS - Gets a string argument value with checking against acceptable values.

Function

Gets a string argument value with checking against acceptable values.

Description

Assumes "id" is an Sds Structure item containing the required argument and "name" if the name of the argument.

If "values" is non-zero, then it is an array of acceptables values. If the actual value is not in this array, then status is set to GIT__ARGVAL.

If "defVal" is non-zero, then if there is any error in getting the value, including its value not being acceptable, the actual value is it to that specified by "defVal" and status will be reset to OK, (see flags arguments to change the effect on status).

Language

Call

(void) = GitArgGetS (id, name, position, values, defVal, flags, actValLen, actValue, index, status)

Parameters

(">" input, "!" modified, "W" workspace, "<" output)

>	id	SdsIdType	Id of the argument system.
>	name	Char `*`	Name of the argument to get
>	position	int	The position of the argument. This is used if "name" is a null pointer, an empty string or if we can't find an `SDS` structure item of that name.
>	values	Char `*`{[]}	If non-null, array of pointers to the possible values. Terminate with 0.
>	defVal	Char `*`	If non-null, the default value. Note, this value is `NOT` validated against the values array.
>	flags	Int	A bit-mask of flags. Possible values are

`GIT_M_ARG_UPPER`	Convert value to upper case.
`GIT_M_ARG_LOWER`	Convert value to lower case.
`GIT_M_ARG_KEEPERR`	If we use the default value, return the error which caused it to be taken. (If we don't have a default value, then we return the error).
`GIT_M_ARG_ABBREV`	Allow abbreviations. The minimum abbreviation is 2 characters. The first value in the "values" array which is correct to length of the supplied value is used. The full length value is copyied from "values" to actValue.
`GIT_M_ARG_KEEPVALERR`	Only retain the error if we found the item (and its value was in error). If we did not find the item, then return status ok and the default.

>	actValLen	Int	Length of actValue
<	actValue	Char `*`	The actual value is written here.
<	index	Int `*`	If non-null - if we found a value in the values array, this is the index to that value. Otherwise, it is set to -1.
`!`	status	StatusType `*`	Modified status. If we have an error and `GIT_M_ARG_KEEPERR` is true then a message is reported using {\tt ErsRep} and status is set. In addition to error codes from the underlying Arg and Sds routines, one of the following may be returned

`GIT__NOARG`	The argument id is zero or no item was found. Will not be returned if `GIT_M_ARG_KEEPVALERR` flag is set, in that case, just return the default with status ok.
`GIT__ARGVAL`	Invalid argument value, not one of those specified in the values array.

Include files

Git.h

External functions used

SdsFreeId	Sds	Free and Sds Id.
ArgGetString	Arg	Get an argument value
ErsRep	Ers	Report an error.
ErsPush	Ers	Increase error context
ErsPop	Ers	Decreate error context
ErsAnnul	Ers	Annul error messages
islower	`CRTL`	Determines if a character is lower case.
isupper	`CRTL`	Determines if a character is upper case.
toupper	`CRTL`	Convert a character to upper case.
tolower	`CRTL`	Convert a character to lower case.
strcmp	`CRTL`	Compare one string to anoterh
strncpy	`CRTL`	Copy one string to another.

External values used

none

Prior requirements

As above

Support

Tony Farrell, AAO

Click here for the DRAMA home page and here for the AAO home page.

For more information, contact tony.farrell@mq.edu.au