CONTENTS Title Page Copyright Page Preface Part I Components and Design 1 ACMS Desktop Components and Processing 1.1 ACMS Desktop Gateway Components 1.1.1 Desktop Client Program Components 1.1.2 Network Components 1.1.3 ACMS Desktop Gateway System Components 1.2 Desktop Client Program Processing 1.2.1 ACMS Desktop Client Services 1.2.2 Desktop Client Program Action Routines 1.2.3 Phases of Desktop Client Program Processing 1.3 Programming with ACMS Desktop Software 1.4 System Management with ACMS Desktop Software 1.5 ACMS Desktop Sample Application 2 Designing ACMS Desktop Solutions 2.1 ACMS Desktop Design Questions 2.1.1 Understanding Application Requirements 2.1.2 Choosing Presentation Software 2.1.3 Understanding Memory Constraints 2.1.4 Strategy for Implementing the Solution 2.2 Processing Design 2.2.1 NO I/O and I/O Tasks 2.2.1.1 NO I/O Task and ACMS Desktop Interaction 2.2.1.2 I/O Task and ACMS Desktop Interaction 2.2.1.3 Choosing Between I/O and NO I/O Tasks 2.2.2 Application Design Approaches 2.2.2.1 Common ACMS Applications 2.2.2.2 Tailored ACMS Applications 2.2.2.3 Conversion of a Task: I/O to NO I/O 2.2.3 Preventing Loss of Work with Local Data Capture 2.2.4 Event-Driven Systems and the Nonblocking Environment 2.2.5 Nonblocking Design Considerations 2.2.6 ACMS Desktop Gateway Availability 2.2.7 Error Handling 2.2.8 ACMS Desktop Gateway Error Checking 2.3 User Interface Design 2.4 Data Design 2.4.1 Data Conversion 2.4.2 Data Alignment with RISC Architecture Clients and OpenVMS Servers 2.4.3 Data Validation 2.4.4 Data Integrity 2.4.5 Workspace Design 2.4.5.1 Unidirectional and Bidirectional Workspaces 2.5 Design Conclusions 3 Developing ACMS Applications 3.1 Overall Development on the OpenVMS System 3.2 Creating Data Definitions for the Desktop System 3.3 Treating Forms in Task and Task Group Definitions 3.4 Enabling Version Checking on OpenVMS Systems 3.4.1 Building the ACMSDI_GET_VERSION Shareable Image 3.4.2 Defining the Version-Checking Logical Name 3.5 Getting Desktop Submitter Information 3.5.1 Coding the Routine 3.5.2 Building the Shareable Image 3.6 Debugging ACMS Desktop Solutions 3.6.1 Debugging the Desktop Client Program Only 3.6.2 Debugging NO I/O Tasks 3.6.3 Debugging Tasks Called from Desktop Client Programs 3.6.3.1 Defining the Gateway Process and Network Names 3.6.3.2 Defining Logical Names 3.6.3.3 Required Privileges 3.6.3.4 Installing the Desktop Gateway Images 3.6.3.5 Troubleshooting Problems in Starting Multiple Gateways 3.6.3.6 Starting the ACMS Desktop Gateway from an ACMS Task 3.6.3.7 Running the Task Debugger Session 3.6.3.8 Selecting a Gateway from a Portable API Client Program 3.6.3.9 Selecting a Gateway from a Macintosh Client 3.6.3.10 Managing ACMS Desktop Gateways Being Used for Debugging Purposes 3.6.3.11 Stopping an ACMS Desktop Gateway 3.6.3.12 Restrictions on Using Multiple Gateways 3.6.4 Debugging Procedure Server Code Part II Portable API and Macintosh Client Development 4 Developing Portable API Client Programs 4.1 Guideline Summary 4.1.1 Managing Code on the Desktop Client System 4.1.2 Structuring Exchange Steps in the Presentation Code 4.1.3 Data Conversion 4.1.4 Preventing Concurrent Use 4.2 Generating Workspaces for the Client 4.2.1 Generating Workspace Definitions 4.2.2 Using the MAKE_RECORDS.COM Utility 4.2.3 Generating Individual Workspace Definitions 4.2.4 Coding Workspace Fields 4.2.4.1 Initializing Workspaces from ACMS 4.2.4.2 Initializing Workspaces to ACMS 4.2.5 Choosing the Network Software 4.3 Writing Version-Checking Routines 4.3.1 Version-Checking Processing 4.3.2 Requesting Version Checking 4.4 AVERTZ Sample Desktop Client Program for DOS 4.4.1 AVERTZ Components for DOS 4.4.2 AVERTZ Component Processing Flow 4.4.3 Reusing the CLIENT.EXE Routines 4.5 Writing Procedures Using Blocking ACMS Desktop Client Services 4.5.1 Calling the Sign-In Service 4.5.2 Enabling Password Expiration Checking 4.5.3 Establishing an Exit Handler 4.5.4 Calling Tasks and Signing Out 4.5.5 Passing Multiple Workspaces on acmsdi_call_task 4.5.6 Using Unidirectional Workspaces on acmsdi_call_task 4.5.7 Providing Stub Routines 4.6 Writing Presentation Procedures in a Blocking Environment 4.6.1 Coding for acmsdi_enable and acmsdi_disable 4.6.2 Coding Return Status Values 4.7 Building and Debugging the Desktop Client Program 4.7.1 Linking the Desktop Client Program 4.7.2 Debugging the Desktop Client Program with Tasks 4.8 Using the DOS Desktop Client Program on Other Systems 5 Using Portable API Extensions for Microsoft Windows 5.1 Event-Driven Processing 5.2 Guidelines for Developing Windows Desktop Client Programs 5.3 AVERTZ Sample Desktop Client Program for Microsoft Windows 5.3.1 AVERTZ Components for Microsoft Windows 5.3.2 AVERTZ Component Processing Flow 5.4 Writing Client Procedures Using Nonblocking Services 5.4.1 Calling Nonblocking Services 5.4.2 Setting Up Polling 5.4.3 Establishing Session Context 5.4.4 Writing a Call to Other Nonblocking Services 5.4.5 Canceling Active Tasks 5.5 Writing Nonblocking Presentation Procedures 5.6 Writing Memory Allocation Routines 5.7 Building and Debugging Windows Desktop Client Programs 5.7.1 Building a Windows 95 or Windows NT Client Application 5.7.2 Maximum Lengths for Environmental Variables 5.8 Using ACMS Desktop DLLs in Windows Version 3.1 Applications 5.8.1 Guidelines for Using DLLs 5.9 Debugging the Nonblocking Desktop Client Program with Tasks 5.9.1 Using a Debugger to Step Through the Microsoft Windows Sample Application 6 Using Portable API Extensions for OSF/Motif 6.1 Event-Driven Processing 6.2 Guidelines for Developing X Windows Desktop Client Programs 6.3 AVERTZ Sample Desktop Client Program for X Windows 6.3.1 AVERTZ Components for X Windows 6.3.2 AVERTZ Component Processing Flow 6.4 Writing Client Procedures Using Nonblocking Services 6.4.1 Calling Nonblocking Services 6.4.2 Setting Up Polling 6.4.3 Establishing Session Context 6.4.4 Writing a Call to Other Nonblocking Services 6.5 Canceling Tasks 6.6 Writing Nonblocking Presentation Procedures 6.7 Special Handling of Workspaces for RISC Client Applications 6.8 Writing Memory Allocation Routines 6.9 Building and Debugging Motif Desktop Client Programs 6.9.1 Debugging the Nonblocking Desktop Client Program with Tasks 6.9.2 Using a Debugger to Step Through the Motif Sample Application 7 Forced Nonblocking Extension to the Portable API 7.1 Benefits of Forced Nonblocking 7.2 Portable API Extensions for Forced Nonblocking 7.3 New Data Structures 7.3.1 ACMSDI_FORM_RECORD_BIND Structure 7.3.2 ACMSDI_WORKSPACE_BIND Structure 7.4 Forced Nonblocking Programming Considerations 7.4.1 Establishing a Forced Nonblocking Session 7.4.2 Canceling a Task from a Forced Nonblocking Session 7.4.3 Polling for Messages 7.4.4 Obtaining Completion Arguments 7.5 Forced Nonblocking Exchange Step Handling 7.5.1 Enable Exchange Arguments 7.5.2 Receiving Exchange Arguments 7.5.3 Requesting Exchange Step Arguments 7.5.4 Send Exchange Step Arguments 7.5.5 Transceive Exchange Step Arguments 7.6 Sending and Receiving Forms Records and Workspaces 7.6.1 Receiving Send Forms Records and Control Text 7.6.2 Sending Receive Forms Records and Control Text 7.6.3 Sending and Receiving TDMS Request Workspaces 7.7 Forced Nonblocking Flow of Control 7.7.1 Structures Declared in Client Application Memory 7.7.2 Differences Between Standard and Forced Nonblocking 7.8 Forced Nonblocking Sample Application 7.8.1 Starting the Forced Nonblocking Sample 7.8.2 The Main Form 7.8.3 Starting and Stopping Polling 7.8.4 Forced Nonblocking Sample Sign In 7.8.5 Calling the ACMS Task from Sample 7.8.6 Forced Nonblocking Exchange Steps 7.8.6.1 Forced Nonblocking Enable Exchange Step 7.8.6.2 Transceive, Send and, Receive Exchange Steps 7.8.7 Task Completion 7.8.8 Signing Out 7.8.9 Cancelling the Task 8 Developing Macintosh Desktop Client Programs 8.1 Guidelines for Developing Macintosh Desktop Client Programs 8.1.1 Data Access Manager 8.1.2 Desktop Client Program Processing Flow 8.1.3 ACMS Desktop Services for Macintosh 8.1.4 Restrictions 8.1.5 Data Conversion and Data Types 8.1.6 Routine for Data Conversion, _ByteSwap 8.1.7 Date Format Conversion Routines 8.1.7.1 MACToVMSTime 8.1.7.2 VMSToMACTime 8.1.8 Macintosh Data Type Conversion Package 8.1.8.1 Data Conversion Module Description 8.1.8.2 MacToVms Function Description 8.1.8.3 VmsToMac Function Description 8.1.8.4 Locating and Using the Data Type Conversion Module 8.1.9 Communication Tools Supported by ACMS Desktop 8.1.10 Unidirectional Workspaces 8.1.11 Checking Software Versions 8.2 Implementing Macintosh Desktop Client Programs 8.2.1 Readying the Data Access Manager 8.2.2 Starting a Session 8.2.2.1 Sharing Sessions Across Client Programs and HyperCard Applications 8.2.2.2 Macintosh Handling of Password Expiring Messages 8.2.2.3 Starting a Session Following Program Termination 8.2.3 Calling a Task 8.2.3.1 Using Unidirectional Workspaces 8.2.4 Receiving Information from a Task 8.2.4.1 Checking for a Message 8.2.4.2 Receiving Task Results 8.2.5 Ending an Active Session 8.2.6 Getting Error Information 8.2.7 Canceling Active Tasks on the Macintosh System 8.2.8 Deleting Orphaned Sessions 8.3 Exchange Step Support and Other Advanced Features 8.3.1 DAM Constraints 8.3.2 Message Types 8.3.3 Keyword Acquisition 8.3.3.1 CALLTASK 8.3.3.2 Keywords that Identify Messages Sent from the Back End 8.3.3.3 Keyword Acquisition Using DBGetItem 8.3.4 Nonworkspace Data Items 8.3.4.1 Sending Nonworkspace Data 8.3.4.2 Alternate Method for Sending Nonworkspace Data 8.3.4.3 Acquiring Nonworkspace Data 8.3.5 Workspace Data 8.3.5.1 Sending Workspace Data 8.3.5.2 Acquiring Workspace Data 8.3.5.3 Workspaces in Request Messages 8.4 Building the Presentation Code 8.5 Debugging the Presentation Code 8.6 ACMS Desktop Samples for Macintosh 8.6.1 C Language Sample 8.6.2 HyperCard Samples 8.6.2.1 HyperCard ACMS Desktop Toolkit 8.6.2.2 4th Dimension Sample and External Functions 8.6.2.3 Sample XFCN Routines 8.6.3 AVERTZ Sample for Macintosh Part III ACMS Desktop Direct-Client Development for ACMSxp 9 ACMS Desktop Direct Client Development 9.1 ACMS Desktop Direct Client 9.1.1 Development Phase 9.1.2 Execution Phase 9.2 Writing Direct-Client Applications 9.3 PC-DCE Configuration 9.4 STDL Command Options A Sample Application Code B Tools