HP OpenVMS Systems Documentation

HP OpenVMS RTL Library (LIB$) Manual

The Convert Date String to Quadword routine converts an absolute date string into an OpenVMS internal format date-time quadword. That is, given an input date/time string of a specified format, LIB$CONVERT_DATE_STRING converts this string to an OpenVMS internal format time.

Format

LIB$CONVERT_DATE_STRING date-string ,date-time [,user-context] [,flags] [,defaults] [,defaulted-fields]

RETURNS

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

Arguments

date-string

OpenVMS usage:	time_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor

Date string that specifies the absolute time to be converted to an internal system time. The date-string argument is the address of a descriptor pointing to this date string. This string must have a format corresponding to the currently defined input format, or it must be one of the relative day strings YESTERDAY, TODAY, or TOMORROW, or their equivalents in the currently selected language.

date-time

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

Receives the converted time. The date-time argument is the address of an unsigned quadword that contains this OpenVMS internal format converted time.

user-context

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Context variable that receives the translation context from a call to LIB$INIT_DATE_TIME_CONTEXT and then retains the translation context over multiple calls to LIB$CONVERT_DATE_STRING. The user-context argument is the address of an unsigned longword that contains this context. The user program should not write directly to this variable once it is initialized.

The user-context parameter is optional. However, if a context cell is not passed, the routine LIB$CONVERT_DATE_STRING may abort if two threads of execution attempt to manipulate the context area concurrently. Therefore, when calling this routine in situations where reentrancy might occur, such as from AST level, HP recommends that users specify a different context cell for each calling thread.

flags

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

Specifies which date or time fields of the date-string argument might be omitted so that default values are applied. The flags argument is the address of a longword bit mask that contains these flags. A set bit indicates that the field may be omitted. The bit definitions for the mask correspond to the fields in a $NUMTIM "timbuf" structure as follows:

Field	Bit Number	Mask
Year	0	01
Month	1	02
Day of month	2	04
Hours	3	08
Minutes	4	16
Seconds	5	32
Fractional seconds	6	64

Bits 7 through 31 must be zero and are reserved for use by HP. If this parameter is omitted, a default value of 120 (78H) is used, indicating that the time fields may be defaulted but the date fields may not.

defaults

OpenVMS usage:	vector_word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference, array reference

Supplies the defaults to be used for omitted fields. The defaults argument is the address of an array of unsigned words containing these default values. This array corresponds to a 7-word $NUMTIM "timbuf" structure. If the defaults argument is omitted, the following defaults are applied:

• For the date group, the default is the current date.
• For the time group, the default is 00:00:00.00.

defaulted-fields

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

Indicates which date or time fields have been defaulted. The defaulted-fields argument is the address of a longword bit mask that specifies these fields. The bit definitions are identical to those of the flags bit mask. A set bit indicates that the field was defaulted. Bits 7 through 31, which are reserved for use by HP, are zeroed.

Description

LIB$CONVERT_DATE_STRING converts an absolute date string into an OpenVMS internal format date-time quadword. The input date string can either correspond to the format specified, or it can be the language equivalent of one of the relative date strings YESTERDAY, TODAY, or TOMORROW. The language to be used and the format in which to interpret the information are programmable using either of the following methods:

• The language and format are programmable at compile time through the use of the routine LIB$INIT_DATE_TIME_CONTEXT.
• The language and format can be determined at run time through the translation of the logical names SYS$LANGUAGE and LIB$DT_INPUT_FORMAT.

In general, if an application is reading text from internal storage, the language and input format should be specified at compile time. If this is the case, use the routine LIB$INIT_DATE_TIME_CONTEXT to specify the language and input format of your choice.

If an application is accepting text from a user, the logical name method of specifying language and format should be used. In this method, the user assigns equivalence names to the logical names SYS$LANGUAGE and LIB$DT_INPUT_FORMAT, thereby selecting the language and input format of the date and time at run time.

The calling program can choose to apply defaults for omitted fields in the date string. To do this, the flags argument is used to indicate which fields are to be defaulted, and the defaults argument is used to supply the default values. If the defaults argument is not supplied, the following default values are applied:

• For the date group, the default is the current date.
• For the time group, the default is 00:00:00.00.

Optionally, you can use the defaulted-fields argument to receive information on which input fields were omitted and thus accepted default values.

Note Because the default is the current date for the date group, if you specify a value of 00 with the !Y2 format, the year is interpreted as 1900. After January 1, 2000, the value 00 will be interpreted as 2000.

See the HP OpenVMS Programming Concepts Manual for a description of system date and time operations as well as a detailed description of the format mnemonics used in these routines.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
LIB$_AMBDATTIM	Ambiguous date or time.
LIB$_DEFFORUSE	Default format used; unable to determine desired format.
LIB$_ENGLUSED	English used by default; unable to translate SYS$LANGUAGE.
LIB$_ILLFORMAT	Illegal format string; too many or not enough fields.
LIB$_INCDATTIM	Incomplete date or time; missing fields with no defaults.
LIB$_INVARG	Invalid argument; a required argument was not specified.
LIB$_INVSTRDES	Invalid input string descriptor.
LIB$_IVTIME	Invalid date or time.
LIB$_REENTRANCY	Reentrancy detected.
LIB$_UNRFORCOD	Unrecognized format code.
LIB$_WRONUMARG	Wrong number of arguments.

Any condition value returned by RTL routines LIB$GET_VM, LIB$FREE_VM, LIB$FREE1_DD, and LIB$SCOPY_R_DX, and system services $NUMTIM and $GETTIM.

The Calculate a Cyclic Redundancy Check routine calculates the cyclic redundancy check (CRC) for a data stream.

Format

LIB$CRC crc-table ,initial-crc ,stream

RETURNS

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

The computed cyclic redundancy check.

Arguments

crc-table

OpenVMS usage:	vector_longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference, array reference

The 16-longword cyclic redundancy check table created by a call to LIB$CRC_TABLE. The crc-table argument is the address of a signed longword integer containing this table. Because this table is created by LIB$CRC_TABLE and then used as input in LIB$CRC, your program must call LIB$CRC_TABLE before it calls LIB$CRC.

initial-crc

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference

Initial cyclic redundancy check. The initial-crc argument is the address of a signed longword integer containing the initial cyclic redundancy check.

stream

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

Data stream for which LIB$CRC is calculating the CRC. The stream argument is the address of a descriptor pointing to the data stream.

Description

Before your program can call LIB$CRC, it must call LIB$CRC_TABLE. LIB$CRC_TABLE takes a polynomial as its input and builds the table that LIB$CRC uses to calculate the CRC.

LIB$CRC allows your high-level language program to use the CRC instruction, which calculates the cyclic redundancy check.¹ This instruction checks the integrity of a data stream by comparing its state at the sending point and the receiving point. Each character in the data stream is used to generate a value based on a polynomial. The values for each character are then added together. This operation is performed at both ends of the data transmission, and the two result values compared. If the results disagree, then an error occurred during the transmission.

Condition Values Returned

None.

Example

For an example on how to use LIB$CRC, refer to the BASIC example at the end of the description of LIB$CRC_TABLE.

LIB$CRC_TABLE

The Construct a Cyclic Redundancy Check Table routine constructs a 16-longword table that uses a cyclic redundancy check polynomial specification as a bit mask.

Format

LIB$CRC_TABLE polynomial-coefficient ,crc-table

RETURNS

None.

Arguments

polynomial-coefficient

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

A bit mask indicating which polynomial coefficients are to be generated by LIB$CRC_TABLE. The polynomial-coefficient argument is the address of an unsigned longword integer containing this bit mask.

crc-table

OpenVMS usage:	vector_longword_signed
type:	longword integer (signed)
access:	write only
mechanism:	by reference, array reference

The 16-longword table that LIB$CRC_TABLE produces. The crc-table argument is the address of a signed longword integer containing the table.

Description

The table created by LIB$CRC_TABLE can be passed to the LIB$CRC routine for generating the cyclic redundancy check value for a stream of characters.

Condition Values Returned

None.

Example

1   %TITLE "Demonstrate LIB$CRC and LIB$CRC_TABLE"
    %SBTTL "Declarations"
    %IDENT "1-001"


    !--

    OPTION TYPE = EXPLICIT

    DECLARE LONG        CRC_TABLE(15),      ! CRC table array &
            LONG        CRC_VAL_1,          ! CRC for first stream &
            LONG        CRC_VAL_2,          ! CRC for second stream &
            STRING      DATA_1,             ! First data stream &
            STRING      DATA_2              ! Second data stream

    EXTERNAL LONG FUNCTION LIB$CRC          ! Rtn to calculate CRC

    EXTERNAL SUB LIB$CRC_TABLE              ! Rtn to set up table for CRC


    OPEN "SYS$INPUT:" FOR INPUT AS FILE 1%

    !+
    ! Initialize the CRC table.  Use the CRC-16 polynomial (refer to the
    ! "VAX Architecture Reference Manual"). This is the polynomial used by
    ! DDCMP and Bisync.
    !-

    CALL LIB$CRC_TABLE( O'120001'L, CRC_TABLE() BY REF )

    !+
    ! Get data from user.
    !-

    LINPUT #1%, 'Enter string: ';DATA_1

    !+
    ! Calc the CRC for the user's input.  This CRC polynomial needs
    ! an initial CRC of 0 (refer to the "VAX Architecture Reference Manual").
    ! LIB$CRC returns a longword, but only the low-order word is valid
    ! for this polynomial.
    !-

    CRC_VAL_1 = LIB$CRC( CRC_TABLE() BY REF, 0%, DATA_1 )
    CRC_VAL_1 = CRC_VAL_1 AND 32767%

    !+
    ! Get more data from user.
    !-

    LINPUT #1%, 'Enter a second string: ';DATA_2

    CRC_VAL_2 = LIB$CRC( CRC_TABLE() BY REF, 0%, DATA_2 )
    CRC_VAL_2 = CRC_VAL_2 AND 32767%

    !+
    ! Tell the user the results of the CRC comparison.
    !-

    IF CRC_VAL_1 = CRC_VAL_2
    THEN
        PRINT "The two CRCs";CRC_VAL_1;" and ";CRC_VAL_2;" were the same"
    ELSE
        PRINT "The two CRCs";CRC_VAL_1;" and ";CRC_VAL_2;" were different"
    END IF


    IF DATA_1 = DATA_2
    THEN
        PRINT "The two strings were the same"
    ELSE
        PRINT "The two strings were different"
    END IF

    END


      

This BASIC example program shows the use of LIB$CRC and LIB$CRC_TABLE. One example of the output generated by this program is as follows:

$ RUN CRC Enter string: DOVE Enter a second string: HOSE The two CRCs 29915 and 29915 were the same The two strings were different

The Create a Directory routine creates a directory or subdirectory.

Format

LIB$CREATE_DIR device-directory-spec [,owner-UIC] [,protection-enable] [,protection-value] [,maximum-versions] [,relative-volume-number] [,initial-allocation]

RETURNS

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

Arguments

device-directory-spec

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

Directory specification of the directory or subdirectory that LIB$CREATE_DIR will create. The device-directory-spec argument is the address of a descriptor pointing to this directory specification.

The format of the device-directory-spec string conforms to standard OpenVMS Record Management Services (RMS) format. This specification must contain a directory or subdirectory specification. It may contain a disk specification. SMD$:[THIS.IS.IT] is an example of a standard RMS file specification, where SMD$ is the disk specification and [THIS.IS.IT] is the subdirectory specification.

This specification cannot contain a node name, file name, file type, file version, or wildcard characters. The maximum size of this string is 255 characters on VAX, and 4095 characters on Alpha.

owner-UIC

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

User identification code (UIC) identifying the owner of the created directory or subdirectory. The owner-UIC argument is the address of an unsigned longword that contains the UIC. If owner-UIC is zero, the owner UIC is that of the parent directory. The specified value for owner-UIC is interpreted as a 32-bit octal number, with two 16-bit fields:

bits 00--15 --- Member number
bits 16--31 --- Group number

This is an optional argument. The default is the UIC of the current process except when the directory is in UIC format. For a directory in UIC format, for example [123,321], the UIC of the created directory is used.

protection-enable

OpenVMS usage:	mask_word
type:	word (unsigned)
access:	read only
mechanism:	by reference

Mask specifying the bits of protection-value to be set. The protection-enable argument is the address of an unsigned word containing this protection mask.

Figure lib-1 shows the structure of a protection mask. Access is allowed for bits set to 0.

Figure lib-1 Structure of a Protection Mask

Bits set in the protection-enable mask cause corresponding bits of protection-value to be set. Bits not set in the protection-enable mask cause corresponding bits of protection-value to take the value of the corresponding bit in the parent directory's file protection. Bits in the parent directory's file protection that indicate delete access do not cause corresponding bits of protection-value to be set, however.

Following is an example of how the protection-value protection mask is defined:

The protection-enable argument is optional. It should be used only when you want to change protection values from the parent directory's default file protection. The default for protection-enable is a mask of all zero bits, which results in the propagation of the parent directory's file protection. If the protection-enable mask contains zeros, protection-value is ignored.

protection-value

The bits of protection-value are set or cleared in the method described in the definition of protection-enable above.

The protection-value argument is optional. The default is a word of all zero bits, which specifies full access for all access categories. Typically, protection-value is not omitted unless protection-enable is also omitted. If protection-enable is omitted, protection-value is ignored.

maximum-versions

The maximum-versions argument is optional. The default is the parent directory's default version limit. If maximum-versions is zero, the maximum number of versions is not limited.

relative-volume-number

initial-allocation

The initial-allocation argument applies only to Files--11 Level 2 volumes; it is ignored for other volumes.

This argument is the address of an unsigned longword that contains the initial number of blocks to be allocated to the directory.

The initial-allocation argument is optional. The default allocation is 1 block.

Description

LIB$CREATE_DIR creates a directory. You can specify:

• The owner and protection of the directory.
• The maximum number of different versions of a file that can exist in the directory.
• The relative volume number of the volume set member in which the directory is to be created.
• The number of blocks to be allocated initially to the directory.

Note This routine calls LIB$GET_EF. Please read the note in the Description section of that routine.

Condition Values Returned

SS$_CREATED	Routine successfully completed; one or more directories created.
SS$_NORMAL	Routine successfully completed; all specified directories already exist.
LIB$_INVARG	Invalid argument to Run-Time Library. Either the required argument was omitted, or device-directory-spec is longer than 4095 characters.
LIB$_INVFILSPE	Invalid file specification. Either the file specification did not contain an explicit directory and device name, or it contained a node name, file name, file type, file version, or wildcard. This error is also produced if the device specified was not a disk.