| Previous | Contents | Index |
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.
| 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 DIGITAL 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
5.8 DBGetSessionNum
This service returns the session number for the session you specify
with the session ID parameter. All active sessions being handled by the
ACMSDI DDEV at a given time have unique session numbers, numbered
sequentially starting at 1. These numbers can be in use at the same
time by other DDEVs.
DBGetSessionNum (sessID,
sessNum,
reserved )
sessID
Type: Long Int
Access: read
Mechanism: by value
The session ID, as returned by the DBInit service.sessNum
Type: Short Int
Access: write
Mechanism: by reference
Session number for this session.reserved
Type: Long Int
Access: read
Mechanism: by reference
Specify as NULL.
The status values returned by the DBGetSessionNum service are listed in Table 5-10.
Table 5-10 DBGetSessionNum Return Status Values Status Value Description noErr 0 No error rcDBBadSessID --806 Session ID is invalid rcDBAsyncNotSupp --809 DDEV does not support asynchronous calls rcDBPackNotInited --813 InitDBPack not called
5.9 DBInit
This service loads the TP Desktop Connector DDEV into memory and
authenticates the user on the target system as a valid OpenVMS and
ACMS user by performing an ACMS sign-in. The call
returns a session identification that must be used in other services.
See DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide for guidelines on using the service.
This service corresponds functionally to the sign-in service in the ACMS Systems Interface (SI).
DBInit (sessID,
ddevName,
host,
username,
password,
connStr,
reserved )
sessID
Type: Long Int
Access: write
Mechanism: by reference
The DAM session identification returned by the DBInit service. This is the functional equivalent of the ACMSDI submitter identification used for communication between the TP Desktop Connector DDEV and the TP Desktop Connector gateway.A nonzero session identification and a bad return status together on the DBInit call represents a zombie session (see DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide).
ddevName
Type: char *
Access: read
Mechanism: by reference
A Pascal string with a maximum length of 63 characters containing the name of the DDEV that handles the routine. For TP Desktop Connector software, this name is ACMSDI.host
Type: char *
Access: read
Mechanism: by reference
A Pascal string with a maximum length of 255 characters containing the node name of the host system to which this TP Desktop Connector session is to be connected.username
Type: char *
Access: read
Mechanism: by reference
A Pascal string with a maximum length of 255 characters containing the name to be used to authenticate the user of the desktop client program on the TP Desktop Connector gateway system. For DBInit to complete successfully, the user must be a valid user of both OpenVMS and ACMS.password
Type: char *
Access: read
Mechanism: by reference
A Pascal string with a maximum length of 255 characters containing the unencrypted password to be used to authenticate the user of the desktop client program on the TP Desktop Connector gateway system as a valid OpenVMS user.connStr
Type: char *
Access: read
Mechanism: by reference
A Pascal string with a maximum length of 255 characters identifying the Communications Toolbox tool to use to connect this session to an ACMS system. The communications tool name is required and must always be the first parameter specified. The valid communications tools are:
- AppleTalk ADSP Tool
Direct communications link (with no gateway)- AppleTalk-DECnet Tool
Communications through the AppleTalk-DECnet Gateway- DECnet Tool
Direct DECnet communications- MacTCP Tool
Direct TCP/IP communications- XPC Tool
Dialin communications though the TP Desktop Connector Serial-DECnet GatewayThe connection string can contain any of several additional arguments, most of which are specific to the tool. However, you can use the following three arguments with all communications tools:
- TimeOut
Specifies the length of time that the DDEV attempts to establish a communications connection.- IntegrityCheck
Activates cyclic redundancy checking (CRC) from the Macintosh client application.- BufferSize
Specifies the size of the message buffers the DDEV uses to transfer data to and from the communications tool.See DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide for a discussion of the communications tools supported and the valid connection string arguments associated with each tool.
reserved
Type: Long Int
Access: read
Mechanism: by reference
Specify as NULL.
The status values returned by the DBInit service are listed in Table 5-11.
Table 5-11 DBInit Return Status Values Status Value Description noErr 0 No error rcDBError --802 Error initiating session rcDBBreak --804 Function timed out; connection could not be established within time out period rcDBBadDDev --808 Invalid DDEV name on DBInit rcDBAsyncNotSupp --809 DDEV does not support asynchronous calls rcDBPackNotInited --813 InitDBPack not called
5.10 DBSend
This service sends a message element to the ACMSDI DDEV for later
transmission to the TP Desktop Connector gateway. The DDEV sends the
message when the desktop client program calls the DBExec service.
DBSend is equivalent to DBSendItem without the ability to support some specific features; you can use them interchangeably for most situations. Regardless of whether a client program uses DBSend or DBSendItem for a given element of a starting task message, the elements must be sent in a call task in the following order:
For unidirectional workspaces, you must specify the access type with the flags parameter of DBSendItem service. You cannot use DBSend with unidirectional workspaces, because DBSend has no flags parameter to specify read, write, or modify workspaces. All workspaces sent with DBSend are modifiable.
You must identify nonworkspace data items when they are sent in a header record with the special data type typHdrRec. You must use DBSendItem in this case, because DBSend does not support this data type parameter.
DBSend (sessID,
buffer
len,
reserved )
sessID
Type: Long Int
Access: read
Mechanism: by value
The session identification as returned by the DBInit service.buffer
Type: char *
Access: read
Mechanism: by reference
The address of data to be sent.len
Type: Short Int
Access: read
Mechanism: by value
The length in bytes of the data item being sent.reserved
Type: Long Int
Access: read
Mechanism: by reference
Specify as NULL.
The status values returned by the DBSend service are listed in Table 5-12.
Table 5-12 DBSend Return Status Values Status Value Description noErr 0 No error rcDBError --802 Error trying to send item rcDBBadSessID --806 Bad session identification rcDBAsyncNotSupp --809 DDEV does not support asynchronous calls rcDBPackNotInited --813 InitDBPack not called
5.11 DBSendItem
This service passes a message element to the TP Desktop Connector DDEV
for later transmission to the TP Desktop Connector gateway. The order
of calling the service is fixed (see DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide). The DDEV sends the
message when the desktop client program calls the DBExec service.
For unidirectional workspaces, the DBSendItem must specify the access type in the flags parameter. Because no flags parameter is available with DBSend, you must use DBSendItem if a client program distinguishes between read, write, or modify workspaces.
Use the datatype parameter to specify when you send nonworkspace data items in a header record.
DBSendItem (sessID,
datatype,
len,
reserved,
flags,
buffer,
reserved )
sessID
Type: Long Int
Access: read
Mechanism: by value
The session identification as returned by the DBInit service.datatype
Type: unsigned Long Int
Access: read
Mechanism: by value
Identification of the data type of the message. To indicate that all nonworkspace data for the message, excluding the keyword, is being sent in a header record, define datatype as typeHdrRec.
len
Type: Short Int
Access: read
Mechanism: by value
The length in bytes of the data item being sent.reserved
Type: Short Int
Access: read
Mechanism: by value
Specify as NULL.flags
Type: Short Int
Access: read
Mechanism: by value
If the message element is a workspace, specify the type of access for the workspace as either read-only, write-only, or modifiable.buffer
Type: Ptr
Access: read
Mechanism: by reference
The address of the data to be sent.reserved
Type: Long Int
Access: read
Mechanism: by reference
Specify as NULL.
The status values returned by the DBSendItem service are listed in Table 5-13.
Table 5-13 DBSendItem Return Status Values Status Value Description noErr 0 No error rcDBError --802 Error trying to send item rcDBBadSessID --806 Bad session identification rcDBAsyncNotSupp --809 DDEV does not support asynchronous calls rcDBPackNotInited --813 InitDBPack not called
5.12 DBState
This service provides information on the state of the outstanding
request to the TP Desktop Connector gateway. The return status tells
whether the ACMS system successfully executed a request and
whether it has data available for retrieval.
DBState (sessID,
reserved )
sessID
Type: Long Int
Access: read
Mechanism: by value
The session identification as returned by the DBInit service.reserved
Type: Long Int
Access: read
Mechanism: by reference
Specify as NULL.
The status values returned by the DBState service are listed in Table 5-14.
Table 5-14 DBState Return Status Values Status Value Description rcDBNull --800 No data retrieved rcDBValue --801 Data retrieved rcDBError --802 The operation has failed rcDBExec --805 Request currently executing rcDBBadSessID --806 Bad session identification rcDBAsyncNotSupp --809 DDEV does not support asynchronous calls rcDBPackNotInited --813 InitDBPack not called
| Previous | Next | Contents | Index |