[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS RTL Library (LIB$) Manual


Previous Contents Index

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


LIB$CRC

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


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.

Note

1 On Alpha systems, OpenVMS Alpha instructions perform the equivalent operation.

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 


LIB$CREATE_DIR

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:

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


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

System/Owner/Group/World protection value of the directory you are creating. The protection-value argument is the address of an unsigned word that contains this protection mask.

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


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

Maximum number of versions allowed for files created in the newly created directories. The maximum-versions argument is the address of an unsigned word containing the value of the maximum number of 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


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

Relative volume number within a volume set on which the directory or subdirectory is created. The relative-volume-number argument is the address of an unsigned word containing the relative volume number. The relative-volume-number argument is optional. The default is arbitrary placement within the volume set.

initial-allocation


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

Initial number of blocks to be allocated to the directory. This argument is useful for creating large directories, for example MAIL.DIR;1. It can improve performance by avoiding the need for later dynamic expansion of the directory.

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:

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.


LIB$CREATE_USER_VM_ZONE

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

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5932PRO_004.HTML