OpenVMS System Services Reference Manual

The string can be either a physical device name or a logical name. If it is a logical name, it must translate to a physical device name.

phylen

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Word into which $ALLOC writes the length of the device name string for the device it has allocated. The phylen argument is the address of this word.

phybuf

OpenVMS usage:	device_name
type:	character-coded text string
access:	write only
mechanism:	by descriptor--fixed-length string descriptor

Buffer into which $ALLOC writes the device name string for the device it has allocated. The phybuf argument is the address of a character string descriptor pointing to this buffer.

acmode

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

Access mode to be associated with the allocated device. The acmode argument is a longword containing the access mode.

The most privileged access mode used is the access mode of the caller. Only equal or more privileged access modes can deallocate the device.

flags

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

Longword of status flags indicating whether to interpret the devnam argument as the type of device to be allocated. Only one flag exists, bit 0. When it is set, the $ALLOC service allocates the first available device that has the type specified in the devnam argument.

This feature is available for the following mass storage devices:

RA60 RA80 RA81 RC25

RCF25 RK06 RK07 RL01

RL02 RM03 RM05 RM80

RP04 RP05 RP06 RP07

RX01 RX02 TA78 TA81

TS11 TU16 TU58 TU77

TU78 TU80 TU81

DESCRIPTION

The Allocate Device service allocates a device for exclusive use by a process and its subprocesses. No other process can allocate the device or assign channels to it until the image that called $ALLOC exits or explicitly deallocates the device with the Deallocate Device ($DALLOC) service.
When a process calls the Assign I/O Channel ($ASSIGN) service to assign a channel to a nonshareable, nonspooled device, such as a terminal or line printer, the device is implicitly allocated to the process.
You can use this service only to allocate devices that either exist on the host system or are made available to the host system in an OpenVMS Cluster environment.
Required Access or Privileges

Read, write, or control access to the device is required.
Required Quota

None
Related Services

$ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_BUFFEROVF The service completed successfully. The physical name returned overflowed the buffer provided, and was truncated.

SS$_DEVALRALLOC The service completed successfully. The device was already allocated to the calling process.

SS$_ACCVIO The device name string, string descriptor, or physical name buffer descriptor cannot be read by the caller, or the physical name buffer cannot be written by the caller.

SS$_DEVALLOC The device is already allocated to another process, or an attempt to allocate an unmounted shareable device failed because other processes had channels assigned to the device.

SS$_DEVMOUNT The specified device is currently mounted and cannot be allocated, or the device is a mailbox.

SS$_DEVOFFLINE The specified device is marked off line.

SS$_IVDEVNAM The device name string contains invalid characters, or no device name string was specified.

SS$_IVLOGNAM The device name string has a length of 0 or has more than 63 characters.

SS$_IVSTSFLG The bits set in the longword of status flags are invalid.

SS$_NODEVAVL The specified device in a generic search exists but is allocated to another user.

SS$_NONLOCAL The device is on a remote node.

SS$_NOPRIV The requesting process attempted to allocate a spooled device and does not have the required privilege, or the device protection or access control list (or both) denies access.

SS$_NOSUCHDEV The specified device does not exist in the host system. This error is usually the result of a typographical error.

SS$_TEMPLATEDEV The process attempted to allocate a template device; a template device cannot be allocated.

The $ALLOC service can also return any condition value returned by $ENQ. For a list of these condition values, see the description of $ENQ.

$ASCEFC

Associates a named common event flag cluster with a process to execute the current image and to be assigned a process-local cluster number for use with other event flag services. If the named cluster does not exist but the process has suitable privilege, the service creates the cluster.

Format

SYS$ASCEFC efn ,name ,[prot] ,[perm]

C Prototype

int sys$ascefc (unsigned int efn, void *name, char prot, char perm);

ARGUMENTS

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Number of any event flag contained within the desired common event flag cluster. The efn argument is a longword value specifying this number; however, $ASCEFC uses only the low-order byte.
There are two common event flag clusters: cluster 2 and cluster 3. Cluster 2 contains event flag numbers 64 to 95, and cluster 3 contains event flag numbers 96 to 127. (Clusters 0 and 1 are process-local event flag clusters.)
To associate with common event flag cluster 2, specify any flag number in the cluster (64 to 95); to associate with common event flag cluster 3, specify any event flag number in the cluster (96 to 127).
name

OpenVMS usage: ef_cluster_name

type: character-coded text string

access: read only

mechanism: by descriptor--fixed-length string descriptor

Name of the common event flag cluster with which to associate. The name argument is the address of a character string descriptor pointing to this name string.
The character string descriptor can be 1 to 15 bytes in length, and each byte can be any 8-bit value.
Common event flag clusters are accessible only to processes having the same UIC group number, and each such process must associate with the cluster using the same name (specified in the name argument). The operating system implicitly associates the group UIC number with the name, making the name unique to a UIC group.

prot

OpenVMS usage: Boolean

type: byte (unsigned)

access: read only

mechanism: by value

Protection specifier that allows or disallows access to the common event flag cluster for processes with the same UIC group number as the creating process. The prot argument is a longword value, which is interpreted as Boolean.
The default value 0 specifies that any process with the same UIC group number as the creating process can access the event flag cluster. The value 1 specifies that only processes having the UIC of the creating process can access the event flag cluster.
When the prot argument is 1, all access to the Group category is denied.
The process must have associate access to access an existing common event flag cluster.
perm

OpenVMS usage: Boolean

type: byte (unsigned)

access: read only

mechanism: by value

Permanent specifier that marks a common event flag cluster as either permanent or temporary. The perm argument is a longword value, which is interpreted as Boolean.
The default value 0 specifies that the cluster is temporary. The value 1 specifies that the cluster is permanent.

DESCRIPTION

The Associate Common Event Flag Cluster service associates a named common event flag cluster with a process for the execution of the current image and to assign it a process-local cluster number for use with other event flag services. A process needs associate access to call the $ASCEFC service.
When a process associates with a common event flag cluster, that cluster's reference count is increased by 1. The reference count is decreased when a process disassociates from the cluster, whether explicitly with the Disassociate Common Event Flag Cluster ($DACEFC) service or implicitly at image exit.
Temporary clusters are automatically deleted when their reference count goes to 0; you must explicitly mark permanent clusters for deletion with the Delete Common Event Flag Cluster ($DLCEFC) service.
When a new cluster is created, a security profile is created with the process UIC as the owner of the common event flag cluster; the remaining characteristics are taken from the COMMON_EVENT_CLUSTER.DEFAULT template profile.
Because the $ASCEFC service automatically creates the common event flag cluster if it does not already exist, cooperating processes need not be concerned with which process executes first to create the cluster. The first process to call $ASCEFC creates the cluster and the others associate with it regardless of the order in which they call the service.
The initial state for all event flags in a newly created common event flag cluster is 0.
If a process has already associated a cluster number with a named common event flag cluster and then issues another call to $ASCEFC with the same cluster number, the service disassociates the number from its first assignment before associating it with its second.
If you previously called any system service that will set an event flag (and the event flag is contained within the cluster being reassigned), the event flag will be set in the newly associated named cluster, not in the previously associated named cluster.
Required Access or Privileges

The calling process must have PRMCEB privilege to create a permanent common event flag cluster.
Required Quota

Creation of temporary common event flag clusters uses the quota of the process for timer queue entries (TQELM); the creation of a permanent cluster does not affect the quota. The quota is restored to the creator of the cluster when all processes associated with the cluster have disassociated.
Related Services

$CLREF, $DACEFC, $DLCEFC, $READEF, $SETEF, $WAITFR, $WFLAND, $WFLOR

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The cluster name string or string descriptor cannot be read by the caller.

SS$_EXPORTQUOTA The process has exceeded the number of event flag clusters with which processes on this port of the multiport (shared) memory can associate.

SS$_EXQUOTA The process has exceeded its timer queue entry quota; this quota controls the creation of temporary common event flag clusters.

SS$_INSFMEM The system dynamic memory is insufficient for completing the service.

SS$_ILLEFC You specified an illegal event flag number. The cluster number must be in the range of event flags 64 through 127.

SS$_INTERLOCK The bit map lock for allocating common event flag clusters from the specified shared memory is locked by another process.

SS$_IVLOGNAM The cluster name string has a length of 0 or has more than 15 characters.

SS$_NOPRIV The process does not have the privilege to create a permanent cluster; the process does not have the privilege to create a common event flag cluster in memory shared by multiple processors; or the protection applied to an existing cluster by its creator prohibits association.

SS$_NOSHMBLOCK The common event flag cluster has no shared memory control block available.

SS$_SHMNOTCNT+ The shared memory named in the name argument is not known to the system. This error can be caused by a spelling error in the string, an improperly assigned logical name, or the failure to identify the multiport memory as shared at system generation time.

+VAX specific

$ASCTIM

Converts an absolute or delta time from 64-bit system time format to an ASCII string.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$ASCTIM [timlen] ,timbuf ,[timadr] ,[cvtflg]

C Prototype

int sys$asctim (unsigned short int *timlen, void *timbuf, struct _generic_64 *timadr, char cvtflg);

ARGUMENTS

timlen

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

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

mechanism: by 32-bit reference (VAX)

Length (in bytes) of the ASCII string returned by $ASCTIM. The timlen argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a word containing this length.
timbuf

OpenVMS usage: time_name

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 (VAX)

Buffer into which $ASCTIM writes the ASCII string. The timbuf argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a character string descriptor pointing to the buffer.
The buffer length specified in the timbuf argument, together with the cvtflg argument, controls what information is returned.
timadr

OpenVMS usage: date_time

type: quadword

access: read only

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

mechanism: by 32-bit reference (VAX)

Time value that $ASCTIM is to convert. The timadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of this 64-bit time value. A positive time value represents an absolute time. A negative time value represents a delta time. If you specify a delta time, it must be less than 10,000 days.
If timadr is not specified or is specified as 0 (the default), $ASCTIM returns the current date and time.
cvtflg

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: read only

mechanism: by value

Conversion indicator specifying which date and time fields $ASCTIM should return. The cvtflg argument is a longword value, which is interpreted as Boolean. The value 1 specifies that $ASCTIM should return only the hour, minute, second, and hundredths-of-second fields. The default value 0 specifies that $ASCTIM should return the full date and time.

DESCRIPTION

The Convert Binary Time to ASCII String service converts an absolute or delta time from 64-bit system time format to an ASCII string. The service executes at the access mode of the caller and does not check whether address arguments are accessible before it executes. Therefore, an access violation causes an exception condition if the input time value cannot be read or the output buffer or buffer length cannot be written.
This service returns the SS$_INSFARG (insufficient arguments) condition value if one or both of the required arguments are not supplied.
The ASCII strings returned have the following formats:

Absolute Time: dd-mmm-yyyy hh:mm:ss.cc
Delta Time: dddd hh:mm:ss.cc
The following table lists the length (in bytes), contents, and range of values for each field in the absolute time and delta time formats.

Field Length
(Bytes) Contents Range of Values

dd 2 Day of month 1--31

-- 1 Hyphen Required syntax

mmm 3 Month JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC

-- 1 Hyphen Required syntax

yyyy 4 Year 1858--9999

blank n Blank Required syntax

hh 2 Hour 00--23

: 1 Colon Required syntax

mm 2 Minutes 00--59

: 1 Colon Required syntax

ss 2 Seconds 00--59

. 1 Period Required syntax

cc 2 Hundredths-of-second 00--99

dddd 4 Number of days (in 24-hr units) 000--9999

Month abbreviations must be uppercase.
The hundredths-of-second field now represents a true fraction. For example, the string .1 represents ten-hundredths of a second (one-tenth of a second), and the string .01 represents one-hundredth of a second.
Also, you can add a third digit to the hundredths-of-second field; this thousandths-of-second digit is used to round the hundredths-of-second value. Digits beyond the thousandths-of-second digits are ignored.
The results of specifying some possible combinations for the values of the cvtflg and timbuf arguments are as follows.

Time Value Buffer Length
Specified CVTFLG
Argument Information
Returned

Absolute 23 0 Date and time

Absolute 12 0 Date

Absolute 11 1 Time

Delta 16 0 Days and time

Delta 11 1 Time

Required Access or Privileges

None
Required Quota

None
Related Services

$BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIME, $SETIMR

Field	Length (Bytes)	Contents	Range of Values
dd	2	Day of month	1--31
--	1	Hyphen	Required syntax
mmm	3	Month	JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC
--	1	Hyphen	Required syntax
yyyy	4	Year	1858--9999
blank	n	Blank	Required syntax
hh	2	Hour	00--23
:	1	Colon	Required syntax
mm	2	Minutes	00--59
:	1	Colon	Required syntax
ss	2	Seconds	00--59
.	1	Period	Required syntax
cc	2	Hundredths-of-second	00--99
dddd	4	Number of days (in 24-hr units)	000--9999

Time Value	Buffer Length Specified	CVTFLG Argument	Information Returned
Absolute	23	0	Date and time
Absolute	12	0	Date
Absolute	11	1	Time
Delta	16	0	Days and time
Delta	11	1	Time

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_BUFFEROVF The buffer length specified in the timbuf argument is too small.

SS$_INSFARG One or both required arguments are missing.

SS$_IVTIME The specified delta time is equal to or greater than 10,000 days.

$ASCTOID

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

Format

SYS$ASCTOID name ,[id] ,[attrib]

C Prototype

int sys$asctoid (void *name, unsigned int *id, unsigned int *attrib);

ARGUMENTS

name

OpenVMS usage: char_string

type: character-coded text string

access: read 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 translated when $ASCTOID completes execution. The name argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a character-string descriptor pointing to the identifier name.
id

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 resulting when $ASCTOID completes execution. The id argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a longword in which the identifier value is written.
attrib

OpenVMS usage: mask_longword

type: longword (unsigned)

access: write only

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

mechanism: by 32-bit reference (VAX)

Attributes associated with the identifier returned in id when $ASCTOID completes execution. 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 a bit mask specifying the attributes.
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 symbols are defined in the system macro $KGBDEF library. The symbolic names for each bit position are listed in the following table.

Bit Position Meaning When Set

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

KGB$V_HOLDER_HIDDEN Prevents someone from getting a list of users who hold an identifier, unless they own the identifier themselves. Special privilege is required to translate hidden names.

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. Special privilege is required to translate hidden names.

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 the holder to charge resources, such as disk blocks, to the identifier.

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

Bit Position	Meaning When Set
KGB$V_DYNAMIC	Allows holders of the identifier to remove it from or add it to the process rights database by using the DCL command SET RIGHTS_LIST.
KGB$V_HOLDER_HIDDEN	Prevents someone from getting a list of users who hold an identifier, unless they own the identifier themselves. Special privilege is required to translate hidden names.
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. Special privilege is required to translate hidden names.
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 the holder to charge resources, such as disk blocks, to the identifier.
KGB$V_SUBSYSTEM	Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem access control entry (ACE) to the application images in the subsystem.

DESCRIPTION

The Translate Identifier Name to Identifier service converts the specified identifier name to its binary identifier value.
Required Access or Privileges

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4527P002.HTM
  OSSG Documentation
  22-NOV-1996 12:58:42.87
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

RA60	RA80	RA81	RC25
RCF25	RK06	RK07	RL01
RL02	RM03	RM05	RM80
RP04	RP05	RP06	RP07
RX01	RX02	TA78	TA81
TS11	TU16	TU58	TU77
TU78	TU80	TU81

SS$_NORMAL	The service completed successfully.
SS$_BUFFEROVF	The service completed successfully. The physical name returned overflowed the buffer provided, and was truncated.
SS$_DEVALRALLOC	The service completed successfully. The device was already allocated to the calling process.
SS$_ACCVIO	The device name string, string descriptor, or physical name buffer descriptor cannot be read by the caller, or the physical name buffer cannot be written by the caller.
SS$_DEVALLOC	The device is already allocated to another process, or an attempt to allocate an unmounted shareable device failed because other processes had channels assigned to the device.
SS$_DEVMOUNT	The specified device is currently mounted and cannot be allocated, or the device is a mailbox.
SS$_DEVOFFLINE	The specified device is marked off line.
SS$_IVDEVNAM	The device name string contains invalid characters, or no device name string was specified.
SS$_IVLOGNAM	The device name string has a length of 0 or has more than 63 characters.
SS$_IVSTSFLG	The bits set in the longword of status flags are invalid.
SS$_NODEVAVL	The specified device in a generic search exists but is allocated to another user.
SS$_NONLOCAL	The device is on a remote node.
SS$_NOPRIV	The requesting process attempted to allocate a spooled device and does not have the required privilege, or the device protection or access control list (or both) denies access.
SS$_NOSUCHDEV	The specified device does not exist in the host system. This error is usually the result of a typographical error.
SS$_TEMPLATEDEV	The process attempted to allocate a template device; a template device cannot be allocated.

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

OpenVMS usage:	ef_cluster_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

OpenVMS usage:	Boolean
type:	byte (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	time_name
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 (VAX)

OpenVMS usage:	date_time
type:	quadword
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

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

OpenVMS usage:	char_string
type:	character-coded text string
access:	read 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:	rights_id
type:	longword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)