Document revision date: 30 March 2001 | |
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
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.
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
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.
LIB$MOVTUC source-string ,stop-character ,translation-table ,destination-string [,fill-character]
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.
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.
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.
None.
The Multiply Delta Time by an F-Floating Scalar routine multiplies a delta time by an F-floating scalar.
LIB$MULTF_DELTA_TIME multiplier ,delta-time
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.)
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.
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.
LIB$MULT_DELTA_TIME multiplier ,delta-time
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.)
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.
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.
LIB$PARSE_ACCESS_CODE access-string, [access-names,] ownership-category, access-mask, [end-position]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
LIB$PARSE_SOGW_PROT protection-string, [access-names], protection-mask, ownership-mask, [end-position]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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 |