Previous | Contents | Index |
DBExec (sessID,
reserved )
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.
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.
DBGetConnInfo (sessID,
sessNum,
returnedID,
version,
ddevName,
host,
username,
network,
connStr,
start,
state,
reserved )
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.
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.
DBGetErr (sessID,
err1,
err2,
item1,
item2,
errorMsg,
reserved )
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.
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.
DBGetItem (sessID,
timeout,
datatype,
len,
reserved,
reserved,
buffer,
reserved )
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.
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 |