VM/ESA Graphical User Interface Facility
Readme File
VM/ESA GUI Facility - Readme File
The purpose of this file is to provide hints and tips regarding
installation and use of the VM/ESA Graphical User Interface Facility (CMS GUI API and CMS Desktop),
as well as highlight some
portions of the library documentation. This document should be
viewed as a supplement to the information found in
the VM/ESA publications: "VM/ESA Graphical User Interface Facility (SC24-5789)"
and "VM/ESA Distributed GUI Toolkit (SC24-5724)".
This Readme file is divided into
two major sections&mdash.one for the system programmer installing the
VM/ESA Graphical User Interface Facility,
and the other for people using the CMS Desktop
or a local application using the CMS GUI API
(Distributed GUI Toolkit).
The system programmer is
encouraged to read both major sections of this Readme file, and to make
the General User section available for everyone
using the CMS Desktop
or applications developed using the CMS GUI API.
The information contained in this Readme file was collected from
customer experiences using the CMS Desktop in the extended Beta program,
system test experiences, and the formal documentation.
It is hoped that the presentation of this information assists in
properly setting the expectations of those who use the CMS Desktop
and assists in answering questions that may arise during the
installation of the VM/ESA Graphical User Interface Facility or use of the CMS Desktop.
As people have become exposed to the VM/ESA Graphical User Interface Facility, through either early
use of the facility or through presentations, one common misconception
has arisen. The CMS Desktop (CMSDESK command) has many times been
equated with the VM/ESA Graphical User Interface Facility. In other words, people equate the
VM/ESA Graphical User Interface Facility
with what they find in the CMS Desktop. This is
exactly opposite of what was intended with the VM/ESA Graphical User Interface Facility.
The VM/ESA Graphical User Interface Facility is intended to be an environment for developing
applications on VM that utilize workstations for presentation of the
application user interface. Thus the rich API provided with the
VM/ESA Graphical User Interface Facility should be the central focus. In order to
provide a useful, functioning, example application
for customers to become familiar with the
CMS GUI API, an application known as the CMS Desktop has been provided.
This application allows a VM/ESA V2 R1
user to perform some basic VM tasks,
such as manipulating files on minidisks or in SFS directories and
maintaining their reader. In addition, it also provides a means to
launch local applications using the CMS GUI API.
Therefore, the CMS Desktop should not be viewed as the sum total of
the VM/ESA Graphical User Interface Facility or
a full and complete interface to VM/ESA. It is rather a place for
application developers to start when becoming familiar with
the CMS GUI API, as well as an application VM/ESA V2 R1 users can use
to see what can be done with the CMS GUI API.
The following sections contain
information about
installation, host performance of the CMS Desktop,
usage tips for the CMS Desktop, and various workstation agents.
The "VM/ESA Program Directory for Graphical User Interface Facility"
includes a table that identifies the minidisks and SFS directories
where various parts
associated with the CMS GUI API and CMS Desktop are placed during
the installation process.
The parts required for use of the CMS GUI API and CMS Desktop are built on the
2VMVMY10 29E and 400 minidisks.
The workstation agents are located on the
400 minidisk, and all other runtime code is located on the 29E minidisk.
The installation process does not define what the production runtime
disk should be. Rather, it is left up to each installation to decide
where to locate the production runtime code. The only requirement is
that this code must be copied to a location that is accessible by
all users who run CMS GUI API applications or use the CMS Desktop. Thus an
installation may choose to locate the runtime code on the 19E minidisk.
Because the CMS GUI API and CMS Desktop are closely tied to a
particular level of CMS, an installation may choose to copy the runtime
code directly to the CMS 190 minidisk.
In either case, it is important to recognize that both the runtime
code and the workstation agent code must be accessible to those who
use the CMS GUI API and CMS Desktop.
The VM/ESA Graphical User Interface Facility is serviced through normal service channels.
Portions
of CMS that directly support the VM/ESA Graphical User Interface Facility may have service included on
the
standard VM/ESA RSU. The CMS Desktop and CMS GUI API are serviced by a
new OpenExtensions RSU. This RSU contains service for not only the
VM/ESA Graphical User Interface Facility, but also the VM/ESA OpenExtensions
DCE feature and VM/ESA Shell and Utilities
feature. A description of the product service upgrade procedure and
the installation of RSU tapes can be found in the "VM/ESA Service
Guide (SC24-5749)".
When installing service, care should be taken to service the base
VM/ESA components first using the base RSU. After the base service is
completely installed, the OpenExtensions RSU can then be
installed. This ensures that any base component service
requisites are already installed, so that
service levels for the base components and OpenExtensions RSU
components remain
synchronized.
While it is not required that code for the VM/ESA Graphical User Interface Facility
be installed in saved segments, it is strongly recommended that
installations use the two segments provided:
- GUICSLIB
- contains the CSL library (VMGUILIB) that supports applications
written with the CMS GUI API, including the CMS Desktop. This segment is
loaded automatically when the first application using the CMS GUI API is
started.
- GUIVMGUI
- contains execs and modules that make up the CMSDESK command,
(CMSDESK LSEG).
This segment is
not loaded automatically. The segment must be loaded
explicitly with a SEGMENT LOAD CMSDESK command. This command can
be placed in SYSPROF EXEC or a locally written "front-end"
exec to the CMSDESK command.
The "VM/ESA Program Directory for Graphical User Interface Facility"
identifies the steps required to define and save
the segments associated with the VM/ESA Graphical User Interface Facility. Both of
these segments can be located above the 16MB boundary. The GUIVMGUI
segment, in particular, should
be located high in storage because its size
is 7MB.
It may be wise to enter a QUERY SEGMENT after invoking the
CMSDESK command
to check that the two segments are indeed being used.
If you are installing the LE/370 feature, you will run into
conflicts with the segment definitions for the VM/ESA Graphical User Interface Facility segments and
the LE/370 segment. Information APAR II09462 describes this
conflict and the
recommended solution. The APAR text has been
included at the end of this file.
In order to support the VM/ESA Graphical User Interface Facility, service has been added to CMS in
VM/ESA V2 R1. It is important to ensure that this service is applied to
CMS before attempting to use the VM/ESA Graphical User Interface Facility. The requisite service is
included on the 9603 RSU for VM/ESA V2 R1. One component in particular,
CMS Pipelines, has received service on which
the VM/ESA Graphical User Interface Facility depends.
Consequently, it
is very important that the CMSPIPES segment be resaved following
the application of service and prior to using
the CMS GUI API or CMS Desktop.
If the CMSPIPES segment is not updated prior to using the VM/ESA Graphical User Interface Facility,
various pipelines error messages may occur.
The recommended virtual machine size for users of the CMS Desktop is
24MB. Testing and other experiences have shown that
this virtual machine size
provides sufficient storage to open multiple CMS Desktop windows, as well
as perform file searches across a realistic number of files.
While this is the recommended virtual storage size, an
additional study
was conducted to determine storage requirements for the CMS Desktop. A
series of tests was conducted running the CMS Desktop in a virtual machine
with 7MB of storage. In this environment it took:
- 1.3MB to display the CMS Desktop window
- 1.4MB to display the File Search window
- 1.7MB to display the Minidisk A window with 282 files on
the A-disk
- 1.7MB to display the Note window (to create a new note)
- 8.0MB to conduct a file search across 15,000 files
With the exception of conducting a file search,
most windows on
average required
approximately 1.5MB of storage. Thus, opening one window
in addition to the CMS Desktop window would require approximately 3MB
of storage.
When a window is closed, the storage utilized by the window is
released. The above analysis indicates that it would be possible
to run the CMS Desktop in a 7MB virtual machine as long as old windows were
closed before new windows were opened. It would, however, not be
possible to conduct a file search across 15,000 files, since that
would require 8MB of storage.
If IP is selected as the protocol for communication between
the VM host and a workstation, then the CMS Desktop or any application
written with the CMS GUI API
must determine
the user ID of the TCP/IP virtual machine.
This information is obtained
by first checking the TCPIPID entry in the CENV group in the user's
LASTING GLOBALV file. If this entry does not exist, then an attempt is
made to locate the TCPIP DATA file on any accessed disk. If this file
is located, the CMS Desktop
uses the user ID designated by the TCPIPUSERID
entry. If neither of these sources are available, the user ID defaults
to TCPIP. The TCPIPID entry can be set in the LASTING GLOBALV file by
entering the following command:
GLOBALV SELECT CENV SETP TCPIPID userid
where userid is the TCP/IP virtual machine name.
When installing and setting up AVS, the default LOGMODE setting is
typically #INTER.
With this LOGMODE, users of the CMS Desktop are allowed to have
four concurrent sessions. Within the CMS Desktop, this limitation would
translate into being able to open windows associated with 4 CMS Desktop
functions concurrently. For example, a CMS Desktop user could have the
Reader window, Open window, and Reply window open in addition to the
CMS Desktop window. When an attempt was made to open a window associated
with another CMS Desktop function, the request would be queued until one of
the four sessions in use was released. No message is given to the
CMS Desktop user that this is happening.
System programmers should carefully review the default LOGMODE used
when setting up the AVS gateways for use with the VM/ESA Graphical User Interface Facility.
The "VM/ESA Graphical User Interface Facility (SC24-5789)"
manual identifies workstation hardware and software
requirements for using the CMS Desktop. Portions of that information
are emphasized here:
- Programmable Workstations Supported
- 486 or pentium processor
- 2MB of available disk space
- 8MB of memory
- RS/6000 Workstations Supported
- RS/6000 Model 340 or higher
- 8MB of available disk storage
- Workstation Operating Systems Supported
- RS/6000 Operating Systems Supported
- AIX V3.2.5 with AIX Windows installed, or higher
The preceding information highlights the hardware and
workstation based operating system requirements. Refer to the
"VM/ESA Graphical User Interface Facility (SC24-5789)"
manual for a complete list of requirements.
The CMS GUI API and CMS Desktop are only supported on VM/ESA V2 R1
and CMS 12.
Testing has shown that running the CMS Desktop under CMS 12 on a VM/ESA V1
R2.2 CP can cause unpredictable results. This is especially true if SFS
servers are accessed that are at the VM/ESA V1 R2.2 level. Running a
backlevel copy of CP with a new CMS is not a supported
environment.
Because the CMS Desktop interfaces with the virtual machine reader and
uses the CMS NOTE and SENDFILE commands,
careful testing should be conducted if
modified copies of the NOTE and SENDFILE commands are used.
For example, when the TCP/IP for VM product is installed, the
versions of NOTE (NOTETCP) and SENDFILE (SENDTCP) are typically
renamed NOTE EXEC and SENDFILE EXEC. If an installation has
also made modifications to these execs to tailor the function to
local needs, those modifications should be tested carefully with
the CMS Desktop. Modified
copies of these commands may behave in ways not expected by the
CMS Desktop and thus produce unpredictable results.
In order to use the CMS GUI API, the proper workstation agent must be
downloaded from the host VM system and installed on a workstation. In
addition, whenever maintenance is applied to the workstation agent, the
updated workstation
agent must be downloaded and reinstalled on all workstations.
Note: The workstation agent version and level
can be determined by accessing the
"Help" menu bar choice and selecting
the "About..." menu choice.
In a large enterprise, distributing and maintaining the workstation
agent on individual workstations can
pose administrative and logistical difficulties.
In order to avoid problems caused by keeping numerous end user
workstations at the proper level of workstation agent, it is recommended
that the workstation agents be downloaded to servers. This way, one
copy of a particular workstation
agent can be utilized by many end users. In
addition, the smaller number of workstation
agents can be more easily maintained
when changes are made.
If the workstation agent is started from a directory
other than from the directory
where the workstation files were installed,
the HELP files may not be found. For OS/2 and Microsoft Windows,
it is suggested that you start the agent in the same directory
where the workstation files reside. For AIX, you need additional
steps to find the HELP files when the agent is started
from a another directory.
See
"VM/ESA Graphical User Interface Facility AIX Workstation Agent"
for information on accessing the HELP files on AIX workstations.
One question that is typically foremost in the minds of system
programmers when installing a new feature is: what impact will
installing this new feature have on my existing environment regardless
of whether it is used or not? The next question may be:
what impact will use of this new feature have on my system?
The following paragraphs provide some summary
information to assist in planning for the installation of the CMS GUI API and
CMS Desktop.
For more detailed information, refer to
VM/ESA V2R1.0 GUI Performance Report.
Installing the CMS GUI API and CMS Desktop has a negligible effect on
your existing environment. Performance measurements show that there
is no effect on the number of nonshared (per user) real storage
requirements when the CMS GUI API and CMS Desktop are installed but not used.
Thus, it should be possible to install the service to CMS required for
the CMS GUI API and CMS Desktop without impacting your existing VM environment.
Use of the CMS Desktop has an impact on the real storage
requirements, paging slots, and processor utilization of your host
VM/ESA system. The use of saved segments for the CMS Desktop code and the
CMS GUI API CSL library reduce the real storage impact. On average, a
single CMS user that calls the CMS Desktop, uses the file manager, views
a minidisk with 500 files, XEDITs a file, and then quits the CMS Desktop
uses 998 nonshared pages. This number is roughly 20%
higher if saved segments are not used. Tests show that main storage
requirements associated with a CMS Desktop user are substantially higher
than those associated with users doing analogous work in a traditional
3270-based environment. For example, when XEDIT is called from the
CMS Desktop, about 530 nonshared pages are referenced. When XEDIT is
called in a 3270 environment, 100 nonshared pages are referenced.
Tests show that while the CMS Desktop is in use, a large increase in
total pages used by that virtual machine occurs.
However, when
the CMS Desktop is closed, most of these pages are released. A net
increase of about 30 pages was observed for virtual machines that opened
the CMS Desktop, performed some work, and then closed the CMS Desktop.
These pages persisted until CMS was IPLed again
in the virtual machine.
Most of these pages are associated with the use of CMS multitasking
by the CMS Desktop.
The results of these tests indicate that a potential increase in DASD
paging space may be required if large scale use of the
CMS Desktop is anticipated.
Additional tests were conducted to determine the
effect of users starting the CMS Desktop and then
letting the CMS Desktop go idle while performing other CMS work on a 3270
session. These tests revealed that
nonshared real storage requirements increased
by about two pages per user. This was due mainly to the effects of using
CMS multitasking. When the CMS Desktop was later closed, the two pages
observed in the idle user tests still remained. Thus, users who start
the CMS Desktop,
let it go idle, then later close the CMS Desktop increase
real storage requirements by about two pages per user.
For CPU usage, tests demonstrate that host system CPU usage
required to accomplish a given function through the CMS Desktop is
substantially higher than the CPU usage required to accomplish a similar
function through a 3270 interface. For example, total CPU usage to
display one reader file using the CMS Desktop was measured at about 0.48
seconds. On the same system, the CPU time required to display the same
reader file using the RDRLIST command
was measured at about 0.03 seconds.
End user response time is affected by average host
processor utilization (CPU contention), the choice of communications
protocol used (TCP/IP or APPC), the workstation processor speed, and
available workstation memory. For example, tests conducted with average
processor utilizations of 17% and 69% resulted in increases in average
response time from 1.2 seconds to 1.5 seconds. Tests further showed
that response times were higher under certain circumstances
when the APPC protocol
suite was used instead of the TCP/IP protocol suite.
Function startup time within the CMS Desktop was slower when using APPC
due to the session start overhead. However, for a
particular function, once the session is started, both communication
alternatives appear to have equivalent performance.
Workstation
processor speed was also shown to have a large effect on CMS Desktop
response time.
Further information on each of these factors can be
obtained from the
VM/ESA V2R1.0 GUI Performance Report.
The CMS Desktop and other applications that use the CMS GUI API reside
completely on a VM/ESA host and must be started within a virtual
machine on the host. As a consequence, typically a 3270 session
is established in order to enter the command associated with the
CMS GUI API application. This does not mean that the application
that is started from the command line uses the 3270 emulator session.
The CMS Desktop
and other CMS GUI API applications do not use 3270 sessions, nor are they
related in any way to the 3270 sessions used to enter the specific
host command.
It is possible
to call the CMS Desktop or another application
using the CMS GUI API,
without first logging on to the host VM/ESA system.
The method to
accomplish this differs depending upon whether your workstation is
using TCP/IP or APPC to communicate with the VM/ESA host.
It is important to recognize that with either of the
methods, the
workstation user does not have access to a VM command line. Thus, it
is not possible to run CP or CMS commands outside of the
context of what is available through the CMS Desktop or local application
using the CMS GUI API.
If the host virtual machine spools the console, it is possible
to capture the output of any CP or CMS commands that are run on the
host as a result of using the CMS Desktop or local application.
Without spooling the console, any
error messages associated with commands on the host are lost, unless
trapped and presented in workstation windows by
the CMS GUI API application.
While the following methods allow the
CMS Desktop or a CMS GUI API application to be called
without starting a 3270 session, it is important to remember that it is
also possible to log on to the VM host system, start a CMS GUI API
application, and then disconnect from the host to remove the 3270
window.
- TCP/IP
With TCP/IP, the REXEC facility can
start the CMS Desktop or a CMS GUI API application
from the workstation desktop without first
establishing a 3270 session. In order to use the REXEC facility,
follow these steps:
- Create a program object on the workstation desktop. The command
line associated with program object should call REXEC with parameters
specifying the VM host address and the CMS GUI API application.
For example, a
program object named CMSDESK could be created on an OS/2 desktop. The
path and file name associated with the program object would be
d:\TCPIP\BIN\REXEC.EXE. The optional parameters included in the program
object would be a VM host name or IP address, and CMSDESK.
- Update the PROFILE EXEC on the host VM user ID to link and access the
TCP/IP client minidisk (usually TCPMAINT 592).
- Update the PROFILE EXEC on the host virtual machine to
issue a SET WORKSTAT IP x.xx.xx.xx command, with the IP address
of the workstation that calls REXEC.
- Update the PROFILE EXEC of the host virtual machine to bypass
starting any full screen applications if the virtual machine is
running disconnected.
- Ensure that the host virtual machine is logged off.
Once all of the necessary preparations are made, the workstation user
can double click on the new program object to call REXEC.
When this is done, a window is displayed
requesting the host user ID name and host password. When both of these
are entered, the CMSDESK Connection Pending window is displayed on
the workstation.
Note: CMS GUI API programs do not use the virtual console and do not
communicate using the REXEC connection. Thus, REXEC
detects that the REXEC connection is idle, and after an
installation-defined amount of time (usually four minutes), terminates
the REXEC connection. This causes the host VM user ID to be logged
off. Thus, to use this method for long term CMSDESK usage,
changes would have to be made to lengthen the timeout period for REXEC.
Note: Since REXEC autologs the host VM user ID to process the
specified command, you must ensure that the host VM user ID is logged
off prior to calling REXEC.
- APPC
You can use CMS APPC private resource server support to start CMS GUI API
programs without logging on to VM. The following instructions
illustrate how to do this for the CMS Desktop. Refer to the
"VM/ESA Graphical User Interface Facility (SC24-5789)" manual for more information.
- Place the GUIAUTO EXEC (sample included in the
"VM/ESA Graphical User Interface Facility (SC24-5789)" manual)
on a disk or directory
automatically accessed by your virtual machine when it is logged on.
- Modify your PROFILE EXEC to include the commands SET SERVER ON and
SET AUTOREAD OFF. Also modify the PROFILE EXEC to remove any commands
that would call full screen applications or SET FULLSCREEN ON.
- Install the sample CMSDESKR.CMD file on your workstation (included
in the "VM/ESA Graphical User Interface Facility (SC24-5789)" manual).
- Activate the CPI Communications REXX interface by entering the
CPICREXX command from any OS/2 command line. Because this command need
only be issued once when your workstation is started,
you can place this command in the STARTUP.CMD file.
- If the workstation LU name that you are using for APPC is not your
control point (CP) name, then you must indicate the alias assigned to
the APPC LU name by entering:
SET APPCLLU=alias
There must not be any
blanks between the equals sign and the alias name. This command
sets an OS/2 environment variable named APPCLLU for the current
OS/2 session used by CPI Communications. This variable,
if set, is used by CPI-C during the Initialize_Conversation call
issued by CMSDESKR.CMD to determine the local LU on which to start the
Transaction Program instance.
- Enter CMSDESKR avslu vmuserid vmpassword
on your workstation, or
create a program object on the desktop that specifies CMSDESKR as the
path and file name to call, and avslu vmuserid vmpassword
as the
parameters. In this example, avslu
is the fully-qualified LU name
(netid.luname) or the alias of an AVS private gateway on your host VM
system.
When the CMSDESKR command is entered or the program object is
selected,
the host virtual machine is autologged by CP (unless it is already
logged on) and the transaction program specified in CMSDESKR is
started.
Note: This method of starting a CMS GUI API application is not constrained by
the timeout defaults associated with REXEC. It is, however, slightly
more complex to set up.
When working with the IBM Support Center to resolve VM/ESA Graphical User Interface Facility
problems, you may be asked to obtain a VM/ESA Graphical User Interface Facility communications trace.
To start the trace, enter the command:
GLOBALV SELECT CENV SET DTTRACE 3
This creates GUIAPPC DTTRACE A or GUITCPIP DTTRACE A, depending
on the connectivity method you use. If the trace file already exists,
the trace records are appended to the end of the file. When
obtaining new traces, be sure to erase or rename the old trace file.
To stop the trace, enter the command:
GLOBALV SELECT CENV SET DTTRACE
Only applications started after the trace has been activated
appear in the trace file.
Applications that already have windows displayed are
not traced.
Many of the operations associated with CMS Desktop functions are
implemented on the host as REXX execs with imbedded pipelines. Since
this is the case, it is tempting to resolve problems by
simply tracing the host execs. However, due to the manner in which the
CMS Desktop code is implemented on the host, it is not possible to view an
interactive exec trace (such as with SET EXECTRAC ON).
The following is one method of
tracing the host execs:
When the specified exec is called through interaction with the
CMS Desktop, a file with the trace output is placed on your
A-disk. Each invocation of the exec writes a new version of the
trace file. If you want each invocation of the particular
exec appended to a single trace file, substitute:
'| >> GUIxxxx TRACE A'
for
'| > GUIxxxx TRACE A'
To resolve problems more quickly,
gather all information from the workstation
and the host.
For example, if a trap error occurs on the workstation, display
and note the register contents. Also, make note of the workstation
operating system level, the function being used (file manager, note
etc.), the communication protocol being used (APPC, or TCP/IP), and the
level of the workstation agent. The level of the workstation agent can
be determined by clicking on the
"Help" menu bar choice on the Workstation Agent window
and selecting
the "About..." menu choice.
This displays a
window that identifies the service level of the
workstation agent. On the VM host side, record any host messages that
may appear on the 3270 console, the CMS service level, and the
segment load address for the CMSDESK logical
segment.
To obtain the segment address,
enter the CMS command QUERY SEGMENT and note the address under
the heading "Location" for CMSDESK.
Before issuing the CMSDESK command, a SET WORKSTATION command must
be issued specifying your IP or LU address. If a host name is used
instead of a dotted-decimal internet address, then the C runtime
library (SCEERUN LOADLIB) must be included in the list of libraries
specified in a prior GLOBAL LOADLIB command, before running CMSDESK.
This is necessary for host name resolution to take place.
If SCEERUN LOADLIB is not included in the list of libraries,
message DMS3208E will be issued with reason
code 99606. For a list of reason codes possible during host name
resolution, see Reason Codes under the WorkstationGetAddress CSL
routine in the
"VM/ESA Graphical User Interface Facility
(SC24-5789)" manual.
Because there is no explicit function within the CMS Desktop to provide
access to the CP/CMS command line, many users may be tempted to enter
CP or CMS commands from the command line of the XEDIT window. This is
XEDIT subcommands
are fully supported from this command line. Some CP and CMS commands
may be supported, depending on the type of I/O they issue. There is
more information about console I/O in the following section.
It is also possible to create local CMS GUI API applications that can be
added to the CMS Desktop, which perform I/O to the virtual console. These
applications are also be subject to the limitations regarding 3270
console I/O discussed in the following section.
CP commands called through the CMS Desktop
that cause output to appear on the virtual console, do not,
in general,
cause problems within the host virtual machine or with the user's
ability to interact with the CMS Desktop. Console I/O resulting from CP
commands does not utilize any of the CMS I/O routines to write to the
virtual console. The CMS Desktop, however, is not able to trap any
of the output from CP commands and displays it in a window on the
CMS Desktop workstation. If the virtual machine is disconnected and
the virtual console is spooled, the results of the CP command
appear in the spooled console.
Problems may
result if the 3270 emulator session is placed into a More/Holding
state as a result of CP I/O to the virtual console. In this case,
interaction with the CMS Desktop is inhibited until the More/Holding
condition is removed. In order to prevent More/Holding conditions
from arising, the following commands may be entered in the host
virtual machine:
SET FULLSCREEN ON
or
CP TERMINAL MORE 0 0
CP TERMINAL HOLDING OFF
The effect of applications or CMS commands called through the
CMS Desktop depends upon how the CMSDESK command was entered. The
CMSDESK command supports two invocation options that determine
how the CMSDESK command uses CMS multitasking support.
BACKGROUND, which is the default option,
specifies that the CMSDESK
command run in background mode. When the CMSDESK command runs in
background mode, it runs as child process of the CMS root process.
Since the routines within CMS that perform I/O operations to the virtual
console are designed to run as part of the CMS
Command process, running programs that interact with the virtual
console,
from the within the CMS Desktop, when
it is
running in background mode, is not supported.
It is possible that starting such a command or
application can result in a failure within the host virtual machine.
When the CMSDESK command is entered with the BACKGROUND option,
the CMS command
line is available for use through a 3270 emulator session.
The CMSDESK command can also be entered with the
FOREGROUND option. Specifying the FOREGROUND option causes the
CMSDESK command to be started as a child process of the CMS Command
process. When CMSDESK is started in this manner, it is possible to
call host programs from the CMS Desktop that may interact with the
virtual console, subject to the following limitations.
When
the CMSDESK command is entered with the FOREGROUND option, it is not
possible to enter any CMS commands from the command line of a 3270
emulator session. The CMS command line will not be free until the
CMSDESK command ends. All host commands would need to be started
from the CMS Desktop through a locally written CMS GUI API application that
provides such a capability.
See the "VM/ESA Graphical User Interface Facility (SC24-5789)" manual
for more
information on the FOREGROUND and BACKGROUND options.
When the CMSDESK command is entered with the FOREGROUND option, it
is possible to call CMS commands and host applications that perform
line-mode I/O to the virtual console. If these commands or applications
are entered from the XEDIT command line, the line-mode responses are
displayed on the workstation in a CMS Output window. It is also
possible to call CMS commands or applications that perform full
screen I/O to the 3270 emulator session. In this case, the output of
the CMS command or application is displayed on the 3270 emulator
session. Interaction with the CMS Desktop is inhibited until the
application or CMS command is ended.
Applications that do not close their console path may appear to hang
when they end. This is due to CP not automatically returning the
console to line-mode and clearing the screen
after the application ends. The next line-mode write
performed to the 3270 emulator session (for example, when a message is
sent to the virtual machine user ID) returns the virtual console to
normal.
Code was added to the CMS Desktop to eliminate this problem for
applications that close their console path and for XEDIT. In these
cases, CONSOLE CLEAR is called to simulate CP clearing the virtual
console.
Refer to the "VM/ESA Graphical User Interface Facility (SC24-5789)", Appendix A, for more
information on this subject.
If it is anticipated that many users of the CMS Desktop will
call applications from the CMS Desktop that perform I/O to the virtual
console, it is recommended that a front end exec be created for
the CMSDESK command.
This exec could issue a SEGMENT LOAD for the CMSDESK logical
segment, determine the proper workstation ID to set, using the
GUIAUTO EXEC or a TCP/IP equivalent,
and then call the CMSDESK command with the FOREGROUND option.
If this front end exec were on a common minidisk, it would then be
possible for the system programmer to control whether FOREGROUND or
BACKGROUND is the default options when users enter the
CMSDESK command.
One further consideration pertains to execs written in the EXEC 2
language. Execs written in the EXEC 2 language should not be called
from a CMS Desktop application, from a VM/ESA Graphical User Interface Facility XEDIT environment, or
from a 3270 emulator session when the VM/ESA Graphical User Interface Facility is being used.
This is because the EXEC 2 interpreter uses WAITRD rather than the
CONSOLE macro or the VSCREEN command.
The CMS GUI API can be used from programs written in REXX, C, C++,
and assembler language.
Binding files are provided that allow the API
routines, which are resident in a VM Callable Services Library, to be
accessed by programs written in these languages.
The "VM/ESA Distributed GUI Toolkit (SC24-5724)" manual
describes the CMS GUI API.
The CMS GUI API has a limitation on the size of its objects. CMS GUI API
objects cannot be larger than 64KB bytes. This limit is most commonly
encountered when using the DtString object with a string greater than
64KB bytes. When the object exceeds the 64KB byte limit, a CMS abend
usually results. This problem can also occur when
creating a table of pointers that has over 16KB 4-byte pointers.
Currently, the application code has to check and prevent
CMS GUI API objects from reaching this 64KB limit.
In the "VM/ESA Distributed GUI Toolkit (SC24-5724)" manual, the
description of the ReadOnly attribute of the DtEntry object on
page 254 has the explanation for DtTrue and DtFalse reversed.
It should read, "If the ReadOnly attribute is set to DtFalse,
the user can change the contents of the entry field. If the
ReadOnly attribute is set to DtTrue, the user cannot change the
contents of the entry field."
The updates to the CMS GUI API
for the June 1996 RSU contain a change to
the spacing of gaps (DtGap object). In this version of the
CMS Desktop, some gaps were removed to compensate for this change.
Customer applications may also need to make this adjustment.
Creation of applications using the CMS GUI API
can require a substantial number of
instructions outside of the program logic to build and maintain the
graphical elements of the application. To assist in developing the
graphical elements in an application, IBM has created a tool that is
a visual application builder.
This tool may in the
future form the foundation of a full-function product, enabling visual
application development in the CMS GUI API environment.
This tool is workstation based and runs on many platforms,
such as MS Windows, MS Windows NT, and
OS/2. It provides a visual-based, interactive environment for the
application developer using the CMS GUI API to define
application windows and visual objects on the windows.
Once all of the elements and interactions between visual objects
are defined, the tool
generates source code for the program in either C++ or REXX. The CMS GUI API
application
developer can then take the source code generated by the tool and add
to it any program logic that is required, as well as coding for
complex object interactions.
Use of the tool does not eliminate the need to be familiar with the
CMS GUI API. Rather, it simplifies and speeds the task of creating CMS GUI API
application programs, allowing the developer to spend more time
concentrating on program logic and less time on the mechanics of
building the objects to display a workstation window. The tool
also does not provide a mechanism for ongoing maintenance of the
generated source code.
The application developer maintains the source code
produced by the tool using normal CMS methods.
IBM intends to make this tool available as is, free of charge, via
the Internet. Because this
GUI builder is a tool, no formal IBM warranty
service is supplied for it.
It is anticipated that a forum will be available through
the IBM VM/ESA World Wide Web home
page to discuss use of this tool.
Documentation for this tool will also be available through the VM/ESA
home page. For information on this tool, please visit the IBM VM/ESA
home page at:
http://www.vm.ibm.com
As more information on this tool becomes available, the IBM VM/ESA
home page will be updated, as well as this file in the RSU memo.
To enhance application performance,
the following general suggestions should be remembered when creating
applications with the CMS GUI API:
- Minimize the number of objects in a window.
- Minimize the number of workstation/host interactions.
- Minimize the number of bytes that are transferred between host and
workstation.
- When possible, update the objects in the existing window rather than
rebuilding and relaunching the window.
- Do not acquire the same attribute handle multiple times. Get it
once, save it, and reuse it.
The appearance of CMS Desktop windows displayed on the workstation is
significantly affected by the font selected through the Workstation
Agent window.
If a large font is selected, windows displayed by
the CMS Desktop may not fit
entirely on the physical workstation screen.
When this problem occurs, select the "Options"
menu bar choice
in the Workstation Agent window, then
select the "Set Font..." menu choice
and choose
a smaller nonproportional font. The font selection made does not take
effect until the workstation agent is stopped and restarted.
The change, however, remain in effect for subsequent invocations of
the workstation agent.
The font selection depends not only upon the workstation platform
being used, but also upon the display type (for example,
VGA, SVGA, XGA) and resolution. Thus,
it is not possible to make any categorical recommendations for default
font. The proper font selection must be made by the individual
CMS Desktop user as different functions are used.
Due to some font changes in the June 1996 RSU, users may see some
slight differences in the size of some windows from the previous level
of the function. You may decide to choose a smaller font to get a
window size comparable to what you are used to viewing.
The XEDIT window is one of the CMS Desktop windows where the use of a
font tailored to the characteristics of your workstation is
especially important. Because the number of lines displayed by XEDIT
through the CMS Desktop is determined by the characteristics of your
3270 emulator session,
a smaller nonproportional font is in many cases the
best choice.
For more information, see "Effects of Host PROFILE XEDIT".
The following are font preferences from participants in the VM/ESA Graphical User Interface Facility
Beta Program who were using the OS/2 platform.
- 14" VGA
- 4 pt. System VIO
- 17" SVGA
- 10 pt. System VIO
- 17" 1280x1024
- 10 pt. System Monospaced
- 21" SVGA
- 14 pt. System VIO
Because the VM/ESA Graphical User Interface Facility workstation
agents use the native workstation platform to render
windows, it is possible to use the capabilities of the workstation
software to change the colors associated
with VM/ESA Graphical User Interface Facility windows. Each workstation
platform has a different means of doing this.
One difference to note within the CMS Desktop is the XEDIT window.
With this window,
the colors displayed on the workstation can be modified
through the host PROFILE XEDIT. One area of the window, however, that
cannot be changed from the host is the space between the entry fields
in the file area portion of the window.
The PROFILE XEDIT is discussed
in "Effects of Host PROFILE XEDIT".
On the OS/2 platform, for example, the VM/ESA Graphical User Interface Facility workstation
agent uses the default
color scheme associated with the OS/2 desktop to render all windows.
In order to change the colors used with an application such as the
CMS Desktop, the color scheme
associated with the OS/2 desktop must be changed. This also
has the effect
of changing the window color scheme for other OS/2 applications that
are not associated with a specific color scheme.
In order to change the background color for all of the CMS Desktop windows,
including the XEDIT window, perform the following steps.
The Folder Background, or for OS/2 2.1 the Window Background,
element listed below, is the window element that affects the
color of the spaces between entry fields on the XEDIT window.
The color of the entry fields is changed using the EntryField/Listbox
Background color element.
- Select System Setup in the OS/2 System folder
- Select Scheme Palette
- Select the particular scheme you are using
- Modify the EntryField/Listbox Background color
- Modify the Folder Background color (or Window Background color
on OS/2 2.1)
- Close the open selections
- Press ALT, and press mouse button 2
- Drag the modified scheme to the OS/2 desktop
- Release the ALT key and mouse button 2
After completing the procedure above,
the background colors that
apply to all of the CMS Desktop windows including XEDIT are changed.
You may then need to look at some of your native OS/2 applications to
ensure that the new default color scheme is acceptable for those
applications. Satisfactory results have been obtained by changing
the two elements mentioned above to the color white.
Some of the windows in the CMS Desktop display rows of data wider than
the initial window used to display the data. These windows supply a
horizontal scroll bar at the bottom of the window to scroll from side to
side through the data. Due to the way in which the VM/ESA Graphical User Interface Facility
workstation agents
implement window elements, headings displayed on these windows are not
scrollable. Thus, when moving from side to side through the displayed
data, the window headings remain fixed.
It is possible to see labels in the heading area that are hidden from
view without expanding the size of the window.
To see the hidden labels,
place the cursor in
the heading area and press the right-arrow key on the keyboard.
This
scrolls the heading area to the right (or left if the left-arrow key is
pressed). Again, this operation is independent of the data displayed in
the text area of a window, such as the Minidisk A window.
In order to use the CMS Desktop, the address of the workstation to
which a connection should be made must be supplied to the CMSDESK
command. This
is accomplished using the SET WORKSTAT command. A problem arises,
however,
when users move between workstations to
conduct their work. In this case, the user must always find the IP
address or LUNAME of the workstation they are physically at before being
able to use the CMS Desktop.
To assist in solving this problem, Appendix B in
the "VM/ESA Graphical User Interface Facility (SC24-5789)" includes a sample exec, GUIAUTO EXEC.
This exec solves the mobility issue
for workstations connected via APPC to the VM Host. In order to use
GUIAUTO, the CMSDESK command must be started from the workstation
as a CMS Private Resource Server. When GUIAUTO is run,
the LUNAME of the workstation starting the private server
is automatically set prior to invoking the CMS Desktop.
The "VM/ESA Graphical User Interface Facility (SC24-5789)"
includes the steps necessary to start
the CMS Desktop in this manner.
If workstations are connected via TCP/IP, the mobility issue can be
solved by using TELNET to log on to the host VM system and
running an exec, such as the following example, from the
host PROFILE EXEC. This exec determines the workstation IP address
used to log on to the host virtual machine and enters a SET WORKSTAT
command prior to starting the CMS Desktop. The TCP/IP NETSTAT command
determines the workstation IP address.
/* See if user is logged on through TCP/IP. If so, get their IP */
/* address and issue SET WORKSTATION. */
user = userid()
address command
gottcp = 0 /* Need NETSTAT command */
'ESTATE NETSTAT MODULE *' /* Is it out there somewhere? */
if rc = 28 then do /* If we can't find NETSTAT, */
'EXEC VMLINK TCPIP (NOI NOTYPE PUSH' /* see if site has established */
if rc <> 0 then exit /* a nickname for TCP/IP client*/
gottcp = 1 /* disk or directory. If not, */
end /* we can't go any further. */
'PIPE cp QUERY USER' user, /* See if user is a logical */
'| spec 11-* 1', /* device (LDEV). If not, */
'| strip', /* stop now. */
'| var device'
If rc <> 0 then Signal Cleanup
If left(device,1) <> 'L' then Signal Cleanup
'PIPE cp QUERY LDEV' device, /* See who owns LDEV. We are */
'| spec w8', /* only interested in those */
'| var owner' /* owned by TCPIP user IDs. */
If rc <> 0 then Signal Cleanup
If left(owner,5) <> 'TCPIP' then Signal Cleanup
'PIPE command NETSTAT TELNET TCP' owner, /* Get IP address from TELNET*/
'| locate / LOGON AS' left(user,8)'/',
'| var resp',
'| spec w1',
'| var ipaddr'
/* If response good, use it. */
if word(resp,1) <> 'Cannot' & ipaddr <> 'IPADDR' then
'SET WORKSTATION IP' ipaddr
Cleanup:
if gottcp then 'EXEC VMLINK TCPIP (POP NOTYPE'
exit
Note: The "VM/ESA Graphical User Interface Facility (SC24-5789)" contains an error in Chapter 5 under
the heading "Automating Workstation Selection". This section should
refer to the exec listed above as AUTOIP2 EXEC rather than the GUIAUTO
EXEC on page 205. Further, the AUTOIP2 EXEC should be included in an
appendix titled "Automated TCP/IP Workstation Selection".
Most of the windows produced by the CMS Desktop are fixed size windows.
Thus, it is not possible to stretch the borders of the windows as many
workstation users are accustomed to doing. In fact, most of the
windows do not have a maximize button in the upper right-hand corner
of the window. Most windows only have a minimize button in that
location. The exceptions to this are the XEDIT window and the CMS
Help windows.
The vertical
size of these windows can be changed by stretching or contracting the
top or bottom border of the window. In addition, these windows
have
both a maximize and minimize button in the upper right-hand corner of
the window.
It should be noted that on the windows previously mentioned,
clicking on the
maximize window button has no effect on the size of the
window. On the OS/2 platform, clicking on the maximize window button
causes the window to be moved to the upper left-hand
corner of the physical
screen. However, the window does not change in size. Clicking again
on the
maximize button causes the window to move back to its original
position on the physical screen.
Even though the windows are fixed size windows, the size of the
window displayed can be affected by other factors. For example, windows
that offer a Settings menu, such as the Reader window, allow the
specification of the number of columns and rows displayed. If the
maximum number of columns and rows are selected, the resulting window
may be too large for the physical screen.
Windows such as the Reader window, also allow for the customization
of columns of data that are displayed. From the Settings
menu, it is
possible to select View, and then choose which data columns are displayed
in the window. Selecting all of the data
columns possible may again result in a window that is too large for the
physical screen. This would also be dependent upon the particular font
being used with the workstation agent.
Thus, it is important to be aware of the many ways in which the size
of a window can be affected. If the windows displayed with the default
settings are too big for the physical workstation screen, the first
course of action should be to choose a new font through the Workstation
Agent
window. Once a satisfactory font is determined, individual windows can
be further customized through the selection of data columns displayed
and the Window Size function.
When a workstation window is minimized in the OS/2 environment, it
generally appears as an icon on the desktop or an icon in a folder.
When a CMS GUI API window is minimized, it does not appear as an icon in any
location. It is only accessible through the Window List.
Because this
behavior is different from what many workstation users would expect, it
is mentioned here to avoid confusion when minimizing windows with the
CMS GUI API.
Because the AIX workstation
agent for CMS GUI API is using X Windows as the presentation
manager, it is possible to modify many X Windows and Motif Window Manager
(MWM) defaults. Modifications to defaults are most commonly made
in a .Xdefaults
file placed in the workstation user's home directory.
One default in particular that may need modification is the MWM mouse
click speed. If you are using the AIX workstation agent
and find that it is
difficult to get the windows to respond when double-clicking on portions
of the CMS GUI API windows, you might want to try modifying this default.
To make this modification, edit the
.Xdefaults file creating an entry
as follows:
Mwm*doubleClickTim: 750
The value specified represents the maximum time (in milliseconds)
between the two clicks of a double-click. Increasing the value above
the default should allow for double-clicks to be recognized without
having to double-click the mouse extremely fast.
When multiple users utilize a single RS/6000 workstation as the
target for the CMS Desktop, a TCP/IP port number must be specified when
starting the workstation
agent and issuing the SET WORKSTAT command. Each user
should start the workstation agent (exporting their display to the proper
device) and select the "Options" menu bar choice.
Within the "Options" menu,
each user should select "Set TCP/IP Port..." menu choice.
Each user should then set
a port number, stop the workstation agent, and
restart the workstation agent. When each user
enters the SET WORKSTAT command on the VM host, they should specify the
IP address as x.xx.xx.xx nnnnn, where nnnnn is the port number they
specified when they called the workstation agent.
While this procedure is required for multi-user AIX workstations, it
is also a good practice for all CMS Desktop users to follow. Specifying a
port address makes monitoring usage and solving problems from a
TCP/IP management perspective easier.
The default port number used by the CMS GUI API workstation agent is 15993.
It is not possible in the CMS Desktop environment to change the shape of
the XEDIT cursor. For example, the cursor does not change to a block
shape cursor when insert mode is entered in a CMS Desktop XEDIT
environment.
You may want to use the mouse pointer to position the cursor in
a particular field before entering data.
If FONTs are not set in AIX, the WSA window may take a
long time to be displayed. The user should set a monospace
font after the WSA window is displayed.
See also
"General NLS Considerations"
for DBCS and AIX font selection.
Use the following process to access the HELP files
on AIX workstations. In this procedure, substitute the
name of the directory containing your workstation agent
with /u/gui/dtwsa
Add the following statement near the top of the
cmdexec file that is in the same directory as
the workstation agent:
export LIBPATH=/u/gui/dtwsa:$LIBPATH
Add the following statements to
your .dtprofile file:
PATH=/u/gui/dtwsa
export PATH
LIBPATH=/u/gui/dtwsa
export LIBPATH
BOOKSHELF=/u/gui/dtwsa
export BOOKSHELF
There is no explicit function in the CMS Desktop to provide
access to the CP/CMS command line. Many of the functions provided
through the CMS Desktop resolve to entering CMS commands on the host.
However, the number of these commands, and the way in which they are
entered, are controlled completely by the functions provided through the
CMS Desktop. The XEDIT window within the CMS Desktop provides an XEDIT
command line. However, entering anything other than XEDIT subcommands
is not fully supported from this window.
It is possible to create a local CMS GUI API
application that can be added to
the desktop that would allow users to execute commonly used execs from
the CMS Desktop.
However, any command invoked from the CMS Desktop may potentially
cause problems if it writes to the 3270 emulator session
(virtual console). See the following section for more information.
It is possible to add applications to your CMS Desktop window that
invoke execs and other applications on the host.
If the host
application that is called
writes to the virtual console (your 3270 emulator
session),
problems may occur in
the host virtual machine.
The results obtained from calling this application
depend upon how the CMS Desktop was started.
The CMSDESK command provides two startup options associated with its
use of CMS multitasking.
BACKGROUND is the default option.
BACKGROUND specifies that the CMSDESK
command runs in background mode. When the CMSDESK command runs in
background mode, it runs as child process of the CMS root process.
Since the routines within CMS that perform I/O operations to the virtual
console (3270 emulator session) are designed to run as part of the CMS
Command process, running programs from the CMSDESK command when it is
running in background mode that interact with the 3270 emulator session,
is not supported. When the CMSDESK command is entered with the
BACKGROUND option,
the CMS command line is available for use through a 3270
emulator session.
The CMSDESK command can also be entered with the FOREGROUND
option.
Specifying this option causes the
CMSDESK command to be started as a child process of the CMS Command
process. When CMSDESK is started in this manner, it is possible to
call host programs from the CMS Desktop that may interact with a 3270
emulator session, subject to the following limitations.
When
the CMSDESK command is entered with the FOREGROUND option, it is not
possible to enter any CMS commands from the command line of a 3270
emulator session. The CMS command line will not be free until the
CMSDESK command ends. All host commands would need to be started
from the CMS Desktop through a locally written CMS GUI API application that
provides such a capability.
See the "VM/ESA Graphical User Interface Facility (SC24-5789)" manual for more
information on the FOREGROUND and BACKGROUND options.
When a host command or application is started with the CMSDESK
command with the FOREGROUND option specified,
line-mode I/O entered from that
command or application can be done to the 3270 emulator session.
Interaction with the CMS Desktop is inhibited at the workstation if
the host emulator session is placed into a More/Holding condition.
Interaction with the CMS Desktop can resume once the host More/Holding
condition is cleared. It is possible to prevent the host emulator
session from being placed into a More/Holding condition by entering
either:
SET FULLSCREEN ON
or
CP TERMINAL MORE 0 0
CP TERMINAL HOLD OFF
When a command or application is invoked on the host that performs
full screen I/O to the 3270 emulator session (such as XEDIT), any
further interaction with the CMS Desktop on the workstation is
inhibited until the application interacting with the 3270 emulator
session is ended. In some cases, when the application interacting with
the 3270 emulator session is ended, it may appear to hang. This is due
to CP not automatically returning the console to line mode and clearing
the screen after the application ends. The next line-mode write
performed to the 3270 emulator session (for example, when a message is
sent to the virtual machine user ID) returns the virtual console to
normal.
Refer to the "VM/ESA Graphical User Interface Facility (SC24-5789)", Appendix A, for more
information on this subject.
Generally, once the CMS Desktop has started, you may disconnect
from your VM host session and continue to run the CMS Desktop. However,
at this time you should avoid sending a note using
GUI note while
disconnected.
When implementing the CMS Desktop, care should be taken to evaluate host
PROFILE XEDIT commands. This is especially true if most users rely upon
a common standard PROFILE XEDIT. Users who
maintain their own PROFILE
XEDIT should read the following information.
It is possible to specify many different color settings in a PROFILE
XEDIT macro. While these colors may be satisfactory in a 3270
environment, they may produce different shades when using the
XEDIT window from the CMS Desktop. The colors specified for areas, such as
the XEDIT
file area, message line, command line, prefix area, pending area,
scale line, and current line
should be carefully evaluated when using the CMS Desktop.
To set the color of the areas previously mentioned, use the following
operands on the SET COLOR subcommand:
FILEAREA, MSGLINE, CMDLINE, PREFIX, PENDING, SCALE, and CURLINE.
The color
statements in PROFILE XEDIT do not affect the color displayed
between the entry fields on the XEDIT window. This color can only
be changed using the facilities of the workstation.
For example, on the OS/2 platform, the color between entry fields on
the XEDIT window is white. Consequently, you may want to modify your
PROFILE XEDIT to specify:
SET COLOR FILEAREA WHITE REVVIDEO
This causes the area where text is displayed in the
XEDIT window to be entirely white, without the appearance of individual
entry fields for each line in the file area. Similar changes can be made
to the prefix area and the current line using the
host PROFILE XEDIT file.
Specifying these areas as WHITE REVVIDEO reduces the appearance of
separate and distinct areas on the workstation XEDIT window. Remember,
however, any changes made to colors through the host PROFILE XEDIT file
should be coordinated with any changes being made through workstation
facilities.
Note: Please see the section on "Workstation Colors" in this document.
PROFILE XEDIT macros should also be inspected for subcommands that
are
only valid on a display terminal. These subcommands are
ignored if XEDIT
is
used and the host virtual machine has been started in disconnected mode,
or disconnected after an initial logon. These subcommands include:
SET TERMINAL, SET APL, and SET FULLREAD. A complete list of XEDIT
subcommands and options that are not supported in the GUI
environment is provided in Chapter 3 of the
"VM/ESA Graphical User Interface Facility (SC24-5789)" manual.
When modifying PROFILE XEDIT to be compatible with the CMS Desktop
environment, it is possible to use a new argument to the XEDIT EXTRACT
command. EXTRACT /GUI/ returns an
indication of either ON or OFF.
If ON is returned, the file is being displayed in a GUI
window rather than a terminal emulator screen. This information can
then be used to tailor PROFILE XEDIT for both the CMS Desktop
environment and 3270 environment.
When using XEDIT from the CMS Desktop, it is a good idea to enter the
XEDIT subcommand
SET NULLS ON in your PROFILE XEDIT. This makes it
much easier to insert text on existing lines in a file.
It is important to note that insert mode is ON by
default when entering XEDIT from within the CMS Desktop for the first
time. With the OS/2 workstation
agent,
when the cursor is moved to the prefix area, it is not possible to
enter a prefix command without first pressing the workstation Insert key
to toggle out of insert mode. Upon subsequent invocations of XEDIT
from within the CMS Desktop, the setting of the Insert key remains the
same as it was last set.
The MS Windows workstation
agent and AIX workstation agent do not respect the setting of the
Insert key when the cursor is in the XEDIT prefix area.
With these workstation
agents, you must first delete some characters when typing commands into
the prefix area.
Rather than
deleting characters in the prefix
area in order to enter prefix commands, specify SET PREFIX
NULLS and SET NUMBER OFF in the host PROFILE XEDIT file or
enter SET PREFIX NULLS and SET NUMBER OFF on the command line.
This eliminates the need to delete characters in order
to enter XEDIT prefix commands. However, it also removes the line
numbering associated with SET NUMBER ON, which may not be desirable.
When an XEDIT window is displayed with the CMS Desktop,
a vertical scroll
bar is provided if the number of lines included in the window
exceeds the window size. The number of lines included in the window is
a function of the size of the user's 3270 emulator window.
It is important to realize that
the scroll bar is provided only to move through the data displayed in
the window. The scroll bar does not page through the file. In order to
page through the file, normal XEDIT subcommands (or function keys
associated with those commands) must be used.
The number of lines in the host file that are displayed in the
workstation window can be controlled by specifying the XEDIT subcommand
SET SCREEN SIZE nn, in PROFILE XEDIT. The argument nn represents
the number of lines XEDIT should use instead of the number associated
with the size of the 3270 emulator window.
When the CMS Desktop is gathering information from the host to display
in a workstation window, temporary files are created on the A-disk
(minidisk or SFS directory). The files have names such as, DESK
CMSUT1 or CMSDESK CMSUT1.
Since
these files can be quite large depending on what CMS Desktop function is
being used, it is possible to run out of space on the minidisk or
directory. If this happens, an error message is displayed on the
workstation indicating that the CMS Desktop was unable to perform a sort
operation or gather the information for a response. To correct this
problem, the user should create additional space on the A-disk or
access another R/W disk as A. In general, users of the CMS Desktop should
be advised to maintain their A-disk such that they have a liberal amount
of free space available.
Within the CMS Desktop, it is possible to select an editor to use when
viewing or updating files. Either a workstation based editor can be
used (for example, EPM or VI) or XEDIT.
When XEDIT is selected, only the
amount of data needed to fill one workstation window is sent at a time.
When a workstation editor is selected, the entire file to be edited
is downloaded to the workstation for use with the editor. This
operation can take a long time if the file to be edited is quite large.
In addition, if the
file selected is large and the workstation is short on disk space, an
error may occur when editing the file. When using AIX, the
amount of space in the file system from which the workstation
agent is called
determines whether the edit operation is successful or not.
Users of the CMS Desktop who select workstation editors should be
advised to maintain their workstation disk drives in such a way as to
have a liberal amount of free space available. If sufficient
workstation disk space does not exist, users should be instructed to
switch their editor preference to XEDIT.
Note: The CMS Desktop does not provide a browse function for looking at
files. Thus, users should be aware that if a workstation editor is being
used and a file is selected from a R/O disk, an attempt is made to
transfer the file back to the host when the editor session is ended. In
the case of a R/O disk, the upload operation fails and a message
window is displayed. When that message window is responded to, a
second message window is displayed regarding the disposition of the
work file on the workstation. If a file is selected on a R/W disk, then
the file is rewritten on the host when the editor session is ended,
even if no changes were made. If no changes were made, the original
date/time stamp for the file is preserved. However, it should be
noted that the file is physically rewritten on the host.
There are limitations on the number of characters
that can be entered in an entry field. Currently, AIX
allows the user to enter any number of characters.
The user must be careful not to enter more data than
is expected. Entering too many characters can cause the
application to loop.
The "Add to Desktop" description is limited to 16
characters. Exceeding the limitations for this field can
cause corruption of the field. You will not be able to
delete the affected entry.
The record length for GUI notes in the CMS Desktop
is set to 70 bytes. The size of the text contained in the
note must not exceed 65,000 bytes. When replying to a note,
the menu options default is to include the original note when
the reply is sent. This can be changed by changing the note
settings from the Reader application.
The language on the host should match the language
for the codepage on the PC. Problems will be encountered
if a user attempts to set the host language to AMENG
or UCENG and tries to use a different codepage on the
PC. The current language set on the host is
used to set the codepage that the workstation agent will use on
the CMS desktop. This will cause an incompatibility if the
PC codepage is not the same as the codepage the workstation agent
is using for translation, and is not supported at this
time.
To use DBCS data on the CMS Desktop, you must
set the language to Kanji or Hanzi before entering the CMSDESK
command.
The DBCS translation from host to workstation and back
deletes and adds SO/SI characters, respectively. Therefore,
some strings may have different lengths and alignments when
viewed on the host versus on the workstation.
Additional SBCS/DBCS considerations are discussed
in the following sections.
The address book does not support DBCS character
streams. Only SBCS translation is supported
with the address book at this time. Therefore, DBCS
nicknames cannot be used.
SBCS should be used whenever a file name or file type
is requested to limit the number of characters
entered. Also, use SBCS when entering fields that access
VM system resources.
Mixed SBCS/DBCS strings are not allowed for the "Add
to Desktop" description. The field is limited to 16
characters, and exceeding the limitations for this field
can cause corruption of the field. You cannot
delete the affected entry.
If a DBCS language is used, font selection is disabled.
The following statement should be included in the
.Xdefaults file:
*fontList: *gothic*:
3270 Japanese Katakana (with DBCS) terminals are not supported.
The CMS Desktop should be used on Japanese Latin or Japanese
Latin Extended terminals. A terminal emulator for DBCS must
also be used.
The AIX agent should never be run in locales other than Ja_JP.
When the AIX agent is run in locales such as ja_JP or En_US, it
requires several minutes until the initial panel is displayed.
During initialization, the other processes are locked.
DBCS-PC code points (0xFA59 and 0x9458) are not correctly
translated into DBCS-Host code points at this time.
PRINT SELECTION FOR APAR - II09462 1996-05-23
ERROR DESCRIPTION:
GUIINFO 568411217 SCEEX LE/370 DCE
The program directory for the GUI feature contains sample or
suggested information for creating the GUICSLIB and GUIVMGUI
segments. The program directory recommends loading the GUICSLIB
segment at 1B00-1BFF, and the GUIVMGUI segment at 1C00-23FF.
However, the SCEEX segment built for the LE/370 feature is
defined at 1900-1CFF. This causes an overlay between the GUI
segments and the SCEEX segment.
In the program directory for Graphical
user interface facility; section 6.5.1,
step number 6, the GUI segment information
should read as follows:
The GUICSLIB segment should be loaded at 1D00-1DFF.
The GUIVMGUI segment can be loaded at 2000-27FF. This
would resolve the conflict with the SCEEX segment.
In addition to changing the segment definition panel, the
virtual machine size of the userid building the segments will
have to be increased to account for the higher segment
addresses.
|
