GitArgGetStruct - Gets a structure argument value.

Function

Gets a structure argument value.

Description

This routine returns the id of an Sds structure which may be specified either directly as the argument to an action or as the name of an SDS file containing the structure.

If the argument system id is non-zero, points to an Sds structure and the structure name is not "ArgStructure", then the id of this structure is returned.

If the argument system id is non-zero and points to the an Sds item named "ArgStructure", the we try to find (by name or position), the requested item. If such an item is found and it is a Sds structure, the id of the item is returned. Otherwise, we interpet the value of the item an a filename and try to read the file. If the succeeds, then we return the id of the structure read from the file use SdsRead.

If we still don't have a value and defValue is non-zero, then it is treated as the name of a file which we read using SdsRead. The resulting Sds id is returned.

If we read the value from a file, the name of the file is returned in actName. Otherwise, the name of the structure is returned in actName.

Language

Call

(void) = GitArgGetStruct (id, name, position, defVal, actNameLen, actName, actValue 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.
>	defVal	Char `*`	If non-null, the default value. We try to read a file of this name.
>	actNameLen	int	Length of buffer pointed to by actName.
<	actName	Char `*`	If we read a file, the name of the file is written here. Otherwise, the name of the structure is written here.
<	actValue	SdsIdType `*`	The actual value is written here.
`!`	status	StatusType `*`	Modified status. If we have an error and no default was supplied, 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`	The argument value is invalid in some way.
`SDS__FOPEN`	We tried to read a file but file. Note that in this case actName will have the name of the file that we tried to open.

Include files

Git.h

External functions used

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
strcmp	`CRTL`	Compare one string to another
strncpy	`CRTL`	Copy one string to another.
SdsRead	Sds	Read an sds item from a file
SdsInfo	Sds	Obtain details of an Sds item.

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