[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

Figure lib-18 is the ASCII uppercase translation table.

Figure lib-18 LIB$AB_UPCASE


ASCII Lowercase Translation Table

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 Digital 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:

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

[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_031.HTML