ISKEY

Retrieve ISAM key information

xcall ISKEY(channel, keynum, status)

Arguments

channel

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

keynum

The number of the key about which information is to be returned. The primary key is 0, the first alternate key is 1, the second alternate key is 2, and so forth. If the key doesn’t exist, an “Illegal key specified” error ($ERR_BADKEY) occurs. (n)

status

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

Discussion

The ISKEY subroutine returns information about a specified key from the ISAM file that’s currently open on the specified channel. (See %ISINFO for additional status information.)

If the status variable is shorter than 90 characters, only the leftmost portion of the information is transferred. If status is longer than 90 characters, only its leftmost characters are filled and the remaining character positions are filled with blanks. Status is filled according to the rules for moving alpha data to an alpha destination. (See Assignment statements for a description of these rules.)

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.

The status information is returned as follows:

Status Information for ISKEY
Character position	Data type	Information
1 – 5	d5	Position of key
6 – 8	d3	Length of key
9	d1	Duplicates allowed flag (1 = duplicates, 0 = no duplicates)
10	d1	Ascending or descending flag (1 = ascending, 0 = descending)
11	d1	Modifiable flag (1 = modifiable, 0 = nonmodifiable)
12 – 26	a15	Name of key
27 – 66	8d5	Positions of segments
67 – 90	8d3	Lengths of segments

The first segment length of status is always nonzero. If the second segment length is nonzero, the key is segmented, and all remaining nonzero lengths represent the segmented keys.

Examples

The following example uses the ISKEY subroutine to retrieve information about the second alternate key in an ISAM file named demo.ism. The program then displays that information to the screen.

.define TTCHN                   ,1
.define ISMCHN                  ,2
.define MAX_KEYS                ,8
record keyinfo
    pos         ,d5
    len         ,d3
    dup         ,d1
    asc         ,d1
    mod         ,d1
    nam         ,a15
    spos        ,MAX_KEYS d5
    slen        ,MAX_KEYS d3
record
    seg         ,d1

proc
    open(TTCHN, o, "tt:")
    open(ISMCHN, i:i, "demo.ism")
  ;Request information about the second alternate key
    xcall iskey(ISMCHN, 2, keyinfo)
    writes(TTCHN, "Information on the key " + nam + ':')
    writes(TTCHN, nam + " start at char:  " + %string(pos))
    writes(TTCHN, nam + "'s length is:" + %string(len))
    if (dup.eq.1) then
      writes(TTCHN, "Duplicates are allowed")
    else
      writes(TTCHN, "No duplicates are allowed")
    if (asc.eq.1) then
      writes(TTCHN, nam + "is in ascending order")
    else
      writes(TTCHN, nam + "is in descending order")
    if (mod.eq.1) then
      writes(TTCHN, nam + "is modifiable")
    else
      writes(TTCHN, nam + "is not modifiable")
    for seg from 2 thru 8
      if (spos(seg).ne.0)
        begin
          writes(TTCHN, "Segment #" + %string(seg) + 
  &              " starts at " +  %string(slen(seg)) + 
  &              " and is " + %string(slen(seg)) + " long")
        end
    stop
end