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:

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:

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