Compaq TP Desktop Connector
for ACMS
Client Application Programming Guide


Previous Contents Index

8.6 TP Desktop Connector Samples for Macintosh

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.

Note

Locate the ACMSDI_MAC_TEST.C file in the Example folder. The ACMSDI$EXAMPLES_MACINTOSH directory on OpenVMS contains a command file ACMSDI_MAC_TEST.COM to build the ACMS application that works with the C language sample.

8.6.2 HyperCard Samples

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 Compaq 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 Compaq ACMS Desktop 4D Externals Users Guide.

8.6.2.3 Sample XFCN Routines

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:

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:

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:

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.


Appendix A
Sample Application Code

This appendix describes where to find sample code that runs on a Compaq 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 TP Desktop Connector gateway starts (see Compaq 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 TP Desktop Connector DDEV and ACMSDI_MAC.H include file
ACMSDI$MSDOS DOS and Windows Version 3.1 TP Desktop Connector client services libraries for building desktop client programs on DOS systems
ACMSDI$WIN95 Windows 95 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 Compaq Tru64 UNIX TP Desktop client services libraries for building Compaq Tru64 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 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 Compaq Tru64 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


Appendix B
Tools

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:

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.


Index Contents