CURSOR

Purpose

Use the CURSOR subcommand to move the cursor to a specified position and to assign a priority to the specified position. The cursor is positioned according to the highest assigned priority when all pending prefix subcommands and any macros are executed or when the screen is redisplayed.

Operands

CMdline

moves the cursor under the command line in the specified column.

Column

moves the cursor under the current line in the current column position.

Home

moves the cursor from the command line to the screen or from the screen to the command line, depending on its current position. If the cursor is on the screen, that is, any place but on the command line, CURSOR HOME remembers its location and moves it to the command line. If the cursor is on the command line, CURSOR HOME returns it to its previous location on the screen.

File

moves the cursor to a line number relative to the beginning of the file.

Screen

moves the cursor relative to the beginning of the logical screen.

lineno

specifies the file line (if used with the FILE operand) or the screen line (if used with the SCREEN operand) where the cursor is to be placed.

colno

specifies the column number where the cursor is to be placed. The location of colno varies according to the option with which it is specified. If used with:

• CMDLINE, colno places the cursor relative to the beginning of the command line (after the arrow).
• FILE, colno places the cursor relative to the beginning of a file line. If not specified and the cursor is currently within the file area, it is placed in the same column number in the specified file line. Otherwise, the cursor is placed in the first column.
• SCREEN, colno places the cursor relative to the beginning of the logical screen (under the first character of the prefix area). When colno is not specified for CURSOR SCREEN, the default cursor position is the current column which it is displayed. If the cursor is on the command line, the colno is 7.

Priority n

is the priority number assigned. It must be greater than or equal to zero and less than 256. Higher numbers denote higher priorities and lower numbers denote lower priorities. If no priority is specified, all priorities of prefix subcommands and macros are ignored and the last CURSOR subcommand issued positions the cursor.

See Prefix Subcommands and Macros for a complete list of the priorities for all prefix subcommands and macros, screen changes, and the ENTER key.

Initial Setting

The initial placement of the cursor is based on the initial setting for SET ENTER:

CURSOR CMDLINE 1 PRIORITY 30

Usage Notes

1. The CURSOR subcommand with the FILE or SCREEN operands is mainly intended to be issued from XEDIT macros.
2. You can display the current cursor position, relative to the beginning of the file and the beginning of the screen, with the QUERY CURSOR subcommand (or, within a macro, you can use the EXTRACT subcommand).
3. CURSOR HOME (and CURSOR COLUMN) are good candidates for PF key assignment. The initial setting of the PF12 key is CURSOR HOME.

   If you issue CURSOR HOME and the cursor cannot be returned to its previous position in the file (for example, if scrolling or splitting the screen removes that part of the file from the current screen), the cursor is positioned in the current column of the current line. However, if the cursor was located in an area other than the file area (like a reserved line) and you issue CURSOR HOME, the cursor returns to its position on the screen even if the screen is scrolled (provided a change to the screen layout does not make this impossible, for example, by splitting the screen).

   If the cursor is not on any logical screen, it moves to the command line. HOME, at this point, is line one, column one.

4. If you issue CURSOR HOME immediately after entering XEDIT, the cursor moves to the current line and column if they are on the logical screen. If the current line and column are not on the screen, the cursor moves to the first verify column.
5. If the cursor is in the prefix area when you issue CURSOR HOME, the cursor moves to the command line. If you issue CURSOR HOME again, the cursor moves to the first verify column within the line adjacent to that prefix area.
6. If the cursor is on a valid position on the virtual screen, but that position is not displayed on the physical screen, the cursor is repositioned according to the rules in the z/VM: CMS Commands and Utilities Reference for the VSCREEN CURSOR command.

Notes for Macro Writers

1. The CURSOR subcommand does not scroll the screen. Therefore, when you use CURSOR FILE lineno, the line number (lineno) must appear on the current logical screen. For example, in the following subcommand,

   cursor file 700

   file line 700 must appear on the current logical screen.

   When you use CURSOR SCREEN lineno, the screen line (lineno) must be within your logical screen size.

   When you use CURSOR COLUMN, the column position must appear on the current logical screen. For example, if using SET VERIFY, you issue:

   clocate 10
   set verify 20 30
   cursor column

   an error message is displayed because column 10 no longer appears on your current logical screen. Other XEDIT subcommands which can affect the contents of the logical screen include RIGHT and LEFT.
2. A macro can indicate where the cursor should be positioned as well as the priority for this cursor movement. As a result, when multiple prefix subcommands are issued and a macro is executed on the command line, the cursor is positioned at the location specified with the highest priority.
   Note: The cursor position is updated ONLY when a higher cursor priority is met. Therefore, if two prefix subcommands are specified that have the same cursor priority, the first one determines the cursor placement. Likewise, if a prefix subcommand is issued and a macro is executed on the command line, both with equal cursor priorities, the prefix subcommand determines the cursor placement.
3. If multiple CURSOR subcommands are issued, the priority of each is checked and the cursor position is updated to reflect the new setting, which corresponds to the command with the highest priority. The cursor remains in the screen it was in when ENTER is pressed; therefore, a CURSOR subcommand in another logical screen has no effect on cursor placement.

Messages and Return Codes

520E

Invalid operand: operand [RC=5]

521E

Invalid line number [RC=1 or 5]

527E

Invalid column number [RC=1]

529E

Subcommand is only valid in {display|editing} mode [RC=3]

543E

Invalid number: number [RC=5]

545E

Missing operand(s) [RC=5]

where return codes are: