![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 30 March 2001 | |
|
|
|
|
|
|
| Previous | Contents | Index |
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.
SYS$ASCTIM [timlen] ,timbuf ,[timadr] ,[cvtflg]
int sys$asctim (unsigned short int *timlen, void *timbuf, struct _generic_64 *timadr, char cvtflg);
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.
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
SpecifiedCVTFLG
ArgumentInformation
ReturnedAbsolute 23 0 Date and time Absolute 12 0 Date Absolute 11 1 Time Delta 16 0 Days and time Delta 11 1 Time None
None
$BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIME, $SETIMR
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.
Translates the specified identifier name into its binary identifier value.On Alpha 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) 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.
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, refer to the OpenVMS Record Management Services Reference Manual.
Converts an absolute time from 128-bit UTC format to an ASCII string.On Alpha 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) 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.
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.
| Previous | Next | Contents | Index |
|
|
| privacy and legal statement | ||
| 4527PRO_003.HTML | ||