RTNCSRLOC (Return Cursor Location) keyword for display files

You 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.