DIGITAL TP Desktop Connector
for ACMS
Client Services Reference Manual

Chapter 5
Client Services for Macintosh Software

This chapter describes the client services that the DIGITAL TP Desktop Connector for ACMS software provides on the Macintosh system.

5.1 Summary of Client Services for Macintosh Software

Table 5-1 summarizes the DIGITAL TP Desktop Connector client services.

Table 5-1 Summary of Client Services for Macintosh Software
Service Description

Initialization

InitDBPack Initializes the Data Access Manager (DAM) software.

Control

DBBreak Cancels an active ACMS task.

DBEnd Requests the TP Desktop Connector gateway to sign a desktop client program session out of the ACMS system.

DBGetConnInfo Returns information about a given session, including the node with which the session is communicating and the current state of the connection.

DBGetErr Returns additional desktop client program information when an unexpected status is returned by another TP Desktop Connector client service.

DBGetSessionNum Returns the session number for a given session.

DBInit Sends an authentication request to a selected TP Desktop Connector gateway. Loads the TP Desktop Connector DDEV and creates a DAM session.

Sending Messages

DBSend Prepares a message of any data type for transmission to the TP Desktop Connector gateway. Used only with modifiable workspaces and header data.

DBSendItem Prepares a message of any data type for transmission to the TP Desktop Connector gateway. Used with modifiable and unidirectional workspaces and header data.

DBExec Sends the message prepared using either DBSend or DBSendItem.

Receiving Messages

DBGetItem Retrieves data returned from the TP Desktop Connector gateway.

DBState Returns status about messages pending from the TP Desktop Connector gateway.

**Table 5-1 Summary of Client Services for Macintosh Software**
	Service	Description
Initialization
	InitDBPack	Initializes the Data Access Manager (DAM) software.
Control
	DBBreak	Cancels an active ACMS task.
	DBEnd	Requests the TP Desktop Connector gateway to sign a desktop client program session out of the ACMS system.
	DBGetConnInfo	Returns information about a given session, including the node with which the session is communicating and the current state of the connection.
	DBGetErr	Returns additional desktop client program information when an unexpected status is returned by another TP Desktop Connector client service.
	DBGetSessionNum	Returns the session number for a given session.
	DBInit	Sends an authentication request to a selected TP Desktop Connector gateway. Loads the TP Desktop Connector DDEV and creates a DAM session.
Sending Messages
	DBSend	Prepares a message of any data type for transmission to the TP Desktop Connector gateway. Used only with modifiable workspaces and header data.
	DBSendItem	Prepares a message of any data type for transmission to the TP Desktop Connector gateway. Used with modifiable and unidirectional workspaces and header data.
	DBExec	Sends the message prepared using either DBSend or DBSendItem.
Receiving Messages
	DBGetItem	Retrieves data returned from the TP Desktop Connector gateway.
	DBState	Returns status about messages pending from the TP Desktop Connector gateway.

5.1.1 Return Status Values

Each service returns a status value defined as Short Int. Only the status codes defined in the related reference sections are valid in the TP Desktop Connector client services. The definitions for the return status values are in the include file ACMSDI_MAC.H.

5.1.2 Session Identification Parameter

The DAM interface services parameter sessID corresponds functionally to the ACMS submitter identification used on other platforms.

5.2 DBBreak

This service cancels an active task with a remote ACMS system. Do not use the DBBreak service while processing an exchange step request.

To return the results of the DBBreak, issue a DBGetErr before issuing a DBState. Once you issue a DBState, any subsequent DBGetErr returns the results of the task call.

Format

DBBreak (sessID,
reserved,
reserved )

Parameters

sessID
Type: Long Int
Access: read
Mechanism: by value
The ID of the session whose task is to be canceled, as returned by the DBInit service.
reserved
Type: Boolean
Access: read
Mechanism: by value
Specify FALSE.
reserved
Type: Long Int
Access: read
Mechanism: by reference
Specify as NULL.

Return Status

The status values returned by the DBBreak service are listed in Table 5-2.

Table 5-2 DBBreak Return Status Values
Status Value Description

noErr 0 No error

rcDBError --802 The operation has failed

rcDBBadSessID --806 Bad session identification

rcDBAsyncNotSupp --809 DDEV does not support asynchronous calls

rcDBPackNotInited --813 InitDBPack not called

Note
See Appendix A for information on return status values specific to TP Desktop Connector.

**Table 5-2 DBBreak Return Status Values**
Status	Value	Description
noErr	0	No error
rcDBError	--802	The operation has failed
rcDBBadSessID	--806	Bad session identification
rcDBAsyncNotSupp	--809	DDEV does not support asynchronous calls
rcDBPackNotInited	--813	InitDBPack not called

5.3 DBEnd

This service ends a DAM session and terminates its connection, if any, with an ACMS system. A desktop client program must call DBEnd to terminate a session.

Format

DBEnd (sessID,
reserved )

Parameters

sessID
Type: Long Int
Access: read
Mechanism: by value
Identification of the session to be terminated, as returned by the DBInit service.
reserved
Type: Long Int
Access: read
Mechanism: by reference
Specify as NULL.

Return Status

The status values returned by the DBEnd service are listed in Table 5-3.

Table 5-3 DBEnd Return Status Values
Status Value Description

noErr 0 No error

rcDBError --802 The operation has failed

rcDBExec --805 ACMS task still executing on back end

rcDBBadSessID --806 Bad session identification

rcDBAsyncNotSupp --809 DDEV does not support asynchronous calls

rcDBPackNotInited --813 InitDBPack not called

**Table 5-3 DBEnd Return Status Values**
Status	Value	Description
noErr	0	No error
rcDBError	--802	The operation has failed
rcDBExec	--805	ACMS task still executing on back end
rcDBBadSessID	--806	Bad session identification
rcDBAsyncNotSupp	--809	DDEV does not support asynchronous calls
rcDBPackNotInited	--813	InitDBPack not called

5.4 DBExec

This service transmits a message to an ACMS system.

Format

DBExec (sessID,
reserved )

Parameters

sessID
Type: Long Int
Access: read
Mechanism: by value
Identification of the session in which the message is to be transmitted, as returned by the DBInit service.
reserved
Type: Long Int
Access: read
Mechanism: by reference
Specify as NULL.

Return Status

The status values returned by the DBExec service are listed in Table 5-4.

Table 5-4 DBExec Return Status Values
Status Value Description

noErr 0 No error

rcDBError --802 Error trying to begin execution

rcDBBadSessID --806 Bad session identification

rcDBAsyncNotSupp --809 DDEV does not support asynchronous calls

rcDBPackNotInited --813 InitDBPack not called

**Table 5-4 DBExec Return Status Values**
Status	Value	Description
noErr	0	No error
rcDBError	--802	Error trying to begin execution
rcDBBadSessID	--806	Bad session identification
rcDBAsyncNotSupp	--809	DDEV does not support asynchronous calls
rcDBPackNotInited	--813	InitDBPack not called

5.5 DBGetConnInfo

This service returns information about a specified session, including:

Version of the DDEV
Name of the remote system on which the session is running
User name
Connection string
Name of the network
Time at which the session started
Status of the session

You can use the function to get information about a particular session, or you can call the function repeatedly, incrementing the session number each time, to get information about all the sessions associated with the DDEV. You can call the function repeatedly until you receive the return status value --807. If you include a nonzero value for the session ID parameter when you call the function, the function returns the session information plus the DDEV name. If you use 0 for the ID and specify the DDEV name and session number, then the function returns the session ID.

SessID is the permanent number assigned to the session by the DDEV. The session number is a number starting at 1 for the oldest still active session in the DDEV, 2 for the next oldest, and so on. The session number for a session can change, depending on what other sessions are active and how these overlap in terms of being active at the same time.

Format

DBGetConnInfo (sessID,
sessNum,
returnedID,
version,
ddevName,
host,
username,
network,
connStr,
start,
state,
reserved )

Parameters

sessID
Type: Long Int
Access: read
Mechanism: by value
The session ID, as returned by the DBInit service. This must be zero if a nonzero session number is specified.
sessNum
Type: Short Int
Access: read or write
Mechanism: by reference
The session number. This must be zero if a nonzero session ID is specified. If you specify the session number, you must also specify DDEV as well.
returnedID
Type: Long Int
Access: write
Mechanism: by reference
The ID of the session corresponding to a particular session number and DDEV.
version
Type: Long Int
Access: write
Mechanism: by reference
The version number of the DDEV.

Note
You can use the DISPLAY_VERSION function call or the DDEV_VERSION macro to convert the version returned by DBGetConnInfo to a format you can display. The ACMSDI_MAC.H file contains a description of the DISPLAY_VERSION call and DDEV_VERSION macro.

ddevName
Type: char *
Access: read
Mechanism: by reference
A Pascal-format string with a maximum of 63 characters containing the name of the DDEV handling this session. You must specify this argument if sessNum is not equal to zero. For TP Desktop Connector, the DDEV name is ACMSDI.
host
Type: char *
Access: write
Mechanism: by reference
A 255-byte Pascal-format string containing the host name and other information used in connecting this session to an ACMS system.
username
Type: char *
Access: write
Mechanism: by reference
A 255-byte Pascal-format string containing the user name used in connecting the session to an ACMS system.
network
Type: char *
Access: write
Mechanism: by reference
A 255-byte Pascal-format string containing the name of the network type used in connecting this session to an ACMS system. The type can be either:

ADSP
AppleTalk
DECnet
TCP/IP
XPC

If the DAM session is a zombie session, the field contains the message *** No Network Connections ***.
connStr
Type: char *
Access: write
Mechanism: by reference
A 255-byte Pascal-format string containing the connection string used in connecting this session to an ACMS system.
start
Type: Long Int
Access: write
Mechanism: by reference
The time at which this session was initiated, in clock ticks since booted.
state
Type: OSErr
Access: write
Mechanism: by reference
The status of the session. Values can be:

Status Value Description

noErr --800 Ready; no data available

rcDBValue --801 Ready; data available

rcDBError --802 Execution ended in an error

rcDBExec --805 Executing a transaction

reserved
Type: Long Int
Access: read
Mechanism: by reference
Specify as NULL.

Status	Value	Description
noErr	--800	Ready; no data available
rcDBValue	--801	Ready; data available
rcDBError	--802	Execution ended in an error
rcDBExec	--805	Executing a transaction

Return Status

The status values returned by the DBGetConnInfo service are listed in Table 5-5.

Table 5-5 DBGetConnInfo Return Status Values
Status Value Description

noErr 0 No error

rcDBBadSessID --806 Session identification is invalid

rcDBBadSessNum --807 Session number is invalid

rcDBBadDDEV --808 Could not find or open DDEV

rcDBAsyncNotSupp --809 DDEV does not support asynchronous calls

rcDBPackNotInited --813 InitDBPack function has not been called

**Table 5-5 DBGetConnInfo Return Status Values**
Status	Value	Description
noErr	0	No error
rcDBBadSessID	--806	Session identification is invalid
rcDBBadSessNum	--807	Session number is invalid
rcDBBadDDEV	--808	Could not find or open DDEV
rcDBAsyncNotSupp	--809	DDEV does not support asynchronous calls
rcDBPackNotInited	--813	InitDBPack function has not been called

5.6 DBGetErr

This service retrieves any error codes and error messages from the TP Desktop Connector DDEV. Use this function to obtain information after any TP Desktop Connector client service passes back a return status. Specify a DBGetErr after a DBBreak to return the status of the cancellation.

Format

DBGetErr (sessID,
err1,
err2,
item1,
item2,
errorMsg,
reserved )

Parameters

sessID
Type: Long Int
Access: read
Mechanism: by value
Identification of the session under which the error occurred.
err1
Type: Long Int
Access: write
Mechanism: by reference
TP Desktop Connector DDEV status value (--4000 range) (see Table 5-7).
err2
Type: Long Int
Access: write
Mechanism: by reference
ACMS system status value (--3000 range) or status value from the communications toolbox in use by the session (--1 or 0 through 11); see Table 5-8 and Table A-1. Many other values are possible. Refer to PATHWORKS for Macintosh documentation set.
item1
Type: char *
Access: write
Mechanism: by reference
255-character Pascal string holding the symbol name for the status value returned in the err1 parameter (see Table 5-7).
item2
Type: char *
Access: write
Mechanism: by reference
Pascal string with a maximum of 255 characters holding the symbol name for the status value returned in the err2 parameter (see Table 5-8 and Table A-1). In addition, item2, in the case of an expiring password, also contains the number of hours until the password expires, concatenated at the end of the string.
errorMsg
Type: char *
Access: write
Mechanism: by reference
Pascal string with a maximum of 255 characters holding the symbol name for the status returned on the original TP Desktop Connector client service call.
reserved
Type: Long Int
Access: read
Mechanism: by reference
Specify as NULL.

Return Status

The status values returned by the DBGetErr service are listed in Table 5-6.

Table 5-6 DBGetErr Return Status Values
Status Value Description

noErr 0 No error

rcDBError --802 Problem retrieving error information

rcDBBadSessID --806 Bad session identification

rcDBAsyncNotSupp --809 DDEV does not support asynchronous calls

rcDBPackNotInited --813 InitDBPack function has not been called

Table 5-7 lists the TP Desktop Connector DDEV status values that can be returned in the err1 parameter, with corresponding symbols that can be returned in the item1 parameter and related text.

Table 5-7 TP Desktop Connector DDEV Status Values
Symbol Value Text

rcDBANormal 0 Normal completion

rcDBAComTooFai --4002 Call Comm Toolbox failed

rcDBALowRes --4003 Low resource error

rcDBANoMorSes --4004 No more sessions allowed

rcDBANoMulSte --4005 Multiple step task is not supported

rcDBAIntErr --4006 Internal error of db extension

rcDBAOpeNotSup --4007 Operation is not supported

rcDBAWroKeyWor --4008 Wrong key word

rcDBAAsyComErr --4009 Completion error in asynchronous call

rcDBASerResErr --4010 Bad response message from back-end server

rcDBAConTorDow --4011 Connection is torn down

rcDBAFail --4012 ACMS failed

rcDBADatLesAsk --4013 Amount of data is less than requested

rcDBABadSta --4014 DDEV is in a bad state

rcDBAReadComp --4015 Read completion routine detected failure

rcDBASigOutFai --4016 Sign-out failed

rcDBANoCTB --4017 Comm Toolbox not installed

rcDBANewConFai --4018 CMNew failed to start a new connection

rcDBAValidFai --4019 CMValidate consistency check failed

rcDBABadFlags --4020 Workspace cannot be both read and write

rcDBABadSprot --4021 Server replied with invalid protocol

rcDBABadKeyWd --4022 Invalid/No Keyword from Desktop application

rcDBAMsgBuilt --4023 Send message fully built, DBExec executed

rcDBATimeOut --4024 DBInit timed out

rcDBAExchActv --4025 Task cancel not valid during exchange step

rcDBATasCanFai --4026 Attempt to cancel the task failed

rcDBABadCRC --4027 Invalid CRC - possible message corruption

rcDBAVal --4050 Data retrieved

rcDBABadTyp --4051 Bad data type

rcDBANul --4052 No data retrieved

rcDBAExec --4053 Executing request

rcDBABadSesID --4054 Bad session identification

rcDBAMorArgExp --4055 More arguments expected

rcDBABadConStr --4056 Invalid connection string

rcDBAZombie --4057 Operation not valid; session is a zombie

rcDBABadSesNum --4058 Bad session number

rcDBAToolNotSup --4059 Communications tool not supported

rcDBAWarn --4060 Back-end ACMSDI or ACMS warning issued

rcDBANoCurrncy --4061 No workspace currency set

rcDBANoMoreWs --4062 No more workspaces

rcDBAPreamClInv --4063 Get preamble call invalid for end task

rcDBAWroState --4064 Session is in wrong state for operation

rcDBAASynccNS --4065 Async call from application unsupported

Previous Next Contents Index

Symbol	Value	Text
rcDBANormal	0	Normal completion
rcDBAComTooFai	--4002	Call Comm Toolbox failed
rcDBALowRes	--4003	Low resource error
rcDBANoMorSes	--4004	No more sessions allowed
rcDBANoMulSte	--4005	Multiple step task is not supported
rcDBAIntErr	--4006	Internal error of db extension
rcDBAOpeNotSup	--4007	Operation is not supported
rcDBAWroKeyWor	--4008	Wrong key word
rcDBAAsyComErr	--4009	Completion error in asynchronous call
rcDBASerResErr	--4010	Bad response message from back-end server
rcDBAConTorDow	--4011	Connection is torn down
rcDBAFail	--4012	ACMS failed
rcDBADatLesAsk	--4013	Amount of data is less than requested
rcDBABadSta	--4014	DDEV is in a bad state
rcDBAReadComp	--4015	Read completion routine detected failure
rcDBASigOutFai	--4016	Sign-out failed
rcDBANoCTB	--4017	Comm Toolbox not installed
rcDBANewConFai	--4018	CMNew failed to start a new connection
rcDBAValidFai	--4019	CMValidate consistency check failed
rcDBABadFlags	--4020	Workspace cannot be both read and write
rcDBABadSprot	--4021	Server replied with invalid protocol
rcDBABadKeyWd	--4022	Invalid/No Keyword from Desktop application
rcDBAMsgBuilt	--4023	Send message fully built, DBExec executed
rcDBATimeOut	--4024	DBInit timed out
rcDBAExchActv	--4025	Task cancel not valid during exchange step
rcDBATasCanFai	--4026	Attempt to cancel the task failed
rcDBABadCRC	--4027	Invalid CRC - possible message corruption
rcDBAVal	--4050	Data retrieved
rcDBABadTyp	--4051	Bad data type
rcDBANul	--4052	No data retrieved
rcDBAExec	--4053	Executing request
rcDBABadSesID	--4054	Bad session identification
rcDBAMorArgExp	--4055	More arguments expected
rcDBABadConStr	--4056	Invalid connection string
rcDBAZombie	--4057	Operation not valid; session is a zombie
rcDBABadSesNum	--4058	Bad session number
rcDBAToolNotSup	--4059	Communications tool not supported
rcDBAWarn	--4060	Back-end ACMSDI or ACMS warning issued
rcDBANoCurrncy	--4061	No workspace currency set
rcDBANoMoreWs	--4062	No more workspaces
rcDBAPreamClInv	--4063	Get preamble call invalid for end task
rcDBAWroState	--4064	Session is in wrong state for operation
rcDBAASynccNS	--4065	Async call from application unsupported

DIGITAL TP Desktop Connector for ACMSClient Services Reference Manual

Chapter 5Client Services for Macintosh Software

Format

Parameters

sessID

reserved

reserved

Return Status

Format

Parameters

sessID

reserved

Return Status

Format

Parameters

sessID

reserved

Return Status

Format

Parameters

sessID

sessNum

returnedID

version

ddevName

host

username

network

connStr

start

state

reserved

Return Status

Format

Parameters

sessID

err1

err2

item1

item2

errorMsg

reserved

Return Status

DIGITAL TP Desktop Connector
for ACMS
Client Services Reference Manual

Chapter 5
Client Services for Macintosh Software