 |
HP OpenVMS System Services Reference Manual
$ALLOC
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.
Format
SYS$ALLOC devnam ,[phylen] ,[phybuf] ,[acmode] ,[flags]
C Prototype
int sys$alloc (void *devnam, unsigned short int *phylen, void *phybuf,
unsigned int acmode, unsigned int flags);
Arguments
devnam
| OpenVMS usage: |
device_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Device name of the device to be allocated. The devnam
argument is the address of a character string descriptor pointing to
the device name string.
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.
You can specify any name from 1 to 43 characters. All processes mapping
to the same global section must specify the same name. Note that the
name is case sensitive.
Use of characters valid in logical names is strongly encouraged. Valid
values include alphanumeric characters, the dollar sign ($), and the
underscore (_). If the name string begins with an underscore (_), the
underscore is stripped and the resultant string is considered to be the
actual name. Use of the colon (:) is not permitted.
Names are first subject to a logical name translation, after the
application of the prefix GBL$ to the name. If the result translates,
it is used as the name of the section. If the resulting name does not
translate, the name specified by the caller is used as the name of the
section.
Additional information on logical name translations and on section name
processing is available in the OpenVMS Programming Concepts Manual.
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 and I64 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 and I64) |
| 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 and I64 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 and I64) |
| 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 and I64 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 and I64 ) |
| 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 and I64 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
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_BUFFEROVF
|
The buffer length specified in the
timbuf argument is too small.
|
|
SS$_INSFARG
|
Required argument is missing.
|
|
SS$_IVTIME
|
The specified delta time is equal to or greater than 10,000 days.
|
|
