OpenVMS System Services Reference Manual

Updated: 11 December 1998

OpenVMS System Services Reference Manual

Contents

Index

For efficiency reasons, the number of parameters on this routine has been limited to six parameters. Three additional parameters are passed by the ios_icc data structure.

Required Access or Privileges

None.

Required Quota

BYTLM (Send and Reply buffers)

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL Normal completion.

SS$_ACCVIO Access violation on parameter.

SS$_BADPARAM Bad parameter value specified.

SS$_EXBYTLM Insufficient byte count quota.

SS$_INSFARG Too few arguments were supplied.

SS$_INSFMEM Insufficient process or system memory to complete the request.

SS$_IVCHAN Unknown connection specified or invalid connection handle.

SS$_IVMODE Attempted to use a connection from a more privileged access mode than the mode in which it was opened.

SS$_LINKDISCON An Incoming disconnect event is in progress.

SS$_SYNCH If synchronous mode was requested at connection time, this return value indicates that completion has already occurred and the AST routine, if specified, will not be called.

SS$_TOO_MANY_ARGS Too many arguments were specified.

SS$_WRONGSTATE Connection is in wrong state for request.

$ICC_TRANSCEIVEW

Sends a single message over a connection and waits for a reply.
The $ICC_TRANSCEIVEW service completes synchronously; that is it returns to the caller when the data from the reply is available.
For asynchronous completion, use the $ICC_TRANSCEIVE service; $ICC_TRANSCEIVE returns to the caller when the transmit portion of the tranceive request has been queued to the transport layer but without waiting for notification that the transport layer has released control of the data buffer or for the reply data from the receiving end of the connection.
On Alpha, this service accepts 64-bit addresses.

Format

SYS$ICC_TRANSCEIVEW
conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

C Prototype:

sys$icc_transceivew (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *send_buf, unsigned int send_len);

$ICC_TRANSMIT

Sends a single message over a connection.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ICC_TRANSMIT conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

C Prototype:

sys$icc_transmit (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *send_buf, unsigned int send_len);

Arguments

conn_handle

OpenVMS usage: connection_id

type: longword (unsigned)

access: read only

mechanism: by value

The handle of the fully established (open) connection to send the data over.
ios_icc

OpenVMS usage: ios_status_block

type: structure IOS_ICC

access: write only

mechanism: by 32-bit or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

I/O status block:
+2 0 ------------------------------------------------- | Undefined | Completion status | ------------------------------------------------- | Unused | ------------------------------------------------- +6 +4
Completion status values:
SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKABORT, SS$_LINKDISCON
astadr

OpenVMS usage: ast_procedure

type: procedure_entry_mask

access: call without stack unwinding

mechanism: by 32-bit or 64-bit linkage reference (Alpha)

mechanism: by 32-bit reference (VAX)

The AST routine to be executed when the operation completes.
astprm

OpenVMS usage: user_arg

type: quadword (unsigned) (Alpha), longword (unsigned) (VAX)

access: read only

mechanism: by 64-bit value (Alpha)

mechanism: by 32-bit value (VAX)

The parameter to be passed to the AST routine.
send_buf

OpenVMS usage: byte_stream

type: character-coded text string

access: read only

mechanism: by 32-bit or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

The 32-bit or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of the buffer containing the data to be sent. The length of this buffer is specified by the argument send_len.
send_len

OpenVMS usage: buffer_length

type: longword (unsigned)

access: read only

mechanism: by value

The length (in bytes) of the data to be sent over the connection. This value specifies the length of the buffer send_buf. The maximum transmission size is 1MB.

Description

This service sends a single message over a connection. When completion is signalled by calling the AST (if supplied), the data has been delivered to the communications system, but not necessarily to the system or application at the other end of the connection. After completion, the user can reuse the buffer.
Alternatively, if the synchronous completion option was requested at connection time, the service may return the optional success status, SS$_SYNCH. When SS$_SYNCH is returned, completion has occurred, and no AST will be delivered.
Required Access or Privileges

None.
Required Quota

BYTLM (send_buf)
Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL Normal completion.

SS$_ACCVIO Access violation on parameter.

SS$_BADPARAM Bad parameter value specified.

SS$_EXBYTLM Insufficient byte count quota.

SS$_INSFARG Too few arguments were supplied.

SS$_INSFMEM Insufficient process or system memory to complete the request.

SS$_IVCHAN Unknown connection specified or invalid connection handle.

SS$_IVMODE Attempted to use a connection from a more privileged access mode than the mode in which it was opened.

SS$_LINKDISCON An Incoming disconnect event is in progress.

SS$_SYNCH If synchronous mode was requested at connection time, this return value indicates that completion has already occurred and the AST routine, if specified, will not be called.

SS$_TOO_MANY_ARGS Too many arguments were specified.

SS$_WRONGSTATE Connection is in the wrong state for the request.

$ICC_TRANSMITW

Sends a single message over a connection.
The $ICC_TRANSMITW service completes synchronously; that is, it returns to the caller when the underlying transport layer has released use of the Transmit buffer. This does not mean that the data has been received by the partner application.
For asynchronous completion, use the $ICC_TRANSMIT service. The $ICC_TRANSMIT service returns to the caller as soon as the transmission request has been queued to the transport layer, without waiting for notification that the transport layer has released control of the data buffer.
On Alpha, this service accepts 64-bit addresses.

Format

SYS$ICC_TRANSMITW conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

C Prototype:

sys$icc_transmitw (unsigned int conn_handle, struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, char *send_buf, unsigned int send_len);

$IDTOASC

Translates the specified identifier value to its identifier name.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$IDTOASC id ,[namlen] ,[nambuf] ,[resid] ,[attrib] ,[contxt]

C Prototype

int sys$idtoasc (unsigned int id, unsigned short int *namlen, void *nambuf, unsigned int *resid, unsigned int *attrib, unsigned int *contxt);

Arguments

id

OpenVMS usage: rights_id

type: longword (unsigned)

access: read only

mechanism: by value

Binary identifier value translated by $IDTOASC. The id argument is a longword containing the binary value of the identifier. To determine the identifier names of all identifiers in the rights database, you specify id as --1 and call $IDTOASC repeatedly until it returns the status code SS$_NOSUCHID. The identifiers are returned in alphabetical order.
namlen

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Number of characters in the identifier name translated by $IDTOASC. The namlen argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a word containing the length of the identifier name written to nambuf.
nambuf

OpenVMS usage: char_string

type: character-coded text string

access: write only

mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)

mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Identifier name text string returned when $IDTOASC completes the translation. The nambuf argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a descriptor pointing to the buffer in which the identifier name is written.
resid

OpenVMS usage: rights_id

type: longword (unsigned)

access: write only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Identifier value of the identifier name returned in nambuf. The resid argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a longword containing the 32-bit code of the identifier.
attrib

OpenVMS usage: mask_longword

type: longword (unsigned)

access: write only

mechanism: by by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Mask of attributes associated with the identifier returned in resid. The attrib argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a longword containing the attribute mask.
Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The following symbols for each bit position are defined in the system macro library ($KGBDEF).

Bit Position Meaning When Set

KGB$V_DYNAMIC Allows holders of the identifier to remove it from or add it to the process rights list using the DCL command SET RIGHTS_LIST.

KGB$V_NAME_HIDDEN Allows holders of an identifier to have it translated, either from binary to ASCII or vice versa, but prevents unauthorized users from translating the identifier.

KGB$V_NOACCESS Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.

KGB$V_RESOURCE Allows holders of an identifier to charge disk space to the identifier. It is used only for file objects.

KGB$V_SUBSYSTEM Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

contxt

OpenVMS usage: context

type: longword (unsigned)

access: modify

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Context value used when repeatedly calling $IDTOASC. The contxt argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a longword used while $IDTOASC searches for all identifiers. The context value must be initialized to the value 0, and the resulting context of each call to $IDTOASC must be presented to each subsequent call. After contxt is passed to $IDTOASC, you must not modify its value.

Bit Position	Meaning When Set
KGB$V_DYNAMIC	Allows holders of the identifier to remove it from or add it to the process rights list using the DCL command SET RIGHTS_LIST.
KGB$V_NAME_HIDDEN	Allows holders of an identifier to have it translated, either from binary to ASCII or vice versa, but prevents unauthorized users from translating the identifier.
KGB$V_NOACCESS	Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE	Allows holders of an identifier to charge disk space to the identifier. It is used only for file objects.
KGB$V_SUBSYSTEM	Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

Description

The Translate Identifier to Identifier Name service translates the specified binary identifier value to an identifier name. While the primary purpose of this service is to translate the specified identifier to its name, you can also use it to find all identifiers in the rights database. Owner or read access to the rights database is required. To determine all the identifiers, call $IDTOASC repeatedly until it returns the status code SS$_NOSUCHID. When SS$_NOSUCHID is returned, $IDTOASC has returned all the identifiers, cleared the context value, and deallocated the record stream.
If you complete your calls to $IDTOASC before SS$_NOSUCHID is returned, use $FINISH_RDB to clear the context value and deallocate the record stream.
When you use wildcards with this service, the records are returned in identifier name order.
Required Access or Privileges

None, unless the id argument is NAME_HIDDEN, in which case you must hold the identifier or have read access to the rights list.
Required Quota

None
Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHANGE_ACL, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB, $ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $FORMAT_AUDIT, $GRANTID, $HASH_PASSWORD, $MOD_HOLDER, $MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The namlen, nambuf, resid, attrib, or contxt argument cannot be written by the caller.

SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database.

SS$_IVCHAN The contents of the context longword are not valid.

SS$_IVIDENT The specified identifier is of invalid format.

SS$_NOIOCHAN No more rights database context streams are available.

SS$_NORIGHTSDB The rights database does not exist.

SS$_NOSUCHID The specified identifier name does not exist in the rights database, or the entire rights database has been searched if the ID is --1.

Because the rights database is an indexed file that you access with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.

$IEEE_SET_FP_CONTROL (Alpha Only)

On Alpha systems, modifies the software IEEE floating-point control register and, optionally, returns the previous register value.
The service provides the mechanism to set the specified bits in the IEEE floating-point control register, to clear the specified bits in the register, and to swap the values of the register.

Format

SYS$IEEE_SET_FP_CONTROL [clrmsk] ,[setmsk] ,[prvmsk]

C Prototype

int sys$ieee_set_fp_control (struct _ieee *clrmsk, struct _ieee *setmsk, struct _ieee *prvmsk);

Arguments

clrmsk

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: read only

mechanism: by reference

Address of a quadword bit mask to be cleared in the IEEE floating-point control register.
The $IEEEDEF macro defines symbols for the floating-point control register. Table SYS-13 shows the symbols, their corresponding masks, and their meaning.

Table SYS-13 Format of the IEEE Floating-Point Control Register (Alpha Only)
Symbol Mask Meaning

IEEE$M_TRAP_ENABLE_INV 2 Invalid operation

IEEE$M_TRAP_ENABLE_DZE 4 Divide by 0

IEEE$M_TRAP_ENABLE_OVF 8 Overflow

IEEE$M_TRAP_ENABLE_UNF 10 Underflow

IEEE$M_TRAP_ENABLE_INE 20 Inexact

IEEE$M_MAP_UMZ 4000 Underflows are mapped to 0.0

IEEE$M_INHERIT 8000 Inherit FP state on thread create

IEEE$M_STATUS_INV 20000 Invalid operation

IEEE$M_STATUS_DZE 40000 Divide by 0

IEEE$M_STATUS_OVF 80000 Overflow

IEEE$M_STATUS_UNF 100000 Underflow

IEEE$M_STATUS_INE 200000 Inexact

setmsk

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: read only

mechanism: by reference

Address of a quadword bit mask to be set in the IEEE floating-point control register.
Table SYS-13 shows the format of the IEEE floating-point control register.
prvmsk

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: write only

mechanism: by reference

Address of a quadword to receive the previous value of the IEEE floating-point control register.

**Table SYS-13 Format of the IEEE Floating-Point Control Register (Alpha Only)**
Symbol	Mask	Meaning
IEEE$M_TRAP_ENABLE_INV	2	Invalid operation
IEEE$M_TRAP_ENABLE_DZE	4	Divide by 0
IEEE$M_TRAP_ENABLE_OVF	8	Overflow
IEEE$M_TRAP_ENABLE_UNF	10	Underflow
IEEE$M_TRAP_ENABLE_INE	20	Inexact
IEEE$M_MAP_UMZ	4000	Underflows are mapped to 0.0
IEEE$M_INHERIT	8000	Inherit FP state on thread create
IEEE$M_STATUS_INV	20000	Invalid operation
IEEE$M_STATUS_DZE	40000	Divide by 0
IEEE$M_STATUS_OVF	80000	Overflow
IEEE$M_STATUS_UNF	100000	Underflow
IEEE$M_STATUS_INE	200000	Inexact

Description

The Set IEEE Floating-Point Control Register service updates the IEEE floating-point control register, maintained by the operating system, with the values supplied by the calling program.
The following steps are used to update the register:

If the prvmsk argument is specified, $IEEE_SET_FP_CONTROL first reads the previous value of the IEEE floating-point control register.
If the clrmsk argument is specified, $IEEE_SET_FP_CONTROL then clears the specified bit masks in the clrmsk argument.
If the setmsk argument is specified, $IEEE_SET_FP_CONTROL then sets the specified bit masks in the setmsk argument.

A program can swap the IEEE floating-point control register (that is, save the old value and specify a new value) by specifying the following:

The clrmsk argument with the address of a quadword of all 1s
The setmsk argument with the address of a quadword that holds the new register value
The prvmsk argument with the address of a quadword to save the old register value

Required Access or Privilege

None
Required Quota

None

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The specified argument cannot be read or cannot be written.

Contents

Index

Legal

 
4527PRO_060.HTML

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_EXBYTLM	Insufficient byte count quota.
SS$_INSFARG	Too few arguments were supplied.
SS$_INSFMEM	Insufficient process or system memory to complete the request.
SS$_IVCHAN	Unknown connection specified or invalid connection handle.
SS$_IVMODE	Attempted to use a connection from a more privileged access mode than the mode in which it was opened.
SS$_LINKDISCON	An Incoming disconnect event is in progress.
SS$_SYNCH	If synchronous mode was requested at connection time, this return value indicates that completion has already occurred and the AST routine, if specified, will not be called.
SS$_TOO_MANY_ARGS	Too many arguments were specified.
SS$_WRONGSTATE	Connection is in wrong state for request.

OpenVMS usage:	connection_id
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	ios_status_block
type:	structure IOS_ICC
access:	write only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	ast_procedure
type:	procedure_entry_mask
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit linkage reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	user_arg
type:	quadword (unsigned) (Alpha), longword (unsigned) (VAX)
access:	read only
mechanism:	by 64-bit value (Alpha)
mechanism:	by 32-bit value (VAX)

OpenVMS usage:	byte_stream
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	buffer_length
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	rights_id
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	char_string
type:	character-coded text string
access:	write only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)
mechanism:	by 32-bit descriptor--fixed-length string descriptor (VAX)

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	write only
mechanism:	by by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The namlen, nambuf, resid, attrib, or contxt argument cannot be written by the caller.
SS$_INSFMEM	The process dynamic memory is insufficient for opening the rights database.
SS$_IVCHAN	The contents of the context longword are not valid.
SS$_IVIDENT	The specified identifier is of invalid format.
SS$_NOIOCHAN	No more rights database context streams are available.
SS$_NORIGHTSDB	The rights database does not exist.
SS$_NOSUCHID	The specified identifier name does not exist in the rights database, or the entire rights database has been searched if the ID is --1.

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	read only
mechanism:	by reference