Previous | Contents | Index |
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
Data Type | Code | Description |
---|---|---|
Single byte | '1' | No conversion is performed. |
Short integer | '2' | Bytes 1 and 2 are swapped. |
Counted field | '3' | Short int count field preceding data is byteswapped; data is skipped. |
Long integer | '4' | Bytes 1 and 4 are swapped; bytes 2 and 3 are swapped. |
Text field | '5' | No conversion is performed. |
Date and time | '6' | Primitive conversions only. The long integer Macintosh time counter is converted to a quadword (C type comp) OpenVMS time counter. |
... | '7' | Reserved. |
Quadword | '8' | Passed as a single 8-byte field. Bytes 8 and 1 are swapped, bytes 7 and 2 are swapped, bytes 6 and 3 are swapped, and bytes 5 and 4 are swapped. |
Float | 'F' | Single precision Macintosh floating-point number is converted to an OpenVMS type f single-precision, floating-point number. |
Double | 'D' | Double-precision Macintosh floating-point number is converted to a OpenVMS type g double-precision floating-point number. |
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
Data Type | Code | Description |
---|---|---|
Single byte | '1' | No conversion is performed. |
Short integer | '2' | Bytes 1 and 2 are swapped. |
Counted field | '3' | Short int count field preceding data is byteswapped; data is skipped. |
Long integer | '4' | Bytes 1 and 4 are swapped; bytes 2 and 3 are swapped. |
Text field | '5' | No conversion is performed. |
Date and time | '6' | Primitive conversions only. The quadword (C type comp) OpenVMS counter is converted to a long integer Macintosh time counter. |
... | '7' | Reserved. |
Quadword | '8' | Passed as a single 8-byte field. Bytes 8 and 1 are swapped, bytes 7 and 2 are swapped, bytes 6 and 3 are swapped and bytes 5 and 4 are swapped. |
Float | 'F' | Single-precision OpenVMS floating-point number is converted to a Macintosh single-precision floating-point number. |
Double | 'D' | Double-precision OpenVMS type g floating-point number is converted to a Macintosh double-precision floating-point number. |
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:
Figure 8-2 Using the DECnet Tool on Macintosh
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
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:
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. DIGITAL 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 |
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 DIGITAL 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 DIGITAL 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 |
You can share a session between one or more client programs on the Macintosh. However, to do so, the program that is adopting the session must issue three special initialization calls to the Communications Toolbox. These calls are:
You must issue these calls before you issue any DAM calls for the adopted session. Failure to do so could cause your Macintosh to crash. The calls must be issued in the same order as listed above. The following code sample illustrates the use of these calls in C:
#include <CRMIntf.h> #include <CTBUtils.h> #include <CMIntf.h> OSErr InitToolbox() { CRMErr CRMstatus; CTBUErr CTBUstatus; CMErr CMstatus; CRMstatus = InitCRM(); if (CRMstatus != noErr) return CRMstatus; CTBUstatus = InitCTBUtilities(); if (CTBUstatus != noErr) return CTBUstatus; CMstatus = InitCM(); return CMstatus; } |
The uses of these calls are explained in PATHWORKS for Macintosh Communications Toolbox Programmer's Reference.
You can also share sessions between HyperCard applications and programs written in some other language. A program written in some other language can adopt a session started by HyperCard.
If a HyperCard application wants to adopt a session written in some other language or from an earlier execution of HyperCard, the application must issue an XFCN call, ACMSInitComm(). Include the ACMSInitComm XFCN as an XFCN resource in your HyperCard stack. Look in the XFCN_resources program in the HyperCard Externals folder for this XFCN. The folder also contains the source code for the ACMSInitComm XFCN.
Any HyperCard stack can adopt a session started by another HyperCard stack in the same execution of HyperCard. Therefore, you do not need to issue an ACMSInitComm call in this case.
Previous | Next | Contents | Index |