Use this record-level keyword to return the location of the cursor to an
application program.
This keyword may be specified in two formats. These formats
are:
- Return the name of the record and field in which the cursor is currently
positioned. Optionally, a third parameter may be specified that will
contain the relative cursor position within the field.
- Return the row and column position of the cursor relative to the
display. Optionally, two additional parameters may be provided that
will return either the row and column position of the cursor relative to the
active window (if one exists) or the location of the cursor at the beginning
of the two event mouse button definition.
The formats of the keyword is:
RTNCSRLOC([*RECNAME]
&cursor-record &cursor-field
[&cursor-position])
or
RTNCSRLOC({*WINDOW | *MOUSE}
&cursor-row &cursor-column
[&cursor-row2
[&cursor-column2]])
The parameter for the first format are:
- The *RECNAME parameter indicates that RTNCSRLOC should return the name of
the record and field on which the cursor is positioned. Optionally, it
will also return the relative position of the cursor with the field.
This parameter is optional.
- The cursor-record parameter specifies the name of a hidden field that, on
input, will contain the name of the record on which the cursor is
located. The field must be defined in the record format as a character
(A in position 35) field of length 10, with usage H (hidden). If the
cursor is not in a record area on input, the cursor-record field will contain
blanks.
- The cursor-field parameter specifies the name of a hidden field that, on
input, will contain the name of the field on which the cursor is
located. The field must be defined in the record format as a character
(A in position 35) field of length 10, with usage H (hidden). If the
cursor is not located on a field on input, the cursor-field field will contain
blanks.
- The optional cursor-position parameter specifies the name of a hidden
field that, on input, will contain the relative position of the cursor within
the field on which it is located. The field must be defined in the
record format as a signed numeric (S in position 35) field of length 4, with 0
decimal positions and usage H (hidden). If the cursor is in the first
position of the field, the cursor-position field will contain the value
1. If the cursor is in the ith position, the cursor-position
field will contain the value i. If the cursor is not located
on a field, the cursor-position field will contain the value 0. If the
cursor is located in a menu-bar or selection-field list, then the cursor
position parameter returns to the choice number on which the cursor is
located.
All three fields specified on the RTNCSRLOC keyword will contain values on
input if the cursor is outside the area of the record that contains the
RTNCSRLOC keyword. The fields also contain values on input if the
cursor is located in a subfile. The cursor-record field will contain a
value if the cursor is located anywhere inside the subfile. The
cursor-field and cursor-position fields will contain values if the cursor is
located on a field within the subfile.
The parameters for the second format are:
- The *WINDOW or *MOUSE parameter is used to qualify the cursor-row2 and
cursor-column-2 parameters. *WINDOW causes these parameters to return
the cursor location relative to the first useable location in the active
window. *MOUSE causes these parameters to return the location of the
cursor just before a two event mouse definition is processed.
- The cursor-row parameter specifies the name of a hidden field that, on
input, contains the number of row on which the cursor is located. The
field must be defined in the record format as a data type S, field length of
3, usage of H, and zero decimal positions. The value returned in this
hidden field will be relative to the entire display where the first row of the
display is row 1.
- The cursor-column parameter specifies the name of a hidden field that, on
input, contains the number of the column on which the cursor is
located. The field must be defined in the record format as a data type
S, field length of 3, usage of H, and zero decimal positions. The value
returned in this hidden field will be relative to the entire display where the
first column of the display is column 1.
- The optional cursor-row2 parameter specifies the name of a hidden
field. If *WINDOW was specified as the first parameter, the hidden
field will contain the relative row position of the cursor to the first
useable location of the active window. If there is no active window,
this value will be the same as &cursor-row. If the cursor is in the
first useable position of the window, the cursor-row2 field will contain the
value 1. If the cursor is outside of the active window, it is possible
for this value to be a negative number. If *MOUSE was specified as the
first parameter, the hidden field contains the row number of the cursor at the
instant just before a two event mouse definition was called. If a two
event mouse definition has not been processed, this field will be set to
zero. The field must be defined in the record format as data type S,
field length of 3, usage H, and zero decimal positions.
- The optional cursor-column2 parameter specifies the name of a hidden
field. If *WINDOW was specified as the first parameter, the hidden
field will contain the relative column position of the cursor to the first
useable location in the active window. If there is no active window,
this value will be the same as &cursor-column. If the cursor is in
the first useable position of the window, the cursor-column2 field will
contain the value 1. If the cursor is outside of the active window, it
is possible for this value to be a negative number. If *MOUSE was
specified as the first parameter, the hidden field will contain the column
number of the cursor when the first event of a two event mouse definition has
occurred. If a two event mouse definition has not been processed, this
field will be set to zero. The field must be defined in the record
format as data type S, field length of 3, usage of H, and zero decimal
positions.
Both formats of this keyword may be specified with the same record.
If the same hidden field is used multiple times for any of the parameters,
unpredictable results will occur.
Option indicators are not valid for this keyword.
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.