 |
OpenVMS System Services Reference Manual
$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
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.
|
$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.
|
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 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) |
| 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 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) |
| 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 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) |
| 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 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.
|
|
