Output lines describe the values (arguments) returned from the external routine, and the way in which the external routine passes the values to GT.M. Each output line corresponds to an output argument. The order of the output lines determines the order in which variables appear in the returned result, which is a comma-delimited string. The number of output lines in a zcentry must equal the number previously specified by the OUTPUTS keyword in the routine line. If the OUTPUTS keyword in the routine line defaults or is set to zero (0), the zcentry should contain no output lines. Output lines must follow the input lines.

The format for the output line is:

	OUTPUT outkeyword=value [, ... ]
	Valid outkeywords:
	* MECHANISM = REFERENCE | DESCRIPTOR
	* POSITION = number
	* TYPE = DOUBLE | FLOATING | G_FLOATING | 
	 H_FLOATING | LONG | QUAD | STRING | 
	 BYTE | BYTEU | WORD | WORDU | LONGU
	[QUALIFIER =] REQUIRED | DUMMY | PREALLOCATE
	VALUE = number	
	

( *) - Denotes required keyword

Use multiple output lines when the external routine returns more than one value. External calls return multiple values as a concatenated string separated by commas.

Output line keywords and their values must appear on a single MACRO line. MACRO lines may be continued by terminating them with a dash.

If the return line specifies CLASS=VALUE, an external call returns the contents of the return register(s) as the first element of the output string. If the return line specifies a CLASS other than VALUE, the first element in the output string corresponds to the first output line; thus, return CLASSes other than VALUE do not contribute to the external call output string. Except for the optional first value contributed by the return line, the order of the output lines determines the position of all values returned in the output string.

The TYPE keyword specifies the data type of the output argument. The table in the previous section on the Return line lists all external call data types supported by GT.M.

The MECHANISM keyword specifies the mechanism by which the external routine passes the output values to GT.M. MECHANISM accepts keywords that specify two types of passing mechanisms: REFERENCE or DESCRIPTOR.

The "Important Considerations for External Calls" section discusses these mechanisms in more detail.

The POSITION keyword in each output line specifies the place of that output 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 receive the returned elements in any order, connecting between each returned element and the appropriate argument in the external routine parameter list. For example, to specify that the third argument in the external routine parameter list should appear as the first element in the comma-delimited string returned by the external routine, place position=3 in the first output line.

The VALUE keyword specifies amount of space to PREALLOCATE for the return string. The VALUE is an integer that designates the number of characters.

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 results in a run-time error. POSITION specifications for output lines must not overlap. Overlapping is explained further in a separate section in this chapter.

The following table shows an example of how arguments in an external call align.

* If the return line specifies CLASS=VALUE, the value of the return register(s) is placed in out1. This is often the status but can be otherwise: the mathematics library routines, for example, pass the answer back in the return register(s). It may often be desirable to return the status as a value from the called program for checking by the calling M routine. Otherwise, if status=error, the program will behave as if an error occurred; that is, will stop, invoking $ZTRAP. For information on $ZTRAP and error processing, refer to the "Error Processing" chapter in this manual.

The set of POSITION numbers constitutes a numeric sequence from one (1) to the total number of arguments to the external routine with no gaps. The external call always places the RETURN VALUE first in the output string.

The QUALIFIER keyword specifies qualifiers for the output arguments of the external routine. The qualifiers are mutually exclusive. By default, the output line uses a QUALIFIER of REQUIRED.

An output line may specify a qualifier keyword alone, rather than as the argument to the QUALIFIER keyword.

The following table lists the output qualifier keywords.

Example:

	zcinit
	routinecallname=lexp, linkname=lexp, output=3
	returnclass=value, type=long
	outputposition=1, mechanism=reference, type=long, -
	 qualifier=required
	outputposition=2, mechanism=reference, type=long, -
	 qualifier=dummy
	outputposition=3, mechanism=descriptor, type=strin g, -
	 qualifier=preallocate, value=255
	zcallfin
	.end
	

This illustrates the use of each output qualifier. The output string from this call would have the return value as the first piece, output line 1 as the second piece, and output line 3 as the third piece. Because the output line 2 specifies a QUALIFIER of DUMMY, it does not contribute to the output string. The hyphen (-) in the last position of the line, for example, at the end of the second output line, acts as a line continuation in MACRO. For a further explanation of the PREALLOCATE qualifier, refer to the "Important Considerations for External Calls" section of this chapter.