ACMS_Desktop_for_OSF/1________________________ Release Notes December 1994 This document provides information about the latest release of ACMS Desktop for OSF/1 that is not supplied in the user documentation. Revision/Update Information: This is a revised manual. Operating System: DEC OSF/1 Version 3.0 Software Version: ACMS Desktop for OSF /1 Version 2.1 Digital Equipment Corporation Maynard, Massachusetts December 1994 Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. © Digital Equipment Corporation 1993, 1994. The following are trademarks of Digital Equipment Corporation: ACMS Desktop, ACMSxp, AXP, DEC, DECtp, and the Digital Logo. The following are third-party trademarks: Microsoft, Microsoft C, Microsoft COBOL, Microsoft Windows MS, MS-DOS, and Visual Basic are registered trademarks of Microsoft Corporation. Windows NT is a trademark of Microsoft Corporation. Open Look and UNIX are registered trademarks of UNIX System Laboratories, Inc. Motif, OSF/1, and OSF/Motif are trademarks of Open Software Foundation, Inc. X Window System is a registered trademark of Massachusetts Institute of Technology. All other trademarks and registered trademarks are the property of their respective holders. This document was prepared using VAX DOCUMENT Version 2.1. ________________________________________________________________ Contents Preface.................................................. vii 1 Technical Notes for ACMS Desktop 1.1 ACMS Desktop Server Notes.................... 1-1 1.1.1 Server Administration and Security....... 1-1 1.2 Portable API Notes........................... 1-1 1.2.1 Establishing an Exit Handler............. 1-2 1.3 DOS and Microsoft Windows Notes.............. 1-2 1.3.1 Disable C Language Optimization.......... 1-2 1.3.2 Using the Microsoft Visual C++ Compiler................................. 1-2 1.3.3 Determining Maximum Workspace Size....... 1-2 1.3.3.1 Large-Memory Model..................... 1-3 1.3.3.2 Small- and Medium-Memory Models........ 1-3 1.3.4 Hardware Mode for Windows Client Programs................................. 1-3 1.3.5 Applications Using DLLs Must Explicitly Call ACMSDI_SIGN_OUT before Exiting...... 1-3 1.3.6 Possible Unexpected Behavior for Winsock Applications............................. 1-4 1.3.7 DOS Client Libraries..................... 1-4 1.3.8 Post-Installation Procedures for DOS..... 1-6 1.3.9 Support for Exchange Steps............... 1-9 1.4 Sample Application Notes..................... 1-9 1.4.1 Microsoft Windows Sample................. 1-10 1.4.1.1 "Unknown Error Occurred" Message on Exit of Windows Sample................. 1-11 1.4.2 Motif Sample............................. 1-11 1.4.2.1 Different Motif Versions May Create X Protocol Errors........................ 1-11 iii 1.4.3 Microsoft COBOL Sample................... 1-12 1.4.3.1 Building the COBOL Sample Using Microsoft COBOL Version 4.0 and Higher................................. 1-12 1.4.4 Visual Basic Sample...................... 1-12 1.4.4.1 Two ACMS Desktop Status Codes Missing in ACMSDI.BAS.......................... 1-12 2 Guidelines for Submitting an SPR 2.1 Calling in a Problem to a Customer Support Center....................................... 2-1 2.2 Submitting an SPR............................ 2-3 Index Tables 1-1 Directories in PATHWORKS Environment..... 1-7 iv ________________________________________________________________ Preface These notes provide information about the latest release of the ACMS Desktop for OSF/1 software. Who Should Use This Document Read this document if you are responsible for installing ACMS Desktop software or designing, implementing, or managing ACMS Desktop applications on a desktop system. This document contains information not found in ACMS Desktop documentation. Structure of This Document This document has the following structure: Chapter 1 Describes errors, workarounds, and usage notes in ACMS Desktop software. Chapter 2 Describes how to submit a software problem report. vii 1 ________________________________________________________________ Technical Notes for ACMS Desktop This chapter presents technical notes for ACMS Desktop software. 1.1 ACMS Desktop Server Notes These notes apply to the ACMS Desktop server 1.1.1 Server Administration and Security The ACMS Desktop server is intended to be run and administered by users who are members of the user group `acmsdi'. At installation time, the files in the directory /usr/opt/ACMSDI210/bin are set to belong to the group `acmsdi'. The csh script files are used to start and stop the ACMS Desktop server and can be executed by members of the acmsdi group. The acmsdid file is the ACMS Desktop server itself, and the acmsdiops file is a privileged surrogate process that is used by the ACMS Desktop process. Before running the ACMS Desktop process, read Chapter 9, Managing an ACMS Desktop System, in ACMS Desktop for OSF/1 Application Development Guide. This describes how to start and stop the ACMS Desktop server and how to build the shareable object versions of the application task stubs. 1.2 Portable API Notes The notes in this section apply to developing desktop client programs with any of the platforms that make up the Portable API (DOS, Microsoft Windows, and DEC OSF/1). Technical Notes for ACMS Desktop 1-1 1.2.1 Establishing an Exit Handler If the ACMS Desktop client program uses the standard C routines atexit or onexit to establish an exit handler and the exit handler calls acmsdi_sign_out, the call to atexit or onexit should be made after the first call to acmsdi_sign_in. If this precaution is not taken, the exit handling built into ACMS Desktop client services occurs before the desktop client program exit handler call to acmsdi_sign_out. Because the submitter or submitters are already signed out, the desktop client program gets error statuses that can be ignored. 1.3 DOS and Microsoft Windows Notes The notes in this section apply to developing DOS desktop client programs. 1.3.1 Disable C Language Optimization Digital recommends that you disable optimization in the Microsoft C compiler. Use the -Od parameter on all compiles. 1.3.2 Using the Microsoft Visual C++ Compiler When using the Microsoft Visual C++ compiler to develop ACMS Desktop client programs, you must select the 1-byte struct member alignment option. To set this option, in the Visual C++ Workbench, choose Options/Project/Compiler. There is a field for struct member byte alignment in the code generation section. 1.3.3 Determining Maximum Workspace Size In general, workspace size is limited only by the environment of the specific platform. Our testing has involved workspace sizes of up to 64K. The only platform on which we have encountered problems with large workspaces (that is, workspaces greater than 32K) is the PC using DOS or Microsoft Windows. 1-2 Technical Notes for ACMS Desktop 1.3.3.1 Large-Memory Model The ACMS Desktop workspace size limitations in the PC environment arise from the general memory limitations of the PC environment. Applications get all their memory for data from 64K portions of memory known as data segments. DOS applications built using the large memory model can use multiple data segments. The only limitation for these applications is that each allocated object must be less than or equal to 64K. When you invoke ACMS Desktop client services, ACMS Desktop creates a message buffer and sends the buffer across the network. This network message buffer needs to be less than or equal to 64K. Considering other ACMS Desktop client services overhead in the message buffers, for large- memory model applications, the maximum total workspace size passed on an acmsdi_call_task is 32K. Use this figure as a guideline. 1.3.3.2 Small- and Medium-Memory Models Small- and medium-memory model applications, however, are limited to just one 64K data segment. As a result, the maximum allowable workspace for these applications varies. The workspace size limits are very dependent upon how much memory the application is allocating for other work, and how the application uses ACMS Desktop client services at run time (number of sign-ins, number of simultaneous running tasks, number of workspaces, and so forth). 1.3.4 Hardware Mode for Windows Client Programs Run Windows applications under Windows in 386 ENHANCED mode (on a 386-based PC). Running Windows desktop client programs (on 286- or 386-based machines) in REAL or STANDARD modes may cause unpredictable results. 1.3.5 Applications Using DLLs Must Explicitly Call ACMSDI_SIGN_OUT before Exiting Visual Basic and Microsoft Windows applications that use the ACMS Desktop DLL must explicitly sign out existing sessions before exiting the application. Unless these applications explicitly call acmsdi_sign_out for each session, those sessions remain active even after the Technical Notes for ACMS Desktop 1-3 application has quit. The DLL has no way of cleaning them up. Once the PC uses its maximum number of network links, calls to acmsdi_sign_in() will fail, returning a status code indicating that the Desktop Server or the network link terminated (ACMSDI_SRVDEAD or -3020). To free up outstanding network links, reboot your PC. 1.3.6 Possible Unexpected Behavior for Winsock Applications ACMS Desktop applications using Windows Sockets Version 1.1 should be prepared to deal with the following situation. Windows Sockets-based transports continue to poll for and dispatch Windows events during the time that the transport is sending and receiving network messages. As a result, your application can continue to service menu commands, button events, and so on, from your user, even while the transport is busy. A problem can arise if your application tries to invoke a ACMS Desktop service in response to one of these menu commands or button events, during the time that the transport is busy. ACMS Desktop services are serially reusable, not reentrant. Therefore, ACMS Desktop services cannot allow two services to be accessing the network connection at the same time. Otherwise, messages can become scrambled, and unpredictable results may occur. The ACMS Desktop services prevent this reentrant behavior by immediately returning an error status code. For more information on serialization violations and these error status codes, see the ACMS Desktop for OSF/1 Application Development and Management Guide. 1.3.7 DOS Client Libraries The client object libraries and DLLs for DOS and Windows are provided on the kit in the directory: /usr/etc/acmsdi/msdos 1-4 Technical Notes for ACMS Desktop The files in this directory are a subset of those provided on the ACMS Desktop Version 2.0 for OpenVMS kit. They are essentially the same files that were set up to work with ACMS/TDL using DECnet. DECnet is not a supported transport for this version of ACMS Desktop for OSF/1, which works with the ACMSxp for OSF/1 AXP product. Static-Link Libraries The static-link libraries ACMSDIS.LIB, ACMSDIM.LIB and ACMSDIL.LIB were set up to work with PATHWORKS Version 4.1 using DECnet. You can use them with this product if you want to work with static-link libraries. However, you must change them to use TCP/IP and install, on your client PC, either of the following list of products: o PATHWORKS Version 4.1, PATHWORKS for DOS (TCP/IP) Version 2.0, and the DOS_SOCK.LIB library obtained from a PATHWORKS server system to link against. This combination is only good for nonWindows-based applications. o PATHWORKS for DOS and Windows Version 5.0 and the PATHWORKS Developer's Kit to obtain the needed libraries. Assuming medium- memory model, for DOS link with mpwsock.lib and lnmapi; for Windows, use mpwsockw.lib and lnmapi. Use the appropriate network modules, which are provided in the same directory and that match both the memory model and the PATHWORKS version, to replace the network modules in the static libraries. For example, to set up a medium- memory model library that you can use with PATHWORKS Version 5.0 over TCP/IP: > LIB ACMSDIM -NETDECM; # Remove the DECnet module > LIB ACMSDIM +NETTCP5M; # Replace with TCP/IP (V4.1 = nettcpm) Dynamic-Link Libraries There are three dynamic-link libraries on the kit. ACMSDI.DLL communicates with only a DECnet based application, which at this time is ACMS OpenVMS based. The ACMSDITC.DLL works with the older socket based TCP/IP interface supported by PATHWORKS for DOS (TCP/IP) Version 2.0. If you want to use this DLL in combination with that version of PATHWORKS, rename ACMSDITC.DLL to ACMSDI.DLL Technical Notes for ACMS Desktop 1-5 and ensure it is in the path where it can be found at run time. ACMSDIWS.DLL is the ACMS Desktop client services DLL that is using WINSOCK to interface over TCP/IP. Make this DLL available in the executable PATH on the PC under the name of ACMSDI.DLL so the client programs can find it to link against. ACMSDIWS.DLL needs to be used in conjunction with a WINSOCK.DLL that implements Version 1.1 of the WINSOCK standard. The ACMSDIWS.DLL has been tested against WINSOCK.DLL libraries provided in the following products: o FTP Software Inc., PC/TCP for DOS Version 2.2 o PATHWORKS Version 5.0 for DOS and Windows o Netmanage Chameleon Version 4.0 TCP/IP for Windows Place the WINSOCK.DLL in the PATH variable on the PC so it can be located at run time. In addition to the DLLs used above for testing, the ACMS Desktop ACMSDIWS.DLL should operate successfully with WINSOCK DLLs from other companies that fully support the Version 1.1 WINSOCK standard. The fourth DLL is DI_CNV.DLL. This DLL is used by the other DLLs to enable the products to be used in international markets. If any of the other DLLs, are used under Windows, you must place DI_CNV.DLL in the executable path. 1.3.8 Post-Installation Procedures for DOS The post-installation batch file procedures used to copy the files from the OSF/1 server to the PC are coded to work with the FTP PC/TCP implementation of the ftp file transfer program that supports the -u option. If you are installing in a PATHWORKS V5.0 environment, the procedures such as disetup.bat will not work as provided. In the PATHWORKS environment, you can create directories like the ones listed in Table 1-1 on the PC and copy the files from the OSF/1 machine manually. You can examine the post-installation batch file procedures and mimic 1-6 Technical Notes for ACMS Desktop them by hand or modify them to work with your vendor's implementation of the ftp command. Table_1-1_Directories_in_PATHWORKS_Environment____________ OSF/1 Directory and PC_Directory_____Files_to_Copy_________Comments___________ c:\acmsdi /usr/etc/acmsdi /msdos Use -I image for acmsdiws.dll copy *.lib Use -I image for *.obj copy *.dll Use -I image for copy Use -I image for copy /usr/etc/acmsdi /common acmsdi.h ppstubs.c forms.h tdms.h c:\vbavertz /usr/examples/acmsdi /msw/vb acmsdi.bas help.txt loadvb.bat vbavertz.bas (continued on next page) Technical Notes for ACMS Desktop 1-7 Table_1-1_(Cont.)_Directories_in_PATHWORKS_Environment____ OSF/1 Directory and PC_Directory_____Files_to_Copy_________Comments___________ mainmenu.frm Use -I image for reserve.frm copy signin.frm Use -I image for vbavertz.exe copy vbavertz.mak Use -I image for copy Use -I image for copy Use -I image for copy c:\avertz /usr/examples/acmsdi /msw *.h *.c *.def *.rc *.bat *.txt *.exe Use -I image for *.ico copy Use -I image for copy /usr/examples/acmsdi /msw_with_dll avertz.def avertz avertz.exe Use -I image for copy (continued on next page) 1-8 Technical Notes for ACMS Desktop Table_1-1_(Cont.)_Directories_in_PATHWORKS_Environment____ OSF/1 Directory and PC_Directory_____Files_to_Copy_________Comments___________ c:\client /usr/examples/acmsdi /msdos *.cbl *.c *.bat *.exe Use -I image for _______________________________________copy_______________ 1.3.9 Support for Exchange Steps The session model is similar to that of the other ACMS Desktop products, where forms sessions exist across task calls. To achieve this, the ACMS Desktop server absorbs ACMSxp FORMS$ENABLE transmissions if they are referring to the same form as an earlier one to the same ACMS Desktop client. 1.4 Sample Application Notes This section contains notes regarding the sample applications supplied with the ACMS Desktop software. For directions on building the sample application, read the notes in file /usr/examples/acmsdi/acmsxp/acmsdi_vr_ application_info.txt. All the ACMS Desktop samples, except the Visual Basic and Macintosh samples, require exchange steps. For this release, no STDL vr_da_appl application has been coded that supports exchange steps. However, you can copy the ACMS Desktop sample code and build or examine it as an aid to developing your own application. If you have support on your PC for Winsock Version 1.1, use the AVERTZ make file in /usr/examples/acmsdi/msw_ with_dll rather than the one for static-link libraries in /usr/examples/acmsdi/msw. If want to try the one in /usr/examples/acmsdi/msw and are working with PATHWORKS Version 5.0 over TCP/IP and have access to the PATHWORKS Developer's Kit, you can modify that make file to work Technical Notes for ACMS Desktop 1-9 with static-link libraries by removing the link reference to mwdnetv4 and inserting references to mpwsockw and lnmapi. However, using the ACMSDIWS.DLL and a WINSOCK.DLL combination for your Windows based applications reduces the transport dependencies and increases the flexibility while building and using the program. When the AVERTZ Windows based client has been built, it will be able to execute through the sign-in to the ACMS Desktop gateway stage. The client samples that use exchange I/O are essentially the same as those provided for the Version 2.0 product. There is no corresponding ACMSxp STDL task provided on the kit. The client code must be reworked to match the alignment considerations of the task server workspace definitions when such an application is provided. The Visual Basic sample has had its nonexchange I/O sample workspaces adjusted in that manner as an example of one approach to achieving matching structure definitions on the client PC and in the ACMSxp task definitions. In the Visual Basic sample code for the SIGNIN.FRM, Transfer Reservation procedure, there are two task selection strings that you may need to change to match the TP selection information in the backend application. The part that needs changing is the TP system namespace that follows the /.: characters. The alternative to changing the code is to use the RPC_DEFAULT_ENTRY environmental variable for the ACMS Desktop gateway to define the ACMSxo task-group locater. In the case of the OSF/1 client, the client services code has been ported and tested using standard regression tests. The Motif AVERTZ sample has been ported and tested against a V2.0 ACMS/TDL application. Again, the sample code might need some modification to work with an ACMSxp task server when it is available. 1.4.1 Microsoft Windows Sample The notes in this section concern the Microsoft Windows sample client program AVERTZ.EXE. 1-10 Technical Notes for ACMS Desktop 1.4.1.1 "Unknown Error Occurred" Message on Exit of Windows Sample If there is more than one active session in the Windows sample when the user exits the sample application, a message box appears displaying the message "Unknown Error Occurred." This message appears due to a reentrancy check (serial- ization enforcement) that has been added to the client API in ACMS Desktop V1.3. (See the ACMS Desktop for OSF /1 Application Development and Management Guide for more information on serialization restrictions.) The sample application uses a recursive shutdown procedure to sign out the active sessions before the application quits. Because a ACMS Desktop service completion routine invokes the shutdown procedure, which calls acmsdi_ sign_out(), the acmsdi_sign_out()service is being called within the scope of the acmsdi_dispatch_message_ service(). The new restrictions on the client API do not allow ACMS Desktop services to be called within the scope of acmsdi_ dispatch_message(). Because the sample application is attempting to do this, the acmsdi_sign_out service returns an error status of ACMSDI_DISPATCHACTV. The sample is not written to expect this status, and therefore, displays the error message: "Unknown Error Occurred." 1.4.2 Motif Sample The notes in this section concern the Motif sample client program. 1.4.2.1 Different Motif Versions May Create X Protocol Errors If the Motif sample application generates X protocol errors while it is running, it is probably due to a mismatch between the version of Motif with which it was built and the version of Motif that is running. To fix this problem, relink the application with the Motif libraries on your system. Technical Notes for ACMS Desktop 1-11 1.4.3 Microsoft COBOL Sample 1.4.3.1 Building the COBOL Sample Using Microsoft COBOL Version 4.0 and Higher Beginning with Microsoft COBOL Version 4.0, the COBOL installation procedure, by default, installs dynamic- link libraries rather than static-link libraries. The procedures to build the COBOL sample's presentation procedures (BLD-PPS.BAT), however, were written to build with static-link libraries. To build the COBOL sample using Microsoft COBOL Version 4.0 or higher, you can either: o Reinstall COBOL, specifying that static-link libraries be installed o Keep the dynamic-link library environment and edit each COBOL compile line in the BLD-PPS.BAT file, to use the static-link libraries. For example, change: cobol CHK-DATE,,NUL,NUL MODEL"LARGE"; To look like: cobol CHK-DATE,,NUL,NUL MODEL"LARGE" LINKLIB "LCOBOL+COBAPI"; 1.4.4 Visual Basic Sample 1.4.4.1 Two ACMS Desktop Status Codes Missing in ACMSDI.BAS Two status codes are missing from the ACMSDI.BAS file. (ACMSDI.BAS is the ACMS Desktop definitions file provided to support Visual Basic client applications.) These two status codes are: o ACMSDI_DISPATCHACTV (-3030) o ACMSDI_CALL_CANCELED (-3011) To support these status codes in your application, add the two following lines to the ACMS Desktop definitions in your Visual Basic application: Global Const ACMSDI_DISPATCHACTV = ACMSDI_MESSAGE_BASE - 30 Global Const ACMSDI_CALL_CANCELED = ACMSDI_MESSAGE_INFO_BASE - 1 1-12 Technical Notes for ACMS Desktop 2 ________________________________________________________________ Guidelines for Submitting an SPR If you encounter a ACMS Desktop problem that you cannot solve in any of the ACMS Desktop components and your site has a contract to receive Digital software support services, you can call your Digital software support center. If you do not have support services, submit a Software Performance Report (SPR) to Digital SPR Administration. If the software problem you have found is related to a product other than ACMS Desktop, submit an SPR for that product rather than for ACMS Desktop. For more information on SPRs, contact Digital SPR Administration or your software specialist. The following sections discuss the kinds of information you should have available when reporting a ACMS Desktop problem. 2.1 Calling in a Problem to a Customer Support Center When you call the customer support center to report a problem, the telephone support specialist asks for the following information: o Which versions of OSF/1, ACMSxp, ACMS Desktop, the forms product, and the programming language you are using. o What commands or process caused the problem. o What were the exact error messages that were received. o What log and dump files are relevant. o Additional information from either the ACMSxp logs or the ACMS Desktop log. Guidelines for Submitting an SPR 2-1 The specialist might also ask for the following informa- tion: o The version number of other products you are using with ACMS Desktop. o A description of the application and, if necessary, a small example of code that duplicates the problem. o Whether you are running a distributed application. o Whether message buffer size or other environmental variables are set. o Whether the problem affects all users or only specific users. o Whether the problem affects all applications or only specific tasks. o The types of devices being accessed. o The ACMSxp system state at the time the problem occurred. o Whether the problem is reproducible. o Whether you can reproduce the problem running your application in the ACMSxp Task Debugger environment. o Whether this command, statement, or application has worked before. If you answer yes to this question, the specialist will want to know what might have caused the change. For example, such changes might include updates to the operating system or layered product, bringing new production applications on line, and adding new users. After listening to your responses, the specialist might be able to provide immediate help or might have to call you back after doing some testing and research. For problems that the specialist cannot reproduce or resolve, you might be asked to send additional detailed information on a magnetic tape to the support person or directly to the ACMS Desktop engineering group. 2-2 Guidelines for Submitting an SPR 2.2 Submitting an SPR If you or the Digital support specialist decide that you need to submit an SPR for a problem, include the following information on magnetic tape with the SPR form: o ACMSxp log files o ACMS Desktop log files in /var/acmsdi/write o Any core dump files o Any client log files o Verification of the ACMSxp version Guidelines for Submitting an SPR 2-3 ________________________________________________________________ Index A__________________________ M__________________________ acmsdi_sign_out service Message size calling from exit handler DOS limit, 1-2 , 1-2 P__________________________ C__________________________ Portable API C language programming notes, 1-1 disable optimization, 1-2 Problems submitting reports on, D__________________________ 2-1 Desktop client program DOS S__________________________ message size limit, Sample application 1-2 Microsoft Windows, 1-10 DOS Motif, 1-11 programming notes, 1-2 notes, 1-9 Software E__________________________ submitting problem Exit handler reports, 2-1 calling, 1-2 SPR guidelines for submitting H__________________________ , 2-1 Hardware mode submitting a, 2-3 Windows, 1-3 T ___________________________ Telephone problem reporting on, 2-1 Index-1 V__________________________ Visual Basic sample, 1-12 W__________________________ Windows hardware mode, 1-3 Index-2