Compaq TP Desktop Connector
for ACMS
Client Application Programming Guide
Previous Contents Index

8.1.8.1 Data Conversion Module Description

The data conversion module converts a data element of a given data type from Macintosh to OpenVMS format and OpenVMS to Macintosh format.

The following data types are converted:

The following data types are not converted:

8.1.8.2 MacToVms Function Description

MacToVms conversion routine converts data elements from Macintosh to OpenVMS format. This routine accepts a pointer to an existing Macintosh element and a pointer to a location where the element is placed after it is converted to OpenVMS format.

The pointers can be to the same location, causing a conversion in place. The MactoVMS routine also accepts a single char, indicating the data type and another short int indicating the length of the element. The length indicator is ignored except when the data type is text. It converts the element and places it where the user wants it.

The routine returns a short int with one of the following values:

MacToVms Input Parameters

MacToVms Function Prototype 


 
pascal short MacToVms (void *MACFmt, 
                       void *VMSFmt, 
                       char dType, 
                       unsigned short len);

This function prototype is included in file acmsdi_mac.h.

8.1.8.3 VmsToMac Function Description

The VmsToMac routine converts data elements from OpenVMS to Macintosh format. This routine accepts a pointer to an existing OpenVMS element and a pointer to a location where the element is placed after it is converted to Macintosh format.

The pointers can be to the same location, causing a conversion in place. Also accepts a single char, indicating the data type and another short int indicating the length of the element. The length indicator is ignored except when the data type is text. Converts the element and places it where the user wants it.

The routine returns a short int with one of the following values:

VmsToMac Input Parameters

VmsToMac Function Prototype 


pascal short VmsToMac (void *VMSFmt, 
                       void *MACFmt, 
                       char dType, 
                       unsigned short len);

This function prototype is included in file acmsdi_mac.h.

8.1.8.4 Locating and Using the Data Type Conversion Module

The data type conversion module is in object form in the Utilities folder within the Acmsdi-System folder. Its name is dataConversions.c.o. A copy of the header file acmsdi_mac.h is also in the folder, to be used when compiling your application modules.

After writing an application module that includes either MacToVms, VmsToMac, or both function calls, you must link the module with three of the object files found in the utilities folder. These three files are dataConversions.c.o, DateConversion.c.o, and byteswap.c.o.

Look in the acmsdi_mac.h file in the Utilities folder with the Acmsdi_System folder for information on data conversion routines and macros.

8.1.9 Communication Tools Supported by TP Desktop Connector

TP Desktop Connector software supports five communication protocols between the Macintosh desktop client program and the TP Desktop Connector Gateway for ACMS:

In Figure 8-3, the TP Desktop Connector gateway can reside on the same system as the AppleTalk-DECnet Transport gateway, although this is not a requirement.

Figure 8-3 Using the AppleTalk-DECnet Tool on Macintosh

8.1.10 Unidirectional Workspaces

A unidirectional workspace is a workspace that travels in one direction on TP Desktop Connector CallTask and EndTask requests. TP Desktop Connector provides three types of workspaces, two of which are unidirectional. The three types of workspaces are:

Note
The read and the write are from the perspective of the ACMS application (back-end) perspective.

The three arguments affected by unidirectional workspaces are flags, buffer, and length. You identify a read-only workspace to the DDEV with the flags parameter of the DBSendItem function. You also identify write-only workspaces with the flags parameter of the DBSendItem function. Because no actual data is sent with the write-only workspace, you can specify the DBSendItem buffer parameter as NULL. You do need to specify the length parameter of the write-only workspace, because the TP Desktop Connector gateway needs to know how long the workspace is to allocate a buffer for it on the host node.

If you use NULL for the flags parameter on the DBSendItem function, TP Desktop Connector defaults to a modify workspace. See Section 8.2.3.1 for information on specifying the parameters to the DBSendItem function.

8.1.11 Checking Software Versions

TP Desktop Connector DDEV does not provide a mechanism for comparing versions of ACMS software and desktop client programs. To protect against problems caused by version differences, include version information in a workspace sent on the CallTask request for comparison in a processing step in the ACMS application. If the processing step detects a difference in version, it can then terminate the task and return a message such as "incompatible versions" to the desktop client program.

8.2 Implementing Macintosh Desktop Client Programs

The work of implementing the desktop client program falls into the following major areas:

Sections 8.4 and 8.5 describe how to build and debug the code you write. Compaq TP Desktop Connector for ACMS Client Services Reference Manual fully describes the TP Desktop Connector DAM services shown in the examples used in this section.

8.2.1 Readying the Data Access Manager

After your desktop client program completes initialization work, such as setting up fonts, windows, menus, and other tools, the program loads the Data Access Manager by calling InitDBPack, as shown in Example 8-1.

Example 8-1 Initializing the Data Access Manager 

short    status;    /* Status Variable */ 
 
    status = InitDBPack(); 
    if (status !=  noErr) 
        { 
        printf ("InitDBPack failed. Error code %d\n", status); 
        exit (0); 
        }

Any error in calling InitDBPack is unrecoverable. The interface routine that implements the InitDBPack function includes a version number for DAM. If the package version returned differs from that specified by the interface routine, the InitDBPack function returns the rcDBWrongVersion return status. If an error occurs in calling InitDBPack, the desktop client program should notify the user of the failure and then exit.

For the HyperCard implementation of AVERTZ, this initialization is handled in the main (stack) script that invokes the ACMSInitPack XFCN, as shown in Example 8-2.

Example 8-2 Calling ACMSInitPack 

on initCall    -- called from "on openstack" 
   .
   .
   .
        put ACMSInitPack() into lastStatus 
        if laststatus is not 0 then 
                answer "Initialization error" 
        end if 
end initCall

8.2.2 Starting a Session

After the Data Access Manager is loaded, the desktop client program can start sessions with an ACMS system. To start a session, use the DBInit service as shown in Example 8-3.

Example 8-3 Calling DBInit 

short       status;                                 /* Status Variable */ 
long        sessid1;                                /* Session Id      */ 
char        username[255];                          /* Username Name */ 
char        password[255];                          /* Password */ 
#define ddev       "\pACMSDI"                       /* ACMSDI DDEV */ 
#define node       "\pBOSTON"                       /* Node Name */ 
#define connstring "\p\"Appletalk-DECnet Tool\"TimeOut 30"/* Communication String */ 
    status = get_access( &username, &password );    /* get username and password */ 
    if (status != noErr) 
            my_exit (status, 0, "Could not get username and password"); 
 
    status = DBInit (&sessid1, 
                      ddev, 
                      node, 
                      username, 
                      password, 
                      connstring, 
                      NULL ); 
 
    if (status != noErr) 
         my_exit (status, sessid1, "DBInit Failed");

The DBInit service executes synchronously in block mode, stalling the program until the ACMS system processes the sign-in request. However, if you include a TimeOut argument as shown in Example 8-3, you can limit the time the DDEV waits for a connection to occur. Example 8-3 specifies 30 seconds. If you do not specify a TimeOut argument, the default wait time is 60 seconds.

You include special sign-in parameters for the TP Desktop Connector DAM API in the connection string argument passed to the DDEV with the DBInit calls. The connection string is a Pascal-type string containing parameters that specify sign-in options.

To enable a communications tool on a desktop system configured with the appropriate software, specify one of the following Pascal-formatted text strings in the connection string parameter: 


"\p\"DECnet Tool\"" for DECnet software 
"\p\"AppleTalk-DECnet Tool\"" for AppleTalk-DECnet Transport Gateway 
software 
"\p\"MacTCP Tool\"" for TCP/IP Transport Services 
"\p\"AppleTalk ADSP Tool\""for direct AppleTalk (with no gateway) 
"\p\"XPC Tool\"" for serial communication services

You can also use the connection string to specify additional arguments to control the communications connection. Most of the connection string arguments are directly related to the communications tool specified. However, you can use the following arguments with all communications tools:

For more information on these special arguments to the connection string argument, see Compaq TP Desktop for ACMS Gateway Management Guide.

If the ACMS sign-in succeeds, the status noErr is returned and a nonzero session identification is returned in the sessid parameter. This session identification is unique on the desktop system (not on the network) and is used on all other calls to the TP Desktop Connector DDEV for the session.

If the DBInit call or the sign-in request fails, a status other than noErr and a nonzero session identification are normally returned. This nonzero session identification refers to what is called a zombie session, which is a session that does not have a network connection and is, therefore, useful only to check error conditions on the DBInit call. The desktop client program can call DBGetErr to receive more information about the error condition. The desktop client program must call DBEnd to close the session and free up session resources (see Section 8.2.5). The error codes returned by the DBInit service are listed in Compaq TP Desktop Connector for ACMS Client Services Reference Manual.

If the status rcDBError is returned, errors are usually related to the following types of problems:

The TP Desktop Connector client services allow the desktop client program to create as many sessions as resources permit, to a maximum of 32. Each session can have only one task active at any time. If the user activity requires data from several tasks at the same time, the desktop client program can start multiple sign-ins. These sign-ins can be with a single ACMS system, different nodes within a single VMScluster, nodes that are not in the same VMScluster, or any combination of the three connections. For more information on failover and connectivity, see Section 2.2.6 and Section 2.3.

The HyperCard implementation of AVERTZ calls the DBInit function as part of the ACMSLogon XFCN. ACMSLogon is called in the Message Catcher script, as shown in Example 8-4.

Example 8-4 Calling ACMSLogon 

function createSession 
   .
   .
   .
    put ACMSLogon ("newSid","ACMSDI",nodeHold,userID,PWhold,connstr) into laststatus 
    if laststatus is not 0 then 
        put GetErr (newSid,"ACMS End On Failed Login") into stat 
        put ACMSEnd (newSID) into stat 
    end if 
   .
   .
   .
end createSession

Previous Next Contents Index