IBM: VM/ESA GUI Facility

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.

System Programmer

Installation

VM/ESA Graphical User Interface Facility Part Locations

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.

APAR and PTF information

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.

Saved Segments

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.

CMS Virtual Machine Size

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.

TCP/IP Virtual Machine Name

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.

APPC Session Limit Considerations

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.

Workstation Requirements

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
- IBM OS/2 2.1 or OS/2 WARP
  Note: From testing and other experiences it appeared as though OS/2 WARP provided a superior environment to that provided by OS/2 2.1.
- Microsoft Windows 3.1, or Microsoft Windows for Workgroup V3.11 with DOS 6.0 or higher
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.

Migration Considerations

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.

Installation of the Workstation Agent

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.

Performance Considerations

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.

Workstation Considerations

Establishing Sessions without a 3270 Window

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.

Trouble Shooting

Communications Problems

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.

General Debugging

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:

Copy the particular GUIxxxx EXEC you want to trace over to your A-disk as some other name, for example, TUIxxxx EXEC.
XEDIT the copy of the exec on your A-disk inserting a Trace R statement at the beginning of the exec.

Create a new version of the GUIxxxx EXEC on your A-disk with the following statements:

  /*******/
  Parse SOURCE . . me .
  date_and_time = 'Trace of' me 'on' date() 'at' Time()
  Address COMMAND 'PIPE COMMAND EXEC TUIxxxx',
                          '| LITERAL' date_and_time,
                          '| > GUIxxxx TRACE A'
  Exit

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.

CMSDESK Command

SET WORKSTATION Command

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.

Entering CP and CMS Commands from the CMS Desktop

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.

Console I/O from Commands and Applications Called through the CMS Desktop

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

      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.

VM/ESA Graphical User Interface Facility API

Languages Supported

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.

Size of CMS GUI API Objects

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.

DtEntry Object

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."

DtGap Object

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.

Graphical Application Build Tool

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.

Application Development Tips for Performance

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.

General User

Workstation Considerations

Workstation Fonts

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

Workstation Colors

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.

Window Headings Not Scrolling with Data

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.

Automating Workstation Selection

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".

Fixed Size Windows

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.

VM/ESA Graphical User Interface Facility OS/2 Workstation Agent

Window Minimize Behavior

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.

VM/ESA Graphical User Interface Facility AIX Workstation Agent

Mouse Click Speed

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.

Multi-User AIX Workstations

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.

XEDIT Cursor

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.

Setting FONTs

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.

HELP Files

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

CMSDESK Command

Entering CP and CMS Commands from the CMS Desktop

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.

Applications That Write to the 3270 Session When the CMS Desktop is Active

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

      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.

Disconnecting from the Host

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.

Effects of Host PROFILE XEDIT

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.

Inserting Text in the XEDIT File Area

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.

XEDIT Prefix Area

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.

Scroll Bars on XEDIT Windows

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.

Work Files on A-Disk

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.

Work Files on the Workstation

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.

Entry Field Length Considerations

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.

GUI Notes

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.

General NLS Considerations

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.

Address Book

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.

Entry Field Length Considerations

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.

Setting Fonts in AIX

If a DBCS language is used, font selection is disabled. The following statement should be included in the .Xdefaults file:

      *fontList: *gothic*:

Terminals, Code Points, and Locales

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.

Attachments

Information APAR II09472 GUI Segment Definitions

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.