Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual

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

See the 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.

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:

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.

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 255 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.

Any condition values returned by system services $ASSIGN, $DASSGN, $PARSE, and $QIO, and RTL routines LIB$ANALYZE_SDESC, LIB$ANALYZE_SDESC_64, and LIB$GET_EF.

The Create User-Defined Storage Zone routine creates a new user-defined storage zone in the 32-bit virtual address space.

Note No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

Format

LIB$CREATE_USER_VM_ZONE zone-id [,user-argument] [,user-allocation-procedure] [,user-deallocation-procedure] [,user-reset-procedure] [,user-delete-procedure] [,zone-name]

RETURNS

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

Arguments

zone-id

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

Zone identifier. The zone-id argument is the address of a longword that receives the identifier of the newly created zone.

user-argument

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

User argument. The user-argument argument is the address of an unsigned longword containing the user argument. LIB$CREATE_USER_VM_ZONE copies the value of user-argument and supplies the value to all user procedures invoked.

user-allocation-procedure

OpenVMS usage:	procedure
type:	procedure value
access:	function call (before return)
mechanism:	by value

User allocation routine.

user-deallocation-procedure

OpenVMS usage:	procedure
type:	procedure value
access:	function call (before return)
mechanism:	by value

User deallocation routine.

user-reset-procedure

OpenVMS usage:	procedure
type:	procedure value
access:	function call (before return)
mechanism:	by value

User routine invoked each time LIB$RESET_VM_ZONE is called for the zone.

user-delete-procedure

OpenVMS usage:	procedure
type:	procedure value
access:	function call (before return)
mechanism:	by value

User routine invoked when LIB$DELETE_VM_ZONE is called for the zone.

zone-name

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

Name to be associated with the zone being created. The optional zone-name argument is the address of a descriptor pointing to the zone name. If zone-name is not specified, the zone will not have an associated name.

Description

LIB$CREATE_USER_VM_ZONE creates a user-defined zone in the 32-bit virtual address space. If an error status is returned, the zone is not created.

Each time that one of the heap management routines (LIB$GET_VM, LIB$FREE_VM, LIB$RESET_VM_ZONE, or LIB$DELETE_VM_ZONE) is called to perform an operation on a user-defined zone, the corresponding user routine that you supplied is used.

You may omit any of the optional user routines. However, if you omit a routine and later call the corresponding heap management routine, the error status LIB$_INVOPEZON will be returned.

Call Format for User Routines

The user routines are called with arguments similar to those passed to LIB$GET_VM, LIB$FREE_VM, LIB$RESET_VM_ZONE, or LIB$DELETE_VM_ZONE. In each case, the user-argument argument from LIB$CREATE_USER_VM_ZONE is passed to the user routine rather than a zone-id argument.

The call format for a user get or free routine is as follows:

user-rtn num-bytes ,base-adr ,user-argument

num-bytes

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

Number of contiguous bytes to allocate or free. The num-bytes argument is the address of a longword integer containing the number of bytes. The value of num-bytes must be greater than zero.

base-adr

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

Virtual address of the first contiguous block of bytes allocated or freed. The base-adr argument is the address of an unsigned longword containing this base address. (This argument is write-only for a get routine and read-only for a free routine.)

user-argument

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

User argument. LIB$CREATE_USER_VM_ZONE copies user-argument as it is supplied to all user routines invoked.

---

Previous

Next

Contents

Index

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5932PRO_004.HTML