Document revision date: 19 July 1999

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

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.

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.

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.

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.

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.

	privacy and legal statement
5932PRO_031.HTML