HP OpenVMS Systems Documentation

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: A--GETUAI 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.

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: A--GETUAI 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.

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: A--GETUAI 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.

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: A--GETUAI 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.

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: A--GETUAI 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.