In some environments, it is desirable to provide a menu or selection
function similar to system displays and allow for a command line at
the bottom of the display.
A similar approach could also be used if you want to create your own
command entry display to either control what commands get executed or
to provide a more permanent audit trail of what was executed. For
example, if you want to audit what commands are entered by the
security officer, you could provide your own command entry display
and write the commands to a journal using SNDJRNE.
The system supports an API for a command line. The API places a
window on top of the current display and allows a command to be
entered. This is much simpler to implement, but does not give the
same appearance as a system menu. Normally, you would define a
function key on a display to request the command line. When pressed,
your code would do:
CALL QUSCMDLN
A window would be displayed with the command line inside the window.
System displays use UIM to provide for a command entry line on the
same display as other functions. A command entry line can be
achieved using a combination of system functions to simulate the
system displays. The code provided is to be used as skeleton code
for your application functions. It provides for both options
(typical menu entries) and a command line:
Command line
------------
** Commands may be entered and executed
** Messages are displayed using a message subfile
** The F9 key exists for retrieving previously executed commands
** The F1/HELP keys exist for accessing the second level of the
messages.
** Command prompting is provided by F4 or by placing a ? in
front of the command
** The commands are logged to the job log and can be executed
again as commands (for example if the command entry display
was accessed)
** If a command is prompted for and exceeds the two lines
available, it will still be properly executed and can be
retrieved with F9.
** If the user is LMTCPB(*YES), the command line will reject the
request unless the command specified is ALWLMTUSR(*YES).
Options
-------
** If an option is successful (no escape message), the messages
received by the program (sent by your application) do not
appear on the display.
** A sample is shown for how to place a completion message on the
display.
** Two forms of error handling are shown:
-- If an option is unsuccessful (escape message occurs),
the program does DSPJOBLOG and sends a message to
QSYSOPR informing the operator that an option has
failed. Options are normally well tested functions
that if they fail you want to ensure that the proper
debugging information exists. You could send a message
to a different queue. The operator sees a status
message while the job log is being printed and a
general failure message when completed.
-- If an option is unsuccessful (escape message occurs),
the messages associated with the error are placed in
the message subfile.
Message logging differences
---------------------------
There is a difference in how messages are sent to the message
subfile. When a system menu has a command line, any escape message
is sent as a diagnostic message. Since other diagnostic messages may
also occur, this can make it difficult to determine which is the
actual escape message. The CMDLINE function displays the escape
messages as escape messages.
Restrictions
------------
** If a command is prompted for, the command string to be
executed cannot exceed 512 bytes.
** If F9 is used, only commands executed from this invocation of
the program can be retrieved.
- If F9 is used, the previous 100 commands can be retrieved.
Usage
-----
The demonstration program exists so you can try the function by
specifying:
CALL TAACMDBC
The intent of the code is that you would copy it for your application
use.
Prerequisites
-------------
The following TAA Tools must be on your system:
SNDESCMSG Send escape message
SNDSTSMSG Send status message
Implementation
--------------
The demonstration program is ready to use.
To implement your own requirement do the following:
** Use CPYTAA to copy the following members to your own source
file(s) and use your own source member names.
Member Type
------ ----
TAACMDBC CLP
TAACMDBD DSPF
TAACMDBR RPG
** Modify the DDS source. Statements within the source describe
what should be modified.
-- At about statements 9.00 - 10.00 is the text for the
title of the display.
-- At about statements 17.00 - 30.00 are the options that
are valid and their text descriptions. These begin on
the display on line 6 and can go thru line 17 (room for
12 options). Change the options and the text to meet
your needs. A two digit option is valid. The options
must be digits 0 -9.
Create the display file.
** Modify the RPG source. Statements within the source describe
what should be modified.
-- At about statement 3.00 is the name of the display
file. Use the one you created instead of TAACMDBD.
-- At about statement 13.00 is the name of the CL program
that will be used. Insert your name instead of
TAACMDBC.
Create the RPG program.
** Modify the CLP source. Statements within the source describe
what should be modified.
-- At about statement 4.00 is the name of the display
file. Use the name that you created instead of
TAACMDBD.
-- At about statement 23.00 is the name of the display
file in an OVRDSPF command. Use the name that you
created.
-- At about statements 96.00 - 124.00 are where the
options are handled. Modify the samples as shown.
Leave the GOTO and MONMSG commands in place. Add more
options to match what you specified for the display
file.
Do not include any completion messages for your options
to appear on the display at this point in the code.
See the later discussion of completion messages.
-- At about statement 215.00 is where the RPG program is
called the first time. Change the name to the program
name you created instead of TAACMDBR.
-- At about statement 258.00 is where the job log is
printed if an error occurs on an option. The output
will be directed to the OUTQ described for the QPJOBLOG
file. You can direct this output to a special file by
doing an override at this point. Note that this
technique is effective during a job, but cannot be used
to direct the job log at the end of the job.The code
you would add is:
OVRPRTF FILE(QPJOBLOG) OUTQ(xxxxx) +
USRDTA(CMDLINE)
DSPJOBLOG OUTPUT(*PRINT)
DLTOVR FILE(QPJOBLOG)
-- At about statement 268.00 is where a message is sent to
QSYSOPR to describe that one of the options has failed
and a job log has been printed. You can change this to
a different message queue, send it also to a
programmer's message queue, change the text, etc.
-- At about statements 296.00 - 301.00 is where you can
insert any completion messages for options that were
taken. This is often desirable if an option does not
perform an interactive display. For example, if an
option submits a batch job, it is generally desirable
to provide some feedback that the option was
successful. At a minimum, delete the sample.
-- At about statement 310.00 is where the RPG program is
called the last time. Change the name to the program
name you created instead of TAACMDBR.
Create the CL program.
You should be ready to try the function.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ----- --------- ---------- -----------
TAACMDBD *FILE DSPF TAACMDBD QATTDDS
TAACMDBC *PGM CLP TAACMDBC QATTCL
TAACMDBR *PGM RPG TAACMDBR QATTRPG
|
