Passes the value of the external routine argument by referencing the address of a VMS descriptor. A VMS descriptor is a defined data structure that describes the characteristics of a datum, including the address and size of the datum. This mechanism is required to pass string data; you may also select it to pass other types.

For more information on the VMS Procedure Calling and Condition Handling Standard, refer to the OpenVMS Calling Standard manual.

The POSITION keyword in each input line specifies the place of that input argument in the external routine parameter list. The value of this keyword must be between one (1) and the total number of arguments to the external routine. The POSITION keyword allows you to place the invocation arguments in any order, then to connect between each invocation argument and the appropriate argument in the external routine parameter list. For example, by specifying position=3 in the first input line, you connect between the first argument in the M external invocation and the third argument in the external routine parameter list.

The positions specified by the input and output lines may overlap, meaning that the same variable in the external routine parameter list is used for both input and output. When overlapping POSITION specifications between input and output lines, make sure the MECHANISMs and TYPEs in the two lines are compatible. Incompatibility will result in an error. POSITION specifications for any two input lines must not overlap. Overlapping is explained further in a separate section in this chapter.

The QUALIFIER keyword specifies qualifiers for the input arguments of the external routine. The qualifiers are mutually exclusive. By default, the input line uses a QUALIFIER of REQUIRED. An input line may specify a qualifier keyword alone, rather than as the argument to the QUALIFIER keyword.

The following table lists the input qualifier keywords.

DEFAULT, OPTIONAL, and OPTIONAL_0 arguments may appear in any order in the external call argument list by specifying a null argument. Null arguments are denoted with two successive commas, or a comma and a right parenthesis to indicate the end of the list. If the number of input lines exceeds the number of arguments to the external call, the function treats the remainder of the arguments as null.

The following example illustrates how the misuse of optional arguments can lead to run-time or logical errors.

Example:

External call table:

	zcinit
	routinecallname=lexp, linkname=lexp, inputs=2
	returnclass=value, type=long
	inputposition=1, mechanism=value, type=long, qualifier=optional
	inputposition=2, mechanism=value, type=long, qualifier=required
	zcallfin
	.end		
	

External routine:

	void lexp(a, b)
	long a,b;
	{
	...
	}	
	

Using the definitions in the example, DO &lexp(,1) calls lexp, passing 1 as input a, and nothing as input b. Specifying a null argument for an OPTIONAL input, as in the sample external call above, means that the call passes nothing for that input, and effectively shifts the rest of the argument list "left" into the "empty" spot. Misuse of optional arguments can cause errors in the external routine.

OPTIONAL arguments should appear after all other arguments in the external call argument list. Any external call using a zcentry that does not observe this precaution must supply all optional arguments to avoid run-time or logical errors.

The VALUE keyword specifies a value that external call passes as a constant or default for the input argument depending on whether the QUALIFIER specifies CONSTANT or DEFAULT. The value can be a number or string.

If the value is a MACRO special character, enclose the character in angle brackets (< >). For a list of special characters, refer to the MACRO-64 Assembler for OpenVMS AXP Systems manual. Enter an empty pair of angle brackets to specify a null string as a value.

Because it only applies to the CONSTANT and DEFAULT qualifiers, the VALUE keyword is optional.

Example:

	zcinit
	routinecallname=lexp, linkname=lexp, inputs=2,
	returnclass=value, type=long
	inputposition=1, mechanism=value, type=long, -
	 qualifier=default, value=5
	inputposition=2, mechanism=value, type=long, -
	 qualifier=constant, value=2
	zcallfin
	.end		
	

The hyphen (-) in the last position of the line, for example, at the end of both input lines, acts as a line continuation in MACRO. Using the above example, DO &lexp() would call the external routine lexp with a longword containing five (5) and a longword containing two (2). The DEFAULT qualifier on the first input line specifies that if the external call supplies no corresponding argument, it passes the VALUE, in this case five (5). The CONSTANT qualifier on the second input line indicates that the external argument has no corresponding argument in the external call. In this case, the external call always passes the VALUE, (2), to the external routine.