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

C

Call

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

Parameters

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

>idSdsIdTypeId of the argument system.
>nameChar *Name of the argument to get
>positionintThe 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.
>valuesChar *{[]}If non-null, array of pointers to the possible values. Terminate with 0.
>defValChar *If non-null, the default value. Note, this value is NOT validated against the values array.
>flagsInt 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 tasken.
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.

>actValLenIntLength of actValue
<actValueChar *The actual value is written here.
<indexInt *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.
!statusStatusType *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.
GIT__ARGVAL Invalid argument value, not one of those specified in the values array.

Include files

Git.h

External functions used

SdsFreeIdSds Free and Sds Id.
ArgGetStringArg Get an argument value
ErsRepErs Report an error.
ErsPushErs Increase error context
ErsPopErs Decreate error context
ErsAnnulErs Annul error messages
islowerCRTL Determines if a character is lower case.
isupperCRTL Determines if a character is upper case.
toupperCRTL Convert a character to upper case.
tolowerCRTL Convert a character to lower case.
strcmpCRTL Compare one string to anoterh
strncpyCRTL 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 tjf@aao.gov.au