Use this record-level keyword to return the location of the cursor
to an application program.
This keyword can 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 can 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 can 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 usable 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 is specified as the first parameter, the hidden
field will contain the relative row position of the cursor to the first usable
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 usable 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 is 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 is 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 is specified as the first parameter, the
hidden field will contain the relative column position of the cursor to the
first usable 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 usable 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 is 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 can 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.
Example
The following example shows how to specify
the RTNCSRLOC keyword.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
A R REC01 RTNCSRLOC(&RCD &FLD &POS);
A RTNCSRLOC(*MOUSE &ROW &COL);
A FLD 10A H
A RCD 10A H
A POS 4S 0H
A FLD1A 2A I 3 2
A 10 FLD2A 6A O 3 18
A N10 FLD3A 10A O 3 18
A*
A R REC02 OVERLAY
A FLD1A 2A I 5 2
A FLD2A 10A O 5 5
A FLD3A 6A O 5 18
A
Both REC01 and REC02 are displayed on the screen and
option indicator 10 is off.
The following table
shows the values returned when the cursor is at the specified positions.
| Row |
Col |
Cursor record |
Cursor field |
Cursor position |
Cursor row |
Cursor column |
|---|
| 3 |
2 |
REC01 |
FLD1A |
1 |
3 |
2 |
| 3 |
19 |
REC01 |
FLD3A1 |
2 |
3 |
19 |
| 3 |
25 |
REC01 |
FLD3A |
8 |
3 |
25 |
| 3 |
40 |
REC01 |
blanks |
0 |
3 |
40 |
| 4 |
40 |
blanks |
blanks |
0 |
4 |
40 |
| 5 |
5 |
REC02 |
FLD2A |
1 |
5 |
5 |
| 5 |
40 |
REC02 |
blanks |
0 |
5 |
40 |
| 1 If
Option indicator 10 were on, FLD2A would be returned when the cursor is at
row 3 column 19. |