Document revision date: 30 March 2001

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

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

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

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

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

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_044.HTML