POS call

For more information about the qualified POS call, refer to the topic "Processing Fast Path Databases" in IMS Version 15.4 Application Programming.

An unqualified POS points to the logical end of the sequential dependent segment (SDEP) data. By default, an unqualified POS call returns the DMACNXTS value, which is the next SDEP CI to be allocated. Because this CI has not been allocated, its specification without the EXCLUDE keyword will often result in a DFS2664A message from the SDEP utilities.

Format

Parameters

db pcb

Specifies the DB PCB for the DEDB that you are using for this call. This parameter is an input and output parameter.

aib

Specifies the AIB for the DEDB that you are using for this call. This parameter is an input and output parameter. These fields must be initialized in the AIB:

AIBID

Eye catcher. This 8-byte field must contain DFSAIBbb.

AIBLEN

AIB lengths. This field must contain the actual length of the AIB that the application program obtained.

AIBRSNM1

Resource name. This 8-byte, left-justified field must contain the name of a DB PCB.

AIBOALEN

I/O area length. This field must contain the length of the I/O area specified in the call list.

keyword

Specifies the Keyword for the DEDB that you are using for this call. It goes in the first part of the i/o area. Returns six words containing field codes to I/O area. The following table lists the five keywords and the corresponding output.

i/o area

Specifies the I/O area in your program that you want to contain the positioning information that is returned by a successful POS call. This parameter is both an input and an output parameter. The I/O area must be long enough to contain all the returned entries. IMS returns an entry for each area in the DEDB.

The I/O area returned on POS call contained six words with nine potential fields of data for each return output. Each field is four or eight bytes. When the successful POS is an unqualified call, the I/O area consists of a 2 byte field that contains the length of the data area (LL), followed by 24 bytes of positioning information. The I/O data area will have 24 bytes of positioning information for every area in the DEDB. By placing one of the five keywords in position zero of the input I/O area, the user specifies the kind of data in the return I/O area. The following table lists the five keywords and the data that an unqualified POS call returns based on the keyword you choose for position zero of the input I/O area. Any keyword should be specified at the beginning of the I/O area.

Table 1. Unqualified POS call: keywords and map of the I/O area return output

Keyword	byte 2	word 0	word 1	word 2	word 3	word 4	word 5
<null>	LL	Field 1		Field 2		Field 4	Field 5
V5SEGRBA	LL	Field 1		Field 3		<null>
PCSEGRTS	LL	Field 1		Field 3		Field 6
PCSEGHWM	LL	Field 1		Field 3		Field 7
PCHSEGTS	LL	Field 1		Field 8		Field 6
PCLBSGTS	LL	Field 1		Field 9		Field 6

Field 1

Area name

This 8-byte field contains the ddname from the AREA statement.

Field 2

Sequential dependent next to allocate CI

This field is the default if no keyword is specified in position zero of the I/O area. The data returned is the 8-byte cycle count and RBA (CC+RBA) acquired from the global DMACNXTS field. This data represents the next pre-allocated CI as a CI boundary.

Field 3

Local sequential dependent next segment

The data returned is the 8-byte CC+RBA segment boundary of the most recently committed SDEP segment. This data is specific to only the IMS that executes the POS call. Its scope is for local IMS use only.

Field 4

Unused CIs in sequential dependent part

This 4-byte field contains the number of unused control intervals in the sequential dependent part.

Field 5

Unused CIs in independent overflow part

This 4-byte field contains the number of unused control intervals in the independent overflow part.

Field 6

Sequential dependent segment time stamp

The data returned is the 8-byte time stamp of the most recently committed SDEP segment across all IMS partners, or for a local SDEP, the time stamp of the first pre-allocated SDEP CI dummy segment of the local IMS. If the area (either local or shared) has not been opened, or a /DBR was performed without any subsequent SDEP segment inserts, the current time is returned.

Field 7

Sequential dependent High Water Mark (HWM)

This 8-byte field contains the cycle count plus RBA (CC+RBA) of the last pre-allocated SDEP CI which is the High Water Mark (HWM) CI.

Field 8

Highest committed SDEP segment

The data returned is the 8-byte cycle count plus RBA (CC+RBA) for the most recently committed SDEP segment across all IMS partners, or for a local SDEP, the CC+RBA of the most recently committed SDEP segment of the local IMS. If the area (either local or shared) has not been opened, or a /DBR was performed without any subsequent SDEP segment inserts, the HWM CI is returned.

Field 9

Logical begin time stamp

This 8-byte field contains the logical begin time stamp from the DMACSDEP_LOGICALBEGIN_TS field.

ssa

Specifies the SSA that you want to use in this call. This parameter is an input parameter. The format of SSA in POS calls is the same as the format of SSA in DL/I calls. You can use only one SSA in this parameter. This parameter is optional for the POS call.

Usage

The POS call:

• Retrieves the location of a specific sequential dependent segment.
• Retrieves the location of last-inserted sequential dependent segment, its time stamp, and the IMS ID.
• Retrieves the time stamp of a sequential dependent segment or Logical Begin.
• Tells you 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.

If the area which the POS call specifies is unavailable, the I/O area is unchanged, and the status code FH is returned.

Restrictions

You can only use the POS call with a DEDB.