CURSOR—Set or Query the Cursor Position

The CURSOR assignment statement either sets the column number and relative line number of the cursor location within the data, or retrieves the column number and relative line number of the cursor location within the data and places them in variables.

Syntax

var1

The name of a variable containing the line number. The line number is a 6-digit value that is left-padded with zeros. It is the ordinal number (not the sequence number) of the line. If the variable is VDEFINEd in character format, it should be defined with a length of 8. The returned value is left-padded with zeros. For compatibility with previous releases of ISPF, a length of 6 or 7 is allowed in cases where no data loss will occur.

var2

The name of a variable containing the data column number. The data column number is a 3-digit number that is left-padded with zeros. If the variable is VDEFINEd in character format, it should be defined with a length of 5. The returned value is left padded with zeros. For compatibility with previous releases of ISPF, a length of 3 or 4 is allowed in cases where no data loss will occur.

The columns are numbered starting with 1 at the first data column. If the cursor is in the command line, the cursor value is column 0 of the first data line on the panel; the value is column 0 if the cursor is in the line command field. When you retrieve the cursor position in an empty member, the line number and column number are both set to 0.

linenum

The relative line number of the line on which the cursor is to be located. Make sure when you set the cursor to a line number that the line number exists.

label

The label of the line on which the cursor is to be located.

Note: If you try to use a label that has not been assigned, you receive a return code of 20. To avoid this, use the LINENUM assignment statement.

ISREDIT (X) = LINENUM .LABEL

When using the LINENUM statement, a return code of 8 is issued if the label does not exist.

col

The data column number where the cursor is to be located.

If the column number is beyond the end of the data area when setting the cursor, the cursor is positioned to the next line, which is equivalent to the first position of the line command field.

Description

The position of the cursor shows the starting or ending location for the SEEK, FIND, CHANGE, and EXCLUDE commands. It is also used as the text split point for TSPLIT. See Referring to column positions for more information on how the column number is determined.

When you run a macro, the cursor value is the cursor position on the panel at run time.

Note: To position the cursor on the command line, issue a return code of 1 from the macro. For example, in CLIST code EXIT CODE(1) as the last statement in your EDIT MACRO to position the cursor on the command line.

These statements can change the cursor position:


CHANGE     CURSOR   EXCLUDE
FIND       SEEK     TSPLIT
USER_STATE

Table 1 shows the line and column numbers returned, depending on the location of the cursor.

Table 1. Cursor position
If the CURSOR location is:	The LINE number is:	The COLUMN number is:
Command line	First display line	0
Line number field	Line by the cursor	0
Left sequence number (the sequence number is on the left of the data when number mode is on)	Line by the cursor	0
Right sequence number	Line by the cursor	Column by the cursor
Left or right of the bounds	Line by the cursor	Column by the cursor
Data within the bounds	Line by the cursor	Column by the cursor
Insert blank space	Line above the cursor. If the cursor is at the top of the panel, then the line number returned is the line below the cursor and the column number is column 0.	Column by the cursor
Non-data line and its line command field (above the last data line)	Line below the non-data line.	0
Non-data line (below the last data line)	Line number of the last line of data	Width of the last line of data plus 1

Return codes

0: Normal completion
4: Column number beyond data, line number incremented
12: Invalid line number
20: Severe error

Examples

To put the line number of the current cursor position into variable &LINE:

ISREDIT (LINE) = CURSOR

To set the cursor position to data line 1, column 1:

ISREDIT CURSOR = 1 1

To set the cursor position to column 1 of the last data line:

ISREDIT CURSOR = .ZLAST 1

To set the cursor position to the line with the label .LAB, without changing the column position:

ISREDIT CURSOR = .LAB