Several samples are provided for Macintosh, including a C language sample, a HyperCard TP Desktop Connector Toolkit, and a HyperCard implementation of AVERTZ.

8.6.1 C Language Sample

The C language sample ACMSDI_MAC_TEST.C, located in the Example folder, illustrates how to call the TP Desktop Connector DDEV from code written in Macintosh Programmer's Workshop (MPW) C language. The acmsdi_mac_test makefile links the sample desktop client program. A TeachText document named ACCOUNT.INFO must be modified to identify the OpenVMS node name, user name, password, and network information before the application can be executed.

The TP Desktop Connector software contains sample HyperCard stacks and external functions (XFCNs).

8.6.2.1 HyperCard TP Desktop Connector Toolkit

The HyperCard TP Desktop Connector Toolkit (HAT) stack provides a toolkit of documentation and samples for using HyperCard with TP Desktop Connector software. It is located in the HAT folder.

8.6.2.2 4th Dimension Sample and External Functions

The TP Desktop Connector software contains two sets of 4th Dimension Externals. One set includes a sample 4th Dimension application with external functions. The sources for this application provide an example of how to invoke the external function and how to write additional external functions.

The second set of 4th Dimension external functions are fully for production use. This set of 4th Dimension externals is documented in DIGITAL ACMS Desktop 4D Externals Users Guide. The guide is located online in the 4D Externals folder. To access the manual,

1. Click on the ACMS Desktop folder.
2. Click on the acmsdi_examples folder.
3. Click on Externals.
4. Click on 4D Externals.
5. Click on DIGITAL ACMS Desktop 4D Externals Users Guide.

TP Desktop Connector supports a set of external functions (XFCNs) that the HyperCard scripts use to communicate with the TP Desktop Connector DDEV. Another set of externals allows you to use Fourth Dimension software with TP Desktop Connector. The XFCNs for HyperCard are located in the XFCN_resources program. The XFCN sources are located in the Externals folder. A description of the XFCNs used with Fourth Dimension is contained in a text file on the kit.

These external functions include the actual calls to the Data Access Manager (DAM) services supported by the TP Desktop Connector DDEV. Figure 8-5 shows the relationship among these various parts of a typical HyperCard desktop client program.

Figure 8-5 HyperCard Desktop Client Program

The HyperCard XFCNs are designed to be common across any HyperCard solution that uses TP Desktop Connector software. The following are the XFCNs provided:

• ACMSEnd calls DBEnd to terminate a TP Desktop Connector session.
• ACMSExec calls DBExec to send a task start message to the TP Desktop Connector Gateway.
• ACMSGetConnInfo calls DBGetConnInfo to return information about an TP Desktop Connector session.
• ACMSGetErr calls the DBGetErr service.
• ACMSGetItem calls the DBGetItem service.
• ACMSGetSessionNum calls DBGetSessionNum to return the session number for the session you specify with the session ID.
• ACMSGetResWorkspace calls DBGetItem to retrieve data returned from an ACMS system in chunks of multiple fields, using a resource to define the data.
• ACMSGetWorkspace and ACMSGetResWorkspace retrieve complex workspaces from the TP Desktop Connector DDEV using the DBGetItem service.
• ACMSInitComm initializes the Communications Toolbox so that a HyperCard application can adopt a TP Desktop Connector session started by another application.
• ACMSInitPack calls the InitDBPack service.
• ACMSLogon calls the DBInit service.
• ACMSSend calls the DBSend service to pass one element to the TP Desktop Connector DDEV.
• ACMSSendItem calls the DBSendItem service to pass one element to the TP Desktop Connector DDEV.
• ACMSSendResWorkspace calls DBSendItem to prepare multiple workspace fields in a start-task message to be sent to a TP Desktop Connector Gateway, using a resource to describe the data.
• ACMSSendWorkspace and ACMSSendResWorkspace pass complex workspaces to the TP Desktop Connector DDEV using the DBSendItem service.
• ACMSState calls the DBState service.

The return status values for these XFCNS are the same as for the corresponding TP Desktop Connector client services. See the HyperTalk TP Desktop Connector Toolkit (HAT) stack for a further description of the sample XFCNs and their parameters.

8.6.3 AVERTZ Sample for Macintosh

The NO I/O version of the AVERTZ reserve task is provided in the VR_DA_APPL application database and in the VR_TASK_GROUP.TDB task group database file stored in the ACMSDI$EXAMPLES directory. To run the NO I/O version of the AVERTZ reserve task, you do not need to make any changes to the VR_DA_APPL application.

The NO I/O version of the reserve activity in the AVERTZ sample demonstrates making available database and computational work through a series of tasks rather than through a single task. For the reserve activity, the Macintosh desktop client program calls the following tasks rather than the single VR_RESERVE_TASK described in Chapter 4:

• VR_RESERVE_RES_DETAILS_TASK
• VR_RESERVE_STORE_CU_TASK
• VR_RESERVE_WRITE_RS_TASK

These tasks contain the processing steps of the original VR_RESERVE_TASK. They are invoked as individual tasks rather than as steps within a larger task.

Example 8-21 shows the source code for the task VR_RESERVE_RES_DETAILS_TASK.

In the I/O task VR_RESERVE_TASK shown in Example 4-4, workspaces are passed from an exchange step to the processing step. In each task in the series of NO I/O tasks shown in Example 8-21, workspaces are instead passed as task arguments into the task. Looping constructs in the action step are removed. Otherwise, the processing step is essentially the same as the corresponding step in the VR_RESERVE_TASK definition.

Example 8-21 VR_RESERVE_RES_DETAILS_TASK Definition

REPLACE TASK AVERTZ_CDD_TASK:VR_RESERVE_RES_DETAILS_TASK /LIST WORKSPACES ARE AVERTZ_CDD_WKSP:VR_RESERVATIONS_WKSP, AVERTZ_CDD_WKSP:VR_RENTAL_CLASSES_WKSP, AVERTZ_CDD_WKSP:VR_CONTROL_WKSP, AVERTZ_CDD_WKSP:VR_CUSTOMERS_WKSP, AVERTZ_CDD_WKSP:VR_CU_ARRAY_WKSP, AVERTZ_CDD_WKSP:VR_TRANS_WKSP, AVERTZ_CDD_WKSP:VR_CU_TRANS_ARRAY_WKSP, AVERTZ_CDD_WKSP:VR_SITES_WKSP, AVERTZ_CDD_WKSP:VR_SENDCTRL_WKSP; TASK ARGUMENTS ARE !+ ! all workspaces are modified either by step procedure or by ! step action clause. !- vr_reservations_wksp WITH ACCESS MODIFY, vr_rental_classes_wksp WITH ACCESS MODIFY, vr_control_wksp WITH ACCESS MODIFY, vr_customers_wksp WITH ACCESS MODIFY, vr_cu_array_wksp WITH ACCESS MODIFY, vr_trans_wksp WITH ACCESS MODIFY, vr_cu_trans_array_wksp WITH ACCESS MODIFY, vr_sites_wksp WITH ACCESS MODIFY, vr_sendctrl_wksp with ACCESS MODIFY; BLOCK WORK WITH NO TERMINAL I/O IS !+ ! Get site information and customer information !- CALL PROCEDURE vr_res_details_proc IN vr_read_server USING vr_reservations_wksp, vr_rental_classes_wksp, vr_control_wksp, vr_customers_wksp, vr_cu_array_wksp, vr_trans_wksp, vr_cu_trans_array_wksp, vr_sites_wksp; ACTION IS SELECT FIRST TRUE OF (ACMS$T_STATUS_TYPE = "B"): GET MESSAGE INTO vr_control_wksp.messagepanel; MOVE "ACTWT" TO vr_sendctrl_wksp.sendctrl_key; END SELECT; END BLOCK WORK; END DEFINITION;

The general steps to convert an I/O task to a series of NO I/O tasks are given in Section 2.2.2.3.

The user invokes the AVERTZ desktop client program (double clicking on the AVERTZ Auto Reservation System) and signs in to the ACMS system (using the Connection pull-down menu for a new connection). From the reservation form, the user can perform the following functions:

• SEND
  1. Fill in site identification. Using the search capabilities on the desktop, the site identification is validated. This operation is processed locally at the desktop level.
  2. Choose car type. The car types are held locally.
  3. Enter reservation pick up and return dates.
  4. Enter a customer identification or a unique customer name. The desktop client program invokes the VR_RESERVE_RES_DETAILS_TASK that checks whether a reservation can be made with the reservation specifications and retrieves the customer information, if it exists and only if the reservation can be made.
  5. If customer information is found, that information is displayed on the reservation form.
  6. A message is displayed on failure. Success is the retrieval of customer data.
     The AVERTZ sample does not support the list retrieval of more than one customer when provided with a nonunique customer name.
• UPDATE
  This function adds or updates customer information:
  1. The user enters customer information: name, address, phone number, and license information.
  2. The desktop client program invokes the VR_RESERVE_STORE_CU_TASK, which updates the customer database on the ACMS system.
  3. A message is displayed for success or failure of this task.

• RENT
  This function updates customer information and makes a reservation.
  1. User enters all information on the AVERTZ reservation and does one of the following:
     • Invokes the SEND function, updates the information, and invokes the RENT function.
     • Invokes the SEND function, updates the information, invokes the UPDATE function, and invokes the RENT function.
       (The customer data is updated twice.)
  2. User enters all data on the screen and invokes the RENT function.
     The desktop client program invokes the VR_RESERVE_RES_DETAILS_TASK first, then the VR_RESERVE_STORE_CU_TASK, and finally the VR_RESERVE_WRITE_RS_TASK.

Section 8.2 describes how to implement solutions that use a series of tasks.

In the HyperTalk sample scripts, all flow control for the reserve function resides in the desktop client program.

This appendix describes where to find sample code that runs on a DIGITAL ACMS system with the TP Desktop Connector Gateway for ACMS and on supported desktop systems. To locate the directories containing the code, use the logical names in Table A-1 and Table A-2.

The logical names in both tables are defined when the DIGITAL TP Desktop Connector gateway starts (see DIGITAL TP Desktop for ACMS Gateway Management Guide). If they are not defined on your system, consult the system manager.

Table A-1 TP Desktop Connector API Directories

Logical Name	Directory Contents
ACMSDI$COMMON	Files common across platforms needed to compile and link the client services
ACMSDI$MACINTOSH	DIGITAL TP Desktop Connector DDEV and ACMSDI_MAC.H include file
ACMSDI$MSDOS	DOS and Windows Version 3.1 DIGITAL TP Desktop Connector client services libraries for building desktop client programs on DOS systems
ACMSDI$WIN95	Windows 95 DIGITAL TP Desktop Connector client services libraries for building desktop client programs on Windows 95 systems
ACMSDI$NT_ALPHA	Windows NT TP Desktop client services libraries for building desktop client programs on Alpha systems
ACMSDI$NT_I86	Windows NT TP Desktop client services libraries for building desktop client programs on Intel systems
ACMSDI$UNIX	Digital UNIX TP Desktop client services libraries for building Digital UNIX client programs
ACMSDI$VMS	OpenVMS TP Desktop client services libraries for building desktop client programs on OpenVMS systems
ACMSDI$VMS_ALPHA	OpenVMS Alpha TP Desktop client services libraries for building desktop client programs on OpenVMS Alpha systems

Table A-2 DIGITAL TP Desktop Connector Directories

Logical Name	Directory Contents
ACMSDI_AVERTZ_DEFAULT	ACMS AVERTZ sources
ACMSDI$EXAMPLES	General tools
ACMSDI$EXAMPLES_ACMS	AVERTZ task definitions and database software
ACMSDI$EXAMPLES_MACINTOSH	Program source and executable file for the Macintosh sample desktop client program
ACMSDI$EXAMPLES_MOTIF	Motif sample sources
ACMSDI$EXAMPLES_MOTIF_UNIX	Platform-specific files: makefile, executable, and so on, for the Digital UNIX Motif sample
ACMSDI$EXAMPLES_MOTIF_VMS	Platform-specific files: makefile, executable file, and so on, for the OpenVMS Motif sample
ACMSDI$EXAMPLES_MOTIF_VMS_ALPHA	Platform-specific files: makefile, executable file, and so on, for the OpenVMS Alpha Motif sample
ACMSDI$EXAMPLES_MSDOS	Program source and executable file for the DOS blocking environment sample desktop client program
ACMSDI$EXAMPLES_MSW31	Program source and executable file for the Microsoft Windows Version 3.1 nonblocking environment sample desktop client program
ACMSDI$EXAMPLES_WIN95	Program source and executable file for the Microsoft Windows 95 client program.
ACMSDI$EXAMPLES_MSWINDOWS_NT_ALPHA	Program source and executable file for the Microsoft Windows NT for Alpha nonblocking environment sample desktop client program
ACMSDI$EXAMPLES_MSWINDOWS_NT_I86	Program source and executable file for the Microsoft Windows NT for Intel nonblocking environment sample desktop client program
ACMSDI$EXAMPLES_MSWINDOWS_VB	Program source and executable file for the Microsoft Visual Basic sample desktop client programs
AVERTZ_TDB	ACMS AVERTZ sources

The ACMSDI$EXAMPLES directory contains a collection of general purpose tools, include files, and sample programs. Table B-1, Table B-2, and Table B-3 contain the following lists:

• Development tools and files
• Runtime tools
• General samples

Table B-1 Development Tools and Files

Tool	Description
FORMS.H	Include file that contains DECforms status codes. These status codes can be used by the client program's presentation procedures to return valid forms status values. (These values are used for the DECforms-style presentation procedures: acmsdi_enable, acmsdi_send, acmsdi_receive, acmsdi_transceive, acmsdi_disable)
MAKE_CBL.COM	Command procedure used by the tool MAKE_RECORDS.COM to generate COBOL include files for workspace definitions.
MAKE_FORMS_H.COM	Command procedure that generates an include file called forms.h. This header file contains all the status codes recognized by forms$manager.exe. It can be used by the client program's presentation procedures to return valid forms status values. (These values are used for the DECforms-style presentation procedures: acmsdi_enable, acmsdi_send, acmsdi_receive, acmsdi_transceive, acmsdi_disable.) For example: $ @MAKE_FORMS_H
MAKE_H.COM	Command procedure used by the tool MAKE_RECORDS.COM to generate C include files for workspace definitions.
MAKE_RECORDS.COM	Command procedure that generates C structure definitions or COBOL record definitions for the ACMS workspaces used by an application. This tool uses the record definitions in CDD to generate either C or COBOL include files. For example: $ @MAKE_RECORDS cdd-path { COBOL | C }
MAKE_TDMS_H.COM	Command procedure that generates an include file called tdms.h. This header file contains all the status codes recognized by tssshr.exe. It can be used by the client program's presentation procedures to return valid forms status values. (These values are used for the TDMS-style presentation procedure, acmsdi_request.) For example: $ @MAKE_TDMS_H
PPGEN.COM	Command procedure that generates presentation procedure code. This tool uses the ACMS application's .TDB file to generate code for the presentation procedures that does the following: Validates the number and size of workspaces passed in to the presentation procedure. Invokes the application-specific presentation procedures. (Names for the application-specific presentation procedures are based on the names used in the task definition.) Stubs for the application-specific presentation procedures are generated as well. For example: $ @PPGEN tdb-file-name
TDMS.H	Include file that contains TDMS status codes. These status codes can be used by the client program's presentation procedures to return valid forms status values. (These values are used for the TDMS-style presentation procedure, acmsdi_request.)

Table B-2 Runtime Tools

Tool	Description
ACMSDI$CANCEL.COM	Command procedure that automatically cancels TP Desktop Connector users who have been inactive for a specified period of time. See the ACMSDI$CANCEL.COM file for instructions on usage.
SHOW_DESKTOP_USERS.EXE	Displays submitter information such as user name, client node name, network transport, and so forth, for all Desktop users that are currently signed in to the TP Desktop Connector Gateway on this node. For example: $ RUN SHOW_DESKTOP_USERS

Table B-3 General Samples

Sample Build Procedure	Description
ACMSDI_GET_VERSION.COM	Command procedure that builds a sample version of ACMSDI$GET_VERSION.EXE. See also the ACMSDI_GET_VERSION sources.
BUILD_SHOW_DESKTOP_USERS.COM	Command procedure that builds a sample, which demonstrates the use of the ACMSDI$GET_SUBMITTER_INFO OpenVMS service. See also the SHOW_DESKTOP_USER sources.