Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $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.

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_003.HTML