Retrieving location with the POS call (for DEDB only)

Use the POS (Position) call to retrieve the location of a specific sequential dependent segment; retrieve the location of the last-inserted sequential dependent segment, its time stamp, and the IMS ID; or retrieve the time stamp of a sequential dependent or Logical Begin. You can also use the POS call to tell the amount of unused space within each DEDB area. For example, you can use the information that IMS returns for a POS call to scan or delete the sequential dependent segments for a particular time period.

The topic "POS Call" in IMS Version 15 Application Programming APIs explains how you code the POS call and what the I/O area for the POS call looks like. If the area that the POS call specifies is unavailable, the I/O area is unchanged, and the FH status code is returned.

Locating a specific sequential dependent

When you have position on a particular root segment, you can retrieve the position information and the area name of a specific sequential dependent of that root. If you have a position established on a sequential dependent segment, the search starts from that position. IMS returns the position information for the first sequential dependent segment that satisfies the call. To retrieve this information, issue a POS call with a qualified or unqualified SSA containing the segment name of the sequential dependent. Current position after this kind of POS call is the same place that it would be after a GNP call.

After a successful POS call, the I/O area contains:

LL: A 2-byte or 4 byte field giving the total length of the data in the I/O area. When the number of DEDB areas is 2048 or fewer, the LL is 2-byte field. When the number of DEDB areas is greater than 2048, the LL is 4-byte field.
Area Name: An 8-byte field giving the ddname from the AREA statement.
Position: An 8-byte field containing the position information for the requested segment.
Exception: If the sequential dependent segment that is the target of the POS call is inserted in the same synchronization interval, no position information is returned. Bytes 11-18 contain X'FF'. Other fields contain normal data.
Unused CIs: A 4-byte field containing the number of unused CIs in the sequential dependent part.
Unused CIs: A 4-byte field containing the number of unused CIs in the independent overflow part.

Locating the last inserted sequential dependent segment

You can also retrieve the position information for the most recently inserted sequential dependent segment of a given root segment. To do this, you issue a POS call with an unqualified or qualified SSA containing the root segment as the segment name. Current position after this type of call follows the same rules as position after a GU call.

You can also retrieve the position of the SDEP, its time stamp, and the ID of the IMS that owns the segment. To do this, you issue a POS call with a qualified SSA and provide the keyword PCSEGTSP in position one of the I/O area as input to the POS call. The keyword requests the POS call to return the position of the SDEP, its time stamp, and the ID of the IMS that owns the segment.

Requirement: The I/O area must be increased in size to 42 bytes to allow for the added data being returned. The I/O area includes a 2-byte LL field that is not shown in the following table. This LL field is described after the following table.

Table 1. Qualified POS call: keywords and map of I/O area returned
Keyword	word 0	word 2	word 4	word 5	word 6	word 8
<null>	Field 1	Field 2	Field 3	Field 4	N/A	N/A
PCSEGTSP	Field 1	Field 2	Field 5		Field 6	Field 7
Field 1 Area name Field 2 Sequential dependent location from qualified SSA Field 3 Unused CIs in sequential dependent part Field 4 Unused CIs in independent overflow part Field 5 Committed sequential dependent segment time stamp Field 6 IMS ID Field 7 Pad

After a successful POS call, the I/O area contains:

LL

(Not shown in table) A 2-byte field, in binary, containing the total length of the data in the I/O area.

(Field 1)

Area Name: An 8-byte field giving the ddname from the AREA statement.

(Field 2)

Position: An 8-byte field containing the position information for the most recently inserted sequential dependent segment. This field contains zeros if no sequential dependent exists for this root.
Sequential dependent location from qualified SSA: IMS places two pieces of data in this 8-byte field after a successful POS call. The first 4 bytes contain the cycle count, and the second 4 bytes contain the VSAM RBA.
If the sequential dependent segment that is the target of the POS call is inserted in the same synchronization interval, no position information is returned. Bytes 11-18 contain X'FF'. Other fields contain normal data.

(Field 3)

Unused CIs in sequential dependent part: A 4-byte field containing the number of unused control intervals in the sequential dependent part.

(Field 4)

Unused CIs in independent overflow part: A 4-byte field containing the number of unused control intervals in the independent overflow part.

(Field 5)

Committed Sequential Dependent Segment Time Stamp: An 8-byte field containing the time stamp that corresponds to the SDEP segment located by the qualified POS call.

(Field 6)

IMS ID: Identifies the IMS that owns the CI where the SDEP segment was located.

(Field 7)

Pad: An 8-byte pad area to align the I/O area on a double word boundary. No data is returned to this field.

Identifying free space

To retrieve the area name and the next available position within the sequential dependent part from all online areas, you can issue an unqualified POS call. This type of call also retrieves the unused space in the independent overflow and sequential dependent parts.

After a unsuccessful unqualified POS call, the I/O area contains the length (LL), followed by the same number of entries as existing areas within the database. Each entry contains the fields shown below:

Area Name: An 8-byte field giving the ddname from the AREA.
Position: An 8-byte field with binary zeros.
Unused SDEP CIs: A 4-byte field with binary zeros.
Unused IOV CIs: A 4-byte field with two binary zeros followed by a bad status code.