graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPQARF - Inquire Archive Files

GPQARF (start, number, buflen, errind, actnum, totnum, arlist, termcond)

Note:

This subroutine is an Archive inquiry. For an overview, see "Archive Inquiries"

Purpose

Use GPQARF to inquire a list of open archive files.

If the current archive state is archive closed (ARCL), then the graPHIGS API returns a value of zero for the total number of open archive files ( totnum).

If the inquired information is available, then the graPHIGS API sets the error indicator to zero and returns the values in the output parameters. If the error indicator is 543 (the start value exceeds the extent of the available data), then only the total number (totnum) parameter is set. If the inquired information is unavailable, then the error indicator (errind) contains an error number indicating the reason, and the values returned in the output parameters are unpredictable.

Parameters

start -- specified by user, fullword integer

The starting member in the list of structure identifiers (>=1)

number -- specified by user, fullword integer

Number of entries requested (>=0)

buflen -- specified by user, fullword integer

Length, in bytes, of the data area specified by the arlist parameter into which the graPHIGS API returns the archive file names (>=0)

errind -- returned by the graPHIGS API, fullword integer

Error indicator. If the error indicator is zero, the request has been completed. Otherwise, one of the following errors exists:

538: START VALUE < ONE
539: REQUESTED NUMBER < ZERO
543: START EXCEEDS DATA EXTENT. TOTAL NUMBER AVAILABLE RETURNED
577: BUFFER LENGTH IS < ZERO

actnum -- returned by the graPHIGS API, fullword integer

Total number of archive file names returned.

totnum -- returned by the graPHIGS API, fullword integer

Total number of open archive files.

arlist -- returned by the graPHIGS API, variable data

List of entries for the requested archive files. The value of each field is expressed in the following data format:

        --------------
        |  entry 1   |
        |------------|
        |  entry 2   |
        |------------|
        Z            Z
        |            |
        |------------|
        |  entry n   |
        | (n=actnum) |
        --------------

where each entry has the following format:

        -----------------
      0 |length of entry| Fullword integer
        |---------------|
      4 |archive file id| Fullword integer
        |---------------|
      8 |  length of    | Fullword integer
        |  descriptor   |
        |---------------|
     12 |  descriptor   | Character data
        -----------------

The graPHIGS API pads each archive file descriptor with blanks to align the next length field on a fullword boundary.

termcond -- returned by the graPHIGS API, fullword integer

Termination condition. The graPHIGS API terminated the list of archive file names due to one of the following reasons:

1- Count Exhausted

The graPHIGS API returned the requested number of archive file names.

2- Buffer Overflow

The graPHIGS API count not return the requested number of elements because there was not enough room in the area provided. actnum contains the actual number returned.

3- End of List of Archive Files

The graPHIGS API reached the last archive file in the list. This condition supercedes the Count Exhausted condition (if that condition was in effect). The total number of archive files returned may not be equal to the number of returned archive files you requested. Check actnum to find the actual number of archive files returned.

Error Codes

None

Related Subroutines

None

RCP code

201336338 (X'0C002612')