ISSTS
Return status information about an ISAM file
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
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:
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