Understanding the Diagnostic Subsystem for AIX

diag_task_screen

Purpose

Displays menus commonly used by Diagnostic Tasks.

Syntax

#include <diag/diag_screen.h>

#include <diag/diag.h>

long  diag_task_screen ( screen_info, screen_task_data, screen_task_msg )

screen_info_t *screen_info;
screen_task_t *screen_task_data;
screen_task_msg_t screen_task_msg[];

Description

The diag_task_screen subroutine displays menus commonly used by Diagnostic Tasks.

Parameters

Parameter	Description
screen_info	Screen Information. This structure defines the screen type.
	short screen_type	Screen Type. INFORMATIVE TRANSITIONAL DIALOG SINGLE_SELECTION MULTIPLE_SELECTION
	short screen_id	Screen Identifier - Not Used.
	short screen_key	Identifies extra function keys for screen. DIAG_LIST_KEY DIAG_HELP_KEY if screen_type is INFORMATIVE
	long item_selected	Indicates the selected item in the list, if screen_type is SINGLE_SELECTION. First selectable item in screen_msg would have a 1 returned, second selectable item would have a 2 returned, and so on. For a MULTIPLE_SELECTION screen_type, this field is used to keep track of the current selection for subsequent calls until the COMMIT function key is used.
screen_task_data	Screen Data. This structure contains all data needed to construct the screen.
	nl_catd fdes	Catalog file descriptor.
	long menu_number	Menu number that is displayed, right-justified, as a hex number at the top-right corner of the screen.
	short msg_count	Total number of messages in the screen_task_msg structure.
screen_task_msg	The screen_task_msg structure contains an array of setid's and msgid's used to construct the text (or body) of the screen. This includes all except the last line, or Instruction line.
	short set_num	The set number containing the message text.
	short msg_num	The message number containing the message text.
	char * message	Text message to use in place of < set_num, msg_num >. This is useful if string substitution was required in order to build the message text. This text will take precedence over the < set_num, msg_num > if not NULL.
	short help_set_num	The set number containing the message text when the HELP key is pressed. Help message text is line sensitive, and is normally used when the msg_type is set to SELECTABLE_MSG or DIALOG_MSG.
	short help_msg_num	The message number containing the message text when the HELP key is pressed. Help message text is line sensitive, and is normally used when the msg_type is set to SELECTABLE_MSG or DIALOG_MSG.
	short msg_type	Flag indicating if text is help, selectable, dialog, or information. TITLE_MSG SELECTABLE_MSG DIALOG_MSG INFO_MSG
	char leading_char	A specific character to be displayed before the message text. Note that this is also used as the mechanism to determine which selectable items had been selected on a MULTIPLE_SELECTION screen.
	long line_num	Internal screen line number.
	char op_type	Type of operation allowed on this field
	char entry_type	type of (user) entry allowed in the field
	char required	DIAG_YES DIAG_YES_NON_EMPTY DIAG_EXCEPT_WHEN_EMPTY DIAG_NO = default DIAG_YES or DIAG_YES_NON_EMPTY means display required flag
	char changed	DIAG_YES, DIAG_NO = default; field changed from default value
	char *disp_values	disp. text of allowed/default choice(s, separated by ",")
	char *data_value	MUST point to string (buffer) of size (entry_size + 1) if there is ANY way values may be changed (typein/list/ring)
	long entry_size	maximum size of (data_)value that can be entered OR returned (include a "return" of anything from disp_values)
	long cur_value_index
	long default_value_index	0 origin index of default value

NOTES:

The screen_task_msg structure must be built exactly for SINGLE_SELECTION, MULTIPLE_SELECTION, and DIALOG screen types. screen_msg[0] MUST have the msg_type set to TITLE_MSG for the TITLE line.

screen_msg[1..n] MUST have the msg_type set to SELECTABLE_MSG or DIALOG_MSG for all selectable/dialog messages.

screen_msg[n+1] MUST have the msg_type set to INFO_MSG if you want some kind of information displayed to the user before the INSTRUCTION line.

Return Value

The diag_task_screen subroutine returns one of the following values:

Return Value	Description
DIAG_OK	Successful return.
DIAG_MALLOCFAILED	Memory allocation was unsuccessful.
DIAG_ENTER	Enter Function key was entered.
DIAG_EXIT	Exit Function key was entered.
DIAG_CANCEL	Cancel Function key was entered.
DIAG_HELP	Help Function key was entered.
DIAG_LIST	List Function key was entered.
DIAG_FAIL	Invalid data structure, software error
DIAG_COMMIT	Commit function key was entered.