IBM Support

QMGTOOLS: Virtual Terminal program

Technote (troubleshooting)


Emulates a virtual terminal that can perform keystrokes as if it were a user.

Diagnosing the problem

The MustGather tools library contains some programs to automate functions such as dumping AA macros to ease data collection.

Resolving the problem

The MustGather tools library contains programs to automate functions such as dumping AA macros, etc to ease some data collections and functions.


If the QMGTOOLS toolkit has not yet been installed, you should refer to the following document for information on how to download and install QMGTOOLS toolkit on your IBM i server.

Virtual Terminal menu

1) To access the Virtual Terminal menu, choose the Misc Tools option (in this case, it is option 9) from the main QMGTOOLS menu. To get to the main menu, type GO QMGTOOLS/MG.

2) There are 2 menu option, VTMCMD - Virtual terminal command and VTMAACMD - Virtual terminal SST functions

VTMCMD option

  • -

    VTMCMD - This is the main program to open up a virtual device and run commands.

    Function *NEW - create a new 5250 session
    *RESUME - resume a 5250 session that was not closed
    *CLOSE - close the 5250 session that was opened
    Signon User ID/pass The OS signon when the 5250 session is opened. This is only required if the function is *NEW
    Virtual Device *AUTO - auto select a virtual device
    virtual device name - enter the name of the virtual device to select
    Command 1 - A command to be run after the signon completes or *FKEY to not run a command but rather hit an F key or Enter key, etc.
    Function key 1 What function to press after command 1

    *NO - no function key
    F1-F24 - function keys
    ENT - enter key
    PGU - page up
    PGD - page down
    Wait for input line Wait for an input field before typing in the command
    Prompt position A screen can have multiple input fields, which input field to type in the command.
    Chain command Because there can be multiple input fields on a screen, chain means that continue to the next command before performing an action
    Command 2 - Command 4 Same definitions as above
    Session data area Data area to store the session information such as session handle, etc.
    Dataq Data queue for the virtual terminal's send/receive API to interact with
    Output file Output file to store the display data
    Output library Output library for the output file

    Example usage :

    In this example, I signed on as user NNGUYEN, ran the DSPNETA, press ENTER, and end. Note that after this command completes, the session is still active. You can either *RESUME to do additional functions, like F3 to back out or *CLOSE to close the session.


    Type choices, press Enter.

    Function . . . . . . . . . . . . > *NEW *NEW, *RESUME, *CLOSE
    Signon user ID . . . . . . . . . > NNGUYEN Character value
    Signon user pass . . . . . . . . > Character value
    Virtual device . . . . . . . . . *AUTO Name
    Command 1 . . . . . . . . . . . > DSPNETA

    Function key 1 . . . . . . . . . > ENT ENT, F1, F2, F3, F4, F5...
    Wait for input line . . . . . . Y Y, N
    Prompt position . . . . . . . 001 Name, 001, 002, 003, 004...
    Chain command . . . . . . . . N Name, N

  • -

    VTMAACMD - Virtual terminal setup for SST AA functions. Allows one to save AA macros either with or without user credentials to be run in sequence.

    Function *START - start the AA macros
    *SETUP - setup AA macros, information is stored in a data area that will be retrieved later
    *RMVUSR - remove saved credentials from AA macro setup
    *DLTDTAARA - delete data area containing the saved AA macros
    Predefined macros Leave as *CUSTOM for now
    Log file If using *START, this is the file to store the output from the 5250 session
    Library If using *START, this is the library for the log file
    Clear first If using *START, clear the log file first before starting
    Output file If using *START, this is the output file to contain the AA dumps
    Output library If using *START, this is the library for the output file
    Clear first If using *START, clear the output file first
    Data area prefix For *SETUP, this is the data area that is created that stores the SST macros and/or user credentials (note that user credentials are stored encrypted).

    For *START, this is the data area that contained the AA macros

    For *RMVUSR, this is the data area to remove the encrypted user credentials

    For *DTLDTAARA, this is the data area to delete off the system

    Data area are stored in the QMGTOOLS library
    Submit job Submit the job or not

    If choosing *SETUP, the next screen will appear.

    For Signon and SST user, leave *NONE if you want the user to enter the credentials every time they run the AA stored macros. Enter credentials to run this as a trap via a CL program. Note that user credentials are stored encrypted in the data area.

    Virtual device - if the user wishes to user a named device or leave *AUTO to auto select device
    Data area prefix - this will be the data area to store the information

    The next screen will allow you to put in the macros and options.

    Up to 20 macros can be entered.

    Macro 1-20 - the macro
    Options - the options for the macro
    Delay - delay for xxx seconds before running the macro. The above example will run TASKINFO -ALL F A -TF 2 in the first round, delay for 30 seconds, and run TASKINFO -ALL F A -TF 2 the second round.

    F6 to update the entries.

    After this is done, the user can run the custom defined AA macros with command


    Where DTAPRF(DAGBO) is the data area that stored the AA macros.

    If user credentials were entered, the command will run. If user credentials were not entered, a screen like this will show up asking for credentials.

Cross reference information
Segment Product Component Platform Version Edition
Operating System IBM i Not Applicable
Operating System IBM i 7.2
Operating System IBM i 7.1
Operating System IBM i 6.1
Operating System IBM i 7.3

Document information

More support for: IBM i

Software version: 6.1, 7.1, 7.2, 7.3

Operating system(s): IBM i

Reference #: N1019952

Modified date: 24 July 2017

Translate this page: