(9844) Argument-Passing Documentation?

[User]

We are performing a quality assurance review of one of our legacy applications.
Specifically, we are looking at the proper use of OpenVMS system services. In
the System Service manual is is stated that service arguments within angle
brackets have a defaul
t. If an argument is optional, it should be described as such in the
explanatory text.

Our implementation language is Fortran.

We have always assumed that system service arguments documented with angle
brackets are "safe" to omit from the call. We have also assumed that trailing
commas in calls are safe to omit, ie the argument list may truncated at the
point where only empty arg
uments would remain in the list.

Now, do these assumptions hold true?

We are also confused by the two constructs

sys$service arg1,[arg2]

and

sys$service arg1 [,arg2]

The latter would indicate that it is safe to truncate the argument list, the
former that it is not.

[Wizard]

The argument-passing syntax involved here is entirely language-specific.
Fortran, in particular, passes in a zero value for an omitted argument
position. Other languages do not provide this, and expect that an
omitted argument must be passed.

The OpenVMS Wizard generally prefers to use an explicit specification
of all arguments, regardless of the language default behaviour. That
written, mandating this or otherwise enforcing this behaviour within a
compiler would have obvious and undesirable repercussions within the
existing source code base.

As for the second construct, your assumption that the argument list
can be truncated is entirely correct -- when the comma is within the
square brackets, the argument can be entirely omitted. When the
comma is outside the square brackets, an omitted argument must be
passed to the function as an explicit zero, or implicitly passed as
a zero through language-specific argument defaulting.


Assume the following OpenVMS documentation for a hypothetical routine
call; a hypothetical application programming interface (API):

FunctionOne( Arg1, [Arg2], [Arg3] )

In Fortran, the following are permitted:

FunctionOne( 5, , )
FunctionOne( 5, 0, 0 )

In C, the following is required

FunctionOne( 5, 0, 0 );

Notice the difference in the specification of the default arguments.
C requires the zero be specified in the argument, while Fortran can
provide it.

Now assume the following hypothetical API documentation:

FunctionTwo( Arg1, [Arg2] [, Arg3] )

In Fortran, the following are permitted:

FunctionTwo( 5, )
FunctionTwo( 5, , )
FunctionTwo( 5, 0, )
FunctionTwo( 5, 0, 0 )

In C, the following is required

FunctionTwo( 5, 0 );
FunctionTwo( 5, 0, 0 );

One subtle difference here: the called function FunctionTwo can
(choose to) determine the numbers of arguments passed, and can
then select and execute different codepaths based on the numbers
of arguments detected. (In C, please see the stdarg.h varargs
mechanisms.)

For details on this area of OpenVMS, please see the Programming
Concepts Manual and the Calling Standard Manual in the OpenVMS
documentation, and please see the language-specific documentation
for details of the language itself.

For the core discussion of common programming errors, please see
topic (1661) here in Ask The Wizard, as well as documentation and
topics referenced there.