ISSTS

Return status information about an ISAM file

xcall ISSTS(channel, status)

Arguments

channel

The channel on which the ISAM file is open. (n)

status

The variable that will be loaded with status information about the file. The format of this information is shown in the Status Information for ISSTS table. (n)

Discussion

The ISSTS subroutine returns status information about the ISAM file that is currently open on the specified channel. (See %ISINFO for additional status information.)

The channel must be open to an ISAM file.

The following error conditions are possible:

If the channel is not open, a “Channel has not been opened” error ($ERR_NOOPEN) is generated.
If the channel is open but is associated with a non-ISAM file, a “Not an ISAM file” error ($ERR_NOTISM) is generated.
If the number of keys exceeds 99, an “Illegal key specified” error ($ERR_BADKEY) is generated. You can trap this error, in which case the number of keys is set to 0. Use the %ISINFO function to access the correct number of keys.

Although 31 characters of status information can be returned, status can be as long as you want. If status is shorter than 31 characters, ISSTS fills the buffer with as much information as will fit. (For example, if status is 20 characters, ISSTS returns the first 20 characters of status information.) If status is longer than 31 characters, only its leftmost characters are filled. Status is filled according to the rules for moving alpha data to an alpha destination. (See Moving alpha data to an alpha destination for a description of these rules.)

The status information is returned as follows:

Status Information for ISSTS
Character position	Data type	Information
1 – 5	d5	Maximum length of data records
6 – 10	d5	Position at which the primary key field starts
11 – 13	d3	Length of primary key field
14 – 21	d8	Approximate capacity of files (in records)
22 – 29	d8	Number of unused records
30 – 31	d2	Total number of primary and alternate keys

Positions 14 through 21 are filled with nines (“99999999”).

If the total number of records meets or exceeds 99,999,999, the number of unused records (positions 22–29) returns 0. Use the %ISINFO function to access the correct number of records.

On OpenVMS, positions 22 through 29 are filled with “09999999”.

With Synergy ISAM, you can calculate the number of records by subtracting the number of unused records from the approximate capacity, as shown in the example below. On OpenVMS, the number of records actually contained in an RMS indexed file cannot be determined without reading the entire file and counting the records.

Examples

The example below uses the ISSTS subroutine to retrieve the current status of an ISAM file called demo.ism and then displays that information to the screen.

.define TTCHN           ,1
.define ISMCHN          ,2
record status
    reclng              ,d5
    keystart            ,d5
    keylng              ,d3
    recsmax             ,d8
    recsleft            ,d8
    numkeys             ,d2
record
    recs                ,d8
proc
    open(TTCHN, i, "tt:")
    open(ISMCHN, i:i, "demo.ism")
    xcall issts(ISMCHN, status)
    writes(TTCHN, "Data record length:   " + %string(reclng))
    writes(TTCHN, "Key starts at char:   " + %string(keystart))
    writes(TTCHN, "Key length is:        " + %string(keylng))
    recs = recsmax - recsleft
    writes(TTCHN, "Total records in file:" + %string(recs))
    writes(TTCHN, "Number of keys:       " + %string(numkeys))
    stop
end