|
HP OpenVMS systems documentation |
Previous | Contents | Index |
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.
LIB$CONVERT_DATE_STRING date-string ,date-time [,user-context] [,flags] [,defaults] [,defaulted-fields]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
LIB$CRC crc-table ,initial-crc ,stream
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by value
The computed cyclic redundancy check.
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.
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.1 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.
None.
For an example on how to use LIB$CRC, refer to the BASIC example at the end of the description of LIB$CRC_TABLE.
1 On Alpha systems, OpenVMS Alpha instructions perform the equivalent operation. |
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.
LIB$CRC_TABLE polynomial-coefficient ,crc-table
None.
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.
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.
None.
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.
LIB$CREATE_DIR device-directory-spec [,owner-UIC] [,protection-enable] [,protection-value] [,maximum-versions] [,relative-volume-number] [,initial-allocation]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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 numberThis 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:
Mask Name | Hexadecimal Number | Value |
---|---|---|
Protection enable | %XDBFF | S:None, O:None, G:E, W:W |
Parent directory | %X13FF | S:RWED, O:RWED, G:RW, W:R |
Protection value | %X37FF | S:RWE, O:RWE, G:RWE, W:RW |
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.
OpenVMS usage: | file_protection |
type: | word (unsigned) |
access: | read only |
mechanism: | by reference |
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.
OpenVMS usage: | word_unsigned |
type: | word (unsigned) |
access: | read only |
mechanism: | by reference |
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.
OpenVMS usage: | word_unsigned |
type: | word (unsigned) |
access: | read only |
mechanism: | by reference |
OpenVMS usage: | longword_unsigned |
type: | longword (unsigned) |
access: | read only |
mechanism: | by reference |
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.
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.
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.
Previous | Next | Contents | Index |