| Previous | Contents | Index |
Translates the specified identifier name into its binary identifier value.On Alpha and I64 systems, this service accepts 64-bit addresses.
SYS$ASCTOID name ,[id] ,[attrib]
int sys$asctoid (void *name, unsigned int *id, unsigned int *attrib);
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.
The Translate Identifier Name to Identifier service converts the specified identifier name to its binary identifier value.None, unless the id is KGB$V_NAME_HIDDEN, in which case you must hold the id or have access to the rights database.
None
$ADD_HOLDER, $ADD_IDENT, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID
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, see the OpenVMS Record Management Services Reference Manual.
Converts an absolute time from 128-bit UTC format to an ASCII string.On Alpha and I64 systems, this service accepts 64-bit addresses.
SYS$ASCUTC [timlen] ,timbuf ,[utcadr] ,[cvtflg]
int sys$ascutc (unsigned short int *timlen, void *timbuf, unsigned int *utcadr [4], char cvtflg);
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.
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
SpecifiedCVTFLG
ArgumentInformation
ReturnedAbsolute 23 0 Date and time Absolute 12 0 Date Absolute 11 1 Time None
None
$BINUTC, $GETUTC, $NUMUTC, $TIMCON
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.
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.
SYS$ASSIGN devnam ,chan ,[acmode] ,[mbxnam] ,[flags]
int sys$assign (void *devnam, unsigned short int *chan, unsigned int acmode, void *mbxnam,...);
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, see the section on access modes in the HP 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, see 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, see the HP OpenVMS I/O User's Reference Manual.
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.
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. For additional information, see the HP OpenVMS Programming Concepts Manual.
If the target of the assignment is on a remote node, the process needs sufficient buffer quota to allocate a network control block.
$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
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.
| Previous | Next | Contents | Index |