Positioning the record pointer in a result set

CICSPlex® SM maintains a current record pointer in each result set. When you first create a result set (with a GET command, for example), the pointer is positioned at the top of the result set. The first command that you issue against the result set affects the first record.

In most cases, when you issue FETCH commands to retrieve records from the result set, the record pointer is positioned to the next record in the result set (that is, the record following the last record that was fetched). However, certain API commands always act upon the last record that was fetched. When you issue any of these commands after a FETCH command, the record pointer is not advanced to the next record:
  • COPY
  • DELETE
  • MARK
  • UNMARK
  • PERFORM SET CURRENT
  • REFRESH CURRENT
  • SET CURRENT
The record pointer in a result set may move either forward or backward, depending on the direction in which you are retrieving records. If you issue a FETCH command and no records are found that match the specified criteria, no records are retrieved. In that case, the pointer is positioned to the top or bottom of the result set, depending on the direction the pointer was moving.

If you issue a FETCH command and there is insufficient storage to retrieve all of the records, the pointer is positioned at the last record that would have been retrieved if there had been enough space. The pointer is not positioned at the last record that was retrieved. To be certain of the pointer's location, you should use the LOCATE command to explicitly position it within the result set.

The GET and FETCH commands leave the record pointer in specific, predefined positions, but other API commands do not. Many API commands manipulate records or update the data in a result set. The position of the record pointer after one of these commands depends on a combination of factors, including the options that you specified on the command. The pointer may have moved forward or backward one or more records, or it may be positioned to the top or bottom of the result set. If you specified the CURRENT option, the record pointer does not move; it remains positioned on the current record after the command is complete.

For this reason, CICSPlex SM provides the LOCATE command, which lets you explicitly position the record pointer within a result set. If you want to use the record pointer after issuing any of these commands, first use the LOCATE command to reposition it:
  • COPY
  • DELETE
  • GETDEF
  • GROUP
  • MARK
  • ORDER
  • PERFORM OBJECT
  • PERFORM SET
  • REFRESH
  • SET
  • UNMARK.