# Compaq TP Desktop Connector
for ACMS
Client Services Reference Manual

Previous | Contents | Index

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

## Format

> DBGetSessionNum (sessID,
> sessNum,
> reserved )

## Parameters

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

## Return Status

> 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 Compaq 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).

## Format

> DBInit (sessID,
> ddevName,
> host,
> username,
> password,
> connStr,
> reserved )

## Parameters

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

> The 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 Compaq 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.

## Return Status

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

1. Keyword
2. Task name
3. Application name
4. Selection string
5. Number of workspaces
6. Each workspace, sent with an individual DBSend or DBSendItem

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.

## Format

> DBSend (sessID,
> buffer
> len,
> reserved )

## Parameters

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

## Return Status

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

## Format

> DBSendItem (sessID,
> datatype,
> len,
> reserved,
> flags,
> buffer,
> reserved )

## Parameters

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

## Return Status

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

## Format

> DBState (sessID,
> reserved )

## Parameters

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

## Return Status

> 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

# 5.13 InitDBPack

This service loads DAM into memory and increments the DAM-use counter. The counter prevents any application from removing DAM from memory while another application is using it.

## Format

> InitDBPack ( )

## Return Status

> The status values returned by the InitDBPack service are listed in Table 5-15.

> Table 5-15 InitDBPack Return Status Values
> Status | Value | Description
> --- | --- | ---
> noErr | 0 | No error
> rcDBWrongVersion | --812 | Wrong version of DDEV

# Chapter 6
System Management Service on OpenVMS

This chapter describes the system management service available on systems running the TP Desktop Connector gateway. The ACMSDI$GET_SUBMITTER_INFO service returns information about the status of TP Desktop Connector gateway processing on the submitter node.

# 6.1 ACMSDI$GET_SUBMITTER_INFO

This service returns information regarding desktop users signed in to the Compaq ACMS system. The service reports only those users signed in to the TP Desktop Connector gateway running on the same node as the program calling the ACMSDI$GET_SUBMITTER_INFO routine. See Compaq TP Desktop Connector for ACMS Client Application Programming Guide for coding and building guidelines.

The C-language function prototype and definitions for the item codes are in the file ACMSDI.H in the ACMSDI$COMMON directory.

The ACMSDI$EXAMPLES directory contains a program, SHOW_DESKTOP_USERS.EXE, that uses the ACMSDI$GET_SUBMITTER_INFO service, the source file (.C), and the build command procedure (.COM). See Compaq TP Desktop Connector for ACMS Client Application Programming Guide for more information about this program.

Note A program using the ACMSDI$GET_SUBMITTER_INFO service that was compiled and linked with TP Desktop Connector Version 1.2 works with only TP Desktop Connector Version 1.2.

## Format

> ACMSDI$GET_SUBMITTER_INFO (user_context,
> itmlst,
> [target_submitter_ID],
> [target_desktop_ID],
> [target_username])

## Parameters

> ### user_context

> Type: longword (unsigned)
> Access: read write
> Mechanism: by reference
> A context variable acting as a placeholder while the program reports on multiple submitters. Before calling ACMSDI$GET_SUBMITTER_INFO initially, the program must set the user context variable to zero. On ACMSDI$GET_SUBMITTER_INFO calls, if the service returns the status ACMSDI$_NORMAL, the program does not modify the variable value.

> ### itmlst

> Type: longword (unsigned)
> Access: read
> Mechanism: by reference
> Item list describing the information to be reported. Itmlst is the address of a list of item descriptors, each of which specifies or controls an item of information to be returned. The list of item descriptors is terminated by an item code of zero.

> Figure 6-1 shows the item descriptor format.

> Figure 6-1 Submitter Item Descriptor Format

The valid item codes are described in Table 6-1.

Table 6-1 Submitter Information Item Codes
Code Name
ACMSDI$K_LATEST_MSG_TIME
| Action: | Returns the OpenVMS absolute date and time at which the desktop submitter most recently sent a message to the TP Desktop Connector gateway.
| Description: | The buffer address field of the item descriptor is the address of a quadword in which the ACMSDI$GET_SUBMITTER_INFO service writes this time.
ACMSDI$K_DESKTOP_ID
| Action: | Returns the desktop gateway submitter identification assigned internally by the TP Desktop Connector gateway.
| Description: | The buffer address field in the item descriptor is the address of a two-longword structure. ACMSDI$GET_SUBMITTER_INFO writes the desktop gateway submitter number into the first field in the target_desktop_ID array, and the instance into the second field. These two values make up the complete desktop gateway submitter identification.
ACMSDI$K_NODENAME
| Action: | Returns the name of the network node from which the desktop submitter is signed in to the ACMS system.
| Description: | The buffer address field in the item descriptor points to a user-provided buffer into which ACMSDI$GET_SUBMITTER_INFO writes the name. The return length address field of the item descriptor points to a word into which ACMSDI$GET_SUBMITTER_INFO writes the length of the node name in bytes.
ACMSDI$K_SIGN_IN_TIME
| Action: | Returns the OpenVMS absolute date and time at which the desktop submitter signed in to the TP Desktop Connector gateway.
| Description: | The buffer address field of the item descriptor is the address of a quadword in which the ACMSDI$GET_SUBMITTER_INFO service writes this time.
ACMSDI$K_SUBMITTER_ID
| Action: | Returns the ACMS submitter_ID of the desktop submitter.
| Description: | The buffer address field in the item descriptor is the address in which the ACMSDI$GET_SUBMITTER_INFO service writes the submitter_ID.
ACMSDI$K_TRANSPORT
| Action: | Returns an enumerated longword value corresponding to the name of the transport used for the submitter sign-in.
| Description: | The buffer address field of the item descriptor is the address of a longword in which ACMSDI$GET_SUBMITTER_INFO writes this value.
ACMSDI$K_USERNAME
| Action: | Returns the user name under which the desktop submitter is signed in.
| Description: | The buffer address field in the item descriptor points to a user-provided buffer into which the ACMSDI$GET_SUBMITTER_INFO service writes the user name. The return length address field of the item descriptor points to a word into which the ACMSDI$GET_SUBMITTER_INFO service writes the length of the user name in bytes.

### target_submitter_ID

Type: unsigned Long Int
Access: read
Mechanism: by reference
The ACMS submitter identification as displayed in the ACMS/SHOW USERS command.

### target_desktop_ID

Type: unsigned Long Int [2]
Access: read
Mechanism: by reference
The desktop gateway submitter identification, ACMS$DESKTOP_ID, on which to report. The first long int contains the desktop gateway submitter number and the second long int contains the instance.

### target_username

Type: character string descriptor
Access: read
Mechanism: by descriptor
The user name on which to report.

## Return Status

> The status values returned by the ACMSDI$GET_SUBMITTER_INFO service are listed in Table 6-2.

> Table 6-2 ACMSDI$GET_SUBMITTER_INFO Return Status Values
> Status | Description
> --- | ---
> ACMSDI$_ILLITEMCODE | An illegal item code appears in the item list. No information is reported.
> ACMSDI$_NOMATCHSUBS | No matching submitter. No submitter matches the selection criteria.
> ACMSDI$_NOMORESUBS | No more submitters to report. No information was reported by this call, because no more submitters match the selection criteria. The snapshot is consistent with the current set of submitters.
> ACMSDI$_NORMAL | Normal successful completion. Information specified by the item list has been reported about a matching submitter. Additional matching submitters can remain to be reported.
> ACMSDI$_OBSINFOREP | Obsolete information reported. No information was returned, because no more submitters match the selection criteria. The snapshot is not consistent with the current set of submitters.

Previous | Next | Contents | Index