[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual


Previous Contents Index


LIB$SYS_ASCTIM

The Invoke $ASCTIM to Convert Binary Time to ASCII String routine calls the system service $ASCTIM to convert a binary date and time value, returning the ASCII string using the semantics of the caller's string.

Format

LIB$SYS_ASCTIM [resultant-length] ,time-string [,user-time] [,flags]


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Arguments

resultant-length


OpenVMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference

Number of bytes written into time-string, not counting padding in the case of a fixed-length string. The resultant-length argument contains the address of an unsigned word integer that is this number.

If the input string is truncated to the size specified in the time-string descriptor, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of time-string.

time-string


OpenVMS usage: time_name
type: character string
access: write only
mechanism: by descriptor

Destination string into which LIB$SYS_ASCTIM writes the ASCII time string. The time-string argument contains the address of a descriptor pointing to the destination string.

user-time


OpenVMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference

Value that LIB$SYS_ASCTIM converts to ASCII string form. The user-time argument contains the address of a signed quadword integer that is this value.

If 0 or no address is specified, the current system date and time are returned. A positive value represents an absolute time. A negative value represents a delta time. Delta times must be less than 10,000 days.

flags


OpenVMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference

Conversion indicator specifying which date and time fields LIB$SYS_ASCTIM should return. The flags argument is the address of an unsigned bit mask that contains this conversion indicator.

A value of 1 causes only the hour, minute, second, and hundredths of a second to be returned, depending on the length of the buffer. A value of 0 (the default) causes the full date and time to be returned, depending on the length of the buffer.

The results of specifying some possible combinations for the values of the flags and time-string arguments are shown below:
Time Value Time-String Length Flags Value 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

The flags argument is passed to LIB$SYS_ASCTIM by reference and is changed to value for use by $ASCTIM.


Description

See the OpenVMS System Services Reference Manual for a complete description of $ASCTIM.

Condition Values Returned

SS$_NORMAL Routine successfully completed.
SS$_IVTIME The specified delta time is greater than or equal to 10,000 days.
LIB$_FATERRLIB Fatal internal error. An internal consistency check has failed. This usually indicates an internal error in the Run-Time Library and should be reported to your Compaq support representative.
LIB$_INSVIRMEM Insufficient virtual memory. Your program has exceeded the image quota for virtual memory.
LIB$_INVSTRDES Invalid string descriptor. A string descriptor has an invalid value in its CLASS field.
LIB$_STRTRU Routine successfully completed, but the source string was truncated on copy.

LIB$SYS_FAO

The Invoke $FAO System Service to Format Output routine calls the $FAO system service, returning a string in the semantics you provide. If called with other than a fixed-length string for output, the length of the resultant string is limited to 256 bytes and truncation occurs.

Format

LIB$SYS_FAO character-string, [resultant-length] ,resultant-string [,directive-argument ,...]


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Arguments

character-string


OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor

ASCII control string, consisting of the fixed text of the output string and FAO directives. The character-string argument contains the address of a descriptor pointing to this control string.

resultant-length


OpenVMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference

Length of the output string. The resultant-length argument contains the address of an unsigned word integer that is this length.

resultant-string


OpenVMS usage: char_string
type: character string
access: write only
mechanism: by descriptor

Fully formatted output string returned by LIB$SYS_FAO. The resultant-string argument contains the address of a descriptor pointing to this output string.

directive-argument


OpenVMS usage: varying_arg
type: unspecified
access: read only
mechanism: unspecified

Directive argument contained in longwords. Depending on the directive, a directive-argument argument can be a value to be converted, the address of the string to be inserted, or a length or argument count. The passing mechanism for each of these arguments should be the one expected by the $FAO system service.

Description

See the OpenVMS System Services Reference Manual for a complete description of $FAO.

Condition Values Returned

SS$_NORMAL Routine successfully completed.
SS$_BADPARAM An invalid directive was specified in the FAO control string.
SS$_BUFFEROVF Successfully completed, but the formatted output string overflowed the output buffer and was truncated.
LIB$_STRTRU Success, but the source string was truncated on copy.
LIB$_INSVIRMEM Insufficient virtual memory to allocate dynamic string.
LIB$_INVSTRDES Invalid string descriptor. A string descriptor has an invalid value in its CLASS field.

LIB$SYS_FAOL

The Invoke $FAOL System Service to Format Output routine calls the $FAOL system service, returning the string in the semantics you provide. If called with other than a fixed-length string for output, the length of the resultant string is limited to 256 bytes and truncation occurs.

Format

LIB$SYS_FAOL character-string [,resultant-length] ,resultant-string ,directive-argument-address


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Arguments

character-string


OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor

ASCII control string, consisting of the fixed text of the output string and FAO directives. The character-string argument contains the address of a descriptor pointing to this control string.

resultant-length


OpenVMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference

Length of the output string. The resultant-length argument contains the address of an unsigned word integer that is this length.

resultant-string


OpenVMS usage: char_string
type: character string
access: write only
mechanism: by descriptor

Fully formatted output string returned by LIB$SYS_FAOL. The resultant-string argument contains the address of a descriptor pointing to this output string.

directive-argument-address


OpenVMS usage: address
type: longword (unsigned)
access: read only
mechanism: unspecified

Directive arguments. The directive-argument-address arguments are contained in an array of unsigned longword directive arguments. Depending on the directive, a directive-argument-address argument can be a value to be converted, the address of the string to be inserted, or a length or argument count. The passing mechanism for each of these arguments should be the one expected by the $FAOL system service.

Description

See the OpenVMS System Services Reference Manual for a complete description of $FAOL.

Condition Values Returned

SS$_NORMAL Routine successfully completed.
SS$_BADPARAM An invalid directive was specified in the FAO control string.
SS$_BUFFEROVF Successfully completed, but the formatted output string overflowed the output buffer and was truncated.
LIB$_INSVIRMEM Insufficient virtual memory to allocate dynamic string.
LIB$_INVSTRDES Invalid string descriptor. A string descriptor has an invalid value in its CLASS field.
LIB$_STRTRU Success, but the source string was truncated on copy.

LIB$SYS_FAOL_64 (Alpha Only)

The Invoke $FAOL_64 System Service to Format Output routine calls the $FAOL_64 system service, returning the string in the semantics you provide. If called with other than a fixed-length string for output, the length of the resultant string is limited to 256 bytes and truncation occurs.

Format

LIB$SYS_FAOL_64 character-string [,resultant-length] ,resultant-string ,directive-argument-address


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Arguments

character-string


OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor

ASCII control string, consisting of the fixed text of the output string and FAO directives. The character-string argument contains the address of a descriptor pointing to this control string.

resultant-length


OpenVMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference

Length of the output string. The resultant-length argument contains the address of an unsigned word integer that is this length.

resultant-string


OpenVMS usage: char_string
type: character string
access: write only
mechanism: by descriptor

Fully formatted output string returned by LIB$SYS_FAOL_64. The resultant-string argument contains the address of a descriptor pointing to this output string.

directive-argument-address


OpenVMS usage: address
type: quadword (unsigned)
access: read only
mechanism: unspecified

Directive arguments. The directive-argument-address arguments are contained in an array of unsigned quadword directive arguments. Depending on the directive, a directive-argument-address argument can be a value to be converted, the address of the string to be inserted, or a length or argument count. The passing mechanism for each of these arguments should be the one expected by the $FAOL_64 system service.

Description

See the OpenVMS System Services Reference Manual for a complete description of $FAOL_64.

Condition Values Returned

SS$_NORMAL Routine successfully completed.
SS$_BADPARAM An invalid directive was specified in the FAO control string.
SS$_BUFFEROVF Successfully completed, but the formatted output string overflowed the output buffer and was truncated.
LIB$_INSVIRMEM Insufficient virtual memory to allocate dynamic string.
LIB$_INVSTRDES Invalid string descriptor. A string descriptor has an invalid value in its CLASS field.
LIB$_STRTRU Success, but the source string was truncated on copy.

LIB$SYS_GETMSG

The Invoke $GETMSG System Service to Get Message Text routine calls the system service $GETMSG and returns a message string into destination-string using the semantics of the caller's string.

Format

LIB$SYS_GETMSG message-id [,message-length] ,destination-string [,flags] [,unsigned-resultant-array]


RETURNS


OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value


Arguments

message-id


OpenVMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference

Message identification to be retrieved by LIB$SYS_GETMSG. The message-id argument contains the address of an unsigned longword integer that is this message identification.

message-length


OpenVMS usage: word_unsigned
type: word integer (unsigned)
access: write only
mechanism: by reference

Number of characters written into destination-string, not counting padding in the case of a fixed-length string. The message-length argument contains the address of an unsigned word integer that is this number.

If the input string is truncated to the size specified in the destination-string descriptor, message-length is set to this size. Therefore, message-length can always be used by the calling program to access a valid substring of destination-string.

destination-string


OpenVMS usage: char_string
type: character string
access: write only
mechanism: by descriptor

Destination string. The destination-string argument contains the address of a descriptor pointing to this destination string. LIB$SYS_GETMSG writes the message that has been returned by $GETMSG into destination-string.

flags


OpenVMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference

Four flag bits for message content. The flags argument is the address of an unsigned longword that contains these flag bits. The default value is a longword with bits 0 through 3 set to 1. The flags argument is passed to LIB$SYS_GETMSG by reference and changed to value for use by $GETMSG.

The following table lists the bit numbers, their values, and corresponding descriptions:
Bit Value Description
0 1 Include text of message.
  0 Do not include text of message.
1 1 Include message identifier.
  0 Do not include message identifier.
2 1 Include severity indicator.
  0 Do not include severity indicator.
3 1 Include facility name.
  0 Do not include facility name.

unsigned-resultant-array


OpenVMS usage: unspecified
type: unspecified
access: write only
mechanism: by reference, array reference

A 4-byte array to receive message-specific information. The unsigned-resultant-array argument contains the address of this array.

The contents of this 4-byte array are as follows:
Byte Contents
0 Reserved
1 Count of FAO arguments
2 User value
3 Reserved


Description

LIB$SYS_GETMSG calls the $GETMSG system service and returns a message string using the semantics of the caller's string. Note that, in order to retrieve a message string for a LIB$ facility message, you must include the file $LIBDEF in your program.

See the OpenVMS System Services Reference Manual for a more complete description of $GETMSG.


Condition Values Returned

SS$_NORMAL Routine successfully completed.
SS$_BUFFEROVF Successfully completed, but the resultant string overflowed the buffer provided and was truncated.
SS$_MSGNOTFND Successfully completed, but the message code does not have an associated message on file.
LIB$_STRTRU Successfully completed, but the source string was truncated on copy.
LIB$_FATERRLIB Fatal internal error.
LIB$_INSVIRMEM Insufficient virtual memory.
LIB$_INVSTRDES Invalid string descriptor.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5932PRO_043.HTML