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:

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:

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