DDS for display files
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 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 was 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 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
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 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.
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.
|
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.