The CMDSEL macro creates a selection mask similar to the SDF forms, in which the user can select one or more items in the guided dialog.
Figure 13 shows the main layout of a selection mask created with CMDSEL.
Figure 13: Layout of a selection mask
A maximum of 24 lines can be output on BS2000 screens. The number of lines needed for the selection masks depends on whether a title is output and how many NEXT lines there are. If there are more than 20 lines in the selection mask, the display is spread over the appropriate number of screen pages. The NEXT line then also contains + (scroll forward) and - (scroll backward).
A line on the screen can contain a maximum of 5 columns. The contents of a column in a line must be available in a data area, the initial address and length of which are passed in the program. The space needed for all the lines in a column is calculated from the number of lines multiplied by the length of the data area of a column.
An item to be output with a certain offset relative to the beginning of the data area and with a specific length is found in each data area of a column. Unless otherwise specified, the item has no offset relative to the beginning of the data area.
Example
The following data structure occurs in a selection box with 2 columns and 3 lines:
AREA1  AREA2  |
Operation | Operands |
CMDSEL | SELECT = *SINGLE / *MULTIPLE / <var: enum-of SELECTION_S:1> ,LINENBR = <integer 1..65536> / <var: int:4> ,MESSAGE@ = NULL / <var: pointer> ,MESSAGEL = NULL / <var: int 0..240> ,MARKL = 1 / <integer 1..75> / <var: int:1> ,OUTPUT = <var: pointer> ,TITLE@ = NULL / <var: pointer> ,TITLEL = <integer 1..240> / <var: int:4> ,TITEMS = NULL / <var: pointer> ,TITEMSL = 0 / <integer 1..65535> / <var: int:4> ,AREA1 = NULL / <var: pointer> ,AREA1L = 0 / <integer 1..65535> / <var: int:2> ,ITOFF1L = *AREA ,ITEM1L = *AREA ,AREA2 = NULL / <var: pointer> ,AREA2L = 0 / <integer 1..65535> / <var: int:2> ,ITOFF2L = *AREA ,ITEM2L = *AREA |
,AREA3 = NULL / <var: pointer> ,AREA3L = 0 / <integer 1..65535> / <var: int:2> ,ITOFF3L = *AREA ,ITEM3L = *AREA ,AREA4 = NULL / <var: pointer> ,AREA4L = 0 / <integer 1..65535> / <var: int:2> ,ITOFF4L = *AREA ,ITEM4L = *AREA ,AREA5 = NULL / <var: pointer> ,AREA5L = 0 / <integer 1..65535> / <var: int:2> ,ITOFF5L = *AREA ,ITEM5L = *AREA |
SELECT =
Specifies whether single or multiple selections are permitted in the mask.
*SINGLE
Only one item can be selected in the mask.
*MULTIPLE
Two or more items can be selected in the mask.
<var: enum-of SELECTION_S:1>
Variable that can assume the following values:
0: as *SINGLE
1: as *MULTIPLE
LINENBR = <integer 1..65536> / <var: int:4>
Number of lines that can be displayed in the selection mask.
MESSAGE@ = <var: pointer>
Specifies the address of a field containing the message to be displayed before any user selection.
MESSAGEL = <var: int 0..240>
Specifies the length of a field containing the message to be displayed before any user selection.
MARKL = 1 / <integer 1..75> / <var: int:1>
Maximal length of the mark value, hence the width of the mark column. The length limit of the rest of the selection line depends on this value (one character less per additional mark column character).
OUTPUT = <var: pointer>
Address of an area in which the result of the selection can be entered. As many bytes must be reserved as specified in the MARKL parameter for each of the selectable items, i.e. the area must have the byte length specified in LINENBR times the value specified in MARKL and be initialized with zero or blank. If the user selects the item(i) (<i> = o..m) with a value <text_1..n> (<n> = 1..75), the bytes (i*n) til (i*n + (n-1)) receive that value in place of zero/blank. If an area is assigned a value other than zero or blank before the user selection, the corresponding item is the default value in the selection mask.
TITLE@ =
Title of the selection box which is output in the first line of the screen.
NULL
No title in the selection box.
<var: pointer>
Address of the character string with the title.
TITLEL = <integer 1..240> / <var: int:4>
Specifies the length of the character string which is output as the title. This parameter is only evaluated if an address other than 0 is specified for TITLE@. The number of lines in the selection body depends on the number of lines in the title part (one line less per additional title line).
TITEMS = NULL / <var: pointer>
Address of an item title which is displayed in the sixth position on the third screen line (with 3270 terminals: 8th position).
TITEMSL = 0 / <integer 1..65535> / <var: int:4>
Length of the item title (maximum 73 characters).
AREAx =
with x=(1..5):
Data area in which the contents of a line are stored in a column, i.e. there must be precisely one of these data areas in each column.
NULL
No item is output in a specific line in column x.
<var: pointer>
Address of the data area in which the item to be output is stored.
AREAxL = 0 / <integer 1..65535> / <var: int:2>
with x=(1..5):
Length of a data area (in bytes) in column x.
The total length of all data areas of column x is calculated by multiplying the number of lines with the value of
AREAxL.
ITOFFxL =
with x=(1..5):
Offset of the item relative to the data area specified in AREA
*AREA_START
No offset.
<integer 1..65535> / <var: int:2>
Offset in bytes.
ITEMxL =
with x=(1..5): Length of the item (maximum 75 characters).
*AREA_LENGTH
The item fills the entire data area AREAx.
<integer 1..75> / <var: int:1>
Length of the item (in bytes).
Return information and error flags
The return code is passed in the standard header of the parameter list.
| Standard header |
| cc: Subcode 2 (SC2) bb: Subcode 1 (SC1) aaaa: Maincode |
| (SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
| 00 | 00 | 0000 | Normal termination |
| 00 | 20 | 0004 | Unrecoverable system error |
| 01 | 0008 | Parameter error: | |
| 00 | wrong parameter list | ||
| 01 | LINENBR | ||
| 02 | SELECT | ||
| 03 | OUTPUT | ||
| 04 | TITLE@ | ||
| 05 | TITLEL | ||
| 06 | Item1 | ||
| 07 | Item2 | ||
| 08 | Item3 | ||
| 09 | Item4 | ||
| 0A | Item5 | ||
| 0C | ITEMS | ||
| 0D | TITEMSL | ||
| 0E | MARKL | ||
| 0F | MESSAGE@ | ||
| 10 | MESSAGEL | ||
| 00 | 40 | 000c | User has not made a selection |
Additional programming notes
OUTPUT: the macro suppresses the NULs (0x00) in the input mark fields i.e. it concatenates the characters of the input mark column if they are separated by NULs and it keeps the rest length filled with NULs.
TITLE and MESSAGE: the presented text can be longer than the text specified in the parameters because the macro inserts the carriage return such as to not cut short words in 2 lines. If the presented text is longer than 3 lines, it is truncated with "...".