# Compaq ACMS for OpenVMS
Systems Interface Programming

Previous | Contents | Index

# A.4 ACMS$DELETE_STREAM

ACMS$DELETE_STREAM deletes a stream. Use this service after ACMS$DISCONNECT_STREAM disconnects all connect IDs to the stream. Once deleted, a stream is not available for use by other tasks.

Note This service has been superseded. ACMS supports this service for applications that have already been implemented. To simplify the writing of agent programs and to simplify program maintenance, use the ACMS$TERM_EXCHANGE_IO service in new applications.

## Format

> ACMS$DELETE_STREAM (stream_id.rq.r,
> [flags.rl.r])

> ACMS$DELETE_STREAM_A (stream_id.rq.r,
> [flags.rl.r],
> [comp_status.wq.r],
> [efn.rbu.r],
> [astadr.szem.r],
> [astprm.rz.v])

## Parameters

> ### stream_id

> The identification of the stream you want to delete. This is the ID returned by ACMS$CREATE_STREAM.

> ### flags

> You can set a bit in the flag, ACMS$M_STRM_DISCONNECT, to specify what to do on a stream deletion.

> ACMS$M_STRM_DISCONNECT disconnects all connections to this stream. If you do not set this bit, the stream is not deleted until all connections to the stream are disconnected.

The parameters comp_status.wq.r, efn.rbu.r, astadr.szem.r, and astprm.rz.v are asynchronous service arguments. See Chapter 2 for a discussion of these parameters.

## Return Status

> The return status codes indicating success or failure of the call follow:

> Status | Severity Level | Description
> --- | --- | ---
> ACMS$_NORMAL | Success | Normal successful completion.
> ACMS$_PENDING | Informational | Successful operation pending asynchronous completion. The final status is in the completion status block.
> ACMS$_BADFLAGS | Error | Some or all of the flags specified were invalid.
> ACMS$_BADSTRMID | Error | The stream ID is not correct; either the stream was not created, it was deleted, or the stream ID was corrupt.
> ACMS$_INSUFPRM | Error | Not enough arguments were passed to this service.
> ACMS$_INVASTADR | Error | The AST address was invalid.
> ACMS$_INVASTPRM | Error | The AST routine parameter was invalid.
> ACMS$_INVCMPSTS | Error | The completion status block was invalid.
> ACMS$_INVEFN | Error | The event flag was invalid.
> ACMS$_INVSTRMID | Error | The stream ID was invalid.
> ACMS$_NOTCREATED | Error | The stream is not yet created or it was not created by this process.
> ACMS$_STILLCONNECTS | Error | There are still connections active on the stream.
> ACMS$_SYNASTLVL | Error | Synchronous services may not be called from AST level.

# A.5 ACMS$DISCONNECT_STREAM

ACMS$DISCONNECT_STREAM breaks a connection to a stream. The application execution controller (EXC) must disconnect from the stream before the agent program can disconnect.

Note This service has been superseded. ACMS supports this service for applications that have already been implemented. To simplify the writing of agent programs and to simplify program maintenance, use the ACMS$TERM_EXCHANGE_IO service in new applications.

## Format

> ACMS$DISCONNECT_STREAM (connect_id.rq.r,
> [flags.rl.r])

> ACMS$DISCONNECT_STREAM_A (connect_id.rq.r,
> [flags.rl.r],
> [comp_status.wq.r],
> [efn.rbu.r],
> [astadr.szem.r],
> [astprm.rz.v])

## Parameters

> ### connect_id

> The identification of the stream you want to disconnect. This is the ID returned by the ACMS$CONNECT_STREAM service.

> ### flags

> Reserved.

The parameters comp_status.wq.r, efn.rbu.r, astadr.szem.r, and astprm.rz.v are asynchronous service arguments. See Chapter 2 for a discussion of these parameters.

## Return Status

> The return status codes indicating success or failure of the call follow:

> Status | Severity Level | Description
> --- | --- | ---
> ACMS$_NORMAL | Success | Normal successful completion.
> ACMS$_PENDING | Informational | Successful operation pending asynchronous completion. The final status is in the completion status block.
> ACMS$_SENDER_DISCONN | Warning | The sender has disconnected from the stream.
> ACMS$_BADCONID | Error | The connect ID is not correct; either the stream is not connected, it is disconnected, or the connect ID is corrupt.
> ACMS$_BADFLAGS | Error | Some or all of the flags specified were invalid.
> ACMS$_INSUFPRM | Error | Not enough arguments were passed to this service.
> ACMS$_INVASTADR | Error | The AST address was invalid.
> ACMS$_INVASTPRM | Error | The AST routine parameter was invalid.
> ACMS$_INVCMPSTS | Error | The completion status block was invalid.
> ACMS$_INVCONID | Error | The connect ID was invalid.
> ACMS$_INVEFN | Error | The event flag was invalid.
> ACMS$_NOTCONNECTED | Error | The connection is not currently connected to the stream.
> ACMS$_SENDER_CONN | Error | Cannot disconnect the agent program until the EXC has disconnected.
> ACMS$_STILLREQUESTS | Error | There are still requests active on the connection.
> ACMS$_SYNASTLVL | Error | Synchronous services may not be called from AST level.

# A.6 ACMS$OPEN_RR

For previously implemented tasks that use TDMS, you call ACMS$OPEN_RR to open a TDMS channel and associate it with a submitter ID. Subsequent task selections for that submitter use the channel for all task request I/O, including remote request I/O. For previously implemented tasks that use the ACMS Request Interface (RI), you call ACMS$OPEN_RR to prepare the agent process to do the I/O. ACMS$OPEN_RR must be closed with ACMS$CLOSE_RR. If an attempt is made to close it with ACMS$TERM_EXCHANGE_IO, an invalid status is returned.

Note This service has been superseded. ACMS supports this service for applications that have already been implemented. To simplify writing agent programs, and to simplify program maintenance, use the ACMS$INIT_EXCHANGE_IO service in new applications.

## Format

> ACMS$OPEN_RR (device.rt.dx,
> channel.wlu.r,
> [submitter_id.rq.r],
> [flags.rl.r],
> [nullarg])

> ACMS$OPEN_RR_A (device.rt.dx,
> channel.wlu.r,
> [submitter_id.rq.r],
> [flags.rl.r],
> [nullarg],
> [comp_status.wq.r],
> [efn.rbu.r],
> [astadr.szem.r],
> [astprm.rz.v])

## Parameters

> ### device

> The name of the terminal the channel opens.

> ### channel

> An output parameter naming the TDMS channel that is open. This parameter can later be used as an input parameter to the ACMS$CLOSE_RR service. The agent program can use this channel for its own TDMS calls.

> ### submitter_id

> The submitter ID corresponding to a signed-in submitter (user). This ID is returned by the ACMS$SIGN_IN service. This parameter defaults to a quadword that is equal to zero.

> ### flags

> TDMS is enabled by default. The ACMS$OPEN_RR remote request service does not enable the agent program to call tasks that use DECforms.

> If agent programs use the ACMS Request Interface (RI), it is necessary to set the ACMS$V_FORCE_AGENT_IO flag. In ACMS Version 3.0, agent programs that did not set this flag could still use the RI in a distributed environment, though they could not use the RI if it selected tasks from an application on the same node. Starting with ACMS Version 3.1, agent programs without this flag do not work in a distributed environment.

> If only the RI is used, TDMS can be disabled to conserve resources. If the agent program sets the ACMS$M_DISABLE_TDMS flag on the call to ACMS$OPEN_RR, TDMS is disabled for the agent process, indicating that the agent program uses only the RI. Because TDMS is completely disabled in the agent process, TDMS is not used even if a task uses TDMS I/O and an .RLB file exists to perform the request.

> ### nullarg

> The nullarg parameter is a place-holding argument. This argument is reserved for Compaq's use.

The parameters comp_status.wq.r, efn.rbu.r, astadr.szem.r, and astprm.rz.v are asynchronous service arguments. See Chapter 2 for a discussion of these parameters.

## Return Status

> The following list summarizes each error returned by this service. Invalid status returns from TSS$CLOSE might be returned to the agent program. See the reference section of VAX TDMS Reference Manual for more information on TSS$CLOSE.

> The return status codes indicating success or failure of the call follow:

> Status | Severity Level | Description
> --- | --- | ---
> ACMS$_NORMAL | Success | Normal successful completion.
> ACMS$_PENDING | Informational | Successful operation pending asynchronous completion. The final status is in the completion status block.
> ACMS$_TDMSNOTINST | Informational | TDMS is not installed.
> ACMS$_NTSNIN | Error | Submitter was not signed in.
> ACMS$_INSUFPRM | Error | Not enough arguments were passed to this service.
> ACMS$_INTERNAL | Error | Internal error.
> ACMS$_INVDEV | Error | The device name was invalid.
> ACMS$_INVEFN | Error | The event flag was invalid.
> ACMS$_SYNASTLVL | Error | Synchronous services may not be called from AST level.
> ACMS$_TDMSDISABLED | Error | TDMS is disabled and RI shared image library has not been specified.

> TSS$OPEN also results in invalid status returns.

# A.7 Superseded Parameters of the Task I/O Argument

This section contains information about parameters that were passed into the task I/O argument in versions of ACMS earlier than Version 3.2. In each case, while the task I/O argument is still supported, use the exchange I/O ID for tasks that perform request I/O, stream I/O, or terminal I/O in new applications.

## A.7.1 Argument List for a Task That Performs Request I/O

Figure A-1 shows an argument list for a task that performs request I/O, supplies data to the second task argument workspace in a task, but does not supply a selection string parameter. This example includes a zero in the first task argument workspace because the agent program does not pass any data into that workspace.

Note This method has been superseded by implementation of the exchange I/O ID feature. This figure is included for reference for agent programs that have already been developed. Use the exchange I/O ID in new agent programs.

Figure A-1 Arguments Passed for a Task Doing Request I/O

## A.7.2 Argument List for a Task That Passes Only Stream I/O

Figure A-2 shows an argument list that passes only a stream ID. The figure illustrates how to set the selection string and extended status parameters to zero when the agent program does not use these arguments.

Note This method has been superseded by implementation of the exchange I/O ID feature. This figure is included for reference for agent programs that have already been developed. Use the exchange I/O ID in new agent programs.

Figure A-2 Arguments Passed for a Task Doing Stream I/O

## A.7.3 Argument List with Selection String, Extended Status, and Terminal I/O Defined

Figure A-3 shows an argument list that has the selection string, extended status, and terminal I/O defined.

Note This method has been superseded by implementation of the exchange I/O ID feature. This figure is included for reference for agent programs that have already been developed. Use the exchange I/O ID in new agent programs.

Figure A-3 Arguments Passed for a Task Doing Terminal I/O

Detailed information about the ACMS$CALL, ACMS$START_CALL, ACMS$GET_PROCEDURE_INFO services and their parameters is available in Chapter 5.

Index | Contents