# Compaq TP Desktop Connector
for ACMS
Client Services Reference Manual

Previous | Contents | Index

# 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

# 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.

## 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

# 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

> Appendix A lists the ACMS system status values that can be returned in the err2 parameter.

> The Communications Toolbox may originate status values that are returned to the desktop client program on a DBGetErr call. These codes (--1 and 0 through 11) can be found in MPW in the include file Connections.h stored in the CIncludes folder within the Interfaces folder.

> The Communications Toolbox also returns some other status values that it receives from services it calls. These values are also returned to the desktop client program on a DBGetErr call. Table 5-8 lists the more common of these Communications Toolbox status values that can be returned in the err2 parameter and related text.

> Table 5-8 Communications Toolbox Status Values
> Value | Text
> --- | ---
> --43 | Communications Toolbox Folder not found
> --1 | Communications Tool missing
> 652 | Invalid Node Name on DBInit call
> 1000 | A communications resource is either not available or has not been properly selected
> 8356 | TP Desktop Connector gateway not active
> 8436 | Timeout occurred. ACMS system not responding

# 5.7 DBGetItem

This service retrieves the next data item from the TP Desktop Connector DDEV.

After the program executes a DBExec and the DBState service returns a status indicating that a message has been received from ACMS, use DBGetItem. You can repeat the DBGetItem function as many times as necessary to retrieve all the data returned by TP Desktop Connector in response to a query or as part of processing the exchange steps for a task. See Compaq TP Desktop Connector for ACMS Client Application Programming Guide.

If the client program has called a task with unidirectional workspaces, only modifiable and write-only workspaces are returned in DBGetItem. Unlike DBSendItem, you do not specify access type in DBGetItem. However, the client program must know what workspaces it expects to receive.

When processing exchange step requests from ACMS, use DBGetItem to acquire a workspace preamble and to set currency on the workspace data. If you specify a NULL buffer pointer, DBGetItem bumps the current data pointer maintained by the DDEV by the number of bytes you specify in the length parameter, without returning any data. Subsequent DBGetItem calls retrieve data starting at the repositioned current data pointer.

You can use DBGetItem to acquire message header items as well as workspace data items. You can acquire a single message header item or all message header items, except for the message keyword, with one DBGetItem call. All messages contain header items, even if the message contains no workspaces. Therefore, you can use DBGetItem to retrieve message header items after the DBState service returns an rcDBNull status.

## Format

> DBGetItem (sessID,
> timeout,
> datatype,
> len,
> reserved,
> reserved,
> buffer,
> reserved )

## Parameters

> ### sessID

> Type: Long Int
> Access: read
> Mechanism: by value
> Identification of the session, as returned by the DBInit service, related to an item retrieved from the TP Desktop Connector DDEV.

> ### timeout

> Type:Long Int
> Access:read
> Mechanism:by value
> The time, in seconds, that the DDEV waits to receive the requested data before canceling the function. If the data is not obtainable within the time specified, a primary error status of rcDBBreak (--804) is returned with a secondary status of rcDBATimeOut (--4024). If you specify NULL or 0, the default value is 60 seconds. You can disable the timeout feature by specifying kDBWaitForever (--1).

> ### datatype

> Type: unsigned Long Int
> Access: read
> Mechanism: by reference
> Identification of the data type of the message. This must be typeAnyType or NULL, unless message header information is being acquired. In that case, set the datatype parameter to typeHdrItem to acquire an individual header item, or typeHdrRec to acquire all the header items for the message exclusive of the keyword. Set datatype to typeWkspPream to acquire workspace preamble, length, and access type. Although datatype is passed by reference, this DDEV does not modify it.

> ### len

> Type: Short Int
> Access: read and write
> Mechanism: by reference
> Set the len parameter to the number of bytes to be returned. The DDEV will modify the len parameter to the number of bytes actually returned if the data available is less than the amount requested.

> ### reserved

> Type: Short Int
> Access: read
> Mechanism: by reference
> Specify as NULL.

> ### reserved

> Type: Short Int
> Access: read
> Mechanism: by reference
> Specify as NULL.

> ### buffer

> Type: Ptr
> Access: write
> Mechanism: by reference
> Memory location to store the retrieved data item. Ensure that the location specified contains enough space for the data item being returned.

> If you specify a null pointer, no data is returned. However, the pointer to the next byte in the source data is bumped by the length specified in the len parameter.

> ### reserved

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

## Return Status

> The status values returned by the DBGetItem service are listed in Table 5-9.

> Table 5-9 DBGetItem Return Status Values
> Status | Value | Description
> --- | --- | ---
> rcDBNull | --800 | Data item was NULL; no more data
> rcDBValue | --801 | Nonzero data item successfully retrieved
> rcDBError | --802 | Execution ended in an error
> rcDBBreak | --804 | Function timed out; data not obtainable
> rcDBBadSessID | --806 | Bad session identification
> rcDBAsyncNotSupp | --809 | DDEV does not support asynchronous calls
> rcDBPackNotInited | --813 | InitDBPack not called

Previous | Next | Contents | Index