Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

Figure lib-18 is the ASCII uppercase translation table.

Figure lib-18 LIB$AB_UPCASE

ASCII Lowercase Translation Table

- The numbers on the left represent the low-order bits of the ASCII characters in hexadecimal notation.
- The numbers across the top represent the high-order bits of the ASCII characters in hexadecimal notation.
- The numbers in the body of the table represent the equivalent lowercase ASCII characters in hexadecimal notation.

Figure lib-19 is the ASCII lowercase translation table.

Figure lib-19 LIB$AB_LOWERCASE

### Condition Values Returned

> SS$_NORMAL | Routine successfully completed.
> LIB$_STRTRU | Routine successfully completed; string truncated. The destination string could not contain all the characters.
> LIB$_FATERRLIB | Fatal internal error.
> LIB$_INSVIRMEM | Insufficient virtual memory.
> LIB$_INVSTRDES | Invalid string descriptor.

### Example

    1   !+
        !This BASIC program shows the method
        !of creating a descriptor for the appropriate
        !translation table in order to call LIB$MOVTC.
        !-

        OPTION TYPE = EXPLICIT

        !+
        !Declare the translation table as an
        !EXTERNAL LONG variable.
        !-

        EXTERNAL LONG LIB$AB_ASC_EBC
        EXTERNAL LONG FUNCTION LIB$MOVTC
        EXTERNAL SUB LIB$STOP
        EXTERNAL LONG CONSTANT DSC$K_CLASS_S, DSC$K_DTYPE_T

        !+
        !Define a record which models the required
        !translation table descriptor.
        !-

        RECORD STR_TYPE
            WORD    DSC$W_LENGTH
            BYTE    DSC$B_DTYPE
            BYTE    DSC$B_CLASS
            LONG    DSC$A_POINTER
        END RECORD STR_TYPE

        DECLARE LONG I, RET_STS
        DECLARE STR_TYPE STR_VAR

        MAP (FOO) STRING DST = 3%
        MAP (FOO) BYTE DST_ARRAY(2)

        !+
        !Fill the translation table descriptor record.
        !Note that the length of the translation table string
        !is set to 256, and the pointer receives the address of
        !the Compaq translation table LIB$AB_ASC_EBC.
        !-

        STR_VAR::DSC$W_LENGTH = 256
        STR_VAR::DSC$B_DTYPE = DSC$K_DTYPE_T
        STR_VAR::DSC$B_CLASS = DSC$K_CLASS_S
        STR_VAR::DSC$A_POINTER = LOC(LIB$AB_ASC_EBC)

        RET_STS = LIB$MOVTC( "ABC", " ", STR_VAR BY REF, DST )
        IF (RET_STS AND 1%) = 0%
        THEN
            CALL LIB$STOP( RET_STS BY VALUE )
        END IF

        !+
        !Add 256 to the translated value in order to return
        !an unsigned value.
        !-

        PRINT (256 + DST_ARRAY(I)) FOR I = 0% TO 2%

        END

> The output generated by this BASIC program is as follows:

>      193
>      194
>      195

## LIB$MOVTUC

> The Move Translated Until Character routine moves the source string, character by character, to the destination string after translating each character using the specified translation table until the stop character is encountered. LIB$MOVTUC makes the VAX MOVTUC instruction available as a callable routine.

> Note On Alpha systems, OpenVMS Alpha instructions perform the equivalent operation.

### Format

> LIB$MOVTUC source-string ,stop-character ,translation-table ,destination-string [,fill-character]

### RETURNS

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

> The relative position in the source string of the character that is translated to the stop character. Zero is returned if the stop character is not found. This value is set to --1 if destination-string cannot be allocated.

### Arguments

> #### source-string

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

> Source string to be translated and moved by LIB$MOVTUC. The source-string argument is the address of a descriptor pointing to this source string.

> #### stop-character

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

> Stop character that causes LIB$MOVTUC to stop translating the source string. The stop-character argument is the address of a descriptor pointing to a string. The first character of this string is used as the stop character. The length of this string is not checked. During the translation, LIB$MOVTUC accesses each character in the source string and uses it as an index into the translation table. If this translated character is the specified stop character, translation stops, and stop-character is not translated.

> #### translation-table

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

> Translation table used by LIB$MOVTUC. The translation-table argument is the address of a descriptor pointing to the translation table string. The translation table string is assumed to be 256 characters long.

> You can use any of the translation tables included in the Description section of LIB$MOVTC, or you can create your own. When using a translation table supplied by Compaq, the names LIB$AB_xxx_yyy represent the addresses of the 256-byte translation tables, and can be accessed as external (string) variables. If a particular language cannot generate descriptors for external strings, then they must be created manually. The example for the routine LIB$MOVTC shows the creation of a string descriptor for a translation table using VAX BASIC.

> #### destination-string

> OpenVMS usage: | char_string
> type: | character string
> access: | write only
> mechanism: | by descriptor

> Destination string into which LIB$MOVTUC writes the translated source-string. The destination-string argument is the address of a descriptor pointing to this destination string.

> #### fill-character

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

> Character used to pad source-string to the length of destination-string. The fill-character argument is the address of a descriptor pointing to a string. The first character of this string is used as the fill character. The length of this string is not checked and fill-character is not translated.

> If the fill character is included, the remainder of the destination string (after the stop character) is filled with the specified fill character. If it is not included, the remainder of the destination string remains unchanged.

### Description

> During the translation, LIB$MOVTUC accesses each character in the source string and uses it as an index into the translation table. If the table entry contains the specified stop character, the routine is terminated and the relative position of the source character is returned.

> If the source string is longer than the destination string, then the source string is truncated. If the optional fill character is present, any remaining positions in the destination string are filled with the fill character. If the source or destination string is exhausted (before the stop character is found), a zero index is returned.

> The results are unpredictable if the source and destination strings overlap and have different starting addresses.

> See the description of LIB$MOVTC for the translation tables used by LIB$MOVTC and LIB$MOVTUC. Each translation table is preceded by explanatory text.

### Condition Values Returned

> None.

## LIB$MULTF_DELTA_TIME

> The Multiply Delta Time by an F-Floating Scalar routine multiplies a delta time by an F-floating scalar.

### Format

> LIB$MULTF_DELTA_TIME multiplier ,delta-time

### RETURNS

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

### Arguments

> #### multiplier

> OpenVMS usage: | floating_point
> type: | F_floating
> access: | read only
> mechanism: | by reference

> The value by which LIB$MULTF_DELTA_TIME multiplies the delta time. The multiplier argument is the address of an F-floating value containing the scalar. If multiplier is negative, the absolute value of multiplier is used.

> #### delta-time

> OpenVMS usage: | date_time
> type: | quadword (unsigned)
> access: | modify
> mechanism: | by reference

> The delta time to be multiplied. The delta-time argument is the address of an unsigned quadword containing the number to be multiplied. The initial delta-time argument must be greater than 0. After LIB$MULTF_DELTA_TIME performs the multiplication, the result is returned to delta-time. (The original delta-time value is overwritten.)

### Description

> LIB$MULTF_DELTA_TIME multiplies a delta time by an F-floating scalar. The result of the multiplication is returned to the delta-time argument.

### Condition Values Returned

> LIB$_NORMAL | Routine successfully completed.
> LIB$_IVTIME | Invalid time.
> LIB$_WRONUMARG | Incorrect number of arguments.

## LIB$MULT_DELTA_TIME

> The Multiply Delta Time by Scalar routine multiplies a delta time by a longword integer scalar.

### Format

> LIB$MULT_DELTA_TIME multiplier ,delta-time

### RETURNS

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

### Arguments

> #### multiplier

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

> The value by which LIB$MULT_DELTA_TIME multiplies the delta time. The multiplier argument is the address of a signed longword containing the integer scalar. If multiplier is negative, the absolute value of multiplier is used.

> #### delta-time

> OpenVMS usage: | date_time
> type: | quadword (unsigned)
> access: | modify
> mechanism: | by reference

> The delta time to be multiplied. The delta-time argument is the address of an unsigned quadword containing the number to be multiplied. The initial delta-time argument must be greater than 0. After LIB$MULT_DELTA_TIME performs the multiplication, the result is returned to delta-time. (The original delta-time value is overwritten.)

### Description

> LIB$MULT_DELTA_TIME multiplies a delta time by a longword integer scalar. The result of the multiplication is returned to the delta-time argument.

### Condition Values Returned

> LIB$_NORMAL | Routine successfully completed.
> LIB$_IVTIME | Invalid time.
> LIB$_WRONUMARG | Incorrect number of arguments.

## LIB$PARSE_ACCESS_CODE

> The Parse Access Encoded Name String routine parses and translates a string of access names into a mask for a particular ownership category.

### Format

> LIB$PARSE_ACCESS_CODE access-string, [access-names,] ownership-category, access-mask, [end-position]

### RETURNS

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

### Arguments

> #### access-string

> OpenVMS usage: | char_string
> type: | character-coded text string
> access: | read only
> mechanism: | by descriptor

> The address of a character-string descriptor pointing to a string of access names. Each access name is abbreviated to one letter. An example of a valid access string is RWE. Access names are specific to each of the different object classes. See the OpenVMS Guide to System Security for a complete list of all valid access names.

> #### access-names

> OpenVMS usage: | access_names
> type: | array [0..31] of quadword string descriptor
> access: | read only
> mechanism: | by reference

> The address of the access name table for the associated object class. For example, it is the value returned by the LIB$GET_ACCNAM routine in the accnam longword. This parameter is optional and defaults to the access name table for the FILE object class.

> #### ownership-category

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

> The address of a word that indicates the ownership category the access names refer to:

> Ownership Category | Mask Value
> --- | ---
> System | 0000000000001111
> Owner | 0000000011110000
> Group | 0000111100000000
> World | 1111000000000000

> #### access-mask

> OpenVMS usage: | mask_word
> type: | word (unsigned)
> access: | write only
> mechanism: | by reference

> The address of a word into which this routine writes the access mask. In this mask, a set bit means the access was requested for the specified ownership. Note that this is the opposite of the standard protection format where a set bit means no access.

> #### end-position

> OpenVMS usage: | word_signed
> type: | word (signed)
> access: | write only
> mechanism: | by reference

> The number of characters from access-string processed by LIB$PARSE_ACCESS_CODE. In the case of an error in parsing the access string, the offset to the offending location is returned.

### Description

> LIB$PARSE_ACCESS_CODE parses a string of access names and translates the string into a mask for the requested ownership category. The string is a concatenated list of 1-letter abbreviations of access names.

> This routine works for any protected object class by specifying the correct access name table. The address of the access name table can be obtained from the LIB$GET_ACCNAM routine.

> This routine is useful for building a protection mask where the ownership names have already been parsed. Use LIB$PARSE_SOGW_PROT for parsing a string containing both ownership and access names.

> The mask returned has bits set for the access requested for the specified ownership category. This is opposite the standard protection format where a set bit in the protection mask means no access.

> The number of characters processed is optionally returned. This is useful for error processing. The end position will be the offset to the character that made the access category name string invalid.

### Condition Values Returned

> SS$_NORMAL | Routine successfully completed.
> LIB$_IVARG | Required parameter missing or a character in access-string did not represent a valid access type.
> LIB$_WRONGNUMARG | Wrong number of arguments.

## LIB$PARSE_SOGW_PROT

> The Parse Protection String routine parses and translates a protection string into a protection mask.

### Format

> LIB$PARSE_SOGW_PROT protection-string, [access-names], protection-mask, ownership-mask, [end-position]

### RETURNS

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

### Arguments

> #### protection-string

> OpenVMS usage: | char_string
> type: | character-coded text string
> access: | read only
> mechanism: | by descriptor

> The address of a character-string descriptor pointing to the protection string. The string components are:
> - Ownership name --- System,Owner,Group,World. Ownership names can be specified in full or truncated to any number of characters. Matching is case blind, and spacing is ignored.
> - Access name --- Access names are always abbreviated to one letter. For example, access names for files are R (for read), W (for write), E (for execute), and D (for delete). Any combination can be passed. For example, RWE is a valid combination. A null access name specification means no access.
> - Separators --- Access names are separated from ownership names by either a colon (:) or an equal sign (=). The comma (,) is the list separator. A null access name specification means no access.

> An example of a valid protection string is:

> SYSTEM=RWED,OWNER:RWED,GROUP,WORLD:R

> #### access-names

> OpenVMS usage: | access_names
> type: | array [0..31] of quadword string descriptor
> access: | read only
> mechanism: | by reference

> The address of the access name table for the associated object class. For example, it is the value returned by the LIB$GET_ACCNAM routine in the accnam longword. This parameter is optional and defaults to the access name table for the FILE object class.

> #### protection-mask

> OpenVMS usage: | protection
> type: | word (unsigned)
> access: | write only
> mechanism: | by reference

> The address of a word into which this routine writes a 16-bit protection mask translation of the protection string. Each bit set in the mask indicates no access for the access type it represents.

> #### ownership-mask

> OpenVMS usage: | mask_word
> type: | word (unsigned)
> access: | write only
> mechanism: | by reference

> The address of a word that indicates which ownership names were present in the protection string.

> Ownership Category | Mask Value
> --- | ---
> System | 0000000000001111
> Owner | 0000000011110000
> Group | 0000111100000000
> World | 1111000000000000

> #### end-position

> OpenVMS usage: | word_signed
> type: | word (signed)
> access: | write only
> mechanism: | by reference

> The number of characters from protection-string processed by LIB$PARSE_SOGW_PROT. In the case of an error in parsing the protection string, the offset to the offending location is returned.

### Description

> LIB$PARSE_SOGW_PROT parses a protection string and translates the string into a 16-bit protection mask. LIB$PARSE_SOGW_PROT works for any protected object class by specifying the correct access name table.

> The address of the access name table can be obtained from the LIB$GET_ACCNAM routine. Note that file access names are valid for any protected object class.

> The number of characters processed is optionally returned. This is useful in error processing. The end position will be the offset to the character that made the protection string invalid. Note that the entire protection string must be valid, or an error is returned.

> Several scenarios can cause the protection string to be invalid. The format of the protection string may be invalid, or the access category abbreviations may not be valid with respect to the access name tables.

### Condition Values Returned

> SS$_NORMAL | Routine successfully completed.
> LIB$_IVARG | Required parameter missing or invalid protection string.
> LIB$_WRONGNUMARG | Wrong number of arguments.

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_032.HTML