XSTAT

Get return value from last routine called

WSupported on Windows

USupported on Unix

VSupported on OpenVMS

NSupported in Synergy .NET

xcall XSTAT([return_value], [bit0], [severity], [message], [facility][, control])

Arguments

return_value

(optional) The variable that will be loaded with the return value of the last function or subroutine called. On OpenVMS, this argument is optional and corresponds to the full 32-bit return status value. It must be 10 digits wide to avoid overflow. (n)

bit0

(optional) A field that corresponds to the value of the low bit of the return value. (n)

severity

(optional) A field that corresponds to the value of bits 0 through 2 of the return value. (n)

message

(optional) A field (five digits wide to avoid overflow) that corresponds to the value of bits 3 through 15 of the return value. (n)

facility

(optional) A field (five digits wide to avoid overflow) that corresponds to the value of bits 16 through 27 of the return value. (n)

control

(optional) A field that corresponds to the value of bits 28 through 31 of the return value. (n)

Discussion

The XSTAT subroutine gets the return value from any of the following:

• The last non-Synergy DBL subroutine or function (including C functions, OpenVMS library routines, and so forth)
• The last Synergy DBL function of type ^VAL
• The last Synergy DBL subroutine that XRETURNed a return value

The return value from a user-defined subroutine that does not XRETURN a return value is one.

The return value from a Synergy DBL system-supplied subroutine or non-^VAL function is zero. The SPAWN and SHELL subroutines are exceptions to this rule.

• On Windows, SPAWN returns the exit status from the system call and SHELL returns the status of cmd.exe, not the program executed by cmd.exe.
• On Unix and OpenVMS, SPAWN and SHELL return the exit status from the system call, which is the return value from the shell.

On Synergy .NET, XSTAT is only supported after a call to SPAWN or SHELL.

On OpenVMS, any of the arguments to the XSTAT subroutine can be passed as null arguments.

Examples

The following example verifies an ISAM file and stops the program if the ISAM file is corrupt.

subroutine chkism
   a_file       ,a
record vfycmd
                ,a*, "isutl -v "
    vfile       ,a40
record
    rtnval      ,d1
proc
    vfile = a_file
    xcall spawn(vfycmd)
    xcall xstat(rtnval)
    if (rtnval)
      begin
        writes(TTCHN, "ISAM file " + vfile + " corrupt")
        xcall cleanup
        stop
      end
    xreturn
endsubroutine

The following example illustrates how to use XSTAT to retrieve the ^VAL return value from an external subroutine. This return value is an integer value of the natural integer size of the machine. (That is, for a 32-bit machine, it is an i4; for a 64-bit machine, it is an i8.) See Writing and calling subroutines and functions for additional information.

main
record
    retval      ,i4
proc
    xcall mult(3, 4)            ;Call mult subroutine
    xcall xstat(retval)         ;Retrieve the ^VAL return value
endmain
subroutine mult
    a_arg1      ,n
    a_arg2      ,n
record
    result      ,i4
proc
    result = a_arg1 * a_arg2
    xreturn result              ;Return the result as a ^VAL value
endsubroutine