 |
HP OpenVMS System Services Reference Manual
$ASCTOID
Translates the specified identifier name into its binary identifier
value.
On Alpha and I64 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 and I64) |
| 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
and I64 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 and I64) |
| 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 and
I64 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 and I64) |
| 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
and I64 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.
|
Description
The Translate Identifier Name to Identifier service converts the
specified identifier name to its binary identifier value.
Required Access or Privileges
None, unless the id is KGB$V_NAME_HIDDEN, in which
case you must hold the id or have access to the rights
database.
Required Quota
None
Related Services
$ADD_HOLDER, $ADD_IDENT, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER,
$FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER,
$REM_IDENT, $REVOKID
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
name argument cannot be read by the caller, or the
id or
attrib arguments cannot be written by the caller.
|
|
SS$_INSFMEM
|
The process dynamic memory is insufficient for opening the rights
database.
|
|
SS$_IVIDENT
|
The format of the specified identifier is invalid.
|
|
SS$_NOSUCHID
|
The specified identifier name does not exist in the rights database, or
the identifier is hidden and you do not have access to the rights
database.
|
|
SS$_NORIGHTSDB
|
The rights database does not exist.
|
Because the rights database is an indexed file accessed 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.
$ASCUTC
Converts an absolute time from 128-bit UTC format to an ASCII string.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$ASCUTC [timlen] ,timbuf ,[utcadr] ,[cvtflg]
C Prototype
int sys$ascutc (unsigned short int *timlen, void *timbuf, unsigned int
*utcadr [4], 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 $ASCUTC. 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 string text |
| access: |
write only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string descriptor
(Alpha and I64 ) |
| mechanism: |
by 32-bit descriptor--fixed-length string descriptor
(VAX) |
Buffer into which $ASCUTC 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.
utcadr
| OpenVMS usage: |
coordinated universal time |
| type: |
utc_date_time |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Time value that $ASCUTC 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 128-bit time value. Relative
times are not permitted. If the timadr argument is not
specified, it defaults to 0 and $ASCUTC 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 $ASCUTC
should return. The cvtflg argument is a longword value
that is interpreted as Boolean. The value 1 specifies that $ASCUTC
should return only the time, including hour, minute, second, and
hundredths-of-second fields. The default value 0 specifies that $ASCUTC
should return the full date and time.
Description
The Convert UTC to ASCII service converts an absolute time from 128-bit
UTC 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.
The $ASCUTC service uses the time zone differential factor encoded in
the 128-bit UTC to convert the UTC to an ASCII string.
This service does not check the length of the argument list, and
therefore cannot return the SS$_INSFARG condition value.
The ASCII strings returned have the following format:
- Absolute Time: dd-mmm-yyyy hh:mm:ss.cc
The following table lists the length (in bytes), contents, and range of
values for each field in the absolute time format:
| 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
|
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
|
Required Access or Privileges
None
Required Quota
None
Related Services
$BINUTC, $GETUTC, $NUMUTC, $TIMCON
Condition Values Returned
|
SS_$NORMAL
|
The service completed successfully.
|
|
SS_$BUFFEROVF
|
The buffer length specified in the
timbuf argument is too small.
|
|
SS_$INVTIME
|
The UTC time supplied is too small to be represented as a Smithsonian
Time, or the UTC time is not valid.
|
$ASSIGN
Provides a process with an I/O channel so input/output operations can
be performed on a device, or establishes a logical link with a remote
node on a network.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$ASSIGN devnam ,chan ,[acmode] ,[mbxnam] ,[flags]
C Prototype
int sys$assign (void *devnam, unsigned short int *chan, unsigned int
acmode, void *mbxnam,...);
Arguments
devnam
| OpenVMS usage: |
device_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string descriptor
(Alpha and I64) |
| mechanism: |
by 32-bit descriptor--fixed-length string descriptor
(VAX) |
Name of the device to which $ASSIGN is to assign a channel. The
devnam argument is the 32- or 64-bit address (on Alpha
and I64 systems) or the 32-bit address (on VAX systems) of a character
string descriptor pointing to the device name string.
If the device name contains a double colon (::), the system assigns a
channel to the first available network device (NET:) and performs an
access function on the network.
chan
| OpenVMS usage: |
channel |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Number of the channel that is assigned. The chan
argument is the 32- or 64-bit address (on Alpha and I64systems) or the
32-bit address (on VAX systems) of a word into which $ASSIGN writes the
channel number.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode to be associated with the channel. The
acmode argument specifies the access mode. The $PSLDEF
macro defines the following symbols for the four access modes:
| Symbol |
Access Mode |
Numeric Value |
|
PSL$C_KERNEL
|
Kernel
|
0
|
|
PSL$C_EXEC
|
Executive
|
1
|
|
PSL$C_SUPER
|
Supervisor
|
2
|
|
PSL$C_USER
|
User
|
3
|
The specified access mode and the access mode of the caller are
compared. The less privileged (but the higher numeric valued) of the
two access modes becomes the access mode associated with the assigned
channel. I/O operations on the channel can be performed only from equal
and more privileged access modes. For more information, refer to the
section on access modes in the OpenVMS Programming Concepts Manual.
mbxnam
| OpenVMS usage: |
device_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string descriptor
(Alpha and I64) |
| mechanism: |
by 32-bit descriptor--fixed-length string descriptor
(VAX) |
Logical name of the mailbox to be associated with the device. The
mbxnam argument is the 32- or 64-bit address (on Alpha
and I64 systems) or the 32-bit address (on VAX systems) of a character
string descriptor pointing to the logical name string.
If you specify mbxnam as 0, no mailbox is associated
with the device. This is the default.
You must specify the mbxnam argument when performing a
nontransparent, task-to-task, network operation.
Only the owner of a device can associate a mailbox with the device; the
owner of a device is the process that has allocated the device, whether
implicitly or explicitly. Only one mailbox can be associated with a
device at any one time.
For unshareable, nonspooled devices, an implicit $ALLOCATE is done.
This requires read, write, or control access to the device.
A mailbox cannot be associated with a device if the device has foreign
(DEV$M_FOR) or shareable (DEV$M_SHR) characteristics.
A mailbox is disassociated from a device when the channel that
associated it is deassigned.
If a mailbox is associated with a device, the device driver can send
status information to the mailbox. For example, if the device is a
terminal, this information might indicate dialup, hangup, or the
reception of unsolicited input; if the device is a network device, it
might indicate that the network is connected or perhaps that the line
is down.
For details on the nature and format of the information returned to the
mailbox, refer to the HP OpenVMS I/O User's Reference Manual.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
An optional device-specific argument. The flags
argument is a longword bit mask.
For more information on the applicability of the flags
argument for a particular device, refer to the HP OpenVMS I/O User's Reference Manual.
Description
The Assign I/O Channel service provides a process with an I/O channel
so input/output operations can be performed on a device. This service
also establishes a logical link with a remote node on a network.
Channels remain assigned until they are explicitly deassigned with the
Deassign I/O Channel ($DASSGN) service or, if they are user-mode
channels, until the image that assigned the channel exits.
The $ASSIGN service establishes a path to a device but does not check
whether the caller can actually perform input/output operations to the
device. Privilege and protection restrictions can be applied by the
device drivers.
Required Access or Privileges
The calling process must have NETMBX privilege to perform network
operations, and system dynamic memory is required if the target device
is on a remote system.
Note that you should use the SHARE privilege with caution.
Applications, application protocols, and device drivers coded to expect
only exclusive access can encounter unexpected and errant behavior when
access to the device is unexpectedly shared. Unless the SHARE privilege
is explicitly supported by the application, the application protocol,
and the device driver, its use is generally discouraged. Refer to the
OpenVMS Programming Concepts Manual for additional information.
Required Quota
If the target of the assignment is on a remote node, the process needs
sufficient buffer quota to allocate a network control block.
Related Services
$ALLOC, $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$_REMOTE
|
The service completed successfully. A logical link is established with
the target on a remote node.
|
|
SS$_ABORT
|
A physical line went down during a network connect operation.
|
|
SS$_ACCVIO
|
The device or mailbox name string or string descriptor cannot be read
by the caller, or the channel number cannot be written by the caller.
|
|
SS$_CONNECFAIL
|
For network operations, the connection to a network object timed out or
failed.
|
|
SS$_DEVACTIVE
|
You specified a mailbox name, but a mailbox is already associated with
the device.
|
|
SS$_DEVALLOC
|
The device is allocated to another process.
|
|
SS$_DEVNOTMBX
|
You specified a logical name for the associated mailbox, but the
logical name refers to a device that is not a mailbox.
|
|
SS$_DEVOFFLINE
|
For network operations, the physical link is shutting down.
|
|
SS$_EXBYTLM
|
The process has exceeded the byte count quota.
|
|
SS$_EXQUOTA
|
The target of the assignment is on a remote node and the process has
insufficient buffer quota to allocate a network control block.
|
|
SS$_FILALRACC
|
For network operations, a logical link already exists on the channel.
|
|
SS$_INSFMEM
|
The target of the assignment is on a remote node and there is
insufficient system dynamic memory to complete the request.
|
|
SS$_INVLOGIN
|
For network operations, the access control information was found to be
invalid at the remote node.
|
|
SS$_IVDEVNAM
|
No device name was specified, the logical name translation failed, or
the device or mailbox name string contains invalid characters. If the
device name is a target on a remote node, this status code indicates
that the network connect block has an invalid format.
|
|
SS$_IVLOGNAM
|
The device or mailbox name string has a length of 0 or has more than 63
characters.
|
|
SS$_LINKEXIT
|
For network operations, the network partner task was started, but
exited before confirming the logical link (that is, $ASSIGN to SYS$NET).
|
|
SS$_NOIOCHAN
|
No I/O channel is available for assignment.
|
|
SS$_NOLINKS
|
For network operations, no logical links are available. The maximum
number of logical links as set for the Network Control Program (NCP)
executor MAXIMUM LINKS parameter was exceeded.
|
|
SS$_NOPRIV
|
For network operations, the issuing task does not have the required
privilege to perform network operations or to confirm the specified
logical link.
|
|
SS$_NOSUCHDEV
|
The specified device or mailbox does not exist, or, for DECnet for
OpenVMS operations, the network device driver is not loaded (for
example, the DECnet for OpenVMS software is not currently running on
the local node).
|
|
SS$_NOSUCHNODE
|
The specified network node is nonexistent or unavailable.
|
|
SS$_NOSUCHOBJ
|
For network operations, the network object number is unknown at the
remote node; for a TASK= connect, the named DCL command procedure file
cannot be found at the remote node.
|
|
SS$_NOSUCHUSER
|
For network operations, the remote node could not recognize the login
information supplied with the connection request.
|
|
SS$_PROTOCOL
|
For network operations, a network protocol error occurred, most likely
because of a network software error.
|
|
SS$_REJECT
|
The network connect was rejected by the network software or by the
partner at the remote node, or the target image exited before the
connect confirm could be issued.
|
|
SS$_REMRSRC
|
For network operations, the link could not be established because
system resources at the remote node were insufficient.
|
|
SS$_SHUT
|
For network operations, the local or remote node is no longer accepting
connections.
|
|
SS$_THIRDPARTY
|
For network operations, the logical link connection was terminated by a
third party (for example, the system manager).
|
|
SS$_TOOMUCHDATA
|
For network operations, the task specified too much optional or
interrupt data.
|
|
SS$_UNREACHABLE
|
For network operations, the remote node is currently unreachable.
|
|
