VMTDSP - Panel Builder/Driver (display)
VMTDSP is a program which provides the logic for building and displaying the various panels used to set data transfer parameters.
micsrm140
The initial menu screen, VMTMNU, is brought into memory, defaults are set from the :SCREEN 0 specification, all other screens in the VMTMNU file are built, and the first screen is displayed. Thereafter, VMTDSP controls the flow from one screen to the next.
VMTDSP is divided into two major routines, @Control and @ScreenFormat. Each consists of a set of internal subroutines. On entry to VMTDSP, @ScreenFormat is called to build the first menu panel and any screens referenced. If there are no problems, the @Control routine is invoked to actually process the panels and interpret any actions requested via PF keys, PA keys, etc.
ScreenFormat Panel Building Routine
The @ScreenFormat routine is initially called at the beginning of VMTDSP with the name of the main (master) menu screen file; for the VM Data Transfer Program, this is VMTMNU. The master menu screen file is brought into memory, defaults are set from the :SCREEN 0 specification, and all other screens defined in the master menu screen file are built. When a subsidiary menu screen is selected, @ScreenFormat is again called from the @Control routine (subroutine DoNEWSCREEN).
Within @ScreenFormat, all line text defaults to blank space, and the default line attributes used in SET RESERVED are default color, no highlighting, and no protect. The default field attributes are protect and no highlighting. The escape character is X'FF'. Lines are first built from the line text definitions, then field descriptors are inserted into the text.
The line text is split at the field column minus 1 (that is, field column number less one), and the field attributes are inserted into the line. If a length greater than zero is specified, a reset attribute is inserted in the line at column plus length. All fields must be defined in ascending order by column within a line. No checking is done for field overlap.
If :PFKLINEs are defined, the definition will replace any existing :LINE definition for the same line. All :PFK settings must occur before the :PFKLINE, or otherwise the text is not added to the display line.
@ScreenFormat reads each line of the screen definition file, and calls subroutines to address the different line types (e.g. :FIELD, :PFK, :LINE, etc.).
Subroutines:
ScreenOnceOnly
Called on the first entry to @ScreenFormat, this routine performs initialization of variables and sets default XEDIT parameters.
- Parameters (entry)
- Master menu screen file name.
- Returns
- Value of 1 that is assigned to @ScreenINIT variable to indicate initialization is complete.
SetScreen
Adds a screen definition; parses the :SCREEN statement. If this is a SCREEN 0 specification, no further processing is performed. For any other type of screen definition a check is made to see if the screen is already defined. If so, arrays containing the lines of text, line attributes, and field attributes for the screen are re-initialized. If the screen is a menu, the menu list is cleared and re- initialized. If the screen is new, the count of screens is incremented, and screen identification information is saved. For both previously defined and new screens the optional identifier and edit function names are also saved.
- Parameters (entry)
- The screen name.
SetCursor
Saves the initial cursor display position by parsing the :CURSOR statement. The position is represented by either a field name, or a line and column number. If a field name is specified, the cursor position information is obtained from the line and column specifications of the field definition.
- Parameters (entry)
- The screen name and number.
TattrDef
Builds a line attribute definition; parses the :TEXTATTR statement; establishes the attributes for a line to be displayed, or the default attributes for the screen, such as protected or non-protected, colors, etc.
- Parameters (entry)
- The screen name and number.
LineDef
Builds a text line display definition; parses the :LINE statement for the line number and text to be displayed on that line; saves the text for later display.
- Parameters (entry)
- The screen name and number.
FieldDef
Adds an input field, or fields, to a text line; parses the :FIELD statement for the line and column number defining the field position on the screen. Also saves off-the- field names, lengths and display attributes. The routine checks for errors to insure that a given position on the screen is associated with only one field name.
Parameters (entry)
The screen name and number.
KeyDef
Builds a program function key definition; parses the :PFK statement for the PF key number and function to be performed based on hitting that key.
- Parameters (entry)
- The screen name and number.
KlineDef
Builds a PF key line definition used to display one or more lines at the bottom of the screen, indicating what action will be caused by a given PF key. The subroutine also parses the :PFKLINE statement to determine which line to use and which keys to display.
- Parameters (entry)
- The screen name and number.
SetMenu
Records the menu selection numbers and the corresponding screen names to be invoked by a given selection. The subroutine also parses the :MENU statement.
- Parameters (entry)
- The screen name and number.
GetAttribute
A function subroutine that returns a one-byte attribute for a line or field, based on a character specification of attributes. GetAttribute is passed a set of parameters (e.g. PROTECT, PINK, HI), and translates these into an array index, which, in turn, is used to obtain a valid attribute byte via the XEDIT SET CTLCHAR command.
Parameters (entry)
Text string containing screen attribute abbreviations.
Returns
One-byte screen attribute for a field or line.
UpAttr
A function subroutine used by the GetAttribute routine to create a string defined by the attr variable. The string contains four values indicating which of the four basic attribute categories has been specified for a field or text. These categories are Protect, Color, Extended Highlighting, and Standard Highlighting.
- Parameters (entry)
- A string containing up to four digits, separated by blanks, representing selected attributes, an attribute category number, or an attribute number.
- Returns
- An updated string reflecting the selected category and attribute number.
InsAttr
A function subroutine used by the FieldDef routine to place an attribute byte in front of any defined fields. The subroutine keeps track of how many attribute bytes are used in the current screen line so fields are properly positioned on the screen.
- Parameters (entry)
- A one-byte attribute character; the name of the variable containing the screen line; the column position in which that attribute should be inserted in.
- Returns
- The screen line with the attribute properly inserted.
AbsLine
A function subroutine which returns a real line number from an input specification. If the parameter passed to AbsLine is a positive number, Absline returns that line number. If the parameter is a negative number, Absline returns the real line number relative to the bottom of the screen. If the letter M is passed to AbsLine as a first parameter, the real line number relative to the middle or the screen is returned based on a positive or negative number as the second parameter. If no second parameter is specified with M, the real line number returned represents the middle line of the screen.
- Parameters (entry):
n
A specific line number, or
n
Lines from bottom of screen, or
'm'
Screen midpoint, or
'm' +n
Screen midpoint plus n lines, or
'm' -n
Screen midpoint minus n lines.
Returns
A real line number
CheckLine
This subroutine is called to reset a variable (@Offset) to zero when a new screen line is defined. The @Offset variable contains the number of attribute bytes associated with this line that are placed in the text definition of the screen. Checkline is used to ensure that fields are properly positioned on the screen.
- Parameters (entry)
- The current real line number.
Control Panel Driver Routine
The @Control routine displays screens and reads the input. If no errors are encountered by @ScreenFormat in processing the main menu screen, then @Control is called. It is passed the name of the screen file and, after initialization, goes into a loop that continues displaying and reading screens until the user indicates that it is ready to exit.
When a screen is read, any RES tags (reserved fields) are edited, and the PF or ENTER key is processed. If a PA2 key tag is encountered, screen diagnostics are displayed.
Subroutines:
GetDataFields
This is called any time a new screen is to be displayed. This subroutine gets the data fields for the screen by using CallFunction with the GET parameter.
- Parameters (entry)
- Screen number
- Returns
- Value of 1 assigned to @ScreenINIT variable to indicate initialization is complete.
ScreenRefresh
This is called to pass lines to XEDIT for display. Loops through the variables created by @ScreenFormat, and for each line issues a SET RESERVED command. Once all of the lines have been displayed, the Cursor is positioned on the screen with the CURSOR SCREEN command.
- Parameters (entry)
- Screen number; cursor position.
PFKey
This puts the pressed PFKey on the pending action queue if the key is defined. The PFK definitions for the current screen are checked first. If a separate definition has been established for this PFK, SetPendAct is called with that a action. If no definition was made, the screen 0 definitions are checked next. If defined, SetPendAct is then called with the appropriate action. Finally, if no definition has been established for the key, an error message is issued by using the ErrMsg function.
- Parameters (entry)
- PFKey number; screen number.
PAKey
If PAKey 2 is pressed, screen diagnostics are displayed, indicating the screen displayed, and the action/edit function used for processing the screen. Furthermore, as each field is processed on the screen, the field name and contents are displayed.
EnterKey
No action is taken by this routine. The RES tags are used to determine the action to be taken.
EditField
This is called when a RES tag is encountered after a screen read. The subroutine parses the tag data to determine the line and column that were modified, and checks to see if the field modified is a menu selection. If so and the choice is valid, a NEWSCREEN internal command is added to the pending stack. If the data is not a menu selection, the data is edited by using the CallFunction function to edit the data.
CallFunction
This calls an edit/action routine. In the case of the VM data transfer program, this amounts to calling profile VMTPARMS, which, in turn, passes control to the appropriate edit or action routine. If a zero return code is received, then routine UpdateFields is called. Regardless of the return code value, routines DisplayMSG, AddAction, and ModifyDisplay are then called in sequence.
- Parameters (entry)
- Screen name; function name (EDIT, SAVE, GET, or ACTION); field name; data value.
- Returns
- A zero return code indicates that everything is O.K.; otherwise the return code is non-zero.
UpdateFields
This is called to update the field values after successful completion of an edit/action routine. The field names for the screen are retrieved, and routine InsData is called to put the data into a line. InsData is assigned to a variable only to invoke the function; the variable created is not used.
InsData
This is called by the subroutine UpdateFields to move a new value into a data field. The screen layout is modified with the new data, and a "refresh line" flag is set.
- Parameters (entry)
- Field name; field value.
- Returns
- A return code of zero.
DisplayMSG
Pulls queued messages off the message stack, and displays them via XEDIT.
ErrMSG
Calls external routine VMTMsg to read in message text from the VMTMSGS ERRMSG * file. ErrMSG then calls DisplayMsg to display the message.
- Parameters (entry)
- Message number; variable list for substitution.
- Returns
- Zero indicates that the message severity level is I, W, or R. Otherwise, the message number is returned.
AddAction
If any actions have been added because of processing done by CallFunction, AddAction calls the SetPendAct routine to place the action on the pending queue.
ModifyDisplay
Performs no function at this time.
SetPendAct
Updates the count of pending actions, and adds an action to the pending action queue.
- Parameters (entry)
- Name of Action to be added. Possible values include: QUIT, PQUIT, SAVE, FILE, PREVSCREEN, NEWSCREEN, NESTSCREEN, ACTION, RELOAD, and HELP.
DoQUIT
Called whenever the pending action is either QUIT or PQUIT. The value returned is set to 1 if this is a PQUIT. It is also set to 1 if the action is a QUIT, and the current screen is not screen 0 (the main menu). If the QUIT message is issued from a nested screen, routine DoPREVSCREEN is called.
- Parameters (entry)
- QUIT or PQUIT.
- Returns
- 1 or 0, indicating whether (1) or not (0) to leave the VMTDSP routine.
DoSAVE
Called whenever the pending action is a SAVE or FILE. A CallFunction then saves the data entered on the current screen. DoSAVE returns a value of 1 when the pending action is FILE and screen 0 is calling the current screen. Otherwise, subroutine DoPREVSCREEN is called.
DoPREVSCREEN
Called to move up one level in terms of screen nesting. The screen that called the current screen is made the new current screen, and the nesting level index is adjusted by subtracting one from the screen level number.
- Returns
- Previous screen name.
DoNESTSCREEN
Called to display a new screen. This subroutine is not used in setting VM data transfer parameters at this time. If called, it updates global nesting variables, and invokes routine DoNEWSCREEN.
DoNEWSCREEN
Called when a menu selection causes a new screen to be displayed. If the screen has not been previously entered during the present session, subroutine ScreenFormat is called to read in the screen and initialize the necessary control variables. If no errors are encountered, the new screen name is returned. If errors are encountered, appropriated error messages are formatted, and current screen name is returned, thereby causing that screen to be displayed again.
- Parameters (entry)
- New screen name.
- Returns
- New or current screen name.
DoACTION
Called when a function specified in the screen as an "action" is requested through a PFkey. The CallFunction subroutine is called with an ACTION parameter.
- Parameters (entry)
- The parameters to be passed to the edit/action routine, such as EDIT SELECT, or REFRESH.
DoHELP
Called when the current pending action is a request for help, usually invoked by the user pressing the PF1 Key. The CMS command HELP is issued with the parameters specified for use with the PF1 key in the screen definition of PFKeys.
- Parameters (entry)
- The PFKey Help parameters.
DoRELOAD
Called when the current pending action is a RELOAD of the screen format information. This subroutine is used for debugging purposes to force a call to the @ScreenFormat subroutine.
Diagnose
Called by the EditField subroutine when screen diagnostics are requested via the PA2 key. The subroutine issues a CMS command MSG displaying the data for the screen as it is processed by the EditField routine. It bypasses the editing of the data entered on the screen.